agentsclimarketplace
Sign in

Readme writing

Skill zhoux77899/flawless/skills/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.From its SKILL.md

Install
npx -y skills add zhoux77899/flawless --skill readme-writing

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

  • 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
  • runs commandsInstructs the agent to run 3 commands, including `python skills/readme-writing/scripts/analyze_repo.py <repo> --format json --output <analysis.json>` and 2 more.

SKILL.md

3.8 KB, 759 tokens by cl100k_base, as published. Nobody here has run it

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.

What ships with it: 19 files

51.6 KB alongside SKILL.md, 2 of them executable

agents/

references/

scripts/

Gives 0 of the 12 instructions most readme changelog skills give in 759 tokens

Counted across 446 of the 460 authors here whose files we hold, read 2026-09-06

  • Follow Keep a Changelog formatin 24 of 446
  • Collect commits since the last git tagin 15 of 446, across 13 files
  • Omit empty sectionsin 14 of 446
  • Put breaking changes first with migration stepsin 14 of 446
  • Include migration guidance for breaking changesin 11 of 446, across 10 files
  • Categorize commits by conventional commit prefixin 11 of 446
  • Mark breaking changes prominentlyin 10 of 446
  • Prepend the new entry to CHANGELOG.mdin 9 of 446
  • Highlight breaking changes with migration notesin 8 of 446, across 7 files
  • Classify changes into Keep a Changelog categoriesin 8 of 446, across 7 files
  • Group related commits into single entriesin 8 of 446
  • Write the changelog from commitsin 8 of 446

Said here and by no other author read

  • Analyze the repository before drafting the README
  • Read the reference index to map repository type
  • Read the agent audience policy before drafting
  • Read research references only when they improve the draft
  • Draft the README from analysis facts and the type guide
  • Apply the given agent content strategy

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.

Keep looking

Skills are one crate of 325,949. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.