zot-skill-cmds

A Go extension for zot v0.3.95 or newer that exposes selected skills as short slash commands.

Mark a skill

Set user-invocable: true in a skill's frontmatter:

---
name: developer:commit
description: Create a clean commit for the current changes.
user-invocable: true
---

Follow the commit workflow described here.

The extension registers the final name component as a command:

/commit review the staged diff

Configuration

The extension stores user configuration in $ZOT_HOME/skill-cmds.json (normally ~/.local/state/zot/skill-cmds.json). Use /skill-cmds to inspect it, or run:

/skill-cmds namespace on
/skill-cmds namespace off

With namespace commands enabled, skills supplied by an enabled zot extension (or Claude-compatible plugin packaged as an extension) use the extension name as a command prefix. For example, a commit skill from the developer extension is registered as /developer-commit; project and user skills remain unprefixed. Restart zot after changing this setting so the command registry is rebuilt.

The canonical zot command remains available:

/skill:developer:commit review the staged diff

Three-state behavior

The extension intentionally treats user-invocable as a three-state alias marker:

Frontmatter	Bare command
omitted	not registered
`user-invocable: true`	registered
`user-invocable: false`	not registered

This is an extension policy. It does not change Claude Code's own default behavior for an omitted field.

Discovery

The extension scans extension-declared skill roots first, matching zot's extension precedence:

./.zot/extensions/*/skills from each enabled extension.json
$ZOT_HOME/extensions/*/skills from each enabled extension.json
./.zot/skills
$ZOT_HOME/skills
./.claude/skills
~/.claude/skills
./.agents/skills
~/.agents/skills

This lets the extension alias skills bundled by installed zot skill extensions, such as /commit for a skill with user-invocable: true. Symlinked extension directories are supported. Only files named SKILL.md are considered. Duplicate canonical skill names keep the first match. Extension-supplied skills use zot's canonical <extension>:<skill> name, while namespace commands optionally use the extension name as the alias prefix.

When a command runs, the extension uses zot v0.3.95's host-mediated tool API to call the built-in skill tool directly. It then submits the returned instructions, the skill directory, and any trailing command arguments as the request. This avoids asking the model to select and call the skill tool itself while preserving skill-relative asset, reference, and script paths. Because zot's skill registry is loaded at startup, restart or reload zot after changing a skill's name or contents.

The current implementation uses a small frontmatter parser and reads name, description, and user-invocable. Unknown fields are ignored.

Install and test

Install zot v0.3.95 or newer. Older hosts do not support extension-initiated tool calls and the command will report an error instead of starting a model turn.

Build the extension:

go build -o zot-skill-cmds .

Run it for one zot session:

zot --ext .

Or install it:

zot ext install .

Run tests:

go test ./...

Collision behavior

Aliases use zot's normal extension command namespace. Built-in zot commands retain priority. If multiple discovered skills produce the same alias, this extension keeps the first skill according to discovery precedence and logs a diagnostic.

The extension process has the same filesystem permissions as the user. Skill files are instruction text; review them before enabling aliases.

zenobi-us/zot-skill-cmds