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 |
QUALITY_RULES.md
View on GitHub# Repo-Docs Quality Rules
## Evidence Standard
Use one status family across the package (README, walkthroughs, modules, references, glossary, change-log, Seed memory):
- **Confirmed / 已确认:** current repo evidence (code, tests, config, data, command output, artifacts) directly shows it.
- **Inferred / 推断:** reasonable inference from inspected evidence, not directly asserted or tested.
- **Planned / 计划中:** accepted or decided future work or design that is not implemented yet.
- **Unknown / 未确认:** plausible, disputed, or awaiting verification.
Confidence and source are orthogonal. When support comes from outside the repo (external papers, docs, design notes), keep the confidence label and add an inline source note such as `Inferred (prior work: ...)`. This replaces a separate "prior work" status, which conflated source with confidence.
Use source links when possible. Include exact line links when available; otherwise link to the file path and say what to search for. Put the page-level default at the end of the page (`Evidence status: Confirmed unless noted.` / `证据状态:除特别标注外,本页基于当前源码已确认。`); use local labels when confidence changes or when a specific statement needs extra support.
Code and data statements require extra discipline:
- Treat current source, tests, config, data, command output, and artifacts as the truth for implemented behavior.
- Treat README files, older docs, memory, papers, and user descriptions as context until runtime evidence confirms them.
- Do not present an uninspected file, field, command, artifact, metric, tool parameter, or test as proof.
- Do not invent sample rows, task ids, function names, output files, metric denominators, or schema fields. Use real evidence or label the item as a neutral example.
- Do not upgrade `Planned` or `Inferred` content to `Confirmed` because it sounds plausible.
- If code and data disagree with old docs or memory, trust current code/data and put a caveat beside the affected topic.
- If verification is cheap, run or inspect it before writing the statement. If verification is not run, say what command or check would confirm it.
- If writing exposes insufficient evidence for the mental model, go back to source discovery: inspect the owning source path, tests, config, schemas, data, commands, or artifacts before polishing the claim.
- Keep evidence labels quiet when one status dominates a page; label locally only when mixing statuses or when a statement needs extra support. A page can contain confirmed current behavior, inferred explanation, planned next work, and unknown caveats, but the reader must be able to tell which is which without reading an evidence table.
- Use skill examples as style references only. Do not copy fictional paths, fields, commands, task ids, or outputs into real docs.
## Quality Bar
The docs are good when a newcomer can answer these in about 15 minutes using the guide alone:
1. What is the repo trying to accomplish?
2. What is the shortest path to understand one real run?
3. How do I reproduce or run the main experiment/workflow?
4. Which concepts remain fuzzy after the walkthrough, and which ones deserve separate module pages?
5. What data contracts or schemas does the walkthrough depend on—and where are exact field names?
6. After reading a concept page, what command or test would confirm I understood the mechanism?
7. For research repos: what is the research question, method, metric, data contract, and baseline/ablation story?
8. What caveats matter for the topic I am reading right now?
9. For any important rule, contract, transformation, or lifecycle step, what is one concrete input/output, before/after, allowed/denied, or normal/boundary case that works, and what edge case fails or stays out of scope?
10. Can a newcomer trace one real workflow from observable entry to output/artifact without opening source code first?
11. For case studies, generated examples, source-heavy docs, or handoff-sensitive work, does `references/quality-review.md` record reader-simulation answers, the understandability review, and residual risk?
12. Does `references/source-evidence.md` record at least two traversal passes and make adjacent out-of-scope paths visible?
13. Does the guide survive a Socratic reader review: why this phase exists, what would break without it, what evidence could falsify the explanation, where assumptions stop, and what a careful newcomer would ask next?
14. After learning the main behavior, can a newcomer use `code-map.md` to say what every in-scope first-party source directory owns, which important file or symbol to inspect first, and which test or check verifies a likely change?
15. Does the code map explicitly distinguish covered source areas from generated, vendored, fixture-only, unrelated, excluded, or deferred areas instead of implying whole-repo coverage?
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 |