菜单
Use when writing or improving README files. Not all READMEs are the same — provides templates and guidance matched to your audience and project type.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 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