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, andlocal-patchesfor a required local fix that every sync reapplies
- Keep frontmatter focused on agent loading:
name,description, and optionalmetadatasuch asversionor author tags. - If setup presets change, run
make setups-check. Every catalog skill belongs to at least one preset or to the Roundfix Baseline; remove a skill that loses its last preset. The exception is this repository's own tooling: a skill that theAGENTS.mddispatch table requires stays in the catalog without a preset. - If the Astro catalog behavior or generated index changes, run the relevant web command from
web/package.jsonand inspect the generated catalog behavior. - When a skill is renamed or deleted — including an upstream rename or removal repaired on a sync PR — load
ai-memory-messagingand notify Roundfix throughmemory_message_send, whose inbox replaces the Secondbrain inbox for project coordination. Verify Roundfix's existing workspace and project names before sending; static clients also name this repository's sender scope explicitly. List each old slug with its new slug orremoved, the presets that named it, and the skills branch, PR, or commit. Label unpublished branch work as pending publication. Say the message is informational for Roundfix to validate its Baseline snapshots and expects no reply. The step is done when ai-memory returns the message ID and that ID is in the work summary. - 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.