Reference Creation

Create references/ directories for complex skills. Reference files organize content into focused sub-topic guides, improving navigability and token efficiency.

When to Use

Skill has 40+ patterns or 4+ distinct sub-topics
SKILL.md would exceed 300 lines with all patterns inline
Advanced techniques would overwhelm beginners in main SKILL.md

Don’t use for:

Simple skills (<15 patterns, 1 topic)
Skills that fit comfortably in SKILL.md alone

Critical Patterns

✅ REQUIRED: Assess Complexity First

Before creating references, verify skill meets threshold:

At least 2 of:
- 40+ patterns?
- 4+ sub-topics?
- Natural groupings?
- SKILL.md would exceed 300 lines?

✅ REQUIRED: Identify Sub-Topics

1. List ALL patterns in SKILL.md
2. Group by theme (what goes together?)
3. Identify clusters of 10-20 related patterns
4. Name clusters descriptively (not "advanced" or "misc")
5. Validate: Each cluster independently learnable?

Example (React skill):

70 patterns →
  - hooks.md (25 patterns: useState, useEffect, custom hooks)
  - components.md (18 patterns: composition, props, HOCs)
  - performance.md (15 patterns: memo, useMemo, code splitting)
  - server-features.md (12 patterns: SSR, RSC, data fetching)

✅ REQUIRED: Name Files Descriptively

# ✅ CORRECT
hooks.md
server-components.md
type-guards.md

# ❌ WRONG
advanced.md        # Too vague
misc.md            # Catch-all
part2.md           # Meaningless ordering

Rule: {topic-description}.md (lowercase, hyphens, descriptive)

✅ REQUIRED [CRITICAL]: Create README.md

Every references/ directory MUST have README.md:

# {Skill Name} References

> {One-line description}

### Quick Navigation

| Reference                    | Purpose   | Read When     |
| ---------------------------- | --------- | ------------- |
| [sub-topic.md](sub-topic.md) | {Purpose} | {When needed} |

### Reading Strategy

For Simple Use Cases:
- Read main SKILL.md only

For Complex Use Cases:
- MUST read: {reference1}, {reference2}
- Optional: {reference3}

✅ REQUIRED: Content Distribution

SKILL.md (300 lines max):

Top 10-15 CRITICAL patterns only
Basic examples (<15 lines each)
Decision Tree with reference links
Resources section listing ALL references

Reference files (200-600 lines each):

Deep dive into ONE sub-topic
10-20 patterns for that topic
Real-world examples (complete code)
Common pitfalls and edge cases

### ✅ REQUIRED [CRITICAL]: Custom Hooks

{Brief inline example}

**For advanced hook patterns:** See [references/hooks.md](references/hooks.md).

✅ REQUIRED: Cross-Link Files

From SKILL.md to references:

### Resources

- [Hooks](references/hooks.md) - useState, useEffect, custom hooks
- [Components](references/components.md) - Composition, HOCs, render props

**See [references/README.md](references/README.md) for complete navigation.**

Between references:

### Related Topics

- See [components.md](components.md) for component composition patterns
- See [performance.md](performance.md) for optimization techniques

✅ REQUIRED [CRITICAL]: Token Efficiency

References must be precise yet economical. Remove filler, condense verbose phrases, eliminate redundancy.

Filler words to remove: “comprehensive”, “detailed”, “robust”, “various”, “multiple”, “This reference provides…”, “It is important to note…”, “In order to”, “Keep in mind”

Condensing patterns:

# ❌ WRONG (verbose)
This section provides comprehensive guidance on how to implement custom hooks.

# ✅ CORRECT (token-efficient)
Covers custom hook implementation in React.

Rule: Every word must add value. If removing a word doesn’t lose meaning, remove it.

See references/templates.md for the full reference file structural template.

✅ REQUIRED: Reference File Structure

