XanBZS Documentation Generator

This skill automatically generates high-quality, DRY documentation for XanBZS features following the project's established patterns. It analyzes feature directories, extracts database schemas via Supabase MCP, documents API endpoints, and generates either simple README.md files or comprehensive docs/ folders based on auto-detected complexity.

Capabilities

• Feature Analysis: Scans src/features/[feature-name]/ to extract components, hooks, pages, types, utilities, and constants
• Auto Complexity Detection: Determines documentation structure (simple vs comprehensive) based on file count and directory depth
• Database Schema Extraction: Uses Supabase MCP execute_sql to query table schemas, relationships, and RLS policies
• Workflow Documentation: Extracts business logic from hooks, services, and state management patterns
• API Endpoint Documentation: Documents Supabase edge functions and RPC calls with request/response types
• Integration Mapping: Identifies feature dependencies and cross-feature integrations
• XanBZS Pattern Compliance: Generates docs following DRY, KISS, MVP principles with XanBZS-specific conventions

Input Requirements

Feature Name (required):

• Feature directory name (e.g., payments, invoices, purchase-orders)
• Must exist in src/features/[feature-name]/

Scope (optional, defaults to "features"):

• features - Document a single feature
• workflow - Document a business workflow (e.g., payment processing)
• api - Document API endpoints and edge functions
• full - Complete feature + workflows + API documentation

Output Location (optional):

• Defaults to feature directory: src/features/[feature-name]/docs/ or src/features/[feature-name]/README.md
• Custom path can be specified

Output Formats

Simple Format (for features with <15 files, no subdirectories)

Single File: README.md

Structure:

# Feature Name

## Purpose
[Clear purpose statement]

## Key Features
- Feature 1
- Feature 2

## Components
- ComponentName - Description

## Hooks
- useHookName - Purpose

## Database Tables
- table_name - Schema description

## Usage Examples
[Code examples]

## Integration Points
[Dependencies on other features]

Comprehensive Format (for features with ≥15 files or subdirectories)

Folder Structure: docs/

Files:

• docs/README.md - Overview and navigation
• docs/COMPONENTS.md - Component catalog with props and usage
• docs/WORKFLOWS.md - Business logic and state flows
• docs/API.md - Edge functions and RPC documentation
• docs/DATABASE.md - Table schemas, relationships, RLS policies
• docs/INTEGRATION.md - Feature dependencies and cross-feature flows

How to Use

Basic Feature Documentation

@xanbzs-doc-generator analyze payments

Generates documentation for the payments feature with auto-detected complexity level.

Workflow Documentation

@xanbzs-doc-generator analyze purchase-orders --scope workflow

Generates comprehensive workflow documentation for purchase order processing.

API Documentation

@xanbzs-doc-generator analyze invoices --scope api

Documents all invoice-related edge functions and RPC calls.

Full Documentation

@xanbzs-doc-generator analyze products --scope full

Generates complete documentation: features + workflows + API + database schemas.

Scripts

This skill uses the following Python modules:

• feature_analyzer.py - Scans feature directory structure and extracts file metadata
• complexity_detector.py - Auto-detects complexity to determine simple vs comprehensive format
• db_schema_extractor.py - Uses Supabase MCP to query database schemas and relationships
• workflow_extractor.py - Extracts business logic from hooks, services, and state management
• api_documenter.py - Documents edge functions and RPC calls with types
• doc_generator.py - Orchestrates documentation generation using templates
• template_engine.py - XanBZS-specific markdown template rendering

Database Schema Extraction

The skill uses Supabase MCP execute_sql tool to extract:

Table Schemas:

SELECT
  column_name,
  data_type,
  is_nullable,
  column_default
FROM information_schema.columns
WHERE table_name = 'table_name'
ORDER BY ordinal_position;

Relationships:

SELECT
  tc.table_name,
  kcu.column_name,
  ccu.table_name AS foreign_table_name,
  ccu.column_name AS foreign_column_name
FROM information_schema.table_constraints AS tc
JOIN information_schema.key_column_usage AS kcu
  ON tc.constraint_name = kcu.constraint_name
