Write technical docs and READMEs with AI
Skills used in this guide (3)
引导用户通过结构化流程共同撰写文档。当用户想写文档、提案、技术规格、决策文档或类似结构化内容时使用。该流程帮助用户高效传递上下文、通过迭代打磨内容，并验证文档对读者是否有效。在用户提及写文档、创建提案、起草规格或相关文档任务时触发。
npx skills add anthropics/skills -g精通 REST 与 GraphQL API 设计原则，构建直观、可扩展、可维护、让开发者愉悦的 API。设计新 API、审查 API 规范、建立 API 设计标准时使用。
npx skills add wshobson/agents -g通过 Context7 MCP 取用库与框架的最新文档，而不是依赖模型训练数据。涉及环境搭建、API 参考、代码示例，或用户点名某个框架时触发。
npx skills add affaan-m/ECC -g
The scare with doc-writing is "AI sounds right but the API name is invented". The discipline: have AI write from real code / real docs, then match each paragraph to source. Don't let it invent APIs from memory.
Who this is for / not for
For:
- Need a README, design doc, or interface spec for a project
- Docs must align with real code and real interfaces
- Willing to have AI read the repo / docs first
Not for:
- External-facing formal SLA / compliance commitments (human must review)
- Code not stable yet (docs go stale fast)
- Zero-human-in-the-loop doc factory
Before you start
- Code / interfaces: AI should write from real content, not thin air.
- Who reads it: developer / user / ops decides depth.
- Template (if any): give the company doc template first.
Steps
1. Install the skill
doc-coauthoring is a doc co-writing skill. Copy its folder into your client's skills directory (same as any Agent Skill):
| Client | Directory |
|---|---|
| Claude Code | ~/.claude/skills/ |
| Codex | ~/.codex/skills/ |
| Cursor | ~/.cursor/skills/ |
| Trae | ~/.trae/skills/ |
| CodeBuddy | ~/.codebuddy/skills/ |
| Tongyi Lingma | ~/.lingma/skills/ |
2. Fetch real docs, then write
Before API docs, use documentation-lookup for latest official docs; before code explanation, have AI read the real definitions in the repo, not memory.
3. Give structure, not vague asks
Write a README for this CLI, fixed structure:
one-line pitch / install / 5 most-used commands (real args) / one end-to-end example / common errors.
Every command must be confirmed to exist in the repo; invented ones marked [unverified].4. Match each paragraph to source
After writing, have AI compare every endpoint / command / arg to source once; confirm before publish.
Pitfalls
| Pit | Symptom | Fix |
|---|---|---|
| Invented API | endpoint doesn't exist | Read real code/docs first |
| Example won't run | wrong command args | Example verified against real CLI |
| Wrong audience | Too tech or too shallow | State reader + depth up front |
| No structure | One blob, hard to read | Fix section structure first |
| Stale | Code changed, doc didn't | Update doc with the PR, don't pile up |
FAQ
Will AI invent APIs?
Yes, so the discipline is "write from real code + match paragraphs after". Invented bits marked [unverified].
Align API docs with official?
Use documentation-lookup for latest official docs before writing; don't rely on memory.
How long should README be?
Enough: pitch / install / common commands / one example / common errors. Long docs split by reader.
Keep docs from going stale?
Bind doc updates into PR review; code change means doc change, don't pile up.
Design docs too?
Yes, doc-coauthoring fits design docs and tutorials; give the structure clearly.
Related guides
Continue across these scenes:
相关源码
- anthropics/skills · doc-coauthoring source
- wshobson/agents · api-design-principles source
- Agent Skill open format spec
一句话结论
结论：让 AI 基于真实代码和文档写，写完后逐段对源码，别让它凭记忆编 API。