marcioaltoe Skill catalog curation
Keep the skill source tree, registry metadata, setup presets, sync lockfile, and Astro catalog aligned.
When to use
- A skill is added, removed, renamed, moved between collections, vendored, or replaced.
skills-registry.json,skills-registry.lock.json,setups/,install.sh,install.ps1,web/, or.github/workflows/deploy-pages.ymlchanges.- The user asks to curate skills, update catalog metadata, adjust tags/authors/provenance, or change what the GitHub Pages catalog shows.
Curation workflow
- Identify the surface being changed:
- Skill body:
skills/<collection>/<name>/SKILL.md - Catalog metadata:
skills-registry.json - Setup presets:
setups/_index.txtandsetups/<preset>.txt - Astro catalog:
web/ - Upstream sync:
scripts/sync-skills.mjsandskills-registry.lock.json
- Skill body:
- For new or replaced skills, verify whether an official upstream skill exists before writing a local one. Prefer official upstream sources; use community sources only when no official source fits or the user asks for that source.
- Keep one canonical skill folder under
skills/<collection>/<skill-name>/. Do not duplicate a skill into multiple collections or add symlinks underskills/. - Put catalog metadata in
skills-registry.json, not in frontmatter:author- curated
tags local-pathcollection- optional upstream
repo,path,ref,update
- Keep frontmatter focused on agent loading:
name,description, and optionalmetadatasuch asversionor author tags. - If setup presets change, run
make setups-check. - If the Astro catalog behavior or generated index changes, run the relevant web command from
web/package.jsonand inspect the generated catalog behavior. - Always run
make listandgit diff --checkbefore claiming the curation work is ready.
Collection choice
Choose the collection by the skill's primary use case, not by every technology it mentions.
00-setup: repo setup, local skills, agent guardrails, setup presets.01-discovery: research, assumption checks, problem discovery.02-planning: PRDs, product planning, GTM, communication planning.03-engineering-design: architecture, security, UX, documentation plans.04-issue-decomposition: issues, triage, acceptance criteria.05-implementation-loop: implementation, frameworks, migrations, tests.06-review-repair: review, debugging, quality repair, verification.07-evidence-delivery: delivery evidence, docs, commits, reports.08-release: release, deployment, observability, operations.09-learning-loop: skill authoring, evaluations, process improvement.10-marketing: marketing, sales, SEO, pitch material.
Astro catalog rules
- The public catalog is static and lives under
web/. web/scripts/build-index.mjsreadsskills-registry.jsonplus eachSKILL.md.src/data/skills.jsonis generated and git-ignored; do not commit it.- GitHub Pages deploys via
.github/workflows/deploy-pages.yml. - Keep collection labels in
web/scripts/build-index.mjsaligned with the repository's collection table.
Validation matrix
| Change | Required validation |
|---|---|
| Skill body only | make list, git diff --check |
| Registry metadata | make list, git diff --check |
| Setup presets | make setups-check, make list, git diff --check |
| Astro catalog | cd web && npm run build, git diff --check |
| Upstream sync script or lockfile | Run the focused sync/check command and inspect sync-report.md |
Anti-patterns
- Editing author, tags, collection, or provenance in
SKILL.mdinstead ofskills-registry.json. - Adding a vendored skill without upstream provenance when the source is known.
- Creating a setup preset that points to a missing skill or a path absent from the registry.
- Treating the Astro page as separate from the registry; it is a projection of registry plus skill frontmatter.