Skip to content

Zeyad-101/Readme-writer-skill

readme-writer

Verified

Writes a production-quality README.md for any code repository, grounded entirely in the repo's real contents. Give it a repo link to clone, or paste/upload the repo's files, and it inventories manifests, CI config, build files, and code, works out what kind of project it actually is, and drafts a README using only the sections that project needs — no placeholder text, no invented badges or benchmarks, no boilerplate sections that don't apply. Works the same way regardless of language, stack, or project category. Use whenever asked to write, generate, or improve a README for a repo, or for a specific named project, in whatever wording that request takes.

FileKindSize
SKILL.mdskill md5.3 KB
assets/master-template.mdmarkdown21.8 KB
references/section-selection.mdmarkdown6.0 KB
references/writing-style.mdmarkdown2.8 KB
---
name: readme-writer
description: Writes a production-quality README.md for any code repository, grounded entirely in the repo's real contents. Give it a repo link to clone, or paste/upload the repo's files, and it inventories manifests, CI config, build files, and code, works out what kind of project it actually is, and drafts a README using only the sections that project needs — no placeholder text, no invented badges or benchmarks, no boilerplate sections that don't apply. Works the same way regardless of language, stack, or project category. Use whenever asked to write, generate, or improve a README for a repo, or for a specific named project, in whatever wording that request takes.
---

# README Writer

Produces one README.md, grounded in what the repository actually contains.
Two failure modes to avoid equally: a generic template with brackets left
in, and a confident README that states things the repo doesn't back up.

## Workflow

### 1. Get the repo

Auto-detect how it's being handed to you:

- **GitHub URL in the request** — shallow clone it:
  `git clone --depth 1 <url> /home/claude/repo-work/<name>`
  This works because `github.com` and `codeload.github.com` are reachable.
  Other hosts (GitLab, Bitbucket, private GitHub) generally aren't — if the
  clone fails, say so plainly and ask for a zip upload or pasted files
  instead of retrying silently.
- **Uploaded zip/files** (`/mnt/user-data/uploads/`) — unzip to a working
  directory.
- **Pasted file contents / directory listing in chat** — work from that text
  directly; ask for the specific files you need if the paste is too partial
  to inventory (e.g. only a tree with no manifest contents).

### 2. Inventory

Before drafting anything, build a picture of what's real:

- Directory structure (`find . -not -path '*/.git/*' | sort`, or similar)
- Manifests: `package.json`, `requirements.txt`/`pyproject.toml`,
  `Cargo.toml`, `go.mod`, `CMakeLists.txt`, `platformio.ini`, `*.pro`
- CI: `.github/workflows/*`, `.gitlab-ci.yml`
- Containers/infra: `Dockerfile`, `docker-compose.yml`, `k8s/`, `helm/`
- `LICENSE`, existing `README*`, `CHANGELOG.md`, `.env.example`
- Entry points and any obviously central source files — open enough of
  them to know what the thing actually does, not just what it's named
- Anything else specific to the stack you find — hardware/pin/protocol
  references, notebook files, workflow-export JSON schemas, and so on

Read this list of evidence like a checklist you'll need in step 5 — every
line you write later has to trace back to something found here.

### 3. Work out what kind of project it is

Use `references/section-selection.md`'s detection signals and keep/drop
guidance. The categories it lists (embedded, desktop app, backend service,
CLI/library, automation export, data/ML) are common patterns, not an
exhaustive or restrictive list — a repo can span more than one, or match
none cleanly. Either way, the same rule underneath applies regardless of
category: a section earns its place only if the inventory actually backs
it up. If a repo doesn't fit any listed pattern, apply that rule directly
from what step 2 found instead of forcing it into one of the examples.

### 4. Choose sections

Open `assets/master-template.md` — it's the full menu of sections this
template family supports (badges, About, Requirements, Quickstart, Usage,
Architecture, Config Matrix, Deployment, Observability, DB Migration
Policy, Rollback, Testing, Troubleshooting, Versioning, Contributing,
License, etc.). Per `references/section-selection.md`'s mapping for this
project's type, keep only the sections with real evidence behind them from
step 2. State your section choice to yourself before drafting — if you
can't name the evidence for a section, it's out.

### 5. Draft

Follow the master template's heading style and ordering for the sections
you kept. Fill every value from the inventory — real commands, real env
var names, real version numbers, real board/sensor names, real function
signatures. Where the template implies something you have no evidence for
(a badge, a benchmark, a support policy), omit that line or row rather than
guessing or leaving a placeholder.

If an existing README is present, read it for facts worth keeping (real
gotchas, real usage notes) — don't reuse its wording, and don't carry over
a claim you can't verify from the current repo state.

### 6. Style pass

Apply `references/writing-style.md`: no marketing filler, no unearned
superlatives, badges only with evidence, sentences that use the project's
own names and numbers. Read the draft once specifically hunting for lines
that could apply to any repo — cut or make them specific.

### 7. Save and hand it over

Write the file to `/mnt/user-data/outputs/README.md` and present it. This
skill only produces the file — it doesn't commit anything back into the
repo. If something notable from the old README couldn't be verified and
was dropped, say so in one line so the user can decide whether to restore
it by hand.

## Reference files

- `references/section-selection.md` — project-type detection signals and
  which sections to keep/drop for each
- `references/writing-style.md` — the anti-filler, anti-fabrication rules
  for the actual prose
- `assets/master-template.md` — the full section menu and heading structure
  to draw from
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 198kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 198kUpdated Claude CodeCodexVerifiedInstall