Documentation README Sync

docs.sync.readme

Overview

docs.sync.readme is the documentation synchronization tool that regenerates the top-level README.md to reflect all current registered skills and agents. It ensures that the README stays in sync with the actual state of the Betty Framework by pulling from registry files.

Purpose

Automates the maintenance of README.md to keep documentation accurate and up-to-date with:

• Skill Registry (registry/skills.json) – All registered skills
• Agent Registry (registry/agents.json) – All registered agents

This eliminates manual editing of the README and prevents documentation drift as skills and agents are added, modified, or removed.

What It Does

1. Reads Registries: Loads skills.json and agents.json
2. Categorizes Skills: Groups skills by tag/category:
   • Foundation (skill., registry., workflow.*)
   • API Development (api.*)
   • Infrastructure (agents, commands, hooks, policy)
   • Governance (policy, audit)
3. Updates Sections:
   • Current Core Skills table with categorized skills
   • Agents documentation links
   • Skills documentation references
4. Maintains Style: Preserves README tone, formatting, and structure
5. Generates Report: Creates sync report with statistics

Usage

Basic Usage

python skills/docs.sync.readme/readme_sync.py

No arguments required - reads from standard registry locations.

Via Betty CLI

/docs/sync/readme

Expected Registry Structure

betty/
├── registry/
│   ├── skills.json      # Skills registry
│   └── agents.json      # Agents registry
└── README.md            # File to update

Behavior

1. Registry Loading

Reads JSON files from:

• registry/skills.json – Skills registry
• registry/agents.json – Agents registry

If a registry file is missing, logs a warning and continues with empty data.

2. Skill Categorization

Foundation Skills:

• Matches: skill.*, registry.*, workflow.*
• Examples: skill.create, workflow.compose

API Development Skills:

• Matches: api.* or tags: api, openapi, asyncapi
• Examples: api.define, api.validate

Infrastructure Skills:

• Matches tags: agents, command, hook, policy, plugin
• Examples: agent.define, hook.register, plugin.sync

Governance Skills:

• Matches tags: governance, policy, audit
• Examples: policy.enforce, audit.log

Only active skills are included. Test skills (starting with test.) are filtered out.

3. Skills Section Update

Replaces the "## 🧩 Current Core Skills" section with:

## 🧩 Current Core Skills

Betty's self-referential "kernel" of skills bootstraps the rest of the system:

### Foundation Skills

| Skill | Purpose |
|--------|----------|
| **skill.create** | Generates a new Betty Framework Skill directory and manifest. |
| **skill.define** | Validates and registers skill manifests (.skill.yaml) for the Betty Framework. |
| **registry.update** | Updates the Betty Framework Skill Registry by adding or modifying entries. |

### API Development Skills

| Skill | Purpose |
|--------|----------|
| **api.define** | Create OpenAPI and AsyncAPI specifications from templates |
| **api.validate** | Validate OpenAPI and AsyncAPI specifications against enterprise guidelines |

### Infrastructure Skills

| Skill | Purpose |
|--------|----------|
| **agent.define** | Validates and registers agent manifests for the Betty Framework. |
| **hook.define** | Create and register validation hooks for Claude Code |

These skills form the baseline for an **AI-native SDLC** where creation, validation, registration, and orchestration are themselves skills.

4. Agents Section Update

Updates the "### Agents Documentation" subsection with current agents:

### Agents Documentation

Each agent has a `README.md` in its directory:
* [api.designer](agents/api.designer/README.md) — Design RESTful APIs following enterprise guidelines with iterative refinement
* [api.analyzer](agents/api.analyzer/README.md) — Analyze API specifications for backward compatibility and breaking changes

Includes both active and draft agents.

5. Report Generation

Creates sync_report.json with statistics:

{
  "skills_by_category": {
    "foundation": 5,
    "api": 4,
    "infrastructure": 9,
    "governance": 1
  },
  "total_skills": 19,
  "agents_count": 2,
  "timestamp": "2025-10-23T20:30:00.123456+00:00"
}

Outputs

Success Response

{
  "ok": true,
  "status": "success",
  "readme_path": "/home/user/betty/README.md",
  "report": {
    "skills_by_category": {
      "foundation": 5,
      "api": 4,
      "infrastructure": 9,
      "governance": 1
    },
    "total_skills": 19,
    "agents_count": 2,
    "timestamp": "2025-10-23T20:30:00.123456+00:00"
  }
}

Failure Response

{
  "ok": false,
  "status": "failed",
  "error": "README.md not found at /home/user/betty/README.md"
}

What Gets Updated

✅ Updated Sections

• Current Core Skills (categorized tables)
• Agents Documentation (agent links list)
• Skills documentation references

❌ Not Modified

• Mission and inspiration
• Purpose and scope
• Repository structure
• Design principles
• Roadmap
• Contributing guidelines
• Requirements

The skill only updates specific documentation sections while preserving all other README content.

Examples

Example 1: Sync After Adding New Skills

Scenario: You've added several new skills and want to update the README

# Create and register new skills
/skill/create data.transform "Transform data between formats"
/skill/define skills/data.transform/skill.yaml

/skill/create telemetry.report "Generate telemetry reports"
/skill/define skills/telemetry.report/skill.yaml

# Sync README to include new skills
/docs/sync/readme

Output:

