# Create Doc

> Create a new doc file in .chalk/docs/ when the user asks to create, write, or add documentation

- Skill: `majiayu000/create-doc-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/create-doc-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/create-doc-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/create-doc-2

---


Create a new documentation file in `.chalk/docs/`.

## Workflow

1. **Parse the request** — Identify the target vertical and topic from `$ARGUMENTS`.
2. **Check existing docs** — Read filenames in the target directory to find the highest numbered file. The next doc number is `highest + 1`.
3. **Draft the doc** — Write substantive content, not stubs. Use the structure and tone guidelines below.
4. **Write the file** — Save to `.chalk/docs/<vertical>/<number>_<slug>.md`.
5. **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

```markdown
# <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 |