playbooks

home / skills / softaworks / agent-toolkit / crafting-effective-readmes

crafting-effective-readmes skill

/skills/crafting-effective-readmes

This skill helps you craft effective READMEs with audience-focused templates and guidance for creating, adding, updating, or reviewing documentation.

npx playbooks add skill softaworks/agent-toolkit --skill crafting-effective-readmes

Review the files below or copy the command above to add this skill to your agents.

Files (14)
SKILL.md
2.6 KB
---
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

Overview

This skill helps you write and improve a project's main documentation file so readers get the answers they need quickly. It provides templates and guided questions tailored to different project types and audiences. Use it to create clear, actionable landing docs for users, contributors, or future-you.

How this skill works

The skill guides you through a three-step process: identify the documentation task, ask task-specific questions, and run a focused review pass. It maps project types to recommended sections and templates, and prompts targeted edits when contents are stale or incomplete. Final output is a concise, audience-focused document with a clear path to 'it works'.

When to use it

  • Starting a new project and creating the initial landing document
  • Adding new functionality or configuration that needs explaining
  • Updating docs after changes in features, APIs, or dependencies
  • Reviewing existing project docs to remove stale info and fix gaps
  • Onboarding teammates who need consistent setup and run guidance

Best practices

  • Always identify the primary audience before writing (user, contributor, teammate, future-you)
  • Open with a one-sentence problem + solution and show the quickest path to success
  • Include minimal runnable examples for usage and setup steps
  • Use project-type templates (open source, internal, personal, config) to pick relevant sections
  • During reviews, check actual project files to verify accuracy and update a last-reviewed date

Example use cases

  • Create an initial landing doc for a new open-source library with install and contributing sections
  • Add a configuration section documenting dotfiles and extension points for future-you
  • Update setup instructions and dependency versions after a breaking release
  • Audit internal project docs to add architecture notes and runbooks for new hires
  • Draft a short portfolio project summary that highlights tech stack and learnings

FAQ

How do I choose the right project type template?

Pick the audience you expect to read the doc: contributors and users → open source; teammates and operators → internal; personal projects → personal; configs → config template.

What’s the most important content to include first?

A clear name, a one- or two-sentence description of what it does and why, and the minimal steps to get something working.