unxed/f4 / .agents/skills/aif-docs
aif-docs
VerifiedGenerate and maintain project documentation. Creates a lean README as a landing page with detailed docs pages split by topic in the configured docs directory. Use when user says "create docs", "write documentation", "update docs", "generate readme", or "document project".
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 22.7 KB |
| references/REVIEW-CHECKLISTS.md | markdown | 4.7 KB |
| templates/html-template.html | other | 2.6 KB |
references/REVIEW-CHECKLISTS.md
View on GitHub# Documentation Review Checklists
## Technical Checklist
Verify structure, links, and completeness:
- [ ] README.md is under 150 lines
- [ ] README has: title, tagline, quick start, example, documentation table, license
- [ ] Each docs/ file has prev/next navigation header following the Documentation table order
- [ ] First doc page has no "← Previous" link; last page has no "Next →" link
- [ ] Each docs/ file has "See Also" section at bottom with 2-3 related links
- [ ] No content was lost during split/reorganization
- [ ] All internal links work (no broken references, no dead anchors)
- [ ] Code examples use the project's actual commands/syntax
- [ ] Installation instructions are real and work (verified from package manager files)
- [ ] No duplicate content between README and docs/
- [ ] No scattered root-level `.md` files that should be in docs/
## Readability Checklist — "New User Eyes"
Read every page as if you are a developer who has **never seen this project before**. For each page, verify:
### First 10 seconds (above the fold)
- [ ] Can I understand what this project does within 10 seconds of reading README?
- [ ] Is the tagline clear and specific — not vague marketing ("next-gen solution")?
- [ ] Is there a real install command I can copy-paste right now?
### "Show, don't tell"
- [ ] Does README have a concrete usage example (not just "install and run")?
- [ ] Do code blocks show real commands with real output, not abstract placeholders?
- [ ] Are examples copy-pasteable — no `<placeholder>` that the user must replace?
### Scannability
- [ ] Can I find any specific topic in under 5 seconds by scanning headers?
- [ ] Are paragraphs short (max 3-4 lines)? Long paragraphs get skipped
- [ ] Are lists used instead of comma-separated inline enumerations?
- [ ] Are tables used for structured data instead of nested bullet lists?
### Jargon and assumptions
- [ ] Does the docs page explain acronyms on first use (or link to explanation)?
- [ ] Are there no assumptions about internal knowledge? ("as described in the RFC" — which RFC?)
- [ ] Would a junior developer understand each page without asking a colleague?
### Navigation and flow
- [ ] After reading README, is it clear where to go next?
- [ ] After finishing any docs/ page, do prev/next links and "See Also" guide me logically forward?
- [ ] Is the Documentation table in README ordered by the path a new user would follow? (getting started → workflow → details)
### Motivation
- [ ] Does the README answer "why should I care?" before "how does it work?"
- [ ] Is there a "wow moment" — a feature or example that makes me want to try it?
- [ ] Does the docs structure feel inviting, not overwhelming? (max 6-8 doc pages)
## Standards Compliance Check
Docs may have been generated by an older version of this skill. Compare existing docs against current Core Principles and templates. Common gaps to detect:
| Missing standard | How to detect | Auto-fix |
|------------------|---------------|----------|
| No prev/next navigation | Header has only `[← Back to README]` without `·` links to sibling pages | Add prev/next links following Documentation table order |
| No "See Also" section | File ends without `## See Also` | Add section with 2-3 related page links |
| Old "Back to README" format | Link path or text doesn't match current pattern | Update to current format |
| Missing Documentation table in README | README has no table linking to docs/ pages | Add table |
| README too long | README is over 150 lines despite docs/ existing | Propose moving excess content to docs/ |
**When gaps are found**, include them in the audit report alongside content issues (Step 2.2). Treat them as regular improvements — show the plan and get user approval before applying.
**Do NOT ask "was this generated by an older version?"** — just silently detect what's missing and fix it. The user doesn't need to know about skill versioning; they just see their docs getting better.
## Presenting the Review
After running both checklists, present a summary:
```
📋 Documentation Review
Technical:
✅ All links verified (14 internal links, 0 broken)
✅ README is 108 lines
✅ All pages have navigation
⚠️ docs/api.md has a placeholder example — needs real endpoint
Readability:
✅ README explains purpose in first 10 seconds
✅ All code examples are copy-pasteable
⚠️ docs/architecture.md has a 12-line paragraph — should be split
⚠️ "CQRS" used without explanation in docs/architecture.md
Fixes applied:
→ Split long paragraph in docs/architecture.md into 3 shorter ones
→ Added "(Command Query Responsibility Segregation)" after first mention of CQRS
→ Replaced placeholder in docs/api.md with real endpoint example
All checks passed ✅
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 197k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |