Repo Skill Maintainer

Repo Skill Maintainer

This skill keeps the aidriven-resources catalog healthy. It is the repo's internal accelerator for the four operations maintainers actually do: add, edit, validate, release. It does not replace the CI gates — those are the source of authority — but it makes sure you arrive at the gates with a green tree.

Golden rules

1. SKILL.md frontmatter is the source of truth. manifest.json is derived; do not edit it by hand — regenerate it with make sync.
2. Skill directory name must equal name: in frontmatter. Both must be kebab-case.
3. Every change ends with make validate. If it reports an error, fix it before committing; CI runs the exact same script and will block the PR otherwise.
4. Releases are driven by manifest.json version + a matching v* git tag. Never tag without running make release-check first.

Branch taxonomy (enforced by CI)

Every agent-driven change must use the right branch prefix. The CI workflow rejects anything else.

feat/ and fix/ branches are scope-locked by CI: the diff must touch only skills/<slug>/ plus optionally manifest.json, README.md, CONTRIBUTING.md, or RELEASING.md. Cross-skill edits belong under chore/.

The four operations

1. Add a new skill

git checkout -b feat/<kebab-case-name>
make new-skill name=<kebab-case-name>
# edit skills/<name>/SKILL.md — replace the placeholder description with a real, trigger-rich one
make sync         # add the new skill to manifest.json
make validate     # confirm everything is green
git commit -am "feat: add <kebab-case-name>"

Good descriptions are the #1 quality signal. See references/description-rules.md before finalizing.

2. Edit an existing skill

git checkout -b fix/<existing-skill-name>

• Change SKILL.md or its references/assets/scripts freely.
• If you touched the frontmatter description, run make sync so the manifest's short description (first sentence) stays aligned.
• Run make validate before committing.
• Don't rename the directory without also updating the name: frontmatter field — the validator will fail the mismatch.
• Commit title: fix(<skill>): <summary>. PR title prefix must match the branch prefix or the CI workflow fails.

3. Fix a failing validator

The validator is a single Python script: scripts/validate_repo.py. The most common failures and their fixes:

For the full rule list, see references/validator-rules.md.

4. Prepare a release

Releases must come from a release/vX.Y.Z branch PR — the Release workflow's provenance check enforces this.

make prepare-release version=X.Y.Z   # creates and pushes release/vX.Y.Z

# After merge:
make publish-release version=X.Y.Z   # tags main and pushes vX.Y.Z

See RELEASING.md for the full checklist.

What this skill will NOT do

• Edit manifest.json by hand — always sync instead.
• Skip make validate before declaring work done.
• Invent skill names not confirmed by the user.
• Add skills whose descriptions are vague or placeholder-only — a weak description is worse than no skill at all because it pollutes trigger matching across the catalog.

Reference index