readme-writing

README Writing

Overview

Write README files from repository facts, not generic templates. Use the bundled scripts to create a stable analysis, then load only the reference files needed for the detected repository type.

Agent-facing content is optional. Decide whether to inline it, link to an agent doc, or omit it using references/audience-policy.md and the script's agent_content_strategy.

Reference Map

After running repository analysis, read references/index.md to map repo_type to the right guide and optional research file. Then load the minimum set needed:

• Agent policy: references/audience-policy.md
• Libraries and SDKs: references/repo-types/libraries-sdks.md
• CLI and developer tools: references/repo-types/cli-devtools.md
• Applications and UI: references/repo-types/apps-ui.md
• AI/ML, data, and benchmarks: references/repo-types/ai-ml-data.md
• Infrastructure and DevOps: references/repo-types/infra-devops.md
• Documentation, learning, and awesome lists: references/repo-types/docs-learning.md
• Plugins and agent skills: references/repo-types/plugins-agent-skills.md
• Security, privacy, and protocols: references/repo-types/security-protocols.md
• Fallback/general repositories: references/repo-types/general.md

Dependencies

• scripts/analyze_repo.py and scripts/validate_readme.py use only the Python standard library. Run them with Python 3.10+.

Workflow

1. Analyze the repository:
   • Run python skills/readme-writing/scripts/analyze_repo.py <repo> --format json --output <analysis.json>.
   • For a human-readable starting point, run python skills/readme-writing/scripts/analyze_repo.py <repo> --format markdown-outline --output <analysis-outline.md>.
   • Treat the output as a draftable fact sheet. Do not commit generated analysis files unless the user asks.
2. Load references:
   • Read references/index.md for the repo-type guide and research mapping.
   • Read references/audience-policy.md.
   • Read the repo-type reference matching repo_type; read a second type only for true hybrids such as CLI plus library or AI app plus dataset.
   • Read the mapped references/research/*.md only when examples or anti-patterns would improve the draft.
3. Draft and validate:
   • Build a natural README structure from the repo-type reference and the analysis output.
   • Use agent_content_strategy: omit means no agent section, link-to-agent-doc means link to existing AGENTS.md or CLAUDE.md, and inline means include concise agent-oriented usage or compatibility notes.
   • Run python skills/readme-writing/scripts/validate_readme.py <repo> --analysis <analysis.json> when you have a README draft saved.
   • Fix reported issues or explain any intentionally accepted warning.

Quality Rules

• Never force For Human or For Agents headings. Use them only when they fit the repo and user request.
• Prefer commands from command_details when inferred is false; label inferred commands explicitly, with the marker source matching command_details.source or command_details.evidence.
• Keep the first screen concrete: project name, value, audience, and the fastest useful action.
• Link to deeper docs instead of duplicating mature documentation.
• Do not copy researched README prose. Use references for patterns, not source text.
• Omit unsupported badges, benchmarks, install commands, guarantees, and roadmap claims.