generate.docs

Overview

generate.docs automatically generates or updates SKILL.md documentation from skill.yaml manifest files, ensuring consistent and comprehensive documentation across all Betty skills.

Purpose

Eliminate manual documentation drift by:

• •Before: Developers manually write and update SKILL.md files, leading to inconsistency and outdated docs
• •After: Documentation is automatically generated from the authoritative skill.yaml manifest

This skill helps maintain high-quality documentation by:

• •Reading skill.yaml manifest files
• •Extracting inputs, outputs, and metadata
• •Creating standardized SKILL.md documentation
• •Ensuring consistency across all Betty skills
• •Supporting dry-run previews and safe overwrites

Usage

Basic Usage

python skills/generate.docs/generate_docs.py <manifest_path> [options]

Parameters

Outputs

Examples

Example 1: Generate Documentation for a New Skill

python skills/generate.docs/generate_docs.py skills/api.define/skill.yaml

Output: Creates skills/api.define/SKILL.md with comprehensive documentation

Result:

{
  "status": "success",
  "data": {
    "doc_path": "skills/api.define/SKILL.md",
    "skill_name": "api.define",
    "dry_run": false
  }
}

Example 2: Preview Documentation Without Writing

python skills/generate.docs/generate_docs.py \
  skills/hook.define/skill.yaml \
  --dry-run=true

Result: Prints formatted documentation preview to console without creating any files

================================================================================
DRY RUN PREVIEW
================================================================================
# hook.define

## Overview
...
================================================================================

Example 3: Overwrite Existing Documentation

python skills/generate.docs/generate_docs.py \
  skills/api.validate/skill.yaml \
  --overwrite=true

Result: Replaces existing skills/api.validate/SKILL.md with newly generated version

Example 4: Custom Output Path

python skills/generate.docs/generate_docs.py \
  skills/workflow.compose/skill.yaml \
  --output-path=docs/skills/workflow-compose.md

Result: Generates documentation at docs/skills/workflow-compose.md instead of default location

Example 5: Batch Documentation Generation

# Generate docs for all skills in the repository
for manifest in skills/*/skill.yaml; do
  echo "Generating docs for $manifest..."
  python skills/generate.docs/generate_docs.py "$manifest" --overwrite=true
done

Result: Updates documentation for all skills, ensuring consistency across the entire framework

Generated Documentation Structure

The generated SKILL.md includes the following sections:

1. •Overview - Skill name and brief description from manifest
2. •Purpose - Detailed explanation of what the skill does
3. •Usage - Command-line usage examples with proper syntax
4. •Parameters - Detailed table of all inputs with types, requirements, and defaults
5. •Outputs - Description of all skill outputs
6. •Usage Template - Practical examples showing common use cases
7. •Integration Notes - How to use with workflows, other skills, and batch operations
8. •Dependencies - Required dependencies from manifest
9. •Tags - Skill tags for categorization
10. •Version - Skill version from manifest

Integration Notes

Use in Workflows

# workflows/maintain_docs.yaml
name: Documentation Maintenance
description: Keep all skill documentation up to date

steps:
  - name: Update skill docs
    skill: generate.docs
    args:
      - "${skill_manifest_path}"
      - "--overwrite=true"

  - name: Commit changes
    command: git add ${doc_path} && git commit -m "docs: update skill documentation"

Use with skill.create

When creating a new skill, automatically generate its documentation:

# Create new skill
python skills/skill.create/skill_create.py my.new.skill

# Generate documentation
python skills/generate.docs/generate_docs.py \
  skills/my.new.skill/skill.yaml

Integration with CI/CD

Add to your CI pipeline to ensure documentation stays in sync:

# .github/workflows/docs.yml
- name: Check documentation is up to date
  run: |
    for manifest in skills/*/skill.yaml; do
      python skills/generate.docs/generate_docs.py "$manifest" --dry-run=true > /tmp/preview.md
      skill_dir=$(dirname "$manifest")
      if ! diff -q "$skill_dir/SKILL.md" /tmp/preview.md; then
        echo "Documentation out of sync for $manifest"
        exit 1
      fi
    done

Use with Hooks

Automatically regenerate docs when skill.yaml is modified:

python skills/hook.define/hook_define.py \
  on_file_save \
  "python skills/generate.docs/generate_docs.py {file_path} --overwrite=true" \
  --pattern="*/skill.yaml" \
  --blocking=false \
  --description="Auto-regenerate SKILL.md when skill.yaml changes"

Benefits

For Developers

• •No manual documentation writing
• •Consistent format across all skills
• •Preview changes before committing
• •Safe overwrite protection

For Teams

• •Single source of truth (skill.yaml)
• •Automated documentation updates
• •Standardized skill documentation
• •Easy onboarding with clear docs

For Maintenance

• •Detect documentation drift
• •Batch regeneration for all skills
• •CI/CD integration for validation
• •Version-controlled documentation

Error Handling

Manifest Not Found

$ python skills/generate.docs/generate_docs.py nonexistent/skill.yaml

Error:

{
  "status": "error",
  "error": "Manifest file not found: nonexistent/skill.yaml"
}

File Already Exists (Without Overwrite)

$ python skills/generate.docs/generate_docs.py skills/api.define/skill.yaml

Error:

{
  "status": "error",
  "error": "SKILL.md already exists at skills/api.define/SKILL.md. Use --overwrite=true to replace it or --dry-run=true to preview."
}

Invalid YAML Manifest

$ python skills/generate.docs/generate_docs.py broken-skill.yaml

Error:

{
  "status": "error",
  "error": "Failed to parse YAML manifest: ..."
}

Customization

After generation, you can manually enhance the documentation:

1. •Add detailed examples - The generated docs include basic examples; add more complex ones
2. •Include diagrams - Add architecture or flow diagrams
3. •Expand integration notes - Add specific team or project integration details
4. •Add troubleshooting - Document common issues and solutions

Note: Manual changes will be overwritten if you regenerate with --overwrite=true. Consider adding custom sections to the generator or maintaining separate docs for detailed content.

Best Practices

1. •Run in dry-run mode first - Preview changes before writing
2. •Use version control - Track documentation changes via git
3. •Regenerate after manifest changes - Keep docs in sync with manifest
4. •Include in PR reviews - Ensure manifest and docs are updated together
5. •Automate in CI - Validate docs match manifests in automated checks

Dependencies

• •

  PyYAML: Required for YAML manifest parsing

  bash

  pip install pyyaml
  

• •

  context.schema: For validation rule definitions

Files Created

• •SKILL.md - Generated skill documentation (in same directory as skill.yaml by default)

See Also

• •skill.create - Create new skills
• •skill.define - Define skill manifests
• •Betty Architecture - Five-layer model
• •Skill Development Guide - Creating new skills

Version

0.1.0 - Initial implementation with manifest-to-markdown generation