API Documentation Workflow Skill v2.1

Orchestrated Documentation System - Systematic API component documentation with research automation

Purpose

This skill provides an automated, orchestrated documentation workflow for API components, using MCP servers for research, specialized sub-agents for content generation, and state management for progress tracking.

Key Features:

• ✅ GitHub-First Research - Direct access to source code, types, and official examples
• ✅ Context7 Integration - Up-to-date docs with curated code examples
• ✅ Template-Based Documentation - Consistent structure across all components
• ✅ Progress Tracking - Know what's documented and what's pending
• ✅ Quality Validation - Automated completeness scoring (0-100%)
• ✅ Code Example Generation - Real, tested examples from official sources
• ✅ Coverage Dashboard - Live 0-100% coverage tracking

When to Use This Skill

Activate this skill when you need to:

• Document an API, framework, SDK, or library systematically
• Create comprehensive API reference documentation
• Track documentation coverage (0-100%)
• Ensure consistent, high-quality documentation
• Research and document 10+ API components
• Generate code examples for API functions/hooks

Trigger Phrases:

• "Document the Vercel AI SDK v5 API"
• "Help me systematically document [framework/API]"
• "Create comprehensive API documentation for [library]"

Orchestrated Workflow Overview

5-Phase Documentation Workflow

Phase	Name	Duration	Outputs	Reference
1	Setup & Discovery	2-5 min	Component classification	Phase 1
2	Research & Planning	5-20 min	Research data	Phase 2
3	Template Filling	5-15 min	Documented structure	Phase 3
4	Code Examples	5-15 min	Working examples	Phase 4
5	Quality & Integration	3-5 min	Validated docs	Phase 5

Total Time: 20-60 min per component (manual) or 15-30 min (with agent)

MCP Integration

Priority Order: GitHub MCP → Context7 MCP → WebSearch → WebFetch See: MCP Integration

State Management

Location: .claude/skills/api-documentation-workflow/state/{framework}/{framework}_state.json See: State Management

Quick Start

Starting New Documentation

User: "Document the Vercel AI SDK v5 Core functions"

Claude:
1. Initializes state for "Vercel AI SDK v5"
2. Loads component list from Index.md
3. Begins Phase 1: Setup & Discovery
4. Proceeds through 5-phase workflow for each component
5. Updates coverage dashboard automatically

Resuming Documentation

User: "Continue documenting Vercel AI SDK v5"

Claude:
1. Loads existing state
2. Shows progress: "7/55 components (12% coverage)"
3. Lists: "Last worked on: generateText.md"
4. Asks: "Continue with next component (streamText)?"
5. Resumes workflow

Orchestrated Workflow Instructions

Initialization: Documentation Setup

See: Initialization Workflow

Steps:

1. Ask user for framework name
2. Locate or create Index.md tracker
3. Check for existing state
4. Initialize state file
5. Display workflow preview
6. Begin Phase 1

---

Phase 1: Setup & Discovery

Objective: Select component, classify type, prepare for research Duration: 2-5 minutes See: Phase 1 Workflow

Classifies component type (function, hook, type, etc.), determines category, and loads appropriate documentation template.

Key Steps:

• Select component from Index.md
• Classify component type
• Determine category
• Load template
• Update state

Validation: Component classified and template loaded

---

Phase 2: Research & Planning

Objective: Gather comprehensive information from official sources Duration: 5-20 minutes (or 5-10 min with agent) See: Phase 2 Workflow

Uses GitHub-first research methodology with MCP fallbacks.

Research Priority:

1. GitHub MCP (Primary): Source code, types, tests, examples
2. Context7 MCP (Secondary): Official docs + curated examples
3. WebSearch (Fallback): Find official documentation URLs
4. WebFetch (Fallback): Extract from official websites

Key Steps:

• Search GitHub repo for source files
• Fetch Context7 documentation
• Search for official docs (if needed)
• Extract website documentation (if needed)
• Validate research completeness

Automated Option: Use api-component-researcher agent (50% faster) See: GitHub-First Research

