name	Documentation README Sync
description	Automatically regenerate README.md from Betty Framework registries

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

Reads Registries: Loads skills.json and agents.json
Categorizes Skills: Groups skills by tag/category:
- Foundation (skill., registry., workflow.*)
- API Development (api.*)
- Infrastructure (agents, commands, hooks, policy)
- Governance (policy, audit)
Updates Sections:
- Current Core Skills table with categorized skills
- Agents documentation links
- Skills documentation references
Maintains Style: Preserves README tone, formatting, and structure
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

Error	Cause	Solution
"README.md not found"	Missing README file	Ensure README.md exists in repo root
"Registry file not found"	Missing registry	Run skill.define to populate registry
"Failed to parse JSON"	Invalid JSON	Fix JSON syntax in registry files

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

Run After Registry Changes: Sync README whenever skills or agents are added/updated
Include in CI/CD: Add README sync to deployment pipelines
Review Before Commit: Check updated README before committing changes
Use Hooks: Set up auto-sync hooks for convenience
Combine with plugin.sync: Keep both plugin.yaml and README in sync
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

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

Install Skill

SKILL.md

docs.sync.readme

Overview

Purpose

What It Does

Usage

Basic Usage

Via Betty CLI

Expected Registry Structure

Behavior

1. Registry Loading

2. Skill Categorization

3. Skills Section Update

4. Agents Section Update

5. Report Generation

Outputs

Success Response

Failure Response

What Gets Updated

✅ Updated Sections

❌ Not Modified

Examples

Example 1: Sync After Adding New Skills

Example 2: Sync After Adding New Agent

Example 3: Automated Sync in Workflow

Integration

With skill.define

With agent.define

With Hooks

With plugin.sync

Categorization Rules

Foundation Category

API Category

Infrastructure Category

Governance Category

Filtering Rules

✅ Included

❌ Excluded

Common Errors

Files Read

Files Modified

Exit Codes

Logging

Best Practices

Troubleshooting

README Not Updating

Skills in Wrong Category

Section Markers Not Found

Architecture

Skill Categories

Design Principles

See Also

Dependencies

Status

Version History