# Readme Writing

> Creates or improves repository README files using repository analysis, type-specific README patterns, and optional agent-facing guidance. Use when the user asks to write, rewrite, audit, or upgrade README.md documentation for libraries, frameworks, CLIs, applications, AI/ML projects, datasets, DevOps tools, infrastructure projects, SDKs, templates, agent plugins, or documentation repositories.

- Skill: `zhoux77899/readme-writing` (Agent Skill, multi-file: 20 files)
- Install (CLI): `npx skillmds@latest add zhoux77899/readme-writing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zhoux77899/readme-writing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: zhoux77899 (https://skillmd.com/u/zhoux77899)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zhoux77899/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.