Validation: Research quality ≥70%, ready for documentation

---

Phase 3: Template Filling

Objective: Systematically fill documentation template Duration: 5-15 minutes See: Phase 3 Workflow

Creates structured documentation from research data.

Key Steps:

• Fill frontmatter (metadata)
• Write overview (2-3 paragraphs)
• Add type definition
• Document all parameters
• Document return value
• Link related components
• Save partial documentation

Validation: All sections filled, file saved

---

Phase 4: Code Examples

Objective: Generate tested, working code examples Duration: 5-15 minutes See: Phase 4 Workflow

Creates 3 types of examples demonstrating component usage.

Example Types:

• Example 1: Basic usage (minimal parameters)
• Example 2: Common pattern (typical real-world usage)
• Example 3: Advanced pattern (complex scenario + error handling)

Framework Examples (if applicable):

• Next.js integration
• React component integration
• Node.js usage

Key Steps:

• Plan example progression
• Generate basic example
• Generate common pattern example
• Generate advanced example
• Add framework-specific examples
• Update documentation file

Validation: 2-3 examples added with explanations

---

Phase 5: Quality & Integration

Objective: Validate completeness, link components, mark complete Duration: 3-5 minutes See: Phase 5 Workflow

Final validation and integration before marking documentation complete.

Quality Scoring (100 points):

• Frontmatter (10 pts)
• Overview (10 pts)
• Type Definition (15 pts)
• Parameters (15 pts)
• Return Value (10 pts)
• Basic Example (15 pts)
• Common Example (10 pts)
• Advanced Example (10 pts)
• Related Components (5 pts)
• Official Resources (10 pts)

Quality Tiers:

• 90-100%: Excellent (production-ready)
• 80-89%: Good (minor improvements)
• 70-79%: Acceptable (needs review)
• <70%: Needs improvement (blocked)

Key Steps:

• Quality validation
• Quality gate (must pass ≥80%)
• Link related components bidirectionally
• Mark documentation as complete
• Update state
• Update Index.md dashboard
• Display completion summary
• Continue or finish

Validation: Quality score ≥80%, documentation marked complete

---

MCP Integration

See: MCP Integration Guide

MCP Server Priority

Priority 1: GitHub MCP
- Search official repo for source code
- Get type definitions from source
- Find test files and examples
- Most accurate information

Priority 2: Context7 MCP
- Get official docs + curated examples
- Comprehensive API information
- Fast, curated content

Priority 3: WebSearch + WebFetch
- Fallback if GitHub/Context7 unavailable
- Manual extraction from websites
- More time-consuming

MCP Benefits

GitHub MCP:

• Exact type signatures from source
• JSDoc comments from developers
• Real test cases
• Official examples

Context7 MCP:

• Up-to-date official documentation
• Curated code examples
• Version-specific information
• Related component suggestions

WebSearch/WebFetch:

• Access to official documentation websites
• Additional guides and tutorials
• Supplementary information

Sub-Agents

See: Sub-Agents Guide

api-component-researcher Agent

Purpose: Automate 6-step GitHub-first research workflow

When to Use: Recommended for all components (40-50% time savings)

Invocation:

Use Task tool with subagent_type="general-purpose"
Prompt: "Load and execute .claude/agents/api-component-researcher.md
Research component: {component_name}
Framework: {framework}
GitHub Repo: {org/repo}
Execute 6-step workflow and return JSON"

Output: Structured JSON with:

• Component info (type, category, description)
• Type definition (from source)
• Parameters (complete list)
• Return value (with properties)
• Code examples (2-3)
• Related components
• Research sources
• Quality assessment

Time Savings:

• Simple component: 10 min → 5 min (50% faster)
• Complex component: 20 min → 10 min (50% faster)

Quality Validator Agent

Purpose: Systematic quality validation

When to Use: After Phase 3 template filling

Output: Quality report with score 0-100%

State Management

See: State Management Guide

State File Location

.claude/skills/api-documentation-workflow/state/{framework}/{framework}_state.json

