# Docs

> 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](file-path) reference pointers instead of inline code blocks.

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

---


# Docs

## Input

```text
$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/`.