workflowskillssyncvalidationagentscatalogUpdated 2026-07-01

Skill Sync Workflow

Keep executable skill sources, runtime symlinks, generated registries, family pages, agent packs, and routing checks in sync.

npm run skills:check

Source: AGENTS.md Skills Wiki Sync, 2026-05-31

Taxonomy

As of the 2026-06-18 stack audit, active executable inventory is tracked in Active Stack (What to Actually Use) rather than repeated by hand on this page. Do not hardcode counts here unless the count is generated or immediately validated.

The relationship is no longer one article per skill. Every executable SKILL.md needs a generated registry row and a family page route. Individual wiki/skills/<slug>.md articles are retired because they made the wiki read like a registry dump. If a skill accumulates durable ideas, merge them into the right family page or a real wiki/tools/ / wiki/concepts/ article.

Creating or editing skills

Use Browser Testing Skills skill. After changes: run npm run skill-registry, rebuild the index, refresh agent packs when routing/source pages changed, append wiki/log.md, and run the sync check. Pre-commit hook enforces the executable/registry contract.

Live edits through Cursor symlink the wiki repo directly; git status in kevin-wiki shows skill changes.

When a skill change is required

Create or update a skill when:

  • Kevin asks for a recurring task.
  • The same agent mistake appears twice.
  • A workflow has enough steps that the next agent would need a checklist.
  • A tool integration has non-obvious setup, auth, routing, or verification.
  • A style or project rule needs to execute in agent behavior, not only exist as reference prose.

Do not create overlapping skills. Check Skill Resolver and the existing skills/personal/ taxonomy first. If a skill already owns the task family, extend it.

Sync checklist

After editing executable skills:

npm run skills:check
npm run skill-registry
npm run skill-registry:check
npm run agent-packs:refresh
npm run agent-packs:check
npm run routing-doctor
npm run trigger-eval
npx tsx scripts/build-index.ts
qmd update
qmd embed

Run the full set when routing, frontmatter, family pages, runtime links, or pack content changed. For a typo-only skill edit, npm run skills:check, npx tsx scripts/build-index.ts, and qmd are usually enough.

Failure handling

  • Missing registry row: run npm run skill-registry; if it stays missing, fix the executable skill directory.
  • Retired individual skill article under wiki/skills/: merge it into a family page or real topic page, then delete it.
  • Resolver dark skill: add routing in Skill Resolver or remove the unused skill.
  • Trigger eval failure: fix the route, not the test, unless the expected behavior truly changed.
  • Agent-pack drift: update the source page, capsule definition, or generator, then rerun npm run agent-packs:refresh; do not hand-edit generated pack prose.

Run Contract

This workflow follows Workflow Run Contract: name the sources, write output or no-op proof, promote only durable facts, update state only when the run really completed, refresh generated surfaces when durable pages or skills change, and log user-visible work.

Timeline

Related Pages

Personal Skills TaxonomyConfig Sync ProtocolBrowser Testing SkillsPre-Commit HooksActive Stack (What to Actually Use)Skill ResolverWorkflow Run ContractGenerated Surface Contract

5 pages link here

Capture Ingest WorkflowWorkflowsPersonal Skills TaxonomyAgent DocsPre-Commit HooksAgent DocsSkills-First EnforcementDecisionsWiki Doctor ContractAgent Docs