add-reference

Add Reference

Create or update structured reference documentation under a skill's references/ directory.

Usage

/add-reference my-domain entities      # Update entity inventory
/add-reference my-domain api-endpoints # Document API surface
/add-reference my-domain               # Update all references for skill
/add-reference my-domain new-topic     # Create new reference

Reference Types

Domain Knowledge

Business rules, regulations, external system behavior. Not generated from code.

Codebase Inventories

Generated by scanning project source. Kept in sync as codebase evolves.

Process

1. Determine Scope

Parse skill name and topic. If no topic, update all references.

2a. Domain Knowledge

1. Ask user for source material
2. If none, scan codebase for clues
3. Structure with tables and categories
4. Include source attribution

2b. Codebase Inventories

Scan relevant directories:

Reference Type	What to Extract
Entities/Models	Names, key fields, types, relationships
Classes/Modules	Names, purpose, category, key methods
API Endpoints	Routes, methods, parameters, responses
Configuration	Config keys, types, defaults
Test Helpers	Factories, fixtures, builder patterns

3. Generate or Update

• Existing file: Read current, merge new findings, preserve manual notes
• New file: Create using formats below

Write to: .claude/skills/{skill}/references/{topic}.md

Output Formats

Domain Knowledge

# {Topic} Reference

## Overview
{One paragraph context}

## {Category}

| {Key Column} | {Details} | {Notes} |
|--------------|-----------|---------|

## Source
{Attribution}

Codebase Inventory — Entities

# {Skill} Entities Reference

## {Entity_Name}

**Purpose:** {one-line description}

| Property | Type | Notes |
|----------|------|-------|
| `field` | String | {note} |

**Key Relationships:**
- Parent: `ParentEntity` via `parent_id`