crafting-effective-readmes

A skill for Claude Code that helps you write, update, and improve README files tailored to your specific project type and audience.

Purpose

Not all READMEs are the same. An open-source library needs different documentation than a personal project or an internal tool. This skill provides:

• Audience-aware guidance - Different readers need different information
• Project-type templates - Ready-to-use structures for OSS, personal, internal, and config projects
• Task-specific workflows - Whether creating, updating, adding to, or reviewing READMEs
• Quality checks - Style guidance and section checklists to avoid common mistakes

When to Use

Use this skill when you need to:

• Create a README for a new project
• Add a new section to an existing README
• Update stale documentation after changes
• Review and refresh README content
• Choose the right sections for your project type

Trigger phrases:

• "Write a README for this project"
• "Help me document this"
• "Create documentation for..."
• "Update the README"
• "Review my README"
• "What sections should my README have?"

How It Works

The skill follows a three-step process:

Step 1: Identify the Task

The skill determines what README task you are working on:

| Task | When to Use | |------|-------------| | Creating | New project with no README yet | | Adding | Need to document something new in existing README | | Updating | Capabilities changed, content is stale | | Reviewing | Checking if README is still accurate |

Step 2: Gather Context

Based on the task, the skill asks targeted questions:

• Creating: What type of project? What problem does it solve? What is the quickest path to "it works"?
• Adding: What needs documenting? Where should it go? Who needs this info most?
• Updating: What changed? Which sections are stale?
• Reviewing: Compares README against actual project state (package.json, main files, etc.)

Step 3: Generate and Refine

The skill uses the appropriate template and follows up with: "Anything else to highlight or include that I might have missed?"

Key Features

Project Type Templates

| Type | Audience | Template | |------|----------|----------| | Open Source | Contributors, users worldwide | templates/oss.md | | Personal | Future you, portfolio viewers | templates/personal.md | | Internal | Teammates, new hires | templates/internal.md | | Config | Future you (confused) | templates/xdg-config.md |

Section Checklist by Project Type

| Section | OSS | Personal | Internal | Config | |---------|-----|----------|----------|--------| | Name/Description | Yes | Yes | Yes | Yes | | Badges | Yes | Optional | No | No | | Installation | Yes | Yes | Yes | No | | Usage/Examples | Yes | Yes | Yes | Brief | | What's Here | No | No | No | Yes | | How to Extend | No | No | Optional | Yes | | Contributing | Yes | Optional | Yes | No | | License | Yes | Optional | No | No | | Architecture | Optional | No | Yes | No | | Gotchas/Notes | Optional | Optional | Yes | Yes | | Last Reviewed | No | No | Optional | Yes |

Reference Materials

The skill includes curated reference materials for deeper understanding:

• art-of-readme.md - Philosophy behind great READMEs, cognitive funneling
• make-a-readme.md - Practical, section-by-section guidance
• standard-readme-spec.md - Formal specification for OSS consistency

Usage Examples

Creating a New README

User: I need a README for my new CLI tool

Claude: What type of project is this - open source, personal, or internal?

User: Open source, it's a Node.js package

Claude: [Uses OSS template, asks about installation, usage, and contributing]

Updating an Existing README

User: Update my README, I added a new feature

Claude: [Reads current README, identifies where to add the new feature,
        proposes specific edits]

Reviewing for Accuracy

User: Check if my README is still accurate

Claude: [Compares README against package.json, main files, etc.
        Flags outdated sections and suggests updates]

Best Practices

1. Always ask about audience - Don't assume OSS defaults for everything
2. Show, don't just tell - Include examples and code samples
3. Use structure - Headers, tables, and lists improve scannability
4. Keep it current - Add "last reviewed" dates for internal/config projects
5. Include installation steps - Never assume setup is obvious
6. Write for YOUR audience - Avoid generic tone

Common Mistakes to Avoid

• No installation steps (never assume setup is obvious)
• No examples (show, don't just tell)
• Wall of text (use headers, tables, lists)
• Stale content (add "last reviewed" date)
• Generic tone (write for YOUR audience)

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)

Directory Structure

crafting-effective-readmes/
  SKILL.md                 # Skill definition
  section-checklist.md     # Quick reference for sections by project type
  style-guide.md           # Common mistakes and prose guidance
  using-references.md      # Guide to reference materials
  templates/
    oss.md                 # Open source project template
    personal.md            # Personal/portfolio project template
    internal.md            # Internal/team project template
    xdg-config.md          # Configuration directory template
  references/
    art-of-readme.md       # README philosophy
    make-a-readme.md       # Section-by-section guidance
    standard-readme-spec.md        # Formal specification
    standard-readme-example-minimal.md  # Minimal compliant example
    standard-readme-example-maximal.md  # Full-featured example

Related Skills

• writing-clearly-and-concisely - For general prose quality, clear writing, and avoiding AI patterns