Readme Skill

When to Use

Use this skill when:

• Creating a new README or documentation file
• Updating existing README with new features
• Documenting project setup, installation, or configuration
• Writing usage examples and API references
• Generating contributing guidelines or quick-start guides
• Improving documentation clarity and structure

Core Workflow

Step 1: Gather Project Information

Analyze the project to understand:

1. Project Purpose: What problem does it solve?
2. Target Audience: Who are the users (developers, users, contributors)?
3. Key Features: What makes this project special?
4. Technical Stack: Languages, frameworks, dependencies
5. Project Structure: How is code organized?

Step 2: Create README Structure

Use this standard structure:

# Project Name

Brief description (1-2 sentences)

## Features

- Feature 1
- Feature 2
- Feature 3

## Installation

[Setup instructions]

## Quick Start

[Basic usage example]

## Documentation

[Link to detailed docs]

## API Reference

[Key endpoints/functions]

## Examples

[Working examples]

## Configuration

[Setup options]

## Troubleshooting

[Common issues and solutions]

## Contributing

[How to contribute]

## License

[License information]

Step 3: Write Clear Content

• Be specific: Use concrete examples, not vague descriptions
• Show, don't tell: Include code examples and screenshots
• Progressive disclosure: Start simple, add complexity gradually
• Organize logically: Group related information
• Use formatting: Headers, lists, code blocks for readability

Step 4: Add Examples

Include practical, working examples:

• Installation examples
• Basic usage snippets
• Complex feature demonstrations
• Common use cases
• Copy-paste ready code

Step 5: Verify Quality

Check before completing:

• Clear project purpose in first paragraph
• Installation instructions are complete
• Examples are runnable
• Table of contents matches sections
• All links work
• Formatting is consistent
• No typos or grammar errors

README Components Reference

Project Title and Description

# Project Name

One-liner explaining what this project does.

Long paragraph (2-3 sentences) describing problem solved and approach.

Features Section

## Features

- ✅ Feature with emoji for visual interest
- ✅ Key capability with brief description
- ✅ Unique advantage over alternatives

Installation

## Installation

### Requirements

- Node.js 18+
- pnpm 8+

### Steps

\`\`\`bash
pnpm install project-name
\`\`\`

Quick Start

Keep this minimal (5-10 lines of code max):

## Quick Start

\`\`\`javascript
import { feature } from 'project-name';

const result = feature({ option: 'value' });
console.log(result);
\`\`\`

Examples

Make examples realistic and copy-paste ready:

## Examples

### Basic Usage

\`\`\`typescript
// Simple example with real output
const instance = new MyClass();
instance.doSomething(); // Output: expected result
\`\`\`

### Advanced Configuration

\`\`\`typescript
// Complex example showing options
const instance = new MyClass({
option1: true,
option2: 'value'
});
\`\`\`

Best Practices

1. Lead with value: First paragraph should answer "why should I use this?"
2. Show working examples: Code examples should be runnable
3. Keep installation simple: Complex setup gets a dedicated guide
4. Document dependencies: List what's required upfront
5. Include screenshots: Visual examples for UI projects
6. Write for skimmers: Use headers so people can scan content
7. Link to detailed docs: README is overview, link to full documentation
8. Keep it current: Update README when adding features
9. Be honest about limitations: What's not covered or not supported
10. Include contributing guidelines: How to report issues or submit PRs

Anti-Patterns

Pattern	Problem	Fix
Wall of text	Impossible to scan	Use headers and lists
Missing setup	Readers can't install	Include step-by-step instructions
No examples	Unclear how to use	Add working code examples
Outdated info	Misleads users	Update with releases
Too detailed	Overwhelming	Link to full docs instead
No table of contents	Hard to navigate	Add section links at top
Broken links	Poor user experience	Test all external links
Marketing fluff	Lacks substance	Focus on what it does, not hype

Iron Laws

1. ALWAYS lead with the value proposition — the first paragraph must answer "what problem does this solve?" before any installation or setup instructions.
2. NEVER write a Quick Start section longer than 10 lines — if setup requires more, link to a detailed guide rather than overwhelming the first-time reader.
3. ALWAYS include working, copy-paste-ready code examples — non-runnable pseudocode examples are worse than no examples because they waste the reader's time.
4. NEVER let a README become stale after a feature release — outdated installation commands and broken examples destroy user trust immediately.
5. ALWAYS test all external links and code examples before considering the README complete — dead links and broken examples are the most common README failure mode.

Anti-Patterns

Anti-Pattern	Why It Fails	Correct Approach
Starting with a long feature list before the description	Readers don't know what the project is, so features are meaningless	Lead with a 1-2 sentence value proposition before listing features
Using pseudocode or placeholder examples	Forces readers to infer the real API; causes frustration and abandonment	Show actual runnable code with real imports, function names, and expected output
Putting a 20-step installation guide in Quick Start	Overwhelming setup drives users away; contradicts "quick" start	Quick Start must be 1-3 commands; link detailed setup to a separate guide
Writing marketing copy instead of technical facts	Vague statements like "blazing fast" give no actionable information	Use specific claims with data: "reduces build time by 40% (measured on 10k LOC)"
Not updating README when features change	Outdated commands fail silently; users blame the project, not the docs	Treat README as code: update it in the same PR as every feature change

Integration Points

Related Skills:

• doc-generator - Automated documentation from code
• writing-skills - Writing quality guidelines
• technical-writer - Professional documentation agent

Related Agents:

• technical-writer - Uses this skill for documentation
• developer - Writes README for new projects

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md

After completing:

• New pattern → .claude/context/memory/learnings.md
• Issue found → .claude/context/memory/issues.md
• Decision made → .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.