xonecas.io
64875
Mc

mini-coder / commit a132bb0

docs: add docs/custom-commands.md tutorial

Sean2026-02-25 a132bb0fad04d45823c195263d22ec855b4df739 parent 65ecd0f

1 file changed

docs/custom-commands.md+133−0
@@ -0,0 +1,133 @@
1+# Custom Commands
2+
3+Custom commands let you define reusable prompts that run as `/command` in the mini-coder REPL.
4+
5+## Where to put them
6+
7+| Location | Scope |
8+|---|---|
9+| `.agents/commands/*.md` | Current repo only |
10+| `~/.agents/commands/*.md` | All projects (global) |
11+
12+Local commands override global ones with the same name.
13+
14+## Create a command
15+
16+Create a markdown file. The filename becomes the command name.
17+
18+`.agents/commands/standup.md`:
19+
20+```md
21+---
22+description: Summarise what changed since yesterday
23+model: zen/claude-3-5-haiku
24+---
25+
26+Run `!`git log --oneline --since=yesterday`` and summarise the changes
27+as a short standup update. Group by theme, skip merge commits.
28+```
29+
30+Then in the REPL:
31+
32+```
33+/standup
34+```
35+
36+## Frontmatter fields
37+
38+| Field | Required | Description |
39+|---|---|---|
40+| `description` | No | Shown in `/help`. Defaults to the command name. |
41+| `model` | No | Override the active model for this command. |
42+
43+## Arguments
44+
45+Use `$ARGUMENTS` for the full argument string, or `$1`, `$2`, … `$9` for individual tokens.
46+
47+`.agents/commands/search.md`:
48+
49+```md
50+---
51+description: Search the codebase for a topic
52+model: zen/claude-3-5-haiku
53+---
54+
55+Search the codebase for: $ARGUMENTS
56+
57+Use glob, grep, and read tools to explore thoroughly. Report all
58+relevant files, key code snippets with line numbers, and a short summary.
59+Be exhaustive but concise. No edits — read only.
60+```
61+
62+```
63+/search session management
64+/search error handling in providers
65+```
66+
67+Positional tokens:
68+
69+```md
70+---
71+description: Create a new component
72+---
73+
74+Create a React component named $1 in the $2 directory.
75+Use TypeScript, include prop types and a default export.
76+```
77+
78+```
79+/component Button src/ui
80+```
81+
82+## Shell interpolation
83+
84+Use `` !`cmd` `` to inject shell output into the prompt at expansion time.
85+Commands time out after 10 seconds.
86+
87+```md
88+---
89+description: Review failing tests
90+---
91+
92+The following tests are currently failing:
93+
94+!`bun test 2>&1 | grep "fail\|✗" | head -20`
95+
96+Investigate the failures and suggest fixes. Read the relevant source
97+files before drawing conclusions.
98+```
99+
100+```
101+/fix-tests
102+```
103+
104+## Model override
105+
106+Specify a model in frontmatter to use a faster or cheaper model for
107+lightweight tasks regardless of what the session is currently set to.
108+
109+```md
110+---
111+description: Quick grep for a symbol
112+model: zen/claude-3-5-haiku
113+---
114+
115+Find all usages of $ARGUMENTS across the codebase using grep and glob.
116+List each occurrence with file path and line number. No explanations needed.
117+```
118+
119+Large models for deep analysis, small models for search and lookup.
120+
121+## Precedence
122+
123+Custom commands shadow built-ins. If you create `.agents/commands/review.md`
124+it will replace the built-in `/review` for that project.
125+
126+## Listing commands
127+
128+```
129+/help
130+```
131+
132+Custom commands are listed at the bottom under **custom commands**, tagged
133+with `(local)` or `(global)`.