softaworks/agent-toolkit / skills/crafting-effective-readmes
crafting-effective-readmes
VerifiedUse when writing or improving README files. Not all READMEs are the same — provides templates and guidance matched to your audience and project type.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 6.0 KB |
| SKILL.md | skill md | 2.6 KB |
| references/art-of-readme.md | markdown | 23.9 KB |
| references/make-a-readme.md | markdown | 6.5 KB |
| references/standard-readme-example-maximal.md | markdown | 1.5 KB |
| references/standard-readme-example-minimal.md | markdown | 169 B |
| references/standard-readme-spec.md | markdown | 9.6 KB |
| section-checklist.md | markdown | 680 B |
| style-guide.md | markdown | 434 B |
| templates/internal.md | markdown | 1.9 KB |
| templates/oss.md | markdown | 1.6 KB |
| templates/personal.md | markdown | 1.1 KB |
| templates/xdg-config.md | markdown | 1.4 KB |
| using-references.md | markdown | 1.3 KB |
README.md
View on GitHub# Crafting Effective READMEs
A skill for Claude Code that helps you write, update, and improve README files tailored to your specific project type and audience.
## Purpose
Not all READMEs are the same. An open-source library needs different documentation than a personal project or an internal tool. This skill provides:
- **Audience-aware guidance** - Different readers need different information
- **Project-type templates** - Ready-to-use structures for OSS, personal, internal, and config projects
- **Task-specific workflows** - Whether creating, updating, adding to, or reviewing READMEs
- **Quality checks** - Style guidance and section checklists to avoid common mistakes
## When to Use
Use this skill when you need to:
- Create a README for a new project
- Add a new section to an existing README
- Update stale documentation after changes
- Review and refresh README content
- Choose the right sections for your project type
**Trigger phrases:**
- "Write a README for this project"
- "Help me document this"
- "Create documentation for..."
- "Update the README"
- "Review my README"
- "What sections should my README have?"
## How It Works
The skill follows a three-step process:
### Step 1: Identify the Task
The skill determines what README task you are working on:
| Task | When to Use |
|------|-------------|
| **Creating** | New project with no README yet |
| **Adding** | Need to document something new in existing README |
| **Updating** | Capabilities changed, content is stale |
| **Reviewing** | Checking if README is still accurate |
### Step 2: Gather Context
Based on the task, the skill asks targeted questions:
- **Creating**: What type of project? What problem does it solve? What is the quickest path to "it works"?
- **Adding**: What needs documenting? Where should it go? Who needs this info most?
- **Updating**: What changed? Which sections are stale?
- **Reviewing**: Compares README against actual project state (package.json, main files, etc.)
### Step 3: Generate and Refine
The skill uses the appropriate template and follows up with: "Anything else to highlight or include that I might have missed?"
## Key Features
### Project Type Templates
| Type | Audience | Template |
|------|----------|----------|
| **Open Source** | Contributors, users worldwide | `templates/oss.md` |
| **Personal** | Future you, portfolio viewers | `templates/personal.md` |
| **Internal** | Teammates, new hires | `templates/internal.md` |
| **Config** | Future you (confused) | `templates/xdg-config.md` |
### Section Checklist by Project Type
| Section | OSS | Personal | Internal | Config |
|---------|-----|----------|----------|--------|
| Name/Description | Yes | Yes | Yes | Yes |
| Badges | Yes | Optional | No | No |
| Installation | Yes | Yes | Yes | No |
| Usage/Examples | Yes | Yes | Yes | Brief |
| What's Here | No | No | No | Yes |
| How to Extend | No | No | Optional | Yes |
| Contributing | Yes | Optional | Yes | No |
| License | Yes | Optional | No | No |
| Architecture | Optional | No | Yes | No |
| Gotchas/Notes | Optional | Optional | Yes | Yes |
| Last Reviewed | No | No | Optional | Yes |
### Reference Materials
The skill includes curated reference materials for deeper understanding:
- **art-of-readme.md** - Philosophy behind great READMEs, cognitive funneling
- **make-a-readme.md** - Practical, section-by-section guidance
- **standard-readme-spec.md** - Formal specification for OSS consistency
## Usage Examples
### Creating a New README
```
User: I need a README for my new CLI tool
Claude: What type of project is this - open source, personal, or internal?
User: Open source, it's a Node.js package
Claude: [Uses OSS template, asks about installation, usage, and contributing]
```
### Updating an Existing README
```
User: Update my README, I added a new feature
Claude: [Reads current README, identifies where to add the new feature,
proposes specific edits]
```
### Reviewing for Accuracy
```
User: Check if my README is still accurate
Claude: [Compares README against package.json, main files, etc.
Flags outdated sections and suggests updates]
```
## Best Practices
1. **Always ask about audience** - Don't assume OSS defaults for everything
2. **Show, don't just tell** - Include examples and code samples
3. **Use structure** - Headers, tables, and lists improve scannability
4. **Keep it current** - Add "last reviewed" dates for internal/config projects
5. **Include installation steps** - Never assume setup is obvious
6. **Write for YOUR audience** - Avoid generic tone
## Common Mistakes to Avoid
- No installation steps (never assume setup is obvious)
- No examples (show, don't just tell)
- Wall of text (use headers, tables, lists)
- Stale content (add "last reviewed" date)
- Generic tone (write for YOUR audience)
## Essential Sections (All Types)
Every README needs at minimum:
1. **Name** - Self-explanatory title
2. **Description** - What + why in 1-2 sentences
3. **Usage** - How to use it (examples help)
## Directory Structure
```
crafting-effective-readmes/
SKILL.md # Skill definition
section-checklist.md # Quick reference for sections by project type
style-guide.md # Common mistakes and prose guidance
using-references.md # Guide to reference materials
templates/
oss.md # Open source project template
personal.md # Personal/portfolio project template
internal.md # Internal/team project template
xdg-config.md # Configuration directory template
references/
art-of-readme.md # README philosophy
make-a-readme.md # Section-by-section guidance
standard-readme-spec.md # Formal specification
standard-readme-example-minimal.md # Minimal compliant example
standard-readme-example-maximal.md # Full-featured example
```
## Related Skills
- `writing-clearly-and-concisely` - For general prose quality, clear writing, and avoiding AI patterns
## Attribution
- Original skill by @joshuadavidthomas from [joshuadavidthomas/agent-skills](https://github.com/joshuadavidthomas/agent-skills) (MIT)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Unverified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |