---
name: docs-plugin-builder
description: Build scalable documentation plugins using the docs-skill + application-skill architecture. Prevents context explosion via grep-driven discovery and cross-linking. Based on proven spanner-mastery pattern.
trigger: When building comprehensive documentation skills, creating doc-heavy plugins, or avoiding context bloat with large reference material
keywords: documentation, plugin, architecture, grep, cross-links, scalability, token-efficiency, skills, meta
version: 1.0.0
---

# Documentation Plugin Builder

This skill teaches you how to build token-efficient documentation plugins that scale to thousands of pages without context explosion.

## The Problem

**Traditional approach fails at scale:**
- Load 1000+ pages of docs into one skill → immediate context bloat
- Can't load multiple skills simultaneously → poor composability
- Mixing reference docs with patterns → unfocused, hard to navigate
- Result: Unusable at scale, poor user experience

**What we need:**
- Access to comprehensive documentation without loading it all
- Multiple focused skills that compose well
- Quick discovery without grep gymnastics
- Token-efficient design that scales infinitely

## The Solution: Docs + Application Architecture

**Core principle:** Separate documentation from application patterns, use grep for discovery.

```
your-plugin/
├── tech-docs/              # Pure reference material + grep patterns
│   ├── SKILL.md            # How to find things via grep
│   └── references/         # Scraped/copied documentation
│       ├── guides/
│       ├── api-reference/
│       └── samples/
│
├── tech-patterns/          # Focused application patterns
│   └── SKILL.md            # Patterns + cross-links to docs
│
├── tech-advanced/          # Advanced patterns
│   └── SKILL.md            # Advanced + cross-links to docs
│
└── tech-integration/       # Integration patterns
    └── SKILL.md            # Integration + cross-links to docs
```

**Why this works:**
- **Docs skill**: Passive, searchable via grep (300-500 lines)
- **Application skills**: Active, focused patterns (300-400 lines each)
- **Total context**: ~1000 lines across 4 skills vs 3000+ in one skill
- **Scales**: Add more application skills without loading more docs

## Five-Phase Implementation

### Phase 1: Documentation Collection

**1.1 Identify documentation sources**

Common sources:
- Official documentation websites
- GitHub repositories (README, wiki, docs/)
- API reference sites
- Blog posts and tutorials
- Code examples and samples

**1.2 Organize URLs into categories**

Create TOC (Table of Contents) files for tracking:

```markdown
<!-- references/guides/TOC.md -->
- Getting Started: https://docs.example.com/getting-started
- Core Concepts: https://docs.example.com/concepts
- Best Practices: https://docs.example.com/best-practices
```

Categories to consider:
- **Guides**: Conceptual explanations, tutorials
- **API Reference**: Function/class/method documentation
- **Samples**: Code examples, recipes
- **Resources**: Whitepapers, case studies, videos

**1.3 Choose scraping method**

Options:
- **FireCrawl API**: Clean markdown extraction (recommended)
- **Manual copy-paste**: For small doc sets
- **Web scraping scripts**: For custom needs
- **Git submodules**: For open-source docs

**1.4 Extract and clean URLs**

```bash
# Extract URLs from TOC files
grep -oE 'https?://[^\)]+' references/*/TOC.md | \
  grep -v '#' | \           # Remove anchors
  sort -u > urls_to_scrape.txt

# Count by category
for toc in references/*/TOC.md; do
  category=$(basename $(dirname $toc))
  count=$(grep -c 'https' "$toc")
  echo "$category: $count URLs"
done
```

### Phase 2: Documentation Skill Creation

**2.1 Directory structure**

```
tech-docs/
├── SKILL.md                  # Main skill with grep patterns
├── references/
│   ├── guides/              # Conceptual docs
│   ├── api-reference/       # API docs
│   ├── samples/             # Code samples
│   └── resources/           # Additional resources
└── TOC.md                   # Master table of contents
```

**2.2 SKILL.md template**

See `templates/docs-skill-template.md` for full template. Key sections:

```markdown
---
skill_name: tech-docs
description: Complete [Technology] documentation reference...
---

# [Technology] Documentation Reference

## Quick Reference Guide

**Finding Documentation:**
\```bash
# Search for concepts
rg -i "keyword" references/guides/

# Find code examples
rg "pattern" references/samples/ -l | head -5

# API reference
rg "function_name" references/api-reference/
\```

## Documentation Structure

### Guides (`references/guides/`)
- Getting Started
- Core Concepts
- Best Practices

**Quick grep patterns:**
\```bash
rg "getting started" references/guides/ -i -l
rg "best practice" references/guides/ -i -l
\```

### API Reference (`references/api-reference/`)
- Functions
- Classes
- Methods

**Quick grep patterns:**
\```bash
rg "function_name" references/api-reference/
rg "ClassName" references/api-reference/
\```

## Cross-References to Application Skills

### tech-patterns
**Use this skill for**: Basic patterns, common use cases

**When to cross-reference:**
- Basic setup and configuration
- Common workflows

### tech-advanced
**Use this skill for**: Advanced patterns, optimization

**When to cross-reference:**
- Performance tuning
- Complex architectures
```

**2.3 Grep pattern best practices**

**Good patterns:**
- Specific enough to be useful
- General enough to find related content
- Include common variations (case-insensitive with `-i`)
- Limit results with `head` or `-l` for file-only matches

```bash
# ✅ GOOD: Specific with options
rg "authentication\|auth\|login" references/guides/ -i -l | head -5

# ❌ BAD: Too broad, no filtering
rg "the" references/

# ✅ GOOD: Contextual search
rg "error handling" references/guides/ -i -A5

# ❌ BAD: No context, overwhelming output
rg "error" references/
```

### Phase 3: Application Skill Creation

**3.1 Identify pattern categories**

Common categories:
- **Basic**: Setup, configuration, common workflows
- **Advanced**: Optimization, complex architectures, edge cases
- **Integration**: Third-party tools, frameworks, platforms
- **Production**: Deployment, monitoring, troubleshooting

**3.2 SKILL.md structure**

See `templates/application-skill-template.md` for full template. Key sections:

```markdown
---
skill_name: tech-patterns
description: [Technology] patterns and examples. Cross-references tech-docs for syntax.
---

# [Technology] Patterns

This skill provides practical patterns. For complete syntax reference, see **tech-docs skill**.

## Quick Pattern Reference

**When to use tech-docs:**
- Syntax reference: `rg "syntax" ../tech-docs/references/`
- Function reference: `rg "function" ../tech-docs/references/`

**When to use this skill:**
- Practical examples
- Common patterns
- Best practices

## Pattern Categories

### Basic Setup

\```[language]
// Example code with inline comments
// explaining key patterns
\```

**Key patterns:**
- Pattern 1: Explanation
- Pattern 2: Explanation

### Common Workflows

\```[language]
// More example code
\```

## Cross-Reference Guide

### Syntax → tech-docs

For complete syntax:

\```bash
# Function reference
rg "function_name" ../tech-docs/references/api-reference/

# Guides
rg "concept" ../tech-docs/references/guides/ -i -l
\```

## Common Pitfalls & Solutions

### Issue 1
**Problem**: Description
**Solution**: Code example

## Production Patterns

Real-world examples from production codebases.

## Next Steps

1. **First time?** → See tech-docs, `rg "getting started" ../tech-docs/references/guides/ -i -l`
2. **Need syntax?** → See tech-docs references
3. **Advanced patterns?** → See tech-advanced skill
```

**3.3 Cross-link syntax**

**Standard format:**
```markdown
**When to use [other-skill]:**
- Use case 1: `rg "pattern" ../other-skill/references/`
- Use case 2: `rg "pattern" ../other-skill/references/`
```

**Relative paths:**
- Same plugin: `../skill-name/`
- Different plugin: `../../plugin-name/skills/skill-name/`
- Always test grep patterns actually work

### Phase 4: Plugin Integration

**4.1 plugin.json structure**

```json
{
  "name": "tech-mastery",
  "version": "1.0.0",
  "description": "Comprehensive [Technology] reference...",
  "keywords": ["tech", "documentation", "patterns"],
  "author": {
    "name": "Your Name"
  },
  "skills": [
    "./skills/tech-docs",        // Docs first
    "./skills/tech-patterns",    // Then application skills
    "./skills/tech-advanced",
    "./skills/tech-integration"
  ]
}
```

**4.2 Skill ordering**

**Best practice:** Docs skill first, then application skills in order of complexity:
1. tech-docs (reference)
2. tech-patterns (basic)
3. tech-advanced (advanced)
4. tech-integration (integration)

**Why?** Users naturally progress from reference → basic → advanced.

**4.3 Keywords for discoverability**

```json
{
  "keywords": [
    "technology-name",        // Exact match
    "tech",                   // Abbreviation
    "documentation",          // Category
    "patterns",               // Use case
    "specific-feature"        // Key features
  ]
}
```

### Phase 5: Testing & Validation

**5.1 Grep pattern validation**

Test every grep pattern in your skills:

```bash
# Test pattern from skill
rg "pattern from docs" path/to/references/

# Should return relevant results
# If empty, pattern needs adjustment
```

**5.2 Cross-link verification**

Navigate skills and verify links resolve:

