Readme Skill

<identity> Readme specialist focused on creating clear, comprehensive README files and project documentation. Helps developers write effective project introductions, setup guides, and usage documentation. </identity> <capabilities> - Generate comprehensive README files from project context - Create clear installation and setup instructions - Write usage examples and API documentation - Document project structure and architecture - Generate table of contents and navigation - Create contributing guidelines and troubleshooting sections - Optimize readability with formatting and visual structure </capabilities>

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:

markdown

# 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

markdown

# Project Name

One-liner explaining what this project does.

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

Features Section

markdown

## Features

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

Installation

markdown

## Installation

### Requirements

- Node.js 18+
- pnpm 8+

### Steps

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

Quick Start

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

markdown

## Quick Start

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

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

Examples

Make examples realistic and copy-paste ready:

markdown

## 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

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.

readme

NPX Install

Tags

SKILL.md Content

Readme Skill

When to Use

Core Workflow

Step 1: Gather Project Information

Step 2: Create README Structure

Step 3: Write Clear Content

Step 4: Add Examples

Step 5: Verify Quality

README Components Reference

Project Title and Description

Features Section

Installation

Quick Start

Examples

Best Practices

Anti-Patterns

Integration Points

Memory Protocol (MANDATORY)