Skills

Skills are per-folder SKILL.md files with a YAML frontmatter header. For normal skills, zot surfaces names and descriptions in the system prompt and exposes a built-in skill tool the model uses to load the full body on demand. Load a skill explicitly for one request, or pin frequently used skills for fresh conversations.

Force a specific skill

Invoke a skill with /skill:<name> to bypass model-side selection. Typing /skill: opens a filtered list of discovered user skills. Use the arrow keys to select one, tab to complete its name, or enter to invoke the highlighted skill. zot expands the command into a user message containing the complete skill instructions and its directory for resolving relative references. Text after the command becomes the request to perform.

/skill:code-review
/skill:code-review focus on security issues

Pinned skills

Run /skills and select a skill. Press p to toggle a project pin or g to toggle a global pin. The picker shows [p-], [-g], or [pg] for the selected scopes. Global and project pins are combined in alphabetical name order, with each skill loaded only once. Removing a project pin does not remove a global pin of the same name.

A read-only [Pinned skills] section above the input shows the pending names and their scopes: (project), (global), or (project + global). Its accent heading and indented, muted names match the other startup information sections. This notice is independent of show loaded resources at startup and does not insert editable placeholders.

Pinning skills does not itself start inference or tool execution. The complete instructions and source directories accompany the first real message in a fresh conversation and are persisted with it. The editor text stays unchanged.

• /new starts a fresh persisted session and prepares pinned skills for its first message.
• /clear prepares pinned skills again for the next message without creating a new session.
• /cd starts fresh and prepares pins for the new directory.
• Continuing, resuming, importing, or branching an existing session does not inject pins again, even if its transcript is empty.
• Switching models and compacting context do not reload pins.
• Changes made before the first message update the pending selection. After that message, pin changes apply on the next fresh conversation or /clear. Unpinning does not remove instructions already in the transcript.

Pin storage and limitations

Pin preferences are local to your machine, stored in $ZOT_HOME/skill-pins.json, not in the repository or config.json. Project pins use the session's absolute starting directory, with symlinks resolved when possible, rather than the Git root. Subdirectories have separate project pins.

{
  "global": ["code-review"],
  "projects": {
    "/home/me/work/app": ["test-fix"]
  }
}

Pins refer to discovered skill names, including extension namespaces, rather than copies of skill files. Normal discovery precedence applies, so a global pin can resolve to a project's higher-priority skill of the same name. Missing or disabled sources are skipped with a warning. Malformed preferences are reported and are not overwritten by a toggle. --no-skill disables preloading, including after /new or /clear. Built-in implementation skills are not pinnable. You can explicitly pin a skill with disable-model-invocation: true.

Interactive, print, stream, and JSON modes support pins, including runs with session persistence disabled. Startup pre commands for .zot agents run before pins are applied. RPC, standalone bots, SDK clients, and swarm background agents do not automatically load pin preferences. The interactive Telegram bridge uses the interactive conversation's pins.

Pinning saves repeated invocation, not tokens. Full skill bodies occupy context and may later be summarized by compaction, so keep pins small when using local models. There is no per-request removal control in the editor. An open interactive session refreshes preferences on /skills, /new, or /clear, not continuously. Concurrent preference edits from separate zot processes are not merged.

Fuzzy skill suggestions

By default, suggestions match case-insensitive name prefixes and are sorted alphabetically. Enable fuzzy skill suggestions in /settings to match characters in order anywhere in a skill name. For example, /skill:review and /skill:crv can both find code-review.

• Results are ranked by relevance, with alphabetical tie-breaking. Matching characters appear in bold, including in the selected row; bold emphasis depends on terminal support.
• Only skill names are searched, not descriptions or the /skill: prefix.
• An empty /skill: query still lists skills alphabetically. An exact name shows only that skill.
• Other slash-command suggestions and exact skill lookup during invocation are unchanged. Use tab to complete a fuzzy query before adding request text, or enter to invoke the highlighted skill.

The setting applies immediately and persists as fuzzy_skill_suggest in $ZOT_HOME/config.json. It is off by default: a missing or false value preserves prefix matching. Turn it off at any time to return to the original behavior.

User-invoked skills

Set disable-model-invocation: true when a skill should run only after explicit user invocation. It remains available through /skills and /skill:<name>, but zot omits its name and description from the model's startup context. Explicitly pinning it also opts into loading its instructions on fresh conversations.

---
name: deploy-release
description: Prepare and deploy a release after explicit user approval.
disable-model-invocation: true
---

# Deploy release

Follow the release checklist in order.

Discovery and inspection

Built-in and user-installed skills load by default from .zot/skills/, $ZOT_HOME/skills/, .claude/skills/, or .agents/skills/. Use --no-skill to disable all skill discovery.

Skill directories and nested category directories can be symlinks into a shared checkout. zot follows directory links but scans each resolved directory only once. Real directories take precedence over aliases within a skill root, so a link cannot rename an existing unnamed skill. When a skill is found only through a link, /skills shows the installed link path. Dangling links and link cycles are ignored.

When different files share a skill name, zot keeps the higher-precedence file and reports a shadowing diagnostic. Rediscovering the same file under the same skill name, including through a symlink, does not produce a warning. This covers overlapping project and global skill locations when you launch zot from your home directory. Distinct extension namespaces remain separate.

Run /skills to inspect discovered user skills. Skills hidden from model invocation are labeled manual. Select a skill and press enter to preview its description, source path, and full body. Long lines wrap to the terminal width rather than being cut off. Use up/down or pgup/pgdn to scroll the preview, including its description and source path on short terminals. Press esc or enter to return to the picker. Picker rows remain single-line and may truncate long descriptions.

Enable show loaded resources at startup in /settings to list user-installed skill names in the compact Skills startup section. Built-in skills stay hidden.