---

name: docs version: 0.0.3 category: productivity description: "Write and maintain project documentation under docs/generated/ — /docs write creates or updates a doc on a topic, /docs check reports stale content, broken code references, and orphan files. Use when the user wants to capture the design intent behind a feature, record an architectural decision, or verify existing docs still match the code. Docs use symbol reference pointers instead of inline code blocks." argument-hint: "<write|check> [topic] [code-path]"

Docs

Input

$ARGUMENTS

Instructions

Document Root

Documents managed by this skill are stored under docs/generated/. They are organized by category subdirectories: docs/generated/<category>/<slug>.md

Documents outside docs/generated/ are considered manually written and must never be modified.

Tool Usage Rules

Always use the tools below for document search and management. Do not open files one by one — search with patterns.

Purpose	Tool	Usage
Find document files	Glob	docs/generated/**/*.md pattern to get full document list
Search frontmatter	Grep	Filter by title:, category: patterns
Read existing docs	Read	Read frontmatter + body (only necessary documents)
Verify code references	Glob	Check if file paths in code_refs exist
Create documents	Write	Create new document files
Update documents	Edit	Update specific parts of existing documents
Scan INDEX	Read	Read docs/generated/INDEX.md for category structure and document list

Subcommand Routing

The first word of $ARGUMENTS determines the subcommand.

First word	Action
write	Read and execute references/write-procedure.md
check	Read and execute references/check-procedure.md
(none / help)	Print usage below and stop

When run without a subcommand:

## docs

Writes and maintains project documentation under `docs/generated/`.

### Commands

| Command | Description |
|---------|-------------|
| write <topic> [code-path] | Write or update a document on the topic |
| check | Check all document status (stale, broken refs, orphan docs) |

### Features

- Uses `[symbol](file-path)` reference pointers instead of code blocks
- Organized by category folders under `docs/generated/`
- INDEX.md based document indexing

Argument Parsing

Parse the remaining arguments after removing the subcommand keyword (write / check).

write arguments:

• First argument: topic (required) — title/topic of the document
• Second argument: code-path (optional) — path to related code (file or directory)

Examples:

• /docs write "auth flow design" → topic only
• /docs write "auth flow" src/auth/ → topic + code-path

check arguments: None.

Document Writing Principles

1. Minimize code blocks: Do not include code snippets directly in documents. Instead, use markdown links in the form [symbol](project-root-relative/file-path) as references.
2. Focus on design intent: Record "why it was done this way" rather than "what was done".
3. Protect manual documents: Never modify documents outside docs/generated/.