```bash
# From application skill directory
cd skills/tech-patterns

# Test cross-link path
ls ../tech-docs/references/  # Should list references/
```

**5.3 Token count validation**

```bash
# Check skill sizes
for skill in skills/*/SKILL.md; do
  lines=$(wc -l < "$skill")
  echo "$skill: $lines lines"
done

# Target: < 500 lines per skill
```

**5.4 Composition testing**

Load multiple skills and verify they work together:
- Load docs + 2 application skills
- Verify grep patterns still work
- Check cross-links resolve
- Confirm total context is manageable

**5.5 Validation checklist**

- [ ] All grep patterns return results
- [ ] Cross-links use correct relative paths
- [ ] Each skill < 500 lines
- [ ] Skills compose well (3+ simultaneously)
- [ ] Documentation is organized by category
- [ ] Scraping scripts work and are repeatable
- [ ] plugin.json is valid and complete
- [ ] Keywords enable discoverability

## Reference Implementation: claude-code-meta

Study this plugin to see how builders, references, and artifacts stay organized:

```
surf-market/plugins/claude-code-meta/
├── .claude-plugin/
│   └── plugin.json          # Plugin metadata and component paths
├── CHANGELOG.md             # Keep-a-Changelog history for releases
├── commands/
│   └── update-plugin.md      # Interactive version bump workflow
└── skills/
    └── claude-code-meta/
        ├── SKILL.md          # Master router + builder entry point
        ├── references/
        │   ├── plugin-builder.md
        │   ├── marketplace-builder.md
        │   ├── hook-builder.md
        │   ├── agent-builder.md
        │   ├── slash-command-builder.md
        │   ├── creating-components.md
        │   ├── plugin-updates.md
        │   ├── docs-plugin-builder.md
        │   ├── skill-examples/    # Exported skill + public artifacts
        │   └── cc-docs-toc.md     # Claude Code docs TOC reference
        └── templates/
            ├── docs-skill-template.md
            └── other templates...
```

**Key observations:**
- Master SKILL.md routes to builder references instead of bundling all content inline.
- Each reference lives under `skills/claude-code-meta/references/` so the context stays focused.
- Exported skill/public artifacts in `references/skill-examples/` supply concrete layout patterns.
- Central `cc-docs-toc.md` now lives next to other references for easy linking.
- Templates and scripts remain co-located with their referencing documents.

## Templates & Resources

### Bundled Templates

- `templates/docs-skill-template.md` - Starter for docs skills
- `templates/application-skill-template.md` - Starter for pattern skills
- `templates/plugin-template.json` - Plugin manifest template

### Bundled Scripts

- `scripts/firecrawl-scraper.sh` - FireCrawl API scraping
- `scripts/url-extractor.sh` - Extract/filter URLs from TOCs

### Reference Guides

- `references/grep-patterns.md` - Common grep pattern examples
- `references/cross-link-syntax.md` - Cross-linking between skills
- `references/scaling-strategies.md` - When/how to split skills

## Scaling Strategies

### When to split an application skill

**Indicators:**
- Skill exceeds 500 lines
- Multiple distinct pattern categories
- User confusion about skill focus

**Strategy:**
- Extract category into new skill (e.g., tech-patterns → tech-advanced)
- Update cross-links
- Maintain clear separation of concerns

### When to split a docs skill

**Indicators:**
- Different doc versions (e.g., v1 vs v2)
- Multiple programming languages
- Distinct technology areas

**Strategy:**
- Create versioned skills: tech-docs-v1, tech-docs-v2
- Or language-specific: tech-docs-python, tech-docs-javascript
- Or area-specific: tech-docs-api, tech-docs-cli

### Handling updates

**Documentation changes:**
- Re-scrape periodically (quarterly recommended)
- Update TOC files with new URLs
- Re-run scraping scripts
- Verify grep patterns still work

**Pattern changes:**
- Update application skills as patterns evolve
- Maintain cross-links
- Version skills if breaking changes

## Real-World Applications

This pattern works for:

**Databases:**
- PostgreSQL docs + SQL patterns + pgBouncer integration
- MongoDB docs + query patterns + aggregation pipelines
- Redis docs + caching patterns + pub/sub

**Frameworks:**
- React docs + component patterns + hooks + performance
- Next.js docs + routing patterns + SSR + deployment
- Express docs + middleware patterns + auth + testing

**Cloud Providers:**
- AWS docs (massive!) + service patterns per service
- GCP docs + Terraform patterns + Cloud Run
- Azure docs + ARM templates + DevOps

**Languages:**
- Python stdlib docs + idiomatic patterns + async
- TypeScript docs + type patterns + generics
- Rust docs + ownership patterns + async

**Tools:**
- Docker docs + Dockerfile patterns + compose
- Kubernetes docs + YAML patterns + operators
- Terraform docs + module patterns + state

## Success Metrics

A well-built docs plugin should achieve:

- ✅ **Token efficiency**: < 500 lines per skill
- ✅ **Quick discovery**: Grep returns results in < 1 second
- ✅ **Scalability**: Support 1000+ pages without bloat
- ✅ **Composability**: Load docs + 3 app skills simultaneously
- ✅ **Maintainability**: Clear separation enables easy updates
- ✅ **Usability**: Users find answers in 1-2 grep commands

## Anti-Patterns to Avoid

### ❌ Inline Documentation

Don't copy full docs into skill:

```markdown
# Bad: Copying docs into skill
## All [Technology] Functions
[1000 lines of function reference copied from docs]
```

**Why it fails:** Bloats context, hard to maintain, poor discoverability.

**Fix:** Use grep-driven discovery instead.

### ❌ Mixing Docs and Patterns

Don't mix reference docs with application patterns in one skill:

```markdown
# Bad: Mixed skill
## [Technology] Reference

### Data Types (reference docs)
[100 lines]

### Patterns (application)
[200 lines]

### API Reference (reference docs)
[300 lines]
```

**Why it fails:** Unfocused, unclear when to use, bloated.

**Fix:** Separate into docs skill (reference) and pattern skill (application).

### ❌ Weak Grep Patterns

Don't provide vague grep patterns:

```bash
# Bad: Too vague
rg "function" references/

# Bad: No options or filtering
rg "error" references/
```

**Why it fails:** Returns too many results, unhelpful.

**Fix:** Provide specific patterns with filtering:

```bash
# Good: Specific with filtering
rg "async function" references/guides/ -i -l | head -5

# Good: Contextual search
rg "error handling" references/ -i -A5
```

### ❌ Broken Cross-Links

Don't use incorrect relative paths:

```markdown
# Bad: Absolute paths (won't work)
See ../tech-docs/references/  # Use relative paths from the current repo root

# Bad: Wrong relative path
See ../../wrong-path/
```

**Why it fails:** Links don't resolve, users can't find references.

**Fix:** Test all relative paths:

```bash
# From application skill directory
ls ../tech-docs/references/  # Should work
```

## Next Steps

1. **Start small**: Build a docs plugin for a technology you use daily
2. **Use templates**: Copy templates from this skill as starting point
3. **Study spanner-mastery**: See the full working implementation
4. **Test grep patterns**: Validate every pattern returns useful results
5. **Iterate**: Refine based on actual usage

**For complete examples and templates, see bundled resources in this skill's directory.**

---

## Appendix: Quick Reference

### File Structure Checklist

```
your-plugin/
├── .claude-plugin/
│   └── plugin.json              # ✅ Skills in order: docs, basic, advanced
├── skills/
│   ├── tech-docs/
│   │   ├── SKILL.md             # ✅ < 500 lines, grep patterns
│   │   ├── references/          # ✅ Organized by category
│   │   │   ├── guides/
│   │   │   ├── api-reference/
│   │   │   └── samples/
│   │   └── TOC.md               # ✅ Master table of contents
│   │
│   ├── tech-patterns/
│   │   └── SKILL.md             # ✅ < 500 lines, cross-links work
│   │
│   └── tech-advanced/
│       └── SKILL.md             # ✅ < 500 lines, cross-links work
```

### grep Pattern Cheat Sheet

```bash
# Case-insensitive search
rg -i "pattern" path/

# List files only (faster)
rg -l "pattern" path/

# Show context (5 lines after)
rg "pattern" path/ -A5

# Multiple patterns (OR)
rg "pattern1\|pattern2" path/

# Limit results
rg "pattern" path/ -l | head -5

# Search specific file types
rg "pattern" path/ -g "*.md"
```

### Cross-Link Syntax Examples

```markdown
**When to use other-skill:**
- Syntax: `rg "CREATE TABLE" ../other-skill/references/`
- Functions: `rg "function_name" ../other-skill/references/api/`
- Guides: `rg "concept" ../other-skill/references/guides/ -i -l`
```

### Validation Commands

```bash
# Check skill sizes
wc -l skills/*/SKILL.md

# Test grep pattern
rg "pattern from skill" path/to/references/

# Verify cross-link
cd skills/app-skill && ls ../docs-skill/references/

# Count documentation files
find skills/tech-docs/references -type f -name "*.md" | wc -l
```

This is the architecture that enables comprehensive documentation plugins without context explosion. Study spanner-mastery, use the templates, and build documentation plugins that scale.
