readme-sync
npx machina-cli add skill yu-iskw/coding-agent-skills/readme-sync --openclawREADME Sync
Purpose
Ensures that the ## Agent Skills section in the root README.md accurately reflects all available skills in skills/.
Workflow
- Identify Skills: Use
Globorfindto locate allSKILL.mdfiles inskills/and.cursor/skills/. - Extract Information: For each skill found, use
uv run skills-ref read-properties <skill-directory>to get thenameanddescription. - Generate Markdown: Format the collected information as a sorted list of markdown items:
- Format:
- **[name](relative/path/to/skill/)**: description
- Format:
- Update README.md: Replace the content between
<!-- START-SKILLS -->and<!-- END-SKILLS -->markers in the rootREADME.mdwith the newly generated list.
Implementation Notes
- The
skills-reftool is part of the project dependencies and can be run viauv run. - Always maintain alphabetical order of the skills in the
README.mdlist. - Ensure the relative paths in the markdown links correctly point to the skill directories from the root.
Examples
Scenario: Updating README.md after adding a new skill
- Find all skills in the directory
skills/. - Get properties for each skill:
uv run skills-ref read-properties skills/claude-code-cli. - Update
README.mdwithin the<!-- START-SKILLS -->block.
Source
git clone https://github.com/yu-iskw/coding-agent-skills/blob/main/.cursor/skills/readme-sync/SKILL.mdView on GitHub Overview
readme-sync ensures the root README's Agent Skills section matches the actual skills in the codebase. It scans skills/ and .cursor/skills/ for SKILL.md files, extracts each skill’s name and description via uv run skills-ref read-properties, and rebuilds an alphabetically ordered Markdown list inside the <!-- START-SKILLS --> and <!-- END-SKILLS --> markers.
How This Skill Works
It identifies all SKILL.md files, uses uv run skills-ref read-properties <skill-directory> to capture name and description, and formats the results as - **[name](relative/path/to/skill/)**: description. The list is sorted alphabetically and replaces the content between the START-SKILLS and END-SKILLS markers in the root README.md.
When to Use It
- After adding a new skill to skills/, to ensure it appears in the root README.
- When a skill’s name or description changes and needs propagation.
- Before releasing a new version to prevent documentation drift.
- As part of CI checks to verify README accuracy.
- After reorganizing skill directories to refresh relative paths.
Quick Start
- Step 1: Identify all SKILL.md files in skills/ and .cursor/skills/ (via Glob or find).
- Step 2: For each, run uv run skills-ref read-properties <skill-directory> to capture name and description.
- Step 3: Generate a sorted Markdown list and replace the content between <!-- START-SKILLS --> and <!-- END-SKILLS --> in the root README.md.
Best Practices
- Keep each skill’s SKILL.md accurate with current name and description.
- Ensure the final list is alphabetical by skill name.
- Verify that Links point to the correct relative paths from the root.
- Run readme-sync in a clean workspace to avoid stale data.
- Commit updates with a concise message referencing readme-sync.
Example Use Cases
- Adding a new skill automatically appears in the root README after running readme-sync.
- Renaming a skill updates the link and description in the README.
- Bulk additions trigger a full refresh of the skills list between markers.
- Reorganizing directories updates relative paths without breaking links.
- A CI job fails on drift until readme-sync is run and docs are updated.
