How do I install the Sync Skills Readme skill?

Run npx skillmds@latest add karozi/sync-skills-readme in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Sync Skills Readme safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Sync Skills Readme?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Sync Skills Readme free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Sync Skills Readme?

karozi (@karozi) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Sync Skills Readme by karozi — Agent Skill

Name: Sync Skills Readme
Author: karozi

Sync Skills Readme

Regenerate and verify the categorized skills catalog in a repository README from installed skill metadata. Use when skills are added, removed, renamed, or re-described in a category-first skills repository, or when that catalog may be stale. Do not use for general README drafting or unrelated documentation edits.

karozi Updated Sep 17, 2026

File contents

Sync Skills README

Keep the repository's skills index derived from its skill packages while preserving every human-written section outside the generated catalog.

Source of Truth

Treat each skills/<category>/<skill>/SKILL.md package as authoritative.

Read the skill name and fallback summary from SKILL.md frontmatter.
Prefer agents/openai.yaml values display_name and short_description for catalog copy when present.
Derive the category label from the category directory name.
Sort categories and skills alphabetically so repeated runs are deterministic.

The bundled generator owns only the content between these markers:

<!-- BEGIN GENERATED SKILLS INDEX -->
<!-- Generated by sync-skills-readme. Do not edit inside these markers. -->
<!-- END GENERATED SKILLS INDEX -->

On its first run, it converts the existing ## Skills section to a marked generated block. Later runs replace only that block. It stops on malformed markers, invalid frontmatter, folder/name mismatches, duplicate skill names, or an empty skills directory instead of guessing.

Sync the Catalog

Locate the repository root. Inspect README.md, the skill tree, and local repository instructions before changing anything.

Run the bundled script with the target repository passed explicitly:

python3 <skill-root>/scripts/sync_skills_readme.py --repo-root <repository-root> --write

Review the README diff. Confirm that human-written content outside the generated markers is unchanged and every link resolves to a real SKILL.md.

Verify idempotence and freshness:

python3 <skill-root>/scripts/sync_skills_readme.py --repo-root <repository-root> --check

Run repository tests or checks that apply. Report catalog changes and any invalid skill metadata that blocked generation.

--check is the default and is used in CI. It performs no writes and returns a non-zero status when the catalog is stale or invalid. Writing always requires the explicit --write flag.

GitHub Automation

When the repository already contains approved README-sync workflows, keep them aligned with the bundled generator. Separate the two trust levels:

pull requests run tests and --check with read-only contents permission;
pushes to the default branch run the generator with contents write permission and commit only README.md when it changed;
pull-request path filters include README.md plus catalog sources, while write-back filters exclude README-only pushes as an extra loop guard;
pull-request concurrency cancels superseded checks, while default-branch write runs are serialized without interrupting an active commit.

Do not add a write-enabled workflow, commit, push, or change branch protection unless the user requested that repository mutation. Never use pull_request_target to execute untrusted contribution code. If branch protection blocks the bot commit, report it and use an approved update-PR pattern; do not weaken protection.

Credit

Created by Karo Zieminski, Product with Attitude.

---name: sync-skills-readmedescription: Regenerate and verify the categorized skills catalog in a repository README from installed skill metadata. Use when skills are added, removed, renamed, or re-described in a category-first skills repository, or when that catalog may be stale. Do not use for general README drafting or unrelated documentation edits.---# Sync Skills READMEKeep the repository's skills index derived from its skill packages while preserving every human-written section outside the generated catalog.## Source of TruthTreat each `skills/<category>/<skill>/SKILL.md` package as authoritative.- Read the skill name and fallback summary from `SKILL.md` frontmatter.- Prefer `agents/openai.yaml` values `display_name` and `short_description` for catalog copy when present.- Derive the category label from the category directory name.- Sort categories and skills alphabetically so repeated runs are deterministic.The bundled generator owns only the content between these markers:```markdown```On its first run, it converts the existing `## Skills` section to a marked generated block. Later runs replace only that block. It stops on malformed markers, invalid frontmatter, folder/name mismatches, duplicate skill names, or an empty skills directory instead of guessing.## Sync the Catalog1. Locate the repository root. Inspect `README.md`, the skill tree, and local repository instructions before changing anything.2. Run the bundled script with the target repository passed explicitly: ```bash python3 <skill-root>/scripts/sync_skills_readme.py --repo-root <repository-root> --write ```3. Review the README diff. Confirm that human-written content outside the generated markers is unchanged and every link resolves to a real `SKILL.md`.4. Verify idempotence and freshness: ```bash python3 <skill-root>/scripts/sync_skills_readme.py --repo-root <repository-root> --check ```5. Run repository tests or checks that apply. Report catalog changes and any invalid skill metadata that blocked generation.`--check` is the default and is used in CI. It performs no writes and returns a non-zero status when the catalog is stale or invalid. Writing always requires the explicit `--write` flag.## GitHub AutomationWhen the repository already contains approved README-sync workflows, keep them aligned with the bundled generator. Separate the two trust levels:- pull requests run tests and `--check` with read-only contents permission;- pushes to the default branch run the generator with contents write permission and commit only `README.md` when it changed;- pull-request path filters include `README.md` plus catalog sources, while write-back filters exclude README-only pushes as an extra loop guard;- pull-request concurrency cancels superseded checks, while default-branch write runs are serialized without interrupting an active commit.Do not add a write-enabled workflow, commit, push, or change branch protection unless the user requested that repository mutation. Never use `pull_request_target` to execute untrusted contribution code. If branch protection blocks the bot commit, report it and use an approved update-PR pattern; do not weaken protection.## CreditCreated by [Karo Zieminski](https://productwithattitude.com/), Product with Attitude.

Frequently asked questions