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

- **Type:** Skill
- **Install:** `agentstack add skill-zhoux77899-flawless-readme-writing`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [zhoux77899](https://agentstack.voostack.com/s/zhoux77899)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [zhoux77899](https://github.com/zhoux77899)
- **Source:** https://github.com/zhoux77899/flawless/tree/main/skills/readme-writing

## Install

```sh
agentstack add skill-zhoux77899-flawless-readme-writing
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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  --format json --output `.
   - For a human-readable starting point, run `python skills/readme-writing/scripts/analyze_repo.py  --format markdown-outline --output `.
   - 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  --analysis ` 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.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [zhoux77899](https://github.com/zhoux77899)
- **Source:** [zhoux77899/flawless](https://github.com/zhoux77899/flawless)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-zhoux77899-flawless-readme-writing
- Seller: https://agentstack.voostack.com/s/zhoux77899
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.