workflowskillssyncvalidationagentscatalogUpdated 2026-08-10

Skill Sync Workflow

Keep executable skill sources, runtime symlinks, generated registries, family pages, command routes, 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 Agent Operations Skills skill. After changes: run npm run skill-registry, refresh the slash-command index when command routes changed, rebuild the index, 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.

Session-Derived Skill Proposals

Session history may propose a skill change, but it is neither canonical memory nor permission to mutate the runtime. A collector such as SkillClaw must pass this promotion chain:

  1. capture only consented, scoped sessions and content-address the raw evidence;
  2. redact secrets/private data and attach classification, retention, and access controls before any shared upload;
  3. extract a candidate with exact session/tool-result locators and a bounded proposed diff;
  4. deduplicate against current skills, open proposals, and retired behavior;
  5. evaluate the current and candidate revisions on representative cases;
  6. require strict improvement on a separate held-out gate plus size, purpose, authority, and compatibility constraints;
  7. review the diff when behavior, permissions, credentials, spend, publishing, or external mutations change;
  8. version the approved source and retain a one-command rollback;
  9. run the normal registry, resolver, trigger, config-sync, and doctor proofs.

The collector/proposer never overwrites a canonical SKILL.md directly. Repeated behavior proves possible reuse, not quality. Failed and rejected candidates stay attached to the proposal as negative evidence. Source: frozen AMAP-ML/SkillClaw source; Controlled Skill Evolution - GEPA and SkillOpt, reviewed 2026-08-10

Sync checklist

After editing executable skills:

npm run skills:check
npm run skill-registry
npm run skill-registry:check
npm run slash-command-index
npm run slash-command-index: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 command surfaces 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.
  • Command-index drift: update the skill or package script, then regenerate and check Slash Command Index.

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 ProtocolAgent Operations SkillsPre-Commit HooksActive Stack (What to Actually Use)Skill ResolverWorkflow Run ContractGenerated Surface ContractSkillClawControlled Skill Evolution - GEPA and SkillOptAgent Self-Improvement Eval Library

8 pages link here

Capability Routing MapMetaCapture Ingest WorkflowWorkflowsControlled Skill Evolution - GEPA and SkillOptConceptsPersonal Skills TaxonomyAgent DocsPre-Commit HooksAgent DocsSkillClawToolsSkills-First EnforcementDecisionsWiki Doctor ContractAgent Docs