Skill: documentation generator

This skill reads your codebase and generates or updates documentation to match the style already in use. Point it at a single file and it adds docstrings. Point it at the whole project and it rebuilds your README with current architecture, commands, and file structure. It detects manually-written sections and leaves them alone.

The skill file

Copy the following into .claude/skills/doc-generator.md (or wherever your agent loads skills from). This is the complete, working skill definition.

# Documentation generator

## Purpose

Generate or update documentation for code. Supports three scopes: a single file, a directory, or the full project. Always matches the documentation style already present in the codebase.

## When to use

- The user asks to document a file, module, or project
- The user asks to update the README
- The user asks to add docstrings, JSDoc, or inline comments
- The user asks to generate an API reference

## Inputs

- **scope**: one of `file`, `directory`, or `project`
- **target**: path to the file or directory (ignored for project scope, defaults to repo root)

## Steps

### 1. Analyze existing documentation style

Before writing anything, study what already exists.

- For file scope: read the target file and 2-3 nearby files in the same directory. Note the docstring format (JSDoc, Google-style Python docstrings, Rust doc comments, etc.), level of detail, and tone.
- For directory scope: read the directory's README or index file if one exists. Sample 3-5 files to understand the module's purpose and conventions.
- For project scope: read the root README.md, CONTRIBUTING.md, and any docs/ directory. Note which sections exist, their heading style, and formatting conventions.

If no existing documentation exists, use these defaults:

- Python: Google-style docstrings
- TypeScript/JavaScript: JSDoc with `@param`, `@returns`, `@throws`
- Rust: `///` doc comments with examples
- Go: standard godoc format
- Other languages: block comments above functions with param/return descriptions

### 2. Read the code

- For file scope: read the entire target file.
- For directory scope: list all source files in the directory. Read each one.
- For project scope: identify the project structure by reading the top-level directory listing, package manifest (package.json, pyproject.toml, Cargo.toml, go.mod), and entry points. Read key source files (not every file, focus on public interfaces and main modules).

Build a mental model of:

- What the code does (purpose, inputs, outputs)
- Public API surface (exported functions, classes, types)
- Dependencies and relationships between modules
- Commands (scripts in package.json, Makefile targets, CLI entry points)

### 3. Detect manually-written sections

Before generating any documentation, identify sections that a human wrote intentionally. These must be preserved exactly as-is.

Markers of manually-written content:

- Sections with prose paragraphs (not just auto-generated lists)
- Content between `<!-- manual-start -->` and `<!-- manual-end -->` comment markers
- Sections titled "Contributing", "License", "Acknowledgments", "Philosophy", "Why this exists"
- Any section containing links to external resources, blog posts, or discussions
- Content that references specific decisions, tradeoffs, or history

When you encounter these sections, preserve them verbatim in their original position.

### 4. Generate documentation

#### File scope

Add or update documentation for every public function, class, method, type, and constant. For each:

- Write a one-line summary of what it does
- Document parameters with types and descriptions
- Document return values
- Document thrown exceptions or error conditions
- Add a brief usage example if the function's purpose is not obvious from its name

Do NOT add documentation to:

- Private/internal helper functions that are self-explanatory (under 5 lines, clear name)
- Import statements
- Simple constant assignments where the name says it all

Place documentation in the position conventional for the language (above the definition for most languages).

#### Directory scope

Generate or update the directory's README.md with:

- One-paragraph module description
- List of public files and what each contains
- Usage example showing how to import and use the module
- Any configuration or setup needed

Then apply file scope documentation to each source file in the directory.

#### Project scope

