# crafting-effective-readmes

Create or revise README files with guidance tailored to the project and its readers. The skill helps choose relevant sections and check documentation against the codebase.

- skill · `type=skill` · Claude Code · 79 installs
- Author: davila7
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/davila7/claude-code-templates/tree/HEAD/cli-tool/components/skills/productivity/crafting-effective-readmes
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/skills/crafting-effective-readmes

## What it does

The skill guides README work from identifying the requested change to reviewing the finished document. It supports writing documentation for a new project, adding material about a feature, refreshing stale instructions, and checking whether an existing README still matches the project. The agent first establishes the task and the intended audience.

Different project types have their own templates: `templates/oss.md` for open-source projects, `templates/personal.md` for personal work and portfolios, `templates/internal.md` for team documentation, and `templates/xdg-config.md` for configuration files. Supporting references include `section-checklist.md`, `style-guide.md`, and `using-references.md` for deciding what to cover and how to write it.

Each README should include a title, a concise explanation of the project's purpose, and usage instructions. When reviewing existing documentation, the agent compares it with `package.json` and key project files before proposing specific edits. That comparison matters: instructions left over from an earlier implementation can mislead readers when the code no longer supports them.

## Install

### Claude Code (native platform)

1. **claude-code-templates**
```bash
npx claude-code-templates@latest --skill productivity/crafting-effective-readmes
```

2. **Skills CLI (Vercel)**
```bash
npx skills add davila7/claude-code-templates --skill crafting-effective-readmes -a claude-code
```

3. **Manually: put the files in place**
- File: `~/.claude/skills/crafting-effective-readmes/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/crafting-effective-readmes/

### Codex

**Manually: put the files in place**
- File: `.agents/skills/crafting-effective-readmes/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

**Manually: put the files in place**
- File: `.cursor/skills/crafting-effective-readmes/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install davila7/claude-code-templates crafting-effective-readmes
```

2. **Manually: put the files in place**
- File: `.github/skills/crafting-effective-readmes/SKILL.md`

### Gemini CLI

**Platform CLI**
```bash
gemini skills install https://github.com/davila7/claude-code-templates --path cli-tool/components/skills/productivity/crafting-effective-readmes
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/crafting-effective-readmes/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/davila7/claude-code-templates/tree/HEAD/cli-tool/components/skills/productivity/crafting-effective-readmes

## When to use it
- Draft a README for a new repository
- Document a new feature in an existing README
- Find stale setup instructions after code changes
- Choose README sections for an internal project or config directory
- Compare documentation with the current project files

## Example prompts
- Write a README for this open-source project using `templates/oss.md`.
- Review the README against `package.json` and the main project files.
- Document this new feature in the existing README and suggest specific edits.

## Similar
- [grill-with-docs](https://affpapa.org/en/nevibecode/skills/grill-with-docs.md) — skill · 1219756 installs
- [skill-creator](https://affpapa.org/en/nevibecode/skills/skill-creator.md) — skill · 414180 installs
- [setup-matt-pocock-skills](https://affpapa.org/en/nevibecode/skills/setup-matt-pocock-skills.md) — skill · 1052851 installs
- [handoff](https://affpapa.org/en/nevibecode/skills/handoff.md) — skill · 1038491 installs
- [triage](https://affpapa.org/en/nevibecode/skills/triage.md) — skill · 990453 installs
- [domain-modeling](https://affpapa.org/en/nevibecode/skills/domain-modeling.md) — skill · 876391 installs

From the same set: [davila7/claude-code-templates](https://affpapa.org/en/nevibecode/by/davila7/claude-code-templates.md) — 804 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md