# Crafting Effective Readmes

Use when writing or improving README files.

- Repository: https://github.com/softaworks/agent-toolkit (2611 stars)
- Category: Writing
- License: MIT
- Last updated: 2026-03-05
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add softaworks/agent-toolkit --skill crafting-effective-readmes -g -a claude-code -y`
Codex: `npx skills add softaworks/agent-toolkit --skill crafting-effective-readmes -g -a codex -y`
Cursor: `npx skills add softaworks/agent-toolkit --skill crafting-effective-readmes -g -a cursor -y`
Gemini CLI: `npx skills add softaworks/agent-toolkit --skill crafting-effective-readmes -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add softaworks/agent-toolkit`

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

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

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

The rest: https://github.com/softaworks/agent-toolkit/blob/HEAD/dist/plugins/crafting-effective-readmes/skills/crafting-effective-readmes/SKILL.md