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:

• Project Purpose: What problem does it solve?

• Target Audience: Who are the users (developers, users, contributors)?

• Key Features: What makes this project special?

• Technical Stack: Languages, frameworks, dependencies

• 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

• Lead with value: First paragraph should answer "why should I use this?"

• Show working examples: Code examples should be runnable

• Keep installation simple: Complex setup gets a dedicated guide

• Document dependencies: List what's required upfront

• Include screenshots: Visual examples for UI projects

• Write for skimmers: Use headers so people can scan content

• Link to detailed docs: README is overview, link to full documentation

• Keep it current: Update README when adding features

• Be honest about limitations: What's not covered or not supported

• 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

• ALWAYS lead with the value proposition — the first paragraph must answer "what problem does this solve?" before any installation or setup instructions.

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

• ALWAYS include working, copy-paste-ready code examples — non-runnable pseudocode examples are worse than no examples because they waste the reader's time.

• NEVER let a README become stale after a feature release — outdated installation commands and broken examples destroy user trust immediately.

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