Generate or update the root README.md with these sections (skip any that don't apply):

1. **Project name and one-line description** (from package manifest or existing README)
2. **What it does** (2-3 sentences, derived from reading the code)
3. **Getting started** (install commands, prerequisites)
4. **Usage** (primary commands, basic examples)
5. **Architecture** (file/directory structure with one-line descriptions)
6. **Configuration** (environment variables, config files)
7. **Development** (how to run tests, dev server, build)
8. **API reference** (if the project exposes a programmatic API, summarize it here or link to generated docs)

Preserve all manually-written sections identified in step 3. Insert them in their original positions.

For the Architecture section, generate a tree view like:

```
src/
  components/    # Reusable UI components
  pages/         # Route handlers
  utils/         # Shared helper functions
  config.ts      # App configuration
```

### 5. Verify nothing broke

After writing documentation:

- If the project has a build command (found in package.json scripts, Makefile, etc.), run it. Documentation changes should not break builds, but template literals in docstrings or malformed comments can cause syntax errors.
- If the project has a linter configured, run the lint command.
- If either command fails, read the error, fix the documentation that caused it, and run again.

Report what was generated: number of files documented, sections added to README, and whether the build/lint passed.

## Output format

Summarize what was done:

```
Documented 12 functions across 4 files.
Updated README.md: added Architecture and Development sections.
Preserved 2 manually-written sections (Contributing, Philosophy).
Build passed. Lint passed.
```

## Important rules

- NEVER delete or rewrite manually-written documentation sections
- NEVER generate documentation that contradicts the code (if a function returns a string, don't say it returns a number)
- NEVER add boilerplate filler ("This function is used to..." just say what it does)
- Keep the same tone as existing documentation. If the project uses casual language, don't switch to formal. If it uses formal language, don't switch to casual.
- If you are unsure about a function's purpose, say so briefly rather than guessing wrong

How to install it

Create the file at .claude/skills/doc-generator.md in your project root. If you are using Claude Code, skills in this directory are loaded automatically when the agent starts a session in the project.

mkdir -p .claude/skills
# paste the skill content into this file
touch .claude/skills/doc-generator.md

If your agent uses a different skill loading mechanism, adapt the path accordingly. The content is plain markdown, so it works with any system that reads skill definitions from files.

Example usage

Ask the agent to document a specific file:

> Document src/utils/parser.ts

Reading src/utils/parser.ts and nearby files to match documentation style...
Found JSDoc format in use (3 of 4 files in src/utils/ use @param/@returns).

Added documentation to 6 functions in src/utils/parser.ts:
- parseConfig(): parses YAML config into typed options
- validateSchema(): checks parsed config against JSON schema
- mergeDefaults(): fills missing config values with defaults
- normalizeKeys(): converts kebab-case keys to camelCase
- readConfigFile(): reads and parses a config file from disk
- ConfigError (class): custom error for config parsing failures

Build passed. Lint passed.

Ask the agent to update the whole project:

> Update the project README with current architecture

Reading existing README.md...
Found 4 manually-written sections: Philosophy, Contributing, License, Acknowledgments.

Updated README.md:
- Rewrote "What it does" to reflect new CLI interface
- Added Architecture section with file tree
- Updated Development section (new test command, added build step)
- Preserved 4 manually-written sections in original positions

Build passed.

How it works

The skill follows a read-then-write pattern that prevents the most common documentation generation mistakes. Here is what each part does and why.

Style matching comes first. Step 1 reads existing files before generating anything. This is the difference between documentation that fits in and documentation that looks pasted from a template. If your project uses /** */ JSDoc blocks, the skill should not start writing // comments. The skill instructions explicitly list default conventions per language as a fallback, so it still produces something reasonable for undocumented codebases. For more on why ordering steps carefully matters, see writing effective skill instructions.

Manual section detection prevents overwrites. Step 3 defines specific markers of human-authored content (prose paragraphs, specific section titles, comment markers). Without this step, the agent would happily replace your carefully written “Philosophy” section with a generated summary. The <!-- manual-start --> and <!-- manual-end --> markers give you explicit control for edge cases where the heuristics might miss something.

The verify step catches breakage. Documentation changes can break builds in surprising ways. A backtick inside a template literal docstring, a malformed JSDoc tag that confuses TypeScript, a Python docstring that breaks indentation. Step 5 runs the build and lint commands to catch these problems immediately, before you discover them later in CI.

The output summary is structured. Instead of just saying “done,” the skill reports exactly what changed and whether checks passed. This matters because documentation generation touches many files and the user needs to know the blast radius. The pattern of summarizing actions taken is covered in how to design AI agent skills.

Customizing it

Add or change default conventions. The fallback conventions in step 1 cover common languages, but your project might have its own standard. Add a line like: “For this project, always use NumPy-style docstrings for Python.” Put project-specific overrides at the top of the style analysis section.

Expand the manual section markers. If your project has sections that should never be touched (changelog entries, auto-generated badges, sponsor lists), add them to the list in step 3. The more specific you are, the fewer accidental overwrites.

Change the architecture output format. The tree view format in step 4 works for most projects, but you might prefer a table or a flat list. Replace the example in that section with your preferred format and the agent will follow it.

Skip verification for speed. If you are generating docs for a branch that is not expected to build yet, remove step 5 or change it to only run the linter. The tradeoff is that you might commit documentation that breaks the build, but for early-stage work that can be acceptable.

Scope down for monorepos. For large repositories, project scope can be too broad. Add a note to step 2: “For project scope in a monorepo, only document the package at the repo root. Treat each sub-package as a separate directory scope.” This keeps the agent from trying to document the entire monorepo in one pass.