YurunChen/repo-docs-skills / skills/repo-docs
repo-docs
VerifiedBuild and maintain a Markdown guide that helps humans understand a repository through real behavior, concepts, and evidence. Use when a user asks to understand a repo, generate or update repo-docs, answer repo-architecture/onboarding questions, seed docs for a new project, sync docs after code changes, or delete generated repo docs.
| File | Kind | Size |
|---|---|---|
| EXAMPLES.md | markdown | 33.1 KB |
| PAGE_RULES.md | markdown | 44.2 KB |
| QUALITY_RULES.md | markdown | 4.8 KB |
| REFERENCE.md | markdown | 1.0 KB |
| ROOT_AGENT_RULES.md | markdown | 4.2 KB |
| SCOPE_MODES.md | markdown | 4.9 KB |
| SKILL.md | skill md | 12.4 KB |
| SYNC_RULES.md | markdown | 20.5 KB |
| WRITING.md | markdown | 15.0 KB |
| evals/README.md | markdown | 3.9 KB |
| evals/fixtures/README.md | markdown | 294 B |
| evals/run_eval.py | script | 20.3 KB |
| scripts/validate_repo_docs.pyexecutable | script | 46.6 KB |
| validate_repo_docs.py | script | 482 B |
evals/README.md
View on GitHub# Repo-Docs Skill Evals
These evals are lightweight regression checks for the `repo-docs` skill rules. They do not score an LLM. They materialize small repo-docs fixtures in a temporary directory, run the bundled validator, and assert the rule text that controls trigger precision.
Run from the repository root:
```bash
python skills/repo-docs/evals/run_eval.py
```
## Cases
| Case | Expected artifacts | Automated assertions | Human check |
| --- | --- | --- | --- |
| `standard-build` | README, walkthrough, code map, module, source evidence, glossary, change log | Validator exits with 0 errors; no extra `references/` pages | The guide teaches behavior first, then maps in-scope source responsibilities. |
| `standard-code-map-required` | Standard fixture with `code-map.md` removed | Validator fails with a missing required file error | Standard packages always preserve the code-navigation layer. |
| `code-map-missing-directory-section` | Code map lists a directory without its detail section | Validator warns with the uncovered directory path | Every summarized source area gets a navigable responsibility section or split-page link. |
| `code-map-missing-code-table` | Directory section lacks the important-code table | Validator warns with the affected directory path | Folder purpose is followed by concrete code and symbol locations. |
| `code-map-missing-coverage-section` | Code map omits its closing coverage section | Validator warns instead of accepting incidental coverage words elsewhere | Scope and exclusions stay explicit. |
| `walkthrough-missing-code-map-route` | Standard walkthrough does not link onward to the code map | Validator fails with a routing error | The published reading order remains behavior first, code location second. |
| `lite-build` | README, walkthrough, source evidence, change log | Validator exits with 0 errors under `--lite`; no module directory required | Lite shape does not invent concept pages. |
| `seed-build` | README, change log, glossary | Validator exits with 0 errors under `--seed` | Planned facts are not described as implemented. |
| `sync-decision-rules` | Skill rule files | `none`, `answer-only`, `foreground patch`, and `background sync` appear in `SKILL.md`, `SYNC_RULES.md`, and root-agent rules | Ordinary repo questions have an answer-only path. |
| `answer-only-docs` | Skill rule files | Sync rules explicitly say ordinary repo questions are not automatic doc edits | The trigger policy will not surprise users with unnecessary patches. |
| `stable-module-gap` | Skill rule files | Stable understanding gaps route to add/refine/merge modules | Knowledge has one durable reader home. |
| `display-shape-router` | Skill rule files | Entry and page rules preserve prose/structure routing and the wall-of-text guard | Reader understanding drives tables, lists, timelines, code blocks, and prose. |
| `strict-references` | A fixture with an extra reference page | Validator fails with a fixed references-scope error | Contract/schema/catalogue content belongs in modules. |
| `code-heavy-opening` | A fixture with a code-name-heavy opening | Validator returns 0 errors and emits the opening-density warning | The warning is useful and low noise. |
| `module-missing-case` | A mechanism module with payload/state language but no representative case | Validator returns 0 errors and emits the module-case warning | Mechanism pages should show the smallest useful case, not only categories. |
| `zh-overlay` | Chinese Lite package | Validator exits with 0 errors under `--lite`; Chinese routes preserve English source identifiers | Chinese carries the mental model while source terms stay exact. |
## Notes
- Fixtures are encoded in `run_eval.py` and materialized under a temporary directory so they cannot dirty the repository.
- Public case studies remain useful examples, but these evals are the fast regression suite for skill behavior.
- Add a new eval whenever a rule change would otherwise rely on reviewer memory.
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: 472k | 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: 198k | 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: 198k | 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: 198k | Updated | Claude CodeCodex | Verified | Install |