Menú
Use when writing or improving README files. Not all READMEs are the same — provides templates and guidance matched to your audience and project type.
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Basado en la clasificación ocupacional SOC
Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
A relentless interview to sharpen a plan or design.
A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
Configure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.
Turn the current conversation into a spec and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed.
Break a plan, spec, or the current conversation into a set of tracer-bullet tickets, each declaring its blocking edges, published to the configured tracker — edges as text in a local file, or native blocking links on a real tracker.
| description | Use when writing or improving README files. Not all READMEs are the same — provides templates and guidance matched to your audience and project type. |
| metadata | {"github-path":"skills/crafting-effective-readmes","github-ref":"refs/heads/main","github-repo":"https://github.com/softaworks/agent-toolkit","github-tree-sha":"72e2a4d89c5a14b762cfc58e3bbd7fd63e9642b0"} |
| name | crafting-effective-readmes |
READMEs answer questions your audience will have. Different audiences need different information - a contributor to an OSS project needs different context than future-you opening a config folder.
Always ask: Who will read this, and what do they need to know?
Ask: "What README task are you working on?"
| Task | When |
|---|---|
| Creating | New project, no README yet |
| Adding | Need to document something new |
| Updating | Capabilities changed, content is stale |
| Reviewing | Checking if README is still accurate |
Creating initial README:
Adding a section:
Updating existing content:
Reviewing/refreshing:
After drafting, ask: "Anything else to highlight or include that I might have missed?"
| Type | Audience | Key Sections | Template |
|---|---|---|---|
| Open Source | Contributors, users worldwide | Install, Usage, Contributing, License | templates/oss.md |
| Personal | Future you, portfolio viewers | What it does, Tech stack, Learnings | templates/personal.md |
| Internal | Teammates, new hires | Setup, Architecture, Runbooks | templates/internal.md |
| Config | Future you (confused) | What's here, Why, How to extend, Gotchas | templates/xdg-config.md |
Ask the user if unclear. Don't assume OSS defaults for everything.
Every README needs at minimum:
section-checklist.md - Which sections to include by project typestyle-guide.md - Common README mistakes and prose guidanceusing-references.md - Guide to deeper reference materials