How do I handle missing markers if docs are out of sync?

If a marker is missing, the tool reports it and you can add the marker in the appropriate file before re-running sync-readme.

Can I auto-run sync-readme in CI?

Yes. Integrate a script that runs before PR checks to generate updated sections and fail the build if drift is detected.

How do I verify changes are correct?

Manually review the updated sections for accuracy, render the Markdown locally if possible, and compare against the actual codebase data (layout, scripts, commands, architecture).

sync-readme

npx machina-cli add skill yu-iskw/coding-agent-fabric/sync-readme --openclaw

Files (1)

SKILL.md

2.2 KB

sync-readme

Use this skill to keep the technical documentation (README.md and CONTRIBUTING.md) up-to-date with the codebase.

When to Use

After adding or renaming packages in the monorepo.
After adding or modifying root scripts in package.json.
After adding or changing CLI commands or subcommands.
After significant architectural changes or package relationship updates.

Workflow

Analyze Project State: Directly observe the project to gather the necessary information:
- Layout: List directories in packages/ and packages/plugins/ to see the monorepo structure.
- Scripts: Read the root package.json to see available scripts.
- Commands: Read CLI command definitions in packages/cli/src/commands/ to identify commands and subcommands.
Locate Sync Markers: Find the following markers in the documentation files:
-  ... 
-  ... 
-  ... 
-  ... 
Update Content: Update the content between the markers based on your observations:
- Layout -> SYNC:LAYOUT (usually in CONTRIBUTING.md): List packages and their descriptions from their respective package.json files.
- Scripts -> SYNC:SCRIPTS (usually in CONTRIBUTING.md): Format scripts from the root package.json as a bulleted list.
- Commands -> SYNC:COMMANDS (usually in README.md): Format CLI commands as markdown headings with bash examples.
- Architecture -> SYNC:ARCHITECTURE (usually in CONTRIBUTING.md): Review and update the Mermaid diagram if package relationships or key components have changed.
Preserve Formatting: Ensure that you keep the markers themselves and only update the content between them. Use appropriate markdown blocks (code blocks, lists) that match the existing documentation style.

References

See references/mapping.md for detailed mapping between metadata and doc sections.

Source

git clone https://github.com/yu-iskw/coding-agent-fabric/blob/main/.claude/skills/sync-readme/SKILL.mdView on GitHub

Overview

sync-readme automates documentation alignment by reflecting the current codebase in README.md and CONTRIBUTING.md. It reads the monorepo layout (packages/ and packages/plugins/), root scripts from package.json, and CLI command definitions, then updates the corresponding sections to match reality.

How This Skill Works

It analyzes the project state by inspecting the layout, the root package.json scripts, and the CLI command definitions under packages/cli/src/commands/. It then locates the markers , , , and  in README.md and CONTRIBUTING.md, and replaces only the content between those markers while preserving formatting and the markers themselves.

When to Use It

After adding or renaming packages in the monorepo.
After adding or modifying root scripts in package.json.
After adding or changing CLI commands or subcommands.
After significant architectural changes or package relationship updates.
Before creating a PR or release to ensure docs match the current codebase.

Quick Start

Step 1: Analyze Project State: Inspect packages/, packages/plugins/, and root package.json to gather current state.
Step 2: Locate Sync Markers: Find the markers , , ,  in the docs.
Step 3: Update Content: Replace the content between the markers with up-to-date information, preserving formatting and markers.

Best Practices

Always locate and preserve the four markers and avoid touching surrounding text.
Generate each section from the actual codebase data (layout, scripts, commands, architecture).
Match the existing documentation style (markdown blocks, headings, and lists).
Preview changes locally to verify formatting and readability.
Include a quick diff or CI gate to catch drift when code changes.

Example Use Cases

A new package is added under packages/foo; run sync-readme to update the LAYOUT section with foo's name and description.
A root script is renamed in package.json; SCRIPTS section updates accordingly.
A new CLI command is introduced in packages/cli/src/commands; COMMANDS section updates with the command and a sample usage.
Major architecture refactor changes package relationships; ARCHITECTURE diagram refreshed.
PR to fix docs; run sync-readme to align docs before merge.

Frequently Asked Questions

Add this skill to your agents