repo-docs
Skill8 starsChanged 3 months agoMITView on GitHub
Audit and upgrade repository documentation to production quality. Generates or rewrites README.md with status badges, at-a-glance metrics, architecture diagrams, document indexes, and proper structure. Validates and improves all docs/ files with cross-references, callouts, summaries, and Mermaid diagrams. Use when docs are stale, thin, or template placeholders. Triggers on "update docs", "fix readme", "improve documentation", "docs audit", "readme", "document this repo".
17 other projects use a version of this.
Adopted by
Most recently taken up by
- RMATI-11861/Claude-Skillstheir own version, first seen Nov 16, 2026
- teacupuk/tpstacktheir own version, first seen Nov 8, 2026
- korya/swd-skillstheir own version, first seen Nov 1, 2026
- certinia/debug-log-analyzer-mcptheir own version, first seen Oct 28, 2026
- ndthanhdev/aiotheir own version, first seen Oct 25, 2026
- bsene/skillstheir own version, first seen Oct 25, 2026
Other versions17 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 17
- YurunChen/repo-docs-skills★ 457same name
- certinia/debug-log-analyzer-mcp★ 36same name
- IndelibleVivi/repo-docs-curator★ 10same name
- phanghonghao/THU-Awesome-Skills★ 8same name
- bsene/skills★ 7same name
- OneDro1d/dark-factory★ 4same name
- rohanhong/tmpl.general-repo★ 3same name
- korya/swd-skills★ 2same name
- IsthisLee/agent-context-manager★ 1same name
- IsthisLee/agentic★ 1same name
7 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository9 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- cotSkill
- dependency-healthSkill
- hibernateSkill
- skill-builderSkill
- skill-validatorSkill
- task-cleanupSkill
- template-upgradeSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
16 rules. 0 are common, 15 are distinctive, and 1 is very specific to this project.
0
Common
Most of the 14 edited versions we read keep these.
15
Distinctive
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
After significant project changes that docs don't reflect
- Distinctive: line 15
Before sharing a repo with collaborators or going public
- Distinctive: line 16
When docs exist but lack structure, cross-references, or visual aids
- Distinctive: line 21
Every repo's documentation should meet these criteria:
- Distinctive: line 55
Read the current documentation and assess:
- Very specific: line 98
Use project context from CLAUDE.md, package.json, and the codebase to generate a complete README following the 14-point standard.
- Distinctive: line 123
Add blockquote summary if missing
- Distinctive: line 124
Add "Last Updated" date
- Distinctive: line 125
Add "Referenced by" / "See also" section with actual cross-references
- Distinctive: line 126
Add GitHub callouts where content warrants warnings, tips, or important notes
- Distinctive: line 128
Add Mermaid diagrams for flow/architecture content
- Distinctive: line 130
Remove or fill TODO placeholders
- Distinctive: line 134
If the repo has 5+ docs, generate a document index section in README.md:
- Distinctive: line 180
Never invent metrics: If you can't verify a number, don't badge it.
- Distinctive: line 184
Cross-reference actively: Every doc should link to related docs.
- Distinctive: line 185
Keep it maintainable: Don't add metrics that will go stale without automation.
“Common” is measured: kept by at least 6 in 10 of the 14 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Repo Documentation Skill
Bring any repository's documentation up to production quality. Modeled on the standard set by well-maintained repos with status dashboards, architecture diagrams, document indexes, and cross-referenced docs.
When to Use
- README is a template placeholder or outdated
- Docs are thin, missing, or inconsistent
- After significant project changes that docs don't reflect
- Before sharing a repo with collaborators or going public
- When docs exist but lack structure, cross-references, or visual aids
- Periodic docs hygiene pass
Quality Standard
Every repo's documentation should meet these criteria:
README.md Must Have
- Title and one-line description — what this project is
- Status badges — phase, build status, key metrics (use shields.io)
- At-a-Glance table — current state of key components with status indicators
- Blockquote summary — 1-2 sentence elevator pitch after badges
- Table of Contents — linked sections for anything over 100 lines
- Architecture section — Mermaid diagram showing system components
- Getting Started — prerequisites, setup, first run
- Commands — dev, build, test, lint (table format)
- Project Structure — file tree with annotations
- Key Decisions — table of important architectural choices with rationale
- Environment Variables — table with required/optional, description
- Deployment — where it runs, how to deploy
- Related Repos — if part of a multi-repo system
- Last Updated date — when the README was last verified
docs/ Files Must Have
- Blockquote summary at top — what this doc covers (within first 5 lines)
- Last Updated date
- Referenced by / See also — cross-references to related docs
- GitHub callouts — WARNING, IMPORTANT, NOTE, TIP, CAUTION where appropriate
- Tables for structured data — not prose paragraphs listing things
- Mermaid diagrams — for anything involving flow, architecture, or relationships
- No unfilled TODOs — replace or remove
<!-- TODO -->placeholders - Working links — all relative links resolve to real files
Procedure
Phase 1: Audit Current State
Read the current documentation and assess:
1. Read README.md — score against the 14-point checklist above
2. List all .md files in docs/ — score each against the 8-point checklist
3. Read CLAUDE.md — extract project context (name, stack, architecture, commands, deployment)
4. Read package.json or equivalent — extract name, description, scripts, dependencies
5. Check git log --oneline -10 — understand recent activity
6. Check for existing Mermaid diagrams, badges, tables
7. Run: find docs/ -name "*.md" -exec grep -L "^>" {} \; — files missing summaries
8. Run: grep -r "<!-- TODO" docs/ README.md — unfilled placeholdersReport findings as a checklist:
## Documentation Audit: {repo-name}
### README.md (X/14)
- [x] Title and description
- [ ] Status badges — MISSING
- [ ] At-a-Glance table — MISSING
- [x] Blockquote summary
...
### docs/ Files (Y total, Z passing)
- docs/EXAMPLE-DOC.md (6/8) — missing: cross-references, Mermaid diagram
- docs/architecture.md (3/8) — missing: summary, date, callouts, links, diagram
...
### Broken Links
- README.md:42 → docs/MISSING.md (not found)
### Stale Placeholders
- CLAUDE.md:15 — "<!-- TODO: Replace with project name -->"Phase 2: Generate / Rewrite
Based on the audit, generate or rewrite documentation:
README.md Generation
Use project context from CLAUDE.md, package.json, and the codebase to generate a complete README following the 14-point standard. Key principles:
- Extract real data — don't invent metrics. Count actual files, issues, tests.
- Use shields.io badges —
https://img.shields.io/badge/{label}-{value}-{color} - Mermaid architecture diagram — derive from CLAUDE.md architecture section or actual file structure
- Commands from package.json — use actual scripts, not guesses
- Project structure from filesystem — use actual directory listing
Badge color conventions:
- Green (
brightgreen): live, complete, passing - Blue (
blue): in progress, informational - Yellow (
yellow): pending, warning - Red (
red): blocked, failing
At-a-Glance table format:
| Metric | Value | Status |
|--------|-------|--------|
| **Phase** | Phase 1: Foundation |  |
| **Stack** | Next.js 14, TypeScript |  |docs/ File Improvement
For each doc file that scored below 6/8:
- Add blockquote summary if missing
- Add "Last Updated" date
- Add "Referenced by" / "See also" section with actual cross-references
- Add GitHub callouts where content warrants warnings, tips, or important notes
- Convert prose lists to tables where appropriate
- Add Mermaid diagrams for flow/architecture content
- Fix broken links
- Remove or fill TODO placeholders
Document Index
If the repo has 5+ docs, generate a document index section in README.md:
## Document Index
| Category | Document | Purpose |
|----------|----------|---------|
| Strategy | [strategy.md](docs/EXAMPLE-DOC.md) | Niche positioning, content model, monetization |
| Architecture | [architecture.md](docs/architecture.md) | System design and tech decisions |Phase 3: Validate
After writing, verify:
1. All relative links in README.md resolve to real files
2. All relative links in docs/*.md resolve to real files
3. README badge counts match filesystem reality
4. No <!-- TODO --> placeholders remain
5. Every docs/ file has a blockquote summary
6. Mermaid diagrams render (check syntax)Report final scores:
## Documentation Updated
### Before → After
- README.md: 5/14 → 14/14
- docs/EXAMPLE-DOC.md: 4/8 → 8/8
- docs/options.md: 3/8 → 7/8
### New Files Created
- (none, or list any)
### Validation
- [x] All links resolve
- [x] Badge counts match reality
- [x] No TODO placeholders
- [x] All docs have summariesImportant Notes
- Never invent metrics. If you can't verify a number, don't badge it.
- Preserve existing content. Improve structure and add missing elements — don't rewrite accurate prose.
- README is the storefront. It's the first thing anyone sees. Invest accordingly.
- CLAUDE.md is the source of truth for project context. README should be consistent with it but serve a different audience (humans browsing GitHub vs. AI agents working in the repo).
- Cross-reference actively. Every doc should link to related docs. Orphaned docs are invisible docs.
- Keep it maintainable. Don't add metrics that will go stale without automation. Static facts (stack, architecture) are fine. Dynamic counts need a process to update.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

