1# zot skills
2
3A skill is a reusable instruction set written as a single
4`SKILL.md` file with a YAML frontmatter header. Unless a skill disables
5model invocation, zot discovers it at startup and surfaces it to the model
6in two ways:
7
81. The system prompt gains a short manifest:
9   `Available skills: ... - code-review — Run a self-review pass...`
102. A built-in `skill` tool lets the model load any one skill's full
11   body on demand.
12
13The on-demand-load model keeps token usage cheap: only the manifest
14goes into every request; the body is fetched as a tool result the
15one or two turns the model actually needs it.
16
17## Anatomy
18
19```markdown
20---
21name: code-review
22description: Run a thorough self-review pass on a recent change.
23allowed-tools: [read, bash]
24permissions:
25  bash: ["git diff*", "git log*"]
26---
27
28# Code review
29
30When asked to review code, ...
31```
32
33### Frontmatter fields
34
35| field | required | purpose |
36|---|---|---|
37| `name` | optional | skill identifier; defaults to the directory name |
38| `description` | required | one-line summary shown in the system prompt |
39| `disable-model-invocation` | optional | when `true`, hide the skill from the model's startup manifest; invoke it explicitly with `/skill:<name>` |
40| `allowed-tools` | optional | list of tool names the skill is meant to use; informational |
41| `permissions` | optional | per-tool patterns; informational |
42
43`allowed-tools` and `permissions` are **parsed but not enforced** in
44this version. They appear in the rendered skill body so the model can
45see them and self-regulate. Future versions may enforce.
46
47The body (everything after the second `---`) is plain markdown.
48There's no template engine; the model sees what you write.
49
50## Discovery
51
52zot looks in these directories, in priority order, and registers the
53first `SKILL.md` it finds for each unique name:
54
55| location | scope |
56|---|---|
57| `./.zot/skills/<name>/SKILL.md` | project (native) |
58| `$ZOT_HOME/skills/<name>/SKILL.md` | global (native) |
59| `./.claude/skills/<name>/SKILL.md` | project (claude-compat) |
60| `~/.claude/skills/<name>/SKILL.md` | global (claude-compat) |
61| `./.agents/skills/<name>/SKILL.md` | project (agent-compat) |
62| `~/.agents/skills/<name>/SKILL.md` | global (agent-compat) |
63
64The compat paths are deliberate: a `SKILL.md` written for an existing
65skill ecosystem works in zot unchanged. Drop your existing
66`.claude/skills/` or `.agents/skills/` directories into a project and
67zot will pick them up.
68
69When `XDG_STATE_HOME` is set on any platform, `$ZOT_HOME` defaults to
70`$XDG_STATE_HOME/zot`. Otherwise it defaults to `~/Library/Application Support/zot/`
71on macOS, `~/.local/state/zot` on Linux, or `%LOCALAPPDATA%\zot` on Windows.
72
73## Inspecting installed skills
74
75In zot, run `/skills`. A picker lists every discovered skill with its
76description and source path. Press enter on a row to view the full
77body inline. Press esc to go back.
78
79## Invoking skills
80
81For normal skills, the system prompt tells the model the skill names and
82short descriptions. When a request matches, the model calls the `skill` tool
83to load the full instructions on demand.
84
85To force a specific skill, invoke it as a slash command. 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.
86
87```text
88/skill:code-review
89/skill:code-review focus on security issues
90```
91
92zot expands the command into a user message containing the complete skill
93body, its directory for resolving relative references, and any text following
94the command as the request. This bypasses model-side skill selection.
95
96Set `disable-model-invocation: true` in a skill's frontmatter when it should
97only run after explicit user invocation. The skill remains visible in
98`/skills` and available through `/skill:<name>`, but its name and description
99are omitted from the model's startup context.
100
101## Writing good skills
102
103- **Be procedural.** Number steps. Tell the model what to do in what
104  order. Skills are habits, not knowledge dumps.
105- **Be precise about boundaries.** "Stop after step 4" is more
106  effective than "don't go too far".
107- **Trim aggressively.** A 200-line skill bloats every turn the
108  model uses it. Aim for 20–80 lines.
109- **One skill per behaviour.** Don't pack three workflows into one
110  SKILL.md; the model picks one path. Two separate skills work better.
111- **Lead with the trigger.** First paragraph should make it
112  obvious *when* to use the skill so the model self-selects correctly.
113
114## Examples
115
116See `examples/skills/` for two starter skills:
117
118- `code-review/` — self-review pass on a recent diff
119- `test-fix/` — diagnose + minimally fix a failing test
120
121## Comparison to other discovery layouts
122
123| ecosystem | path | zot reads it? |
124|---|---|---|
125| (native) | `.zot/skills/<name>/SKILL.md` | yes |
126| (claude-style) | `.claude/skills/<name>/SKILL.md` | yes |
127| (agent-style) | `.agents/skills/<name>/SKILL.md` | yes |
128
129Cross-pollination is intentional: pick whichever convention you're
130already using and zot tags along.