crafting-effective-readmes

$npx mdskill add Kastalien-Research/thoughtbox/crafting-effective-readmes

Create, update, or review READMEs tailored to audience and project type.

  • Guides users through creating, adding, updating, or reviewing README content.
  • Relies on project metadata and user-provided context about the project.
  • Asks targeted questions to determine audience, project type, and task.
  • Outputs structured templates, section suggestions, or specific edits.

SKILL.md

.github/skills/crafting-effective-readmesView on GitHub ↗
---
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.
---

# 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 |
| **Reviewing** | Checking if README is still accurate |

### Step 2: Task-Specific Questions

**Creating initial README:**
1. What type of project? (see Project Types below)
2. What problem does this solve in one sentence?
3. What's the quickest path to "it works"?
4. Anything notable to highlight?

**Adding a section:**
1. What needs documenting?
2. Where should it go in the existing structure?
3. Who needs this info most?

**Updating existing content:**
1. What changed?
2. Read current README, identify stale sections
3. Propose specific edits

**Reviewing/refreshing:**
1. Read current README
2. Check against actual project state (package.json, main files, etc.)
3. Flag outdated sections
4. Update "Last reviewed" date if present

### Step 3: Always Ask

After drafting, ask: **"Anything else to highlight or include that I might have missed?"**

## Project Types

| 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.

## 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)

## References

- `section-checklist.md` - Which sections to include by project type
- `style-guide.md` - Common README mistakes and prose guidance
- `using-references.md` - Guide to deeper reference materials

More from Kastalien-Research/thoughtbox

SkillDescription
assumptionsManage the assumption registry — track, verify, and query assumptions about external dependencies and system behavior. Prevents costly rediscovery of known failures.
capture-learningCapture significant learnings from the current work session. Structures insights for future sessions and updates agent memory.
claude-opus-4-6-prompting>
claude-promptWrite or improve prompts for Claude using Anthropic's official best practices. Creates system prompts, agent prompts, tool descriptions, and MCP resource templates. Pass an existing prompt to improve it, or describe what you need to create one from scratch.
coolify-composeConvert Docker Compose files to Coolify templates. Use when creating Coolify services, converting docker-compose.yml for Coolify deployment, working with SERVICE_URL/SERVICE_PASSWORD magic variables, or troubleshooting Coolify compose errors.
diagramGenerate architecture diagrams for a codebase subsystem or module. Explores source files and produces Mermaid diagrams in docs/.
diataxisStructure, 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.
escalateFormat a structured escalation to the human decision-maker (Chief Agentic). Use when hitting an escalation threshold.
frontend-design-principlesCreate 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.
hddDEPRECATED — use workflow Stage 2 (spec + frontmatter claims). Historical HDD docs are in docs/decisions/archive/.