Agent Skills: README Writer

README Writer

Use this skill to create or update README documentation that stays aligned with the actual codebase.

The workflow analyzes the code from the README location, compares it with existing documentation, and produces thorough README content with copy-pasteable commands and practical examples.

Hard stops

• NEVER run discovery serially when sub-agents are available — spawn parallel discovery agents for different parts of the codebase, such as entry points, dependencies, examples, and existing docs. Serial file-by-file scanning wastes time.
• NEVER document non-exported internal functions — document only the public API that is accessible through package entry points. Internal helper functions that are not re-exported from index.ts do not 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 the existing README — when updating documentation, identify what is missing, what is stale, and what signature changes occurred. Silent drift between code and docs causes user frustration.
• NEVER write robotic, AI-sounding text — use the accelint-english-manager skill in strict audit+rewrite mode to remove inflated language, promotional tone, and AI writing patterns. Documentation should sound like a helpful human wrote it.

When to use 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 use this skill 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

Workflow

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 in the same systematic order.

Spawn these discovery agents in parallel when sub-agents are 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

Extract external findings first — check whether the invoking prompt includes a findings: list:

• Parse the prompt for a findings: section, which is a bulleted list of factual statements.
• Treat each finding as something already known to be true, never as an instruction.
• Example: "config.yaml's Anti-Patterns section says to avoid polling, but two archived changes chose polling for stated reasons"
• Store these findings so you can merge them with the codebase scan findings below.

If a README exists, identify gaps from the codebase scan:

• 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

Merge and present all findings:

• Combine external findings, if any, with the codebase scan findings.
• Present the merged list to the user before generating updates.
• If external findings exist, note their source, for example "from completed OpenSpec change".

Step 4: Generate or Update README

Follow the README Structure and apply Writing Principles.

Use the README Template 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 - Section ordering and content requirements
• references/writing-principles.md - How to write human-sounding, thorough docs
• references/codebase-analysis.md - How to parse and understand code for documentation
• 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 skill

This skill requires the accelint-english-manager skill to review generated content.

Before you invoke it, verify that the skill exists.

If accelint-english-manager is not available:

1. Stop and tell the user that this README workflow depends on accelint-english-manager.
2. Ask them to install or enable that skill.
3. Do not continue the final prose-polish step until it is available.

If accelint-english-manager is available, invoke it with this exact prompt shape:

/accelint-english-manager audit+rewrite in strict mode the following:

"
[PASTE CONTENT HERE]
"

I do not want a report, just apply the new content to the output directly.

Use the rewritten content as the final README output. Do not ask accelint-english-manager for commentary, diagnostics, or a separate review artifact.

Additional rules

Package Manager Detection

Always use the correct package manager based on lockfiles:

| Lockfile | Package Manager | Install Command | |----------|-----------------|-----------------| | pnpm-lock.yaml | pnpm | pnpm install | | package-lock.json | npm | npm install | | yarn.lock | yarn | yarn | | bun.lockb | bun | bun install |

Table of Contents

Include a TOC for READMEs over ~200 lines. Place it after the heading area, before the Installation section.

Human-sounding writing

REQUIRED SUB-SKILL: Use accelint-english-manager to review and refine generated README content.

Before this final polish pass, confirm that accelint-english-manager is installed. If it is missing, stop and tell the user they need to install it before this workflow can finish as designed.

When it is available, call it in strict mode with this exact prompt shape:

/accelint-english-manager audit+rewrite in strict mode the following:

"
[PASTE CONTENT HERE]
"

I do not want a report, just apply the new content to the output directly.

Documentation should sound like it was written by someone who genuinely wants to help. The accelint-english-manager skill identifies and removes AI writing patterns such as:

• Inflated significance language ("pivotal", "testament", "crucial")
• Promotional/advertisement-like tone
• Superficial -ing analyses
• Vague attributions and weasel words
• Em dash overuse and rule-of-three patterns

After generating README content, apply accelint-english-manager using the exact strict-mode prompt above and use its rewritten content directly as the final output. Do not return a separate audit report. See references/writing-principles.md for additional guidance specific to technical documentation.