amhuppert/create-reference

Reference Document Creator

Create or update reference documents that provide AI agents with comprehensive knowledge of a tool, technology, library, framework, or API. The resulting document enables an AI agent to work effectively with the subject without prior knowledge.

<subject> Use the subject and options supplied in the user's invocation. </subject>

Step 1: Parse the Request

Determine the mode and subject from the arguments:

• Create mode (default): Generate a new reference document
• Update mode: If --update <path> is specified or the user asks to update an existing document, read the existing document in full first, then research only the new topic areas and integrate them into the existing structure. Where old and new content contradict, new content takes precedence; remove outdated information. Preserve the overall structure unless the user requests restructuring.

Determine the subject source:

• Public tool/library/framework: Subject is identified by name (e.g., "Zod", "React Router v7", "Playwright"). Perform web research.
• Local codebase/tool: Subject is a local directory or file path. Explore the codebase.
• Both: Some subjects benefit from combining web research with local codebase analysis.

If the subject or scope is ambiguous, ask the user to clarify:

• What specific aspects to cover (full API, specific module, common patterns)
• Target language if the tool supports multiple (e.g., BAML supports TypeScript and Python)
• Intended audience context (what types of projects will use this reference)

Step 2: Research the Subject

Conduct thorough research to build comprehensive understanding.

For Public Tools/Libraries

1. Search for official documentation: API references, getting started guides, configuration docs
2. Search for guides and tutorials: Practical usage patterns, common recipes, best practices
3. Search for changelogs and migration guides: Recent breaking changes or important version-specific behavior
4. Fetch key documentation pages: Read official docs pages in full with the active client's browsing capability to extract precise API details, function signatures, configuration options, and examples
5. Search for common pitfalls: Known gotchas, common mistakes, debugging tips

For Local Codebases

1. Explore the project structure: Search files and list directories to understand organization
2. Read key files: Entry points, configuration files, READMEs, type definitions, public API surfaces
3. Identify the public API: Exported functions, classes, types, CLI commands, configuration options
4. Find usage examples: Tests, examples directories, README snippets
5. Check for existing documentation: Internal docs, JSDoc comments, docstrings

When combining both sources, local code takes precedence where web documentation contradicts the actual implementation.

Step 3: Organize and Draft the Reference

Document Structure Template

# [Subject Name] Reference Guide for AI Agents

<Overview>
[1-3 sentence description of what the tool does and its primary use case.]
[Key workflow or mental model in one sentence.]
</Overview>

## Installation / Setup

[Commands, dependencies, prerequisites]

## Core Concepts

[Key mental models and terminology the agent must understand]

## API Reference / Key APIs

[Function signatures, parameters, return types]
[Organized by logical groupings]

## Configuration

[Config files, environment variables, options]

## Common Patterns

[Practical recipes for frequent tasks]

## Commands / CLI

[If applicable: command syntax, flags, examples]

## Troubleshooting / Gotchas

[Common pitfalls and their solutions]

Adapt this structure to the subject — not all sections apply to every tool, and the structure should follow the natural workflow of using it.

Writing Standards

Format:

• Use bulleted lists over prose, one concept per bullet
• Imperative form for instructions ("Run npm install", not "You should run npm install")
• Include code blocks for all commands, API calls, and configuration examples
• Use tables for reference data (options, flags, type mappings)
• Use Mermaid diagrams for architectural concepts or workflows when clearer than text
• Use XML tags (<Overview>, <critical>, <example>) for structural clarity where appropriate

Content:

• Optimize for AI agent consumption: high information density, minimal tokens, no redundancy between sections
• Include precise API signatures with types, and concrete code examples rather than abstract descriptions
• Specify versions when version-specific behavior exists
• Include the "why" only when it prevents common misuse
• Omit information any LLM would already know
• Focus on actionable knowledge: what to do, how to do it, what to avoid

Code examples:

• Keep examples minimal but complete (runnable when possible)
• Show the most common usage first, then variations
• Include expected output or return values when non-obvious
• Annotate with inline comments for non-obvious behavior

Step 4: Validate the Document

Before saving, verify:

• [ ] Covers installation/setup, core concepts, all major API surfaces with signatures, and common real-world patterns
• [ ] Code examples exist for each major feature and use correct syntax for the documented version
• [ ] Document enables an agent to start using the tool without any other resources

Step 5: Save the Document

For new documents:

• Save to agent-docs/ directory in the project root
• Filename: <subject-name>-reference.md (kebab-case), or <subject-name>-reference-<language>.md for language-specific variants
• If the subject warrants multiple files, create a subdirectory: agent-docs/<subject-name>/

For updates, edit the existing file in place.

After saving, report the file path and a brief summary of what the document covers.