xonecas.io
64875
Mc

mini-coder / commit 9560714

docs: add custom-agents.md covering agents and skills

Sean2026-02-25 9560714935494e7e2c719e461fac6b8595cd674b parent d66284f

1 file changed

docs/custom-agents.md+139−0
@@ -0,0 +1,139 @@
1+# Custom Agents and Skills
2+
3+Two ways to extend mini-coder with reusable AI behaviour via `@` references.
4+
5+---
6+
7+## Agents
8+
9+An agent is a subagent with a custom system prompt and optional model override.
10+Use `@agent-name` anywhere in your prompt to route the message through it.
11+
12+### Where to put them
13+
14+| Location | Scope |
15+|---|---|
16+| `.agents/agents/*.md` | Current repo only |
17+| `~/.agents/agents/*.md` | All projects (global) |
18+
19+Local agents override global ones with the same name.
20+
21+### Create an agent
22+
23+The filename becomes the agent name.
24+
25+`~/.agents/agents/reviewer.md`:
26+
27+```md
28+---
29+description: Strict code reviewer focused on bugs and structure
30+model: zen/claude-sonnet-4-6
31+---
32+
33+You are a senior engineer doing a code review. Be direct and specific.
34+Cite file and line number for every finding. Flag bugs first, then
35+structure issues, then style — only if they violate project conventions.
36+No flattery. End with a one-line verdict.
37+```
38+
39+Then in the REPL:
40+
41+```
42+@reviewer review the auth module for race conditions
43+```
44+
45+The rest of the message (everything except the `@reviewer` token) becomes
46+the prompt. The agent runs in its own context window and returns its output
47+into the conversation.
48+
49+### Combining with skills
50+
51+Skills and files are resolved before the agent fires, so you can mix them:
52+
53+```
54+@reviewer @src/auth/session.ts check this file for issues
55+```
56+
57+The file content is injected into the prompt, then the whole thing is sent
58+to the reviewer agent.
59+
60+### Frontmatter fields
61+
62+| Field | Required | Description |
63+|---|---|---|
64+| `description` | No | Shown in `/help`. Defaults to filename. |
65+| `model` | No | Override the active model for this agent. |
66+
67+The markdown body (after frontmatter) is the agent's system prompt.
68+
69+---
70+
71+## Skills
72+
73+A skill is a reusable instruction file injected inline into your prompt.
74+Use `@skill-name` to load it — the LLM sees the skill content as context
75+before your message.
76+
77+### Where to put them
78+
79+Each skill is a folder containing a `SKILL.md`:
80+
81+| Location | Scope |
82+|---|---|
83+| `.agents/skills/<name>/SKILL.md` | Current repo only |
84+| `~/.agents/skills/<name>/SKILL.md` | All projects (global) |
85+
86+Local skills override global ones with the same name.
87+
88+### Create a skill
89+
90+`.agents/skills/conventional-commits/SKILL.md`:
91+
92+```md
93+---
94+name: conventional-commits
95+description: Conventional commit message format rules
96+---
97+
98+# Conventional Commits
99+
100+All commit messages must follow this format:
101+
102+ <type>(<scope>): <short summary>
103+
104+Types: feat, fix, docs, refactor, test, chore
105+- Summary is lowercase, no period at the end
106+- Breaking changes: add `!` after type, e.g. `feat!:`
107+- Body is optional, wrapped at 72 chars
108+```
109+
110+Then in the REPL:
111+
112+```
113+@conventional-commits write a commit message for my staged changes
114+```
115+
116+The skill content is wrapped in `<skill name="…">…</skill>` tags and
117+prepended to your message before it's sent to the LLM.
118+
119+### Frontmatter fields
120+
121+| Field | Required | Description |
122+|---|---|---|
123+| `name` | No | Skill name for `@` reference. Defaults to folder name. |
124+| `description` | No | Shown in `/help`. Defaults to name. |
125+
126+---
127+
128+## Tab completion
129+
130+Type `@` and press `Tab` to autocomplete. Skills and agents are listed
131+first, then local files — up to 10 results total.
132+
133+## Listing available agents and skills
134+
135+```
136+/help
137+```
138+
139+Agents are shown in magenta, skills in yellow, tagged `(local)` or `(global)`.