accelint-readme-writer

What this skill does

# README Writer

This skill guides the creation and maintenance of comprehensive, human-friendly README documentation by analyzing the codebase and ensuring documentation stays in sync with actual functionality.

## NEVER Do When Writing READMEs

- **NEVER run discovery serially when sub-agents are available** — spawn parallel discovery agents for different aspects (entry points, dependencies, examples, existing docs) to analyze the codebase efficiently. Serial file-by-file scanning wastes time.
- **NEVER document non-exported internal functions** — only document the public API that's accessible through package entry points. Internal helper functions that aren't re-exported from `index.ts` don't belong in the README.
- **NEVER fabricate usage examples** — extract real examples from test files, JSDoc blocks, or `examples/` directories. Made-up examples often contain subtle errors that confuse users.
- **NEVER use the wrong package manager commands** — check for lockfiles (`pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `bun.lockb`) and use the matching package manager in all commands. Wrong commands break the user's first experience.
- **NEVER skip comparing code to existing README** — when updating documentation, identify what's missing, what's stale, and what signature changes occurred. Silent drift between code and docs causes user frustration.
- **NEVER write robotic, AI-sounding text** — use the humanizer skill to remove inflated language, promotional tone, and AI writing patterns. Documentation should sound like a helpful human wrote it.

## When to Activate This Skill

Use this skill when:

- Creating a new README.md for a project or package
- Updating an existing README.md after code changes
- Auditing documentation for completeness and accuracy
- Converting sparse documentation into thorough guides
- User asks to "document this package" or "write a README"
- User mentions README in context of a monorepo subdirectory

## When NOT to Use This Skill

Do not activate for:

- API documentation generation (use JSDoc/TSDoc tools)
- Changelog or release notes
- Internal developer notes not meant for README
- Documentation in formats other than Markdown

## How to Use

### Step 1: Locate the README Context

Identify where the README should live. In monorepos, this determines the scope of codebase analysis:

```
project-root/           # README here documents entire monorepo
├── packages/
│   └── my-lib/         # README here documents only my-lib
│       └── README.md
└── README.md
```

### Step 1.5: Check for Related Documentation

Before analyzing the codebase, check if other onboarding documents exist:

1. **Check for openspec/config.yml or openspec/config.yaml**
   - If exists: Read it to extract:
     - Package manager (use this instead of lockfile detection)
     - Tech stack summary
     - Key libraries and frameworks
   - Skip redundant codebase scanning for these facts

2. **Check for ARCHITECTURE.md**
   - If exists: Read it to understand:
     - System components and their purposes
     - Deployment model
     - External integrations
   - Use for "Architecture & Development Guides" cross-reference section

3. **Check for AGENTS.md or CLAUDE.md**
   - If exists: Note for "Contributing" section
   - Reference it for contribution guidelines

**Benefits:**
- Reduces scanning when other docs exist
- Ensures consistency (README uses same package manager as config.yml)
- Creates proper cross-references automatically

### Step 2: Parallel Codebase Discovery

**Use parallel sub-agents when available** to discover different aspects of the codebase simultaneously. If sub-agents are not available, perform these discovery tasks inline but in the same systematic order.

Spawn these discovery agents in parallel (if sub-agents available):

**Agent A — Entry Points & Public API**
- Check `package.json` for `main`, `module`, `types`, `exports` fields
- Read the main entry point file (e.g., `src/index.ts`)
- Trace all re-exports to map the complete public API
- List all exported functions, classes, types, constants with signatures
- Return: entry point paths, complete export list with types

**Agent B — Dependencies & Configuration**
- Read `package.json` for dependencies, devDependencies, peerDependencies, scripts
- Check lockfile type (`pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `bun.lockb`)
- Look for configuration files: `tsconfig.json`, `.eslintrc*`, `vitest.config.*`, etc.
- Return: dependency list (separate runtime vs peer), available scripts, package manager, configs found

**Agent C — Examples & Usage Patterns**
- Search for `examples/` or `__examples__/` directory
- Read test files (`*.test.ts`, `*.spec.ts`) for usage patterns
- Extract JSDoc `@example` blocks from source files
- Look for inline comments showing usage
- Return: example file paths, extracted usage patterns from tests, JSDoc examples

**Agent D — Documentation Context** *(optional, runs concurrently)*
- Check for existing README.md
- Look for CHANGELOG.md, CONTRIBUTING.md, LICENSE
- Check for TypeDoc/JSDoc configuration
- Return: existing doc files and their key sections

**After all agents complete:** merge findings and identify documentation gaps (what exists in code but not in README, what's documented but doesn't exist, signature mismatches)

### Step 3: Compare Against Existing README

If a README exists, identify gaps:

- **Missing exports**: Public API not documented
- **Stale examples**: Code samples using deprecated patterns
- **Missing sections**: No installation, no quick start, no API reference
- **Outdated commands**: Wrong package manager, missing scripts

### Step 4: Generate or Update README

Follow the [README Structure](references/readme-structure.md) and apply [Writing Principles](references/writing-principles.md).

Use the [README Template](references/readme-template.md) as a starting point for new READMEs.

**For the Architecture & Development Guides section (section 11):** only include it if at least one of the related docs exists (checked in Step 1.5). Within the section, only list files that actually exist — do not include links to missing files. If none of the three docs exist (openspec/config.yml, ARCHITECTURE.md, AGENTS.md/CLAUDE.md), omit this section entirely.

## README Workflow Decision Tree

```
Start
  ↓
Does README.md exist?
  ├─ No → Analyze codebase → Generate from template
  └─ Yes → Analyze codebase → Compare with existing
             ↓
         Identify gaps and staleness
             ↓
         Suggest specific changes
             ↓
         Apply updates (with user confirmation)
```

## Key References

Load these as needed for detailed guidance:

- [references/readme-structure.md](references/readme-structure.md) - Section ordering and content requirements
- [references/writing-principles.md](references/writing-principles.md) - How to write human-sounding, thorough docs
- [references/codebase-analysis.md](references/codebase-analysis.md) - How to parse and understand code for documentation
- [references/readme-template.md](references/readme-template.md) - Copy-pasteable template for new READMEs

## Example Trigger Phrases

- "Create a README for this package"
- "Update the README to reflect recent changes"
- "The README is out of date, can you fix it?"
- "Document this library"
- "Write docs for packages/my-lib"
- "This package needs better documentation"

## Required Skills

This skill requires the `humanizer` skill for reviewing generated content.

If `humanizer` is not available:
1. Check Settings > Capabilities to enable it
2. Or invoke it with `/skill humanizer`

The humanizer skill removes AI writing patterns and ensures documentation sounds natural. Without it, generated READMEs may contain robotic language, inflated significance claims, and other AI artifacts.

## Important Notes

### Package Manager Detection

Always use the correct package manager based on lockfiles:

| Lockfile | Package Manager | Install Command |
|-