agentsclimarketplace

Readme writing

Skill zhoux77899/flawless/skills/readme-writing

Cross-agent plugin skills for better README, repository, and code quality across Claude Code and Codex.

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.

One thing 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.

What its author says it does

Copied from the file, not written here

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.md

3.8 KB, 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.

Keep looking

Skills are one crate of 328,083. 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.