Create a new documentation file in .chalk/docs/.
Workflow
- Parse the request — Identify the target vertical and topic from
$ARGUMENTS.
- Check existing docs — Read filenames in the target directory to find the highest numbered file. The next doc number is
highest + 1.
- Draft the doc — Write substantive content, not stubs. Use the structure and tone guidelines below.
- Write the file — Save to
.chalk/docs/<vertical>/<number>_<slug>.md.
- Confirm — Tell the user the doc was created with its path and a brief summary.
Verticals
| Vertical |
Directory |
Use For |
| Product |
product/ |
Vision, strategy, user research, pricing, competitive analysis |
| AI |
ai/ |
Agent context, codebase orientation, prompt patterns, gotchas |
| Engineering |
engineering/ |
Architecture, conventions, APIs, runbooks, data flows |
| Root |
.chalk/docs/ |
Docs that don't fit a vertical |
If the user specifies a vertical ("engineering doc about..."), use it. If ambiguous, infer from content: technical architecture -> engineering, product strategy -> product, agent context -> ai.
Filename Convention
<number>_<snake_case_slug>.md
- Number is sequential within the vertical directory (profile docs are always
0_)
- Slug is a short snake_case summary
Doc File Structure
# <Doc Title>
Last updated: <YYYY-MM-DD> (<brief change note>)
## <First Section>
Content...
## <Next Section>
Content...
- No YAML frontmatter (docs are plain markdown)
- First
# Heading is the title
- "Last updated" line immediately after the title
- Use
## Heading for sections
- All GFM features supported: tables, checkboxes, strikethrough, code blocks, Mermaid diagrams
Content Guidelines
| Vertical |
Tone |
Focus |
product/ |
Business-facing, concise |
What and why: user problems, strategy, metrics |
ai/ |
Agent-facing, reference-style |
Where things are, how they work, gotchas |
engineering/ |
Technical, comprehensive |
Architecture, conventions, APIs, data flows |
1---2name: create-doc-23description: Create a new doc file in .chalk/docs/ when the user asks to create, write, or add documentation4---5
6Create a new documentation file in `.chalk/docs/`.
7
8## Workflow
9
101. **Parse the request** — Identify the target vertical and topic from `$ARGUMENTS`.
112. **Check existing docs** — Read filenames in the target directory to find the highest numbered file. The next doc number is `highest + 1`.
123. **Draft the doc** — Write substantive content, not stubs. Use the structure and tone guidelines below.
134. **Write the file** — Save to `.chalk/docs/<vertical>/<number>_<slug>.md`.
145. **Confirm** — Tell the user the doc was created with its path and a brief summary.
15
16## Verticals
17
18| Vertical | Directory | Use For |
19|----------|-----------|---------|
20| Product | `product/` | Vision, strategy, user research, pricing, competitive analysis |
21| AI | `ai/` | Agent context, codebase orientation, prompt patterns, gotchas |
22| Engineering | `engineering/` | Architecture, conventions, APIs, runbooks, data flows |
23| Root | `.chalk/docs/` | Docs that don't fit a vertical |
24
25If the user specifies a vertical ("engineering doc about..."), use it. If ambiguous, infer from content: technical architecture -> engineering, product strategy -> product, agent context -> ai.
26
27## Filename Convention
28
29```
30<number>_<snake_case_slug>.md
31```
32
33- Number is sequential within the vertical directory (profile docs are always `0_`)
34- Slug is a short snake_case summary
35
36## Doc File Structure
37
38```markdown
39# <Doc Title>
40
41Last updated: <YYYY-MM-DD> (<brief change note>)
42
43## <First Section>
44
45Content...
46
47## <Next Section>
48
49Content...
50```
51
52- No YAML frontmatter (docs are plain markdown)
53- First `# Heading` is the title
54- "Last updated" line immediately after the title
55- Use `## Heading` for sections
56- All GFM features supported: tables, checkboxes, strikethrough, code blocks, Mermaid diagrams
57
58## Content Guidelines
59
60| Vertical | Tone | Focus |
61|----------|------|-------|
62| `product/` | Business-facing, concise | What and why: user problems, strategy, metrics |
63| `ai/` | Agent-facing, reference-style | Where things are, how they work, gotchas |
64| `engineering/` | Technical, comprehensive | Architecture, conventions, APIs, data flows |
majiayu000