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