Each reference file follows: # Title → 1-2 sentence summary → ## Core Patterns (FIRST H2) → patterns with inline examples → ## Common Pitfalls → ## Real-World Examples → ## Related Topics.

Key constraints:

## Core Patterns must be the FIRST H2 heading in every reference file
NO “Overview” or “Purpose” section before Core Patterns
Use H3 (###) inside reference files to avoid duplicate H2 violations

❌ NEVER: Create Catch-All References

# ❌ WRONG
references/advanced.md    # What's "advanced"?
references/misc.md        # No focus

# ✅ CORRECT
references/optimization.md     # Specific topic
references/type-inference.md   # Specific concept

❌ NEVER: Duplicate Content

References EXPAND on SKILL.md, never repeat it:

SKILL.md: basic useState example (5 lines)
hooks.md: 5-7 useState patterns NOT in SKILL.md

❌ NEVER: Create Too Many Small Files

# ❌ Bad: 10 files, 50 lines each
references/useState.md (50 lines)

# ✅ Good: 1 file, 400 lines, organized
references/hooks.md (400 lines)
  - useState section
  - useEffect section

Target 2-9 references. Hard limit: 10 (enforced by tests). More = harder to discover.

Decision Tree

Skill complexity: <40 patterns?
  → Yes: Use SKILL.md only (no references needed)
  → No: Continue assessment

Natural sub-topics exist (4+)?
  → No: Consider if patterns are truly related to same skill
  → Yes: Plan references/ directory

Each sub-topic has 10+ patterns?
  → No: Merge sub-topics or keep inline in SKILL.md
  → Yes: Create reference file for each sub-topic

References count: 2-10 files?
  → No (>10): Consolidate — hard limit is 10 (enforced by tests)
  → Yes: Create references/ with README.md

README.md created with navigation?
  → No: MUST create (CRITICAL)
  → Yes: Validate cross-links and sync

Token efficiency applied?
  → No: Remove filler words, condense verbose phrases, eliminate redundancy
  → Yes: Ready for review

Workflow

Assess complexity → Verify 40+ patterns or 4+ sub-topics (at least 2 criteria met)
Identify sub-topics → Group into 4-9 clusters of 10-20, descriptively named
Create structure → mkdir references/ + README.md (Quick Navigation, Reading Strategy) + topic files
Distribute content → Top 15 in SKILL.md, deep dives in references (200-600 lines each, no duplication)
Apply token efficiency → Remove filler words, condense verbose phrases, eliminate redundancy
Cross-link → SKILL.md↔references, references↔references, Resources section lists all references
Validate → Run checklist, verify links, sync to model directories

Example

React skill (70 patterns) split into 4 references:

skills/react/
├── SKILL.md (300 lines — top 15 patterns, decision tree, links)
└── references/
    ├── README.md (navigation + reading strategy)
    ├── hooks.md (400 lines — useState, useEffect, custom hooks)
    ├── components.md (350 lines — composition, props, HOCs)
    ├── performance.md (300 lines — memo, useMemo, code splitting)
    └── server-features.md (250 lines — SSR, RSC, data fetching)

README.md has 4 required sections: Quick Navigation table (with line counts), Reading Strategy per use case, File Descriptions, Cross-Reference Map. See interface-design/references/README.md for a real example.

Edge Cases

Version-specific patterns: Create separate files (hooks-react-17.md, hooks-react-18.md) or sections within file.

Cross-cutting concerns: Create dedicated reference (e.g., token-efficiency.md in skill-creation).

Too few patterns per sub-topic: Merge sub-topics or keep inline in SKILL.md.

References exceeding 800 lines: Split into sub-references (hooks-state.md, hooks-effects.md).

Checklist

Resources

REFERENCE-TEMPLATE.md - Template for individual reference files
skill-creation - Main skill creation workflow
code-conventions - Coding standards
critical-partner - Quality validation
references/README.md - Reference file navigation
references/templates.md - Full reference file template and examples