{"id":"ab42cf1b-d93b-42e7-80a6-ed441dd0ebea","shortId":"7VGp34","kind":"skill","title":"crafting-effective-readmes","tagline":"Use when writing or improving README files. Not all READMEs are the same — provides templates and guidance matched to your audience and project type.","description":"# Crafting Effective READMEs\n\n## Overview\n\nREADMEs 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.\n\n**Always ask:** Who will read this, and what do they need to know?\n\n## Process\n\n### Step 1: Identify the Task\n\n**Ask:** \"What README task are you working on?\"\n\n| Task | When |\n|------|------|\n| **Creating** | New project, no README yet |\n| **Adding** | Need to document something new |\n| **Updating** | Capabilities changed, content is stale |\n| **Reviewing** | Checking if README is still accurate |\n\n### Step 2: Task-Specific Questions\n\n**Creating initial README:**\n1. What type of project? (see Project Types below)\n2. What problem does this solve in one sentence?\n3. What's the quickest path to \"it works\"?\n4. Anything notable to highlight?\n\n**Adding a section:**\n1. What needs documenting?\n2. Where should it go in the existing structure?\n3. Who needs this info most?\n\n**Updating existing content:**\n1. What changed?\n2. Read current README, identify stale sections\n3. Propose specific edits\n\n**Reviewing/refreshing:**\n1. Read current README\n2. Check against actual project state (package.json, main files, etc.)\n3. Flag outdated sections\n4. Update \"Last reviewed\" date if present\n\n### Step 3: Always Ask\n\nAfter drafting, ask: **\"Anything else to highlight or include that I might have missed?\"**\n\n## Project Types\n\n| Type | Audience | Key Sections | Template |\n|------|----------|--------------|----------|\n| **Open Source** | Contributors, users worldwide | Install, Usage, Contributing, License | `templates/oss.md` |\n| **Personal** | Future you, portfolio viewers | What it does, Tech stack, Learnings | `templates/personal.md` |\n| **Internal** | Teammates, new hires | Setup, Architecture, Runbooks | `templates/internal.md` |\n| **Config** | Future you (confused) | What's here, Why, How to extend, Gotchas | `templates/xdg-config.md` |\n\n**Ask the user** if unclear. Don't assume OSS defaults for everything.\n\n## Essential Sections (All Types)\n\nEvery README needs at minimum:\n\n1. **Name** - Self-explanatory title\n2. **Description** - What + why in 1-2 sentences  \n3. **Usage** - How to use it (examples help)\n\n## References\n\n- `section-checklist.md` - Which sections to include by project type\n- `style-guide.md` - Common README mistakes and prose guidance\n- `using-references.md` - Guide to deeper reference materials","tags":["crafting","effective","readmes","agent","toolkit","softaworks","agent-skills","automation","claude","claude-code","coding-agent","development"],"capabilities":["skill","source-softaworks","skill-crafting-effective-readmes","topic-agent-skills","topic-automation","topic-claude","topic-claude-code","topic-coding-agent","topic-development"],"categories":["agent-toolkit"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/softaworks/agent-toolkit/crafting-effective-readmes","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add softaworks/agent-toolkit","source_repo":"https://github.com/softaworks/agent-toolkit","install_from":"skills.sh"}},"qualityScore":"0.700","qualityRationale":"deterministic score 0.70 from registry signals: · indexed on github topic:agent-skills · 1847 github stars · SKILL.md body (2,468 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T18:52:56.324Z","embedding":null,"createdAt":"2026-04-18T20:27:48.287Z","updatedAt":"2026-05-18T18:52:56.324Z","lastSeenAt":"2026-05-18T18:52:56.324Z","tsv":"'-2':323 '1':77,125,160,182,197,311,322 '2':117,134,164,185,201,317 '3':143,173,192,211,223,325 '4':152,215 'accur':115 'actual':204 'ad':97,157 'alway':62,224 'answer':34 'anyth':153,229 'architectur':274 'ask':63,81,225,228,290 'assum':297 'audienc':25,37,41,243 'capabl':104 'chang':105,184 'check':110,202 'common':343 'config':60,277 'confus':280 'content':106,181 'context':53 'contribut':254 'contributor':46,249 'craft':2,29 'crafting-effective-readm':1 'creat':91,122 'current':187,199 'date':219 'deeper':352 'default':299 'descript':318 'differ':40,43,52 'document':100,163 'draft':227 'edit':195 'effect':3,30 'els':230 'essenti':302 'etc':210 'everi':306 'everyth':301 'exampl':331 'exist':171,180 'explanatori':315 'extend':287 'file':11,209 'flag':212 'folder':61 'futur':56,258,278 'future-you':55 'go':168 'gotcha':288 'guid':350 'guidanc':21,348 'help':332 'highlight':156,232 'hire':272 'identifi':78,189 'improv':9 'includ':234,338 'info':177 'inform':44 'initi':123 'instal':252 'intern':269 'key':244 'know':74 'last':217 'learn':267 'licens':255 'main':208 'match':22 'materi':354 'might':237 'minimum':310 'miss':239 'mistak':345 'name':312 'need':42,51,72,98,162,175,308 'new':92,102,271 'notabl':154 'one':141 'open':58,247 'oss':49,298 'outdat':213 'overview':32 'package.json':207 'path':148 'person':257 'portfolio':260 'present':221 'problem':136 'process':75 'project':27,50,93,129,131,205,240,340 'propos':193 'prose':347 'provid':18 'question':35,121 'quickest':147 'read':66,186,198 'readm':4,10,14,31,33,83,95,112,124,188,200,307,344 'refer':333,353 'review':109,218 'reviewing/refreshing':196 'runbook':275 'section':159,191,214,245,303,336 'section-checklist.md':334 'see':130 'self':314 'self-explanatori':313 'sentenc':142,324 'setup':273 'skill' 'skill-crafting-effective-readmes' 'solv':139 'someth':101 'sourc':248 'source-softaworks' 'specif':120,194 'stack':266 'stale':108,190 'state':206 'step':76,116,222 'still':114 'structur':172 'style-guide.md':342 'task':80,84,89,119 'task-specif':118 'teammat':270 'tech':265 'templat':19,246 'templates/internal.md':276 'templates/oss.md':256 'templates/personal.md':268 'templates/xdg-config.md':289 'titl':316 'topic-agent-skills' 'topic-automation' 'topic-claude' 'topic-claude-code' 'topic-coding-agent' 'topic-development' 'type':28,127,132,241,242,305,341 'unclear':294 'updat':103,179,216 'usag':253,326 'use':5,329 'user':250,292 'using-references.md':349 'viewer':261 'work':87,151 'worldwid':251 'write':7 'yet':96","prices":[{"id":"a3fbf36c-b632-423b-869b-e8b0f793b6df","listingId":"ab42cf1b-d93b-42e7-80a6-ed441dd0ebea","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"softaworks","category":"agent-toolkit","install_from":"skills.sh"},"createdAt":"2026-04-18T20:27:48.287Z"}],"sources":[{"listingId":"ab42cf1b-d93b-42e7-80a6-ed441dd0ebea","source":"github","sourceId":"softaworks/agent-toolkit/crafting-effective-readmes","sourceUrl":"https://github.com/softaworks/agent-toolkit/tree/main/skills/crafting-effective-readmes","isPrimary":false,"firstSeenAt":"2026-04-18T21:54:24.281Z","lastSeenAt":"2026-05-18T18:52:56.324Z"},{"listingId":"ab42cf1b-d93b-42e7-80a6-ed441dd0ebea","source":"skills_sh","sourceId":"softaworks/agent-toolkit/crafting-effective-readmes","sourceUrl":"https://skills.sh/softaworks/agent-toolkit/crafting-effective-readmes","isPrimary":true,"firstSeenAt":"2026-04-18T20:27:48.287Z","lastSeenAt":"2026-05-07T22:40:50.685Z"}],"details":{"listingId":"ab42cf1b-d93b-42e7-80a6-ed441dd0ebea","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"softaworks","slug":"crafting-effective-readmes","github":{"repo":"softaworks/agent-toolkit","stars":1847,"topics":["agent-skills","ai","automation","claude","claude-code","coding-agent","development"],"license":"mit","html_url":"https://github.com/softaworks/agent-toolkit","pushed_at":"2026-03-05T16:46:24Z","description":"A curated collection of skills for AI coding agents. Skills are packaged instructions and scripts that extend agent capabilities across development, documentation, planning, and professional workflows.","skill_md_sha":"a6c30d955cb7b1f4ab1c70fd65295c6c58e3be1b","skill_md_path":"skills/crafting-effective-readmes/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/softaworks/agent-toolkit/tree/main/skills/crafting-effective-readmes"},"layout":"multi","source":"github","category":"agent-toolkit","frontmatter":{"name":"crafting-effective-readmes","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."},"skills_sh_url":"https://skills.sh/softaworks/agent-toolkit/crafting-effective-readmes"},"updatedAt":"2026-05-18T18:52:56.324Z"}}