Menu
Use when writing or improving README files. Not all READMEs are the same — provides templates and guidance matched to your audience and project type.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
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