JOIN information_schema.constraint_column_usage AS ccu
  ON ccu.constraint_name = tc.constraint_name
WHERE tc.constraint_type = 'FOREIGN KEY';

RLS Policies (optional):

SELECT * FROM pg_policies WHERE tablename = 'table_name';

Complexity Detection Rules

Simple Format (README.md):

• File count ≤ 15
• No subdirectories beyond standard structure
• Single component/hook/page per category
• Minimal integration points

Comprehensive Format (docs/ folder):

• File count > 15
• Multiple subdirectories (e.g., components/shared/, hooks/queries/)
• Complex state management
• Multiple integration points

Auto-Detection Algorithm:

def determine_complexity(feature_path):
    file_count = count_files(feature_path)
    subdir_count = count_subdirectories(feature_path)
    integration_count = count_imports_from_other_features(feature_path)

    complexity_score = (
        file_count * 1.0 +
        subdir_count * 3.0 +
        integration_count * 2.0
    )

    return "comprehensive" if complexity_score > 20 else "simple"

XanBZS-Specific Patterns

DRY Principle

• Reference shared utilities instead of duplicating explanations
• Link to docs/INDEX.md for architecture details
• Point to THEME.md for design system information

KISS Principle

• Focus on purpose, not implementation details
• Highlight key features, not every line of code
• Use simple examples over exhaustive documentation

MVP Focus

• Document what exists, not what's planned
• Prioritize user-facing features
• Include gotchas and anti-patterns

XanBZS Conventions

• Use Tamagui component references (not shadcn/ui)
• Follow @/ absolute import patterns
• Mention TDD workflow with @xanbzs-tdd-assistant skill
• Include design validation with pnpm validate:design

Best Practices

1. Run after feature completion: Document stable features, not work-in-progress
2. Update on major changes: Regenerate docs when adding significant functionality
3. Review generated docs: Always verify accuracy before committing
4. Cross-reference existing docs: Link to docs/INDEX.md, docs/architecture.md, etc.
5. Include examples: Real usage examples > abstract descriptions
6. Document gotchas: Include anti-patterns, common mistakes, edge cases

Limitations

• Accuracy depends on code quality: Poorly structured code produces less clear documentation
• Database schema requires Supabase MCP: Skill needs active Supabase connection
• Manual review required: Generated docs should be verified before committing
• Type inference limitations: Complex TypeScript types may need manual clarification
• Workflow extraction heuristics: Business logic in non-standard locations may be missed

Integration with Claude Code

MCP Tools Used

• mcp__supabase__execute_sql - Database schema queries
• mcp__filesystem-with-morph__edit_file - AST-based file editing (optional)
• mcp__plugin_claude-mem__search_observations - Historical context (optional)

Workflow Integration

1. Feature Development: After completing a feature, invoke skill to generate docs
2. TDD Workflow: Document after tests pass and pnpm validate:design succeeds
3. Code Review: Include generated docs in PR for reviewer context
4. Onboarding: Use comprehensive docs to onboard new developers

Example Session

# After completing feature
pnpm check-all  # Ensure all tests pass

# Generate documentation
@xanbzs-doc-generator analyze new-feature

# Review generated docs
# (skill outputs file paths)

# Commit with docs
git add src/features/new-feature/
git commit -m "feat: add new-feature with documentation"

Troubleshooting

Skill can't find feature directory

• Verify feature exists in src/features/[feature-name]/
• Check spelling and kebab-case naming

Database schema extraction fails

• Ensure Supabase MCP is connected
• Verify table names match feature name patterns
• Check database permissions

Generated docs are incomplete

• Feature may have non-standard structure
• Run with --scope full for comprehensive analysis
• Manually review and augment generated docs

Complexity detection is wrong

• File count threshold may need adjustment
• Override with --force-simple or --force-comprehensive flags

Related Skills

• @xanbzs-tdd-assistant - Generate tests before documenting
• @applying-brand-guidelines - Validate design compliance before documenting
• @file-editing - Edit documentation files using MCP tools

Version History

• v1.0.0 (2025-01-08): Initial release with auto-complexity detection and Supabase MCP integration