菜单
Write and improve README files that orient readers and drive adoption. Use when creating, rewriting, or auditing a project README. Trigger terms: readme, README, project description, quick start, getting started, project documentation entry point.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Write Architecture Decision Records when making significant technical choices. Use when selecting tools, patterns, frameworks, or making structural changes that future developers need to understand.
Write AGENTS.md files that serve as operating contracts for AI agents. Use when creating or updating AGENTS.md for a project. Trigger terms: AGENTS.md, agent instructions, agent contract, agent configuration, coding agent setup.
Quality rules for changelog entries. Use when validating, writing, or reviewing changelog content to ensure user-facing value communication.
Task completion sequence including verification, git, signaling, and handoff. Use when finishing a task or reporting status.
Architecture diagrams for documentation. Covers ASCII, Mermaid, C4, and D2. Applies C4 methodology by default. Trigger terms: diagram, flowchart, architecture diagram, sequence diagram, C4, mermaid, ascii diagram.
Classify documentation by audience and content type. Use when planning, auditing, or placing project documentation.
| name | readme-writing |
| description | Write and improve README files that orient readers and drive adoption. Use when creating, rewriting, or auditing a project README. Trigger terms: readme, README, project description, quick start, getting started, project documentation entry point. |
The README is the front door. Most people decide whether to use a project based on the README alone.
The first line (project name + one-sentence description) must answer "what is this?" completely. Test: cover the name, show the rest to someone unfamiliar — can they say what it does?
Write what the project does, not how it does it.
Get a reader to a working state in under five minutes. Show real commands, expected output, and minimal required setup. No theory, no background.
# Good: real commands, expected output, honest about requirements
npm install -g myproject
export MYPROJECT_API_KEY=your_key_here
myproject convert input.md output.pdf
# Converted 3 pages → output.pdf
If quick start requires a config file or API key, show that. A quick start that omits a required step manufactures frustration.
Readers evaluate top-down and stop when they have enough. Put decision-relevant content first:
Not every project needs every section. Fit structure to the project, but don't invent a new order.
Every claim has a runnable example. "Supports many output formats" teaches nothing. A code block demonstrating three formats teaches everything.
| Content | Where It Goes |
|---|---|
| Agent instructions | AGENTS.md |
| Detailed API reference | Generated docs (Rustdoc, JSDoc, Sphinx) |
| Architecture decisions | docs/adrs/ |
| Research notes | docs/research/ |
| Tutorials | docs/tutorials/ |
| Operational runbooks | docs/ or ops wiki |