crafting-effective-readmes
Crafting Effective READMEs
Overview
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?
Process
Step 1: Identify the Task
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 |
More from joshuadavidthomas/agent-skills
frontend-design-principles
Create polished, intentional frontend interfaces. Use this skill when building any UI — dashboards, admin panels, landing pages, marketing sites, or web applications. Routes to specialized guidance based on context.
18writing-clearly-and-concisely
Use when writing prose humans will read—documentation, commit messages, error messages, explanations, reports, or UI text. Applies Strunk's timeless rules for clearer, stronger, more professional writing.
13reducing-entropy
Use when evaluating designs, reviewing code, or refactoring - measures success by total code in the final codebase, not effort to get there. Bias toward deletion.
10improving-prompts
Use when optimizing CLAUDE.md, AGENTS.md, custom commands, or skill files for Claude 4.5 models - applies documented Anthropic best practices systematically instead of inventing improvements
10diataxis
Structure, classify, and write documentation using the Diátaxis framework. Use when writing docs, README files, guides, tutorials, how-to guides, API references, or organizing documentation architecture. Also use when asked to improve documentation, restructure docs, decide what type of doc to write, or classify existing content. Covers tutorials, how-to guides, reference, and explanation.
8sveltekit
>
6