awesome-docs

Awesome Docs

This skill treats project documentation as an interface between human understanding and automated AI execution. The goal is not to produce verbose reports; the goal is to preserve project state in a form that a human can read quickly and a future AI agent can act on without guessing.

Core Contract

When the user asks to record project knowledge:

1. Resolve the documentation root.
2. Classify the content.
3. Create or update the right document.
4. Write in a concise, factual, readable style with a clear story line.
5. Re-read the full document after writing and run the post-write checklist for readability, consistent structure, complete required modules, evidence, conclusions, and next steps.
6. Unless the user opts out, run the separate plain-language pass after the content review, following references/post-write-polish.md.
7. If the request is about reusable commands, update 常用命令.txt with single-line commands and skip prose polishing for command lines.

Documentation Root

Use the user-specified documentation path if provided.

If the user does not specify a documentation path, use:

<project-root>/docs

Resolve <project-root> as the current repository root when possible. If no repository root is available, use the current working directory.

Required Directory Layout

Ensure the documentation root contains at least these directories:

docs/
├── plan/
├── todo/
├── experiment/
├── knowhow/
├── roadmap/
└── 常用命令.txt

Create missing directories or the command file when needed. Do not rename existing directories unless the user explicitly asks.

Classification Rules

Classify before writing. If a note fits several categories, choose the category that best matches how the content will be reused.

plan/

Use for future-oriented planning and execution design:

• implementation plans
• task breakdowns
• technical proposals
• migration plans
• risk analysis before execution
• design decisions that guide upcoming work