Accelint Readme Writer

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

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 humanizer to review and refine generated README content.

Documentation should sound like it was written by someone who genuinely wants to help. The humanizer skill identifies and removes AI writing patterns including:

• 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 the humanizer skill to ensure the output sounds natural and human-written. See references/writing-principles.md for additional guidance specific to technical documentation.

README Writer

Note:

This document is for agents and LLMs to follow when creating or updating README documentation. Each rule includes one-line summaries here, with links to detailed examples in the references/ folder. Load reference files only when you need detailed implementation guidance.

---

Abstract

Comprehensive guide for creating thorough, human-sounding README documentation that stays in sync with actual codebase functionality. Designed for AI agents working with any JavaScript/TypeScript project, with special handling for monorepos.

---

How to Use This Guide

1. Start here: Scan the rule summaries to identify relevant sections 2. Load references as needed: Click through to detailed examples only when implementing 3. Follow the workflow: Analyze codebase → Compare with existing docs → Generate/update

---

1. Codebase Analysis

1.1 Scoping the Analysis

View detailed examples

• Start from the README's directory, not the repository root
• In monorepos, only analyze the package/directory containing the README
• Respect package boundaries defined by package.json

1.2 Identifying Public API

View detailed examples

• Check package.json exports and main fields for entry points
• Find all export statements in entry point files
• Trace re-exports to their source definitions
• Distinguish between public API (exported from entry) and internal utilities

1.3 Extracting Signatures

View detailed examples

• Capture function signatures with parameter types and return types
• Document generic type parameters
• Note async functions and Promise return types
• Include overloaded signatures if present

1.4 Finding Existing Documentation

View detailed examples

• Read JSDoc/TSDoc comments above exports
• Check for inline usage examples in comments
• Look for examples/ directories
• Review test files for usage patterns

---

2. README Structure

2.1 Required Sections

View detailed examples

Every README must include these sections in order:

1. Heading Area - Title, optional banner, optional badges 2. Installation - How to install the package 3. Quick Start - Minimal working example 4. What - What this package is 5. Why - Why this package exists 6. API - Public API signatures and descriptions 7. Examples - Practical usage examples 8. License - License information

2.2 Optional Sections

View detailed examples

Include when relevant:

• Table of Contents - For READMEs over ~200 lines
• Further Reading - Links to related resources
• Contributing - How to contribute

2.3 Section Ordering

View detailed examples

Follow the prescribed order strictly. Users expect Installation near the top, API details in the middle, and License/Contributing at the bottom.

---

3. Writing Principles

REQUIRED SUB-SKILL: Use humanizer to review all generated README content before finalizing.

3.1 Be Absurdly Thorough

View detailed examples

When in doubt, include it. Assume the reader has never seen this codebase.

3.2 Use Code Blocks Liberally

View detailed examples

Every command should be copy-pasteable. Show example output when helpful.

3.3 Explain the Why

View detailed examples

Don't just say "run this command" — explain what it does and why.

3.4 Use Tables for Reference

View detailed examples

Environment variables, CLI options, configuration options, and script references work great as tables.

3.5 Keep Commands Current

View detailed examples

Detect and use the correct package manager. Never assume npm.

3.6 Write Like a Human

View detailed examples

Sound like someone who genuinely wants to help, not a robot generating docs.

3.7 Apply Humanizer Patterns

After drafting README content, apply the humanizer skill to remove AI writing patterns:

• Remove inflated significance language ("pivotal", "testament", "crucial", "vital")
• Replace promotional tone with neutral, specific language
• Eliminate superficial -ing analyses ("highlighting", "showcasing", "fostering")
• Replace vague attributions with specific sources or remove entirely
• Fix em dash overuse and rule-of-three patterns
• Remove sycophantic language ("Great question!", "Certainly!")
• Add personality and voice — sterile writing is as obvious as AI slop

---

4. Change Detection

4.1 Comparing Code to Docs

When updating an existing README:

1. Parse all public exports from the codebase 2. Parse all documented API from the README 3. Identify:

• Missing: Exports not documented
• Stale: Documentation for removed exports
• Changed: Signature changes not reflected

4.2 Suggesting Changes

Present changes clearly:

## Suggested README Updates

### Missing Documentation
- `parseConfig(path: string): Config` - Not documented in API section
- `ValidationError` class - Not documented