INFO: Starting README.md sync from registries...
INFO: Loading registry files...
INFO: Generating updated README content...
INFO: ✅ Updated README.md
INFO:    - Foundation skills: 5
INFO:    - API skills: 4
INFO:    - Infrastructure skills: 11
INFO:    - Governance skills: 1
INFO:    - Total active skills: 21
INFO:    - Agents: 2

Example 2: Sync After Adding New Agent

Scenario: A new agent has been registered and needs to appear in README

# Define new agent
/agent/define agents/workflow.optimizer/agent.yaml

# Sync README
/docs/sync/readme

The new agent will appear in the "### Agents Documentation" section.

Example 3: Automated Sync in Workflow

Scenario: Include README sync as a workflow step after registering skills

# workflows/skill_release.yaml
steps:
  - skill: skill.define
    args: ["skills/new.skill/skill.yaml"]

  - skill: plugin.sync
    args: []

  - skill: docs.sync.readme
    args: []

This ensures README, plugin.yaml, and registries stay in sync.

Integration

With skill.define

After defining skills, sync the README:

/skill/define skills/my.skill/skill.yaml
/docs/sync/readme

With agent.define

After defining agents, sync the README:

/agent/define agents/my.agent/agent.yaml
/docs/sync/readme

With Hooks

Auto-sync README when registries change:

# .claude/hooks.yaml
- event: on_file_save
  pattern: "registry/*.json"
  command: python skills/docs.sync.readme/readme_sync.py
  blocking: false
  description: Auto-sync README when registries change

With plugin.sync

Chain both sync operations:

/plugin/sync && /docs/sync/readme

Categorization Rules

Foundation Category

Criteria:

• Skill name starts with: skill., registry., workflow.
• Core Betty framework functionality

Examples:

• skill.create, skill.define
• registry.update, registry.query
• workflow.compose, workflow.validate

API Category

Criteria:

• Skill name starts with: api.
• Tags include: api, openapi, asyncapi

Examples:

• api.define, api.validate
• api.generate-models, api.compatibility

Infrastructure Category

Criteria:

• Tags include: agents, command, hook, policy, plugin, registry
• Infrastructure and orchestration skills

Examples:

• agent.define, agent.run
• hook.define, hook.register
• plugin.sync, plugin.build

Governance Category

Criteria:

• Tags include: governance, policy, audit
• Policy enforcement and audit trails

Examples:

• policy.enforce
• audit.log

Filtering Rules

✅ Included

• Skills with status: active
• Agents with status: active or status: draft
• Skills with meaningful descriptions

❌ Excluded

• Skills with status: draft
• Skills starting with test.
• Skills without names or descriptions

Common Errors

Files Read

• README.md – Current README content
• registry/skills.json – Skills registry
• registry/agents.json – Agents registry

Files Modified

• README.md – Updated with current skills and agents
• skills/docs.sync.readme/sync_report.json – Sync statistics

Exit Codes

• 0: Success (README updated successfully)
• 1: Failure (error during sync)

Logging

Logs sync progress:

INFO: Starting README.md sync from registries...
INFO: Loading registry files...
INFO: Generating updated README content...
INFO: ✅ Updated README.md
INFO:    - Foundation skills: 5
INFO:    - API skills: 4
INFO:    - Infrastructure skills: 9
INFO:    - Governance skills: 1
INFO:    - Total active skills: 19
INFO:    - Agents: 2

Best Practices

1. Run After Registry Changes: Sync README whenever skills or agents are added/updated
2. Include in CI/CD: Add README sync to deployment pipelines
3. Review Before Commit: Check updated README before committing changes
4. Use Hooks: Set up auto-sync hooks for convenience
5. Combine with plugin.sync: Keep both plugin.yaml and README in sync
6. Version Control: Always commit README changes with skill/agent changes

Troubleshooting

README Not Updating

Problem: Changes to registry don't appear in README

Solutions:

• Ensure skills have status: active
• Check that skill names and descriptions are present
• Verify registry files are valid JSON
• Run /skill/define before syncing README

Skills in Wrong Category

Problem: Skill appears in unexpected category

Solutions:

• Check skill tags in skill.yaml
• Verify tag categorization rules above
• Add appropriate tags to skill.yaml
• Re-run skill.define to update registry

Section Markers Not Found

Problem: "Section marker not found" warnings

Solutions:

• Ensure README has expected section headers
• Check for typos in section headers
• Restore original README structure if modified
• Update section_marker strings in code if intentionally changed

Architecture

Skill Categories

Documentation – docs.sync.readme maintains the README documentation layer by syncing registry state to the top-level README.

Design Principles

• Single Source of Truth: Registries are the source of truth
• Preserve Structure: Only update specific sections
• Maintain Style: Keep original tone and formatting
• Clear Categorization: Logical grouping of skills by function
• Idempotent: Can be run multiple times safely

See Also

• plugin.sync – Sync plugin.yaml with registries (SKILL.md)
• skill.define – Validate and register skills (SKILL.md)
• agent.define – Validate and register agents (SKILL.md)
• registry.update – Update registries (SKILL.md)
• Betty Architecture – Framework overview (betty-architecture.md)

Dependencies

• registry.update: Registry management
• betty.config: Configuration constants and paths
• betty.logging_utils: Logging infrastructure

Status

Active – Production-ready documentation skill

Version History

• 0.1.0 (Oct 2025) – Initial implementation with skills categorization and agents documentation