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

references/section-selection.md

View on GitHub
# Section Selection Guide

The master template (`assets/master-template.md`) is a menu, not a checklist.
Most repos should use 40-60% of it. Including a section with nothing real to
put in it (placeholder text, invented numbers, a "Kubernetes Deployment"
section for a repo with no Kubernetes anywhere) is worse than leaving it out.

Always ask: is there a real file, config, or code path backing this section?
If not, drop the section. Don't shrink it to a stub — remove it entirely.
That one rule is the whole method — everything below is worked examples of
applying it to patterns that come up often, not a closed list of allowed
project types. A repo that doesn't match any row still gets the same
treatment: look at what's actually there and keep only what it supports.

## Detection signals

These are common patterns, useful for guessing what a repo's README
audience expects — not categories a repo needs to be sorted into.

| Project type | Signals to look for |
|---|---|
| Embedded / firmware / IoT | `platformio.ini`, `*.ino`, `sdkconfig`, `esp_*.h` / `Arduino.h` / `WiFi.h` includes, `CMakeLists.txt` targeting a chip toolchain, `boards.txt`, references to pins/I2C/OneWire/GPIO in code |
| Desktop app | Qt (`.pro`, `CMakeLists.txt` with `find_package(Qt...)`, `QApplication`), Electron (`main.js` + `package.json` with `electron`), `.NET`/WPF, GTK |
| Backend / web service | `Dockerfile`, `docker-compose.yml`, server framework imports (Express, FastAPI, Flask, Gin, Actix, Spring Boot), `k8s/` or `helm/` dirs, OpenAPI/Swagger spec |
| CLI tool | `bin` field in `package.json`, `argparse`/`click`/`cobra`/`clap` usage, single-purpose script with a `main()` entry point, no server code |
| Library / SDK | Published to a package registry (has a `publish` config, version badge target), public API surface is the point, no deployment artifacts |
| Automation workflow export | `.json` with n8n's `nodes`/`connections` schema, Power Automate `.flow` / ARM template export, Zapier/Make export |
| Data / ML project | Notebooks (`.ipynb`), `requirements.txt`/`environment.yml` heavy on pandas/numpy/torch/sklearn, `data/` dir, training scripts |

A repo can match more than one row (e.g. a backend service with a CLI
admin tool). Cover both; don't force a single label.

## What to keep / drop per type

### Embedded / firmware / IoT
**Keep:** About, Key Capabilities, Requirements (rewrite "Hardware Boundary
Profile" as the *actual* board + sensors + wiring, not a resource-limits
table — e.g. "ESP32-WROOM-32, MAX30102 via I2C, DS18B20 via OneWire" from the
real includes/pin defs), Toolchain & flashing (board package version,
upload command / port, not a Docker command), Usage (serial monitor output,
BLE/HTTP API only if the firmware actually exposes one), Architecture (task/
loop structure, interrupt or ISR notes if present), Testing (only if there's
an actual test harness — otherwise a short "Validation" note on how it was
bench-tested, grounded in comments/commit history if evidenced), Troubleshooting
(wiring/upload/port issues), License.
**Drop:** Kubernetes/Helm, Config Matrix (unless there are real build-time
`#define` flags worth tabulating), DB Migration Policy, Observability/health
endpoints, Rollback & Recovery, Scaling Model.

### Desktop app
**Keep:** About, Requirements (Host & OS compatibility, real toolchain
versions from the build files), Quickstart (per-OS build/packaging steps),
Usage (screenshots if present in repo, CLI flags), Architecture (module/class
breakdown for anything non-trivial, e.g. a Qt6 MVC split), Testing, License,
Contributing (only if a `CONTRIBUTING.md` or PR template exists).
**Drop:** Kubernetes, hardware boundary profile, DB migration policy /
observability (unless the app talks to a real backend — then keep a short
data-flow note, not the full production apparatus).

### Backend / web service
Closest to the full template. **Keep:** Config Matrix (from real env vars /
`.env.example`), Deployment, Health & Readiness (only if endpoints exist in
code), Observability (only if logging/metrics/tracing libs are actually
wired in), DB Migration Policy (only if a migration tool/folder exists),
Rollback & Recovery, Scaling Model — all grounded in what's in the repo, not
a generic SRE checklist.

### CLI tool / library / SDK
**Keep:** About, Installation (via the real package manager/registry),
Usage Patterns (real command examples / real function signatures),
API & Interface Documentation (for libraries — pull real exported
functions/classes, not invented ones), Versioning & Changelog (only if a
`CHANGELOG.md` or semver tags exist), License.
**Drop:** Deployment, observability, DB sections, hardware profile.

### Automation workflow export (n8n / Power Automate / Zapier)
This is the one category where the master template's shape barely applies —
write a different structure:
- What it does: trigger → steps → outcome, in plain language
- Required credentials/connections and where to configure them
- Import instructions (n8n: Import from File/URL; Power Automate: import
  package steps)
- Node-by-node or step-by-step summary of the meaningful nodes only
- Customization points (hardcoded URLs, sheet IDs, webhook paths to change)
- Error handling/retry behavior, only if actually configured on the nodes
- License/usage note
Skip deployment, hardware, DB migration, observability sections entirely.

### Data / ML project
**Keep:** About, Data sources (with real dataset names/links found in code
or docs), Environment setup (conda/pip, from the real lockfile), Reproducing
results (real script/notebook invocation order), Key outputs, License notes
for the dataset if stated. **Drop:** deployment/observability unless there's
a real served model API (then treat that part like a backend service).

## When nothing fits cleanly

If the repo is small (a script, a homework assignment, a rough prototype),
most of this guide's "keep" lists still overshoot. In that case use only:
About, Requirements, Quickstart, Usage, License. Don't pad a small project
with sections just because the template has them.
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