Skip to main content
This runbook defines the required operator workflow for skill source identity changes.

​
Canonical Identity

  • Canonical identity is SkillKey { source_uuid, skill_name }.
  • source_uuid is immutable unless changed through lineage events.
  • Runtime execution paths consume canonical identity only.

​
Required Source Record Fields

Every source identity record must include:
  • source_uuid
  • display_name
  • transport_kind
  • locator fingerprint
  • status (active, disabled, or retired)

​
Governance Checks

Startup rejects:
  • One UUID with conflicting fingerprints, even when lineage is present.
  • Distinct UUIDs sharing a fingerprint without connecting lineage. Lineage permits this case, not conflicting fingerprints for the same UUID.
  • split/merge/rotate lineage without complete per-skill remap coverage.

​
Companion Skill Governance

Every nontrivial Meerkat-owned agent-facing tool family should provide:
  • concise tool descriptions and schemas
  • human docs for concepts, guides, reference, and examples where appropriate
  • an embedded companion skill gated by requires_capabilities
Document an explicit exemption when a built-in tool family is too small or too mechanical to justify a companion skill. Companion skills teach agents how to call existing tools. They must not become semantic owners of lifecycle, readiness, policy, or terminal truth. Machines, services, stores, and typed dispatch paths remain authoritative.

​
Migration Procedures

For rotate, split, and merge, the lineage record must declare a nonempty required_from_skills inventory. It is not inferred from the remap rows, so remaps alone do not satisfy validation. Each listed skill name must have a remap from every declared origin UUID into a declared destination UUID. Matching remaps must also cover every declared origin and every declared destination. rename_or_relocate does not require this inventory or these rotate/split/merge coverage checks.

​
Rotate (one source to one source)

  1. Add lineage event rotate from old UUID to new UUID, with a nonempty required_from_skills inventory on its lineage record.
  2. Add remap rows for all affected skills (old_uuid/skill -> new_uuid/skill), covering every required skill and both declared endpoints.
  3. Deploy config and verify canonicalization tests pass.

​
Rename or relocate (same logical source, new UUID/path binding)

  1. Add lineage event rename_or_relocate from old UUID to new UUID.
  2. Add remap rows for all affected skills.
  3. Verify canonicalization still resolves the same semantic skills under the new source identity.

​
Split (one source to many)

  1. Add lineage event split with the origin and all target UUIDs, and a nonempty required_from_skills inventory on its lineage record.
  2. Add explicit per-skill remaps from old UUID to exactly one declared target UUID per skill. Every declared target must receive at least one remap.
  3. Reject deployment if a required source skill or a declared endpoint lacks remap coverage.

​
Merge (many sources to one)

  1. Add lineage event merge with all origin UUIDs and the target UUID, and a nonempty required_from_skills inventory on its lineage record.
  2. Add explicit per-skill remaps from each origin UUID to the target UUID. Every name in required_from_skills requires a remap for each origin, not just one origin that contains that name.
  3. Reject deployment if any required origin/skill pair or declared endpoint lacks remap coverage.

​
Incident Recovery

If startup fails with lineage/remap validation:
  1. Freeze rollout and keep prior registry active.
  2. Fix missing remaps or incorrect lineage edge.
  3. Re-run identity migration tests:
  1. Roll forward only after tests pass and resolver-boundary canonicalization is verified.