Sync Skills Readme

---
name: sync-skills-readme
description: 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 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:

```markdown
<!-- 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

1. 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 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](https://productwithattitude.com/), Product with Attitude.