API Documentation Verification Skill

Purpose

Verify API documentation accuracy against source code. This skill eliminates fabricated API methods, unverified performance claims, non-runnable code examples, and marketing language. Every documented feature must exist in the codebase.

Quick Start

Use this skill to verify:

• API methods exist with correct signatures
• Code examples are runnable and accurate
• Performance claims have benchmark support
• Configuration options match source code
• Error documentation matches thrown errors
• Marketing language is removed
• Dependencies match package.json

Verification Categories (Summary)

CRITICAL (Must Fix Before Commit)

• API Method Existence: Every documented method must exist in source with exact signature
• Parameter/Return Types: Types must exactly match implementation (no guessing)
• Code Examples: All examples must be runnable with proper imports and error handling
• Performance Claims: ZERO tolerance for unverified claims - require benchmarks

HIGH (Should Fix Soon)

• Configuration: Documented options must exist with correct field names
• Error Documentation: All thrown errors must be documented

MEDIUM (Nice to Have)

• Marketing Language: Remove buzzwords (blazing-fast, revolutionary, enterprise-grade)
• Dependency Versions: Match package.json exactly

For detailed checks with examples and verification patterns:

Read `~/.claude/skills/api-documentation-verify/references/VERIFICATION-CHECKS.md`

Use when: Need specific verification patterns, examples of good/bad documentation, or detailed check descriptions

Execution Process (Summary)

Core Steps

1. Identify Documentation: Find all .md files, README, DOCS, API files
2. Extract Claims: Methods, examples, config, performance claims
3. Verify Against Source: Compare documented vs actual (read source files)
4. Check Marketing Language: Scan for banned words/phrases
5. Generate Report: CRITICAL/HIGH/MEDIUM issues with line numbers
6. Provide Corrections: Show correct versions for critical issues
7. Summary Statistics: Count issues, verified items

For detailed execution steps with bash commands and report formats:

Read `~/.claude/skills/api-documentation-verify/references/EXECUTION-STEPS.md`

Use when: Performing verification, need bash commands, or want detailed report format templates

LEGACY CONTENT TO REMOVE

Integration Points

This skill can be invoked:

• Manually when reviewing documentation
• Before commits that modify documentation
• In CI/CD as documentation linting step
• Before releases to ensure doc accuracy

Exit Criteria

• All API methods verified against source code
• All code examples validated for runnability
• All performance claims checked for benchmark support
• All configuration options verified
• All errors documented
• Marketing language flagged
• Report generated with specific line numbers
• CRITICAL issues should block documentation commits

Example Usage

# Manual invocation
/skill api-documentation-verify

# Verify specific doc file
/skill api-documentation-verify README.md

# Verify all docs in directory
/skill api-documentation-verify docs/

Automation Opportunities

This skill can be automated in CI/CD:

# .github/workflows/docs-verify.yml
name: Verify Documentation

on:
  pull_request:
    paths:
      - "**.md"
      - "docs/**"

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Verify API Documentation
        run: |
          # Run skill via Claude Code API
          claude-code skill api-documentation-verify

References

• Diátaxis Framework: https://diataxis.fr/
• Technical Documentation Expert Agent
• Good Docs Project: https://thegooddocsproject.dev/
• API Documentation Best Practices: https://swagger.io/resources/articles/best-practices-in-api-documentation/

Related Agent

For comprehensive documentation guidance that coordinates this and other documentation skills, use the documentation-coordinator agent.