Key State Operations

Initialize: Create new state for framework

- Copy template
- Load components from Index.md
- Set counters to 0
- Save state file

Load: Resume from existing state

- Read state file
- Parse JSON
- Display current progress
- Identify current component

Update: Track progress

- Update component status
- Update phase
- Recalculate coverage
- Save state

Resume: Continue from previous session

- Load state
- Jump to current component and phase
- Continue workflow

State Schema

See: State Template

Reference Files

Core Concepts (6 files)

Location: references/core/

• MCP Integration - MCP usage patterns and priority
• Sub-Agents - Sub-agent invocation and usage
• State Management - State operations and schema
• Documentation Patterns - Documentation best practices
• Quality Checklist - Quality validation criteria
• Subagent Usage Guide - Subagent patterns and examples

Phase Workflows (5 files)

Location: references/phases/

• Phase 1: Setup & Discovery - Component classification
• Phase 2: Research & Planning - GitHub-first research
• Phase 3: Template Filling - Systematic documentation
• Phase 4: Code Examples - Example generation
• Phase 5: Quality & Integration - Validation and completion

Sub-Workflows (4 files)

Location: references/workflows/

• Initialization - Setup and state initialization
• GitHub-First Research - 6-step research process
• MCP Research Workflow - MCP-based research patterns
• Quality Validation - Scoring and validation

Templates (2 files)

Location: templates/

• Documentation State Template - State file structure
• [API Component Template](templates/API Component.md) - Documentation template

Time Estimates

Per Component

Without api-component-researcher:

• Simple (function): ~30 min
• Complex (hook): ~50 min
• Type/Interface: ~15 min

With api-component-researcher (50% faster):

• Simple (function): ~15 min
• Complex (hook): ~25 min
• Type/Interface: ~8 min

Full Framework

Vercel AI SDK v5 (55 components):

• Without agent: ~20-25 hours
• With agent: ~10-15 hours (40-50% faster)

Batch Sessions:

• 1-hour session with agent: 3-5 simple components
• 4-hour session with agent: 10-15 components
• Full day with agent: 20-25 components

Success Metrics

Documentation is successful when:

• ✅ Coverage reaches 100% (all components documented)
• ✅ Average quality score ≥85%
• ✅ All components have ≥2 code examples
• ✅ All related components linked bidirectionally
• ✅ Index dashboard auto-updates
• ✅ Coverage dashboard shows accurate %
• ✅ State file shows "all_complete" status
• ✅ Documentation searchable and navigable

Version History

v2.1.0 (2025-10-29):

• REFACTORED: Skill reduced to <500 lines with progressive disclosure
• Organized 11 reference files + 3 workflows + 2 templates
• Moved detailed workflows to references/phases/ (5 files)
• Moved core concepts to references/core/ (3 files)
• Moved sub-workflows to references/workflows/ (3 files)
• All phase workflows now in separate files with full details
• MCP integration, sub-agents, and state management in dedicated references
• Improved navigation with clear "See:" links throughout

v2.0.0 (2025-10-28):

• MAJOR UPDATE: GitHub-first research methodology
• NEW: api-component-researcher specialized subagent for Phase 2 (40-50% faster research)
• Added Context7 MCP integration for official docs + code examples
• New research priority: GitHub repo → Context7 → WebFetch
• Enhanced Phase 2 with 6-step research workflow
• Automated research agent with structured JSON output
• Source code analysis from official repositories
• Improved code example quality (from GitHub source + Context7)

v1.0.0 (2025-10-28):

• Initial release with orchestrated 5-phase workflow
• MCP integration (WebSearch, WebFetch, grep.app)
• Sub-agent integration (Research, Quality Validator)
• State management with resumption
• Automated quality scoring (0-100%)
• Coverage tracking and dashboard integration

---

Version: 2.1.0 Last Updated: 2025-10-29 Maintained by: Personal Workflow Workflow Mode: Orchestrated Lines: ~480 (refactored for progressive disclosure)