### Stale Documentation
- `oldFunction()` - Documented but no longer exported

### Signature Changes
- `createClient(url)` → `createClient(url, options?)` - New optional parameter

4.3 Preserving Custom Content

When updating:

• Keep custom sections the user added
• Preserve formatting choices where possible
• Don't overwrite detailed explanations with generated text
• Ask before removing content that might be intentional

---

5. Template and Examples

5.1 README Template

View complete template

Use the template as a starting point. Customize section depth based on package complexity.

5.2 API Documentation Format

For each public export:

### `functionName(param1, param2)`

Brief description of what it does.

| Parameter | Type | Description |
|-----------|------|-------------|
| `param1` | `string` | What this parameter is for |
| `param2` | `Options` | Configuration options |

**Returns:** `ReturnType` - Description of return value

**Example:**
\`\`\`typescript
const result = functionName('input', { option: true });
\`\`\`

5.3 Utility vs Pipeline Packages

• Utility packages (many small exports): Document API inline with examples
• Pipeline packages (one main workflow): Use standalone Examples section with full workflows

---

Quick Reference Checklist

Before finalizing a README, verify:

• [ ] Package manager matches lockfile
• [ ] All public exports are documented
• [ ] Code examples are copy-pasteable
• [ ] Installation instructions work on a fresh machine
• [ ] Examples use current API signatures
• [ ] TOC included if > 200 lines
• [ ] License section present
• [ ] No orphaned documentation for removed exports
• [ ] Content reviewed with humanizer skill for AI writing patterns
• [ ] Writing has personality — not sterile or voiceless

Changelog

[1.1.0] - 2026-05-11

Changed

• Step 2: Parallel Codebase Discovery — restructured to use parallel sub-agents for different discovery domains (entry points, dependencies, examples, docs context)
• Rationale: Following the pattern from accelint-architecture-doc, parallel discovery significantly reduces analysis time on codebases with files spread across directories. When sub-agents are available, spawn them simultaneously rather than scanning serially.
• Agents spawn in parallel: Agent A (Entry Points & Public API), Agent B (Dependencies & Configuration), Agent C (Examples & Usage Patterns), Agent D (Documentation Context)
• Falls back to inline serial discovery when sub-agents are unavailable

Added

• NEVER Do When Writing READMEs section with 6 anti-patterns:
• Never run discovery serially when sub-agents are available
• Never document non-exported internal functions
• Never fabricate usage examples
• Never use the wrong package manager commands
• Never skip comparing code to existing README
• Never write robotic, AI-sounding text
• Rationale: These are expert-level knowledge based on common failure modes. Each includes the WHY behind the rule.

Version

• Bumped from 1.0.0 → 1.1.0

README Writer

A skill for creating and maintaining comprehensive, human-friendly README documentation that stays in sync with your actual codebase.

Overview

This skill helps AI agents create thorough README documentation by:

• Recursively analyzing codebases from the README's location
• Identifying public API and extracting type signatures
• Comparing existing documentation against actual code
• Generating human-sounding documentation with practical examples
• Supporting monorepos by scoping analysis to package boundaries

Quick Start

This skill activates automatically when you ask to create or update a README:

"Create a README for this package"
"Update the README to reflect the new API"
"Document packages/my-lib"

The skill will analyze your codebase and either generate a new README or suggest updates to an existing one.

What This Skill Does

1. Analyzes your code - Parses exports, types, and function signatures 2. Identifies gaps - Finds undocumented exports and stale documentation 3. Generates docs - Creates thorough, copy-pasteable documentation 4. Maintains consistency - Ensures docs match actual functionality

Why This Skill Exists

README files often become outdated as code evolves. This skill ensures:

• Documentation stays accurate without manual tracking
• New exports get documented automatically
• Removed functionality gets flagged for doc cleanup
• Examples stay current with API changes

Key Features

Monorepo Support

In monorepos, the skill scopes analysis to the package containing the README, not the entire repository.

Package Manager Detection

Automatically detects and uses the correct package manager based on lockfiles:

Human-Sounding Writing

Generated documentation reads like it was written by someone who genuinely wants to help, not a robot.

Thorough by Default

When in doubt, the skill includes more detail. Every command is copy-pasteable, examples show expected output, and explanations cover the "why" not just the "what."

README Structure

The skill follows a consistent structure:

1. Heading Area - Title, banner, badges 2. Installation - How to install 3. Quick Start - Minimal working example 4. What - What the package is 5. Why - Why it exists 6. API - Public API reference 7. Examples - Practical usage 8. Further Reading (optional) 9. License 10. Contributing (optional)

File Structure

accelint-readme-writer/
├── SKILL.md              # Main skill instructions
├── AGENTS.md             # Detailed implementation guide
├── README.md             # This file
└── references/
    ├── codebase-analysis.md   # How to parse code for docs
    ├── readme-structure.md    # Section ordering and content
    ├── readme-template.md     # Copy-pasteable template
    └── writing-principles.md  # Human-sounding writing guide

For Humans

While this skill is designed for AI agents, humans can use the references for:

• Understanding good README structure
• Learning documentation best practices
• Creating templates for team standardization
• Reviewing AI-generated documentation

Codebase Analysis

How to parse and understand code for documentation purposes.

---

Scoping the Analysis

Starting Point

Always start from the directory containing the README, not the repository root.

monorepo/
├── packages/
│   ├── core/
│   │   ├── src/
│   │   ├── package.json
│   │   └── README.md      ← Analysis starts here, scoped to core/
│   └── utils/
│       ├── src/
│       ├── package.json
│       └── README.md      ← Separate analysis, scoped to utils/
└── README.md              ← Analysis covers entire monorepo

Package Boundaries

Respect package.json boundaries:

• Only analyze files within the package directory
• Don't document imports from sibling packages as "your" API
• Note peer dependencies that users need to install

---

Identifying Entry Points

Check package.json First

Look for entry point definitions:

{
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.js",
      "types": "./dist/index.d.ts"
    },
    "./utils": {
      "import": "./dist/utils.mjs",
      "require": "./dist/utils.js"
    }
  }
}

This tells you:

• index.ts is the main entry point
• utils.ts is a secondary entry point at package-name/utils

Common Entry Point Patterns

Check these files in order:

1. src/index.ts or src/index.js 2. index.ts or index.js at package root 3. src/main.ts or src/main.js 4. File specified in package.json main field

---

Mapping Public API

What Counts as Public

Only document exports that are accessible to package consumers:

✅ Public (document these)

// src/index.ts
export { parse } from './parser';
export { validate } from './validator';
export type { Config, Options } from './types';

❌ Internal (don't document)

// src/parser.ts
// This is only used internally, not re-exported from index
export function tokenize(input: string) { ... }

Tracing Re-exports

Follow the export chain to find the actual implementation:

// src/index.ts
export { parse } from './parser';

// src/parser.ts
export function parse(path: string): Promise<Config> {
  // implementation
}

Document the function as it appears in parser.ts, but note it's accessed via the main entry point.

Export Patterns to Recognize

// Named exports
export function foo() {}
export const bar = 'bar';
export type Baz = string;

// Re-exports
export { foo } from './foo';
export { foo as bar } from './foo';
export * from './types';
export * as utils from './utils';

// Default exports (discourage in documentation)
export default function foo() {}

---

Extracting Signatures

Function Signatures

Capture complete type information:

// Source
export async function parse<T extends Config>(
  path: string,
  options?: ParseOptions
): Promise<T> {
  // ...
}

// Document as
### `parse<T>(path, options?)`

Parse a configuration file.

| Parameter | Type | Description |
|-----------|------|-------------|
| `path` | `string` | Path to config file |
| `options` | `ParseOptions` | Optional parsing settings |

**Type Parameters:**
- `T extends Config` - The expected config shape

**Returns:** `Promise<T>` - Parsed configuration object

Overloaded Functions

Document all overloads:

// Source
export function format(value: string): string;
export function format(value: number, decimals?: number): string;
export function format(value: Date, pattern?: string): string;

// Document as
### `format(value)`

Format a value as a string. Accepts strings, numbers, or dates.

**Overloads:**

| Signature | Description |
|-----------|-------------|
| `format(value: string): string` | Returns string unchanged |
| `format(value: number, decimals?): string` | Format number with optional decimal places |
| `format(value: Date, pattern?): string` | Format date with optional pattern |

Class Signatures

Document constructor and public methods:

// Source
export class Parser {
  constructor(options?: ParserOptions);
  parse(input: string): Result;
  validate(result: Result): boolean;
}

// Document as
### `Parser`

Configuration parser with validation support.

#### Constructor

new Parser(options?: ParserOptions)

#### Methods

| Method | Returns | Description |
|--------|---------|-------------|
| `parse(input)` | `Result` | Parse input string |
| `validate(result)` | `boolean` | Validate a parse result |

---

Finding Existing Documentation

JSDoc/TSDoc Comments

Extract documentation from source:

/**
 * Parse a configuration file.
 *
 * @param path - Path to the config file
 * @param options - Parsing options
 * @returns Parsed configuration object
 * @throws {ParseError} If file cannot be read or parsed
 *
 * @example
 * const config = await parse('./app.config.yaml');
 */
export async function parse(path: string, options?: Options): Promise<Config> {

Use JSDoc as the primary source for:

• Parameter descriptions
• Return value descriptions
• Thrown errors
• Usage examples

Inline Examples

Look for example usage in:

1. JSDoc @example tags 2. Test files (*.test.ts, *.spec.ts) 3. examples/ directory 4. __examples__/ directory

Test Files as Documentation

Tests often show real usage:

// src/parser.test.ts
describe('parse', () => {
  it('reads JSON config', async () => {
    const config = await parse('./fixtures/config.json');
    expect(config.database.host).toBe('localhost');
  });

  it('interpolates environment variables', async () => {
    process.env.DB_HOST = 'production.db';
    const config = await parse('./fixtures/config.yaml');
    expect(config.database.host).toBe('production.db');
  });
});

Extract patterns from tests for the Examples section.

---

Comparing Code to Documentation

Building the Comparison

1. Parse exports from code:

• List all exports from entry points
• Include types, functions, classes, constants

2. Parse documented API from README:

• Extract all items in API section
• Note function signatures, type names

3. Generate diff:

## Documentation Audit

### Missing from README
- `ValidationError` class - exported but not documented
- `Options` type - exported but not documented
- `validate()` function - exported but not documented

### Stale in README
- `legacyParse()` - documented but no longer exported

### Signature Changes
- `parse(path)` → `parse(path, options?)` - new optional parameter added

### Potentially Outdated Examples
- Quick Start uses `parse()` without await (async function)

Staleness Indicators

Flag documentation as potentially stale when:

• Function signatures don't match
• Documented exports don't exist in code
• Import paths in examples are wrong
• Package manager doesn't match lockfile
• Version numbers are outdated

---

Handling Common Patterns

Barrel Exports

When index.ts re-exports everything:

export * from './parser';
export * from './validator';
export * from './types';

Trace each export * to find actual definitions.

Conditional Exports

When different entry points exist for different environments:

{
  "exports": {
    ".": {
      "node": "./dist/node.js",
      "browser": "./dist/browser.js",
      "default": "./dist/index.js"
    }
  }
}

Document the default behavior, note environment-specific differences.

Namespace Exports

When exports are grouped:

export * as parsers from './parsers';
export * as validators from './validators';

Document as namespaced API:

### `parsers`

Parser utilities.

- `parsers.json(input)` - Parse JSON
- `parsers.yaml(input)` - Parse YAML

### `validators`

Validation utilities.

- `validators.schema(config, schema)` - Validate against schema

README Structure

Detailed guide for README section ordering, content requirements, and formatting.

---

Section Order

READMEs must follow this section order. Users expect to find information in predictable locations.

1.  Heading Area
2.  Table of Contents (if > 200 lines)
3.  Installation
4.  Quick Start
5.  What
6.  Why
7.  API
8.  Examples
9.  Further Reading (optional)
10. License
11. Architecture & Development Guides (optional)
12. Contributing (optional)

---

1. Heading Area

The heading area establishes the package identity at a glance.

Required Elements

• Package title as H1 heading
• Brief tagline (one sentence describing what it does)

Optional Elements

• Banner image
• Badges (npm version, build status, coverage, license)

❌ Incorrect: cluttered, no clear title

![Build](badge) ![Coverage](badge) ![npm](badge) ![Downloads](badge) ![License](badge) ![Stars](badge) ![Forks](badge)

A utility library for parsing configuration files in various formats including JSON, YAML, TOML, and INI with schema validation support.

✅ Correct: clean, focused

# config-parser

Parse configuration files with schema validation.

[![npm version](https://img.shields.io/npm/v/config-parser)](https://npmjs.com/package/config-parser)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

Badge Guidelines

• Keep badges to 3-4 maximum
• Most useful: npm version, license, build status
• Avoid: download counts, star counts, redundant badges

---

2. Table of Contents

Include only for READMEs over ~200 lines. Place after heading area.

✅ Correct format

## Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [What is config-parser?](#what-is-config-parser)
- [Why config-parser?](#why-config-parser)
- [API](#api)
  - [parse](#parse)
  - [validate](#validate)
- [Examples](#examples)
- [License](#license)

Keep to 2 levels deep maximum.

---

3. Installation

How to add this package to a project.

Required Content

• Install command with correct package manager
• Any peer dependencies
• TypeScript note (if types included)

✅ Correct: complete installation section

## Installation

pnpm add config-parser

### Peer Dependencies

If you're using schema validation, you'll also need:

pnpm add zod

TypeScript types are included — no separate `@types` package needed.

---

4. Quick Start

Minimal working example. Get users to "hello world" fast.

Requirements

• Complete, copy-pasteable code
• Runnable without modification
• Shows the primary use case
• Under 20 lines of code

❌ Incorrect: too complex for quick start

## Quick Start

import { createParser, registerFormat, validate, loadSchema } from 'config-parser';

const schema = await loadSchema('./config.schema.json'); const parser = createParser({ formats: ['json', 'yaml', 'toml'], validation: { schema, strict: true }, transforms: [normalizeKeys, expandEnvVars], });

registerFormat('ini', iniPlugin);

const config = await parser.parse('./config.yaml'); const result = validate(config, schema);

✅ Correct: minimal working example

## Quick Start

import { parse } from 'config-parser';

const config = await parse('./config.yaml'); console.log(config); // { database: { host: 'localhost', port: 5432 } }

---

5. What Section

Explain what this package is in 2-4 sentences.

Requirements

• Clear, jargon-free explanation
• What problem domain it addresses
• What form the solution takes (library, CLI, framework)

✅ Correct

## What is config-parser?

config-parser is a TypeScript library for reading configuration files. It supports JSON, YAML, and TOML formats out of the box, and can validate configs against a schema. It handles environment variable interpolation automatically.

---

6. Why Section

Explain why this package was created and what makes it different.

Requirements

• The problem that motivated creation
• What alternatives exist and why this is different
• Who should use this (and who shouldn't)

✅ Correct

## Why config-parser?

Most config libraries make you choose: simple API or powerful features. We wanted both.

- **Simpler than alternatives**: One function call for common cases
- **Type-safe by default**: Full TypeScript support with inference
- **Zero dependencies**: No bloat in your bundle
- **Extensible when needed**: Plugin system for custom formats

If you just need to read JSON, use `JSON.parse`. If you need multi-format support with validation, config-parser saves you from writing the glue code.

---

7. API Section

Document all public exports with signatures and descriptions.

Format for Functions

### `functionName(param1, param2)`

Brief description of what it does.

| Parameter | Type | Description |
|-----------|------|-------------|
| `param1` | `string` | What this parameter is for |
| `param2` | `Options` | Optional configuration |

**Returns:** `Promise<Result>` - Description of return value

**Throws:** `ParseError` - When the file cannot be parsed

**Example:**

const result = await functionName('input.yaml', { strict: true });

Format for Types/Interfaces

### `Config`

Configuration object passed to the parser.

interface Config { /* File formats to support / formats: Format[]; /* Enable strict mode validation / strict?: boolean; }

Format for Constants

### `DEFAULT_OPTIONS`

Default configuration options.

const DEFAULT_OPTIONS = { formats: ['json', 'yaml'], strict: false, } as const;

---

8. Examples Section

Practical usage examples beyond the quick start.

For Utility Packages

Document examples inline with API entries when examples are short.

For Pipeline Packages

Use a standalone Examples section with complete workflows:

## Examples

### Reading a Config File

import { parse } from 'config-parser';

const config = await parse('./app.config.yaml');

### Validating Against a Schema

import { parse, validate } from 'config-parser'; import { configSchema } from './schema';

const config = await parse('./app.config.yaml'); const result = validate(config, configSchema);

if (!result.success) { console.error('Invalid config:', result.errors); process.exit(1); }

### Using Environment Variables

// config.yaml // database: // host: ${DB_HOST} // port: ${DB_PORT:5432} # with default

const config = await parse('./config.yaml'); // Environment variables are interpolated automatically

---

9. Further Reading (Optional)

Links to extended documentation, related projects, or background reading.

✅ Correct

## Further Reading

- [API Reference](./docs/api.md) - Complete API documentation
- [Migration Guide](./docs/migration.md) - Upgrading from v1 to v2
- [YAML Spec](https://yaml.org/spec/) - Understanding YAML syntax

---

10. License

State the license. Link to LICENSE file if present.

✅ Correct

## License

MIT - see [LICENSE](./LICENSE) for details.

---

11. Architecture & Development Guides (Optional)

<!-- Include this section only if any of these files exist: openspec/config.yml, ARCHITECTURE.md, AGENTS.md -->

Links to deeper technical and behavioral documentation that complements the README.

✅ Correct

## Architecture & Development Guides

For deeper technical and behavioral context:

- **[openspec/config.yml](./openspec/config.yml)** — Tech stack, coding patterns, and domain concepts
- **[ARCHITECTURE.md](./ARCHITECTURE.md)** — System architecture, deployment, and data flows
- **[AGENTS.md](./AGENTS.md)** — How AI agents should behave when working in this codebase

These documents form a layered guidance system: config.yml defines what the project is, ARCHITECTURE.md explains how it's structured and deployed, and AGENTS.md governs how agents collaborate on it.

Note: Only include files that actually exist. Check for openspec/config.yml (or config.yaml), ARCHITECTURE.md, and AGENTS.md/CLAUDE.md before adding this section. If none exist, omit this section entirely.

---

12. Contributing (Optional)

How to contribute to the project.

✅ Correct

## Contributing

Contributions welcome! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) before submitting PRs.

Run tests

pnpm test

Run linting

pnpm lint

README Template

Copy-pasteable template for new README files. Replace placeholders with actual content.

---

The Template

````markdown

package-name

Brief one-line description of what this package does.

 

<!-- Include Table of Contents only if README exceeds ~200 lines --> <!--

Table of Contents

• Installation
• Quick Start
• What is package-name?
• Why package-name?
• API
• Examples
• License

-->

Installation

pnpm add package-name

<!-- Add peer dependencies section if needed --> <!--

Peer Dependencies

pnpm add required-peer-dep

-->

<!-- Add TypeScript note if types are included --> TypeScript types are included.

Quick Start

import { mainFunction } from 'package-name';

const result = mainFunction('input');
console.log(result);
// Expected output here

What is package-name?

2-4 sentences explaining what this package is. Cover:

• What problem domain it addresses
• What form the solution takes (library, CLI, framework)
• Key capabilities at a high level

Why package-name?

Explain why this package was created:

• The problem that motivated its creation
• How it differs from alternatives
• Who should use this (and who might prefer something else)

API

mainFunction(input, options?)

Description of what this function does.

Returns: ReturnType - Description of return value

Example:

const result = mainFunction('input', { option: true });

---

SecondaryClass

Description of this class.

Constructor

new SecondaryClass(config: Config)

Methods

Example:

const instance = new SecondaryClass({ setting: 'value' });
const result = instance.process(data);

---

HelperType

Type definition for configuration.

interface HelperType {
  /** Required field description */
  required: string;
  /** Optional field description */
  optional?: number;
}

Examples

Basic Usage

import { mainFunction } from 'package-name';

const result = mainFunction('simple input');

With Configuration

import { mainFunction } from 'package-name';

const result = mainFunction('input', {
  verbose: true,
  format: 'json',
});

Error Handling

import { mainFunction, PackageError } from 'package-name';

try {
  const result = mainFunction('input');
} catch (error) {
  if (error instanceof PackageError) {
    console.error('Package error:', error.message);
  }
  throw error;
}

<!-- Include Further Reading only if you have external resources --> <!--

Further Reading

• Full API Documentation
• Migration Guide
• Related Project

-->

License

MIT - see LICENSE for details.

<!-- Include Contributing only if accepting contributions --> <!--

Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

# Run tests
pnpm test

# Run linting
pnpm lint

--> ````

---

Template Customization Guide

For Utility Packages

Utility packages have many small, independent functions. Customize by:

• Keeping API section comprehensive with all exports
• Including examples inline with each API entry
• Removing standalone Examples section if API examples are sufficient

For Pipeline Packages

Pipeline packages have one main workflow. Customize by:

• Keeping API section focused on main entry points
• Expanding Examples section with complete workflows
• Adding step-by-step guides for common tasks

For CLI Tools

CLI packages need command documentation. Add:

## Usage

package-name <command> [options]

### Commands

| Command | Description |
|---------|-------------|
| `init` | Initialize a new project |
| `build` | Build the project |
| `serve` | Start development server |

### Options

| Option | Default | Description |
|--------|---------|-------------|
| `--config, -c` | `./config.json` | Path to config file |
| `--verbose, -v` | `false` | Enable verbose output |
| `--help, -h` | | Show help |

### Examples

Initialize with defaults

package-name init

Build with custom config

package-name build --config ./my-config.json

Start server in verbose mode

package-name serve --verbose

For Monorepo Packages

When documenting a package within a monorepo, add context:

## Installation

This package is part of the `@org/monorepo` monorepo.

From monorepo root

pnpm add @org/package-name

Or if using workspace protocol

pnpm add @org/package-name@workspace:*

---

Section Length Guidelines

Total target: 100-300 lines for most packages.

---

Checklist Before Publishing

Use this checklist to verify README completeness:

• [ ] Package name in title matches package.json
• [ ] Install command uses correct package manager
• [ ] Quick Start code is copy-pasteable and runs
• [ ] All public exports are documented in API section
• [ ] Examples use current API (not deprecated patterns)
• [ ] License matches package.json license field
• [ ] No broken internal links
• [ ] No placeholder text remaining
• [ ] TOC included if > 200 lines
• [ ] Badges link to correct URLs

Writing Principles

Guidelines for creating thorough, human-sounding documentation.

REQUIRED SUB-SKILL: Use humanizer to review generated content for AI writing patterns.

This document covers README-specific writing principles. The humanizer skill provides comprehensive patterns for removing AI-generated text artifacts. Use both together.

---

1. Be Absurdly Thorough

When in doubt, include it. More detail is always better for documentation.

❌ Incorrect: assumes too much knowledge

## Installation

Install the package and configure it.

✅ Correct: explains everything

## Installation

Install the package using your preferred package manager:

pnpm add @acme/toolkit

If you're using TypeScript, you're all set — types are included. For JavaScript projects, the package works with both CommonJS and ESM.

---

2. Use Code Blocks Liberally

Every command should be copy-pasteable. Don't describe commands in prose when you can show them.

❌ Incorrect: describes instead of shows

Run the build script using pnpm to compile the TypeScript files.

✅ Correct: shows the actual command

Build the project:

pnpm build

This compiles TypeScript to JavaScript in the `dist/` directory.

---

3. Show Example Output

When helpful, show what the user should expect to see. This confirms they're on the right track.

❌ Incorrect: no indication of success

pnpm test

✅ Correct: shows expected output

pnpm test

You should see output like:

✓ src/parser.test.ts (12 tests) 45ms ✓ src/validator.test.ts (8 tests) 23ms

Test Files 2 passed (2) Tests 20 passed (20)

---

4. Explain the Why

Don't just say "run this command" — explain what it does and why someone would need it.

❌ Incorrect: what without why

Set the `DEBUG` environment variable:

export DEBUG=true

✅ Correct: includes motivation

For verbose logging during development, enable debug mode:

export DEBUG=true

This prints detailed information about each step, which is helpful when tracking down issues but too noisy for production.

---

5. Assume Fresh Machine

Write as if the reader has never seen this codebase. Don't assume they know your conventions.

❌ Incorrect: assumes familiarity

After cloning, run the usual setup commands.

✅ Correct: spells it out

After cloning the repository:

git clone https://github.com/acme/toolkit.git cd toolkit pnpm install

This installs all dependencies. The first install may take a few minutes.

---

6. Use Tables for Reference

Environment variables, CLI options, configuration options, and script references work great as tables.

❌ Incorrect: hard to scan

The `format` option can be "json" or "yaml". The `output` option specifies where to write results. The `verbose` option enables detailed logging.

✅ Correct: scannable table

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `format` | `"json" \| "yaml"` | `"json"` | Output format |
| `output` | `string` | `"./out"` | Output directory |
| `verbose` | `boolean` | `false` | Enable detailed logging |

---

7. Keep Commands Current

Detect the actual package manager and use it consistently. Never assume npm.

❌ Incorrect: wrong package manager

# Project uses pnpm (has pnpm-lock.yaml)

npm install
npm run build

✅ Correct: matches project tooling

# Project uses pnpm (has pnpm-lock.yaml)

pnpm install
pnpm build

Package Manager Detection

Check for lockfiles in this order:

1. pnpm-lock.yaml → use pnpm 2. yarn.lock → use yarn 3. bun.lockb → use bun 4. package-lock.json → use npm

---

8. Write Like a Human

Sound like someone who genuinely wants to help, not a robot generating documentation.

❌ Incorrect: robotic

The function accepts a configuration object parameter. The configuration object must contain the required fields. An error will be thrown if required fields are missing.

✅ Correct: conversational

Pass in a config object with your settings. At minimum, you need `apiKey` and `endpoint` — the function will let you know if anything's missing.

Avoid These Patterns

• Overly formal: "It should be noted that..." → "Note that..."
• Passive voice: "The file is read by the parser" → "The parser reads the file"
• Unnecessary hedging: "This may potentially help" → "This helps"
• Corporate speak: "Leverage the functionality" → "Use"
• Filler phrases: "In order to" → "To"

Aim For

• Direct, active voice
• Second person ("you") when addressing the reader
• Contractions where natural (it's, you'll, don't)
• Concrete examples over abstract descriptions
• Personality without being unprofessional

---

9. Include a Table of Contents

For READMEs over ~200 lines, add a TOC at the top after the heading area.

✅ Good TOC format

## Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [API Reference](#api-reference)
  - [createClient](#createclient)
  - [parseConfig](#parseconfig)
- [Examples](#examples)
- [License](#license)

Keep TOC entries to 2 levels deep maximum. Deeper nesting makes the TOC harder to scan than the document itself.

---

10. Remove AI Writing Patterns

After drafting content, apply the humanizer skill to catch patterns this guide doesn't cover. Key patterns to watch for in README context:

Significance Inflation

❌ AI pattern:

This package serves as a pivotal tool in the JavaScript ecosystem, marking a crucial advancement in configuration management.

✅ Human version:

This package parses config files. It supports JSON, YAML, and TOML.

Promotional Language

❌ AI pattern:

Nestled within the Node.js ecosystem, this groundbreaking library offers seamless, intuitive, and powerful configuration management.

✅ Human version:

A config parser for Node.js projects.

Superficial -ing Phrases

❌ AI pattern:

The validate function checks your config, ensuring compliance with your schema while highlighting any issues.

✅ Human version:

The validate function checks your config against a schema and returns any errors.

Vague Attributions

❌ AI pattern:

Industry experts agree this approach improves developer productivity.

✅ Human version:

In our benchmarks, this reduced config load time by 40%.

(Or just remove the claim entirely if you don't have specific data.)

Rule of Three

❌ AI pattern:

The package is fast, flexible, and fully featured.

✅ Human version:

The package is fast. See benchmarks below.

Generic Conclusions

❌ AI pattern:

The future looks bright for this project as we continue our journey toward excellence.

✅ Human version:

See the roadmap in CONTRIBUTING.md for planned features.

---

11. Add Personality (Not Just Remove Patterns)

Avoiding AI patterns is only half the job. Sterile, voiceless writing is just as obvious.

Signs of soulless writing:

• Every sentence is the same length
• No opinions, just neutral reporting
• No first-person perspective when appropriate
• Reads like a press release

How to add voice:

Have opinions when relevant:

# ❌ Sterile
The library provides configuration parsing functionality.

# ✅ Has a pulse
Config files are a pain. This library makes them less painful.

Acknowledge tradeoffs:

# ❌ Too neutral
The library supports multiple formats.

# ✅ Honest
We support JSON, YAML, and TOML. We don't support INI because frankly it's a mess to parse reliably.

Use "you" and "we" naturally:

# ❌ Distant
The user should run the install command.

# ✅ Direct
Run the install command.

Vary rhythm:

# ❌ Monotonous
This function parses configs. It returns an object. It throws on invalid input.

# ✅ Varied
Parse a config file. You get back a typed object, or an error if something's wrong.