Skip to main content
Use this page when you need exact skill-system vocabulary rather than a task walkthrough.

​
Core identity model

  • SourceUuid is the stable source identity. Builtins use 00000000-0000-4b11-8111-000000000001; conventional project-local .rkat/skills uses 00000000-0000-4b11-8111-000000000002.
  • SkillName is a lowercase dash-separated slug ([a-z0-9-], no leading/trailing dash, no --).
  • SkillKey { source_uuid, skill_name } is the canonical skill identity across runtime, RPC, REST, SDK, CLI, and tool surfaces.
  • SkillRef is the wire wrapper for per-turn refs. It currently has one tagged form:
preload_skills carries plain SkillKey objects; skill_refs carries tagged SkillRef objects. Legacy string refs are rejected.

​
Source Identity

Each source has a SourceIdentityRecord:
  • source_uuid
  • display_name
  • transport_kind: embedded, filesystem, git, http, or stdio
  • fingerprint
  • status: active, disabled, or retired
The source identity registry applies lifecycle checks before load. Disabled or retired sources fail resolution. Source UUID rotations, renames, splits, and merges are represented with lineage events plus SkillKeyRemap entries where the event needs per-skill coverage. Shadowing is keyed by the full SkillKey, not by skill_name alone. Two sources can both contain email-extractor; they are distinct skills unless their source_uuid is also the same.

​
Source Transports

​
Companion Skill Convention

Meerkat-owned nontrivial agent-facing tool families use embedded companion skills as their operating manuals. A companion skill is a normal skill:
  • source: embedded builtin source
  • identity: normal SkillKey { source_uuid, skill_name }
  • gating: requires_capabilities
  • activation: preload_skills, skill_refs, or an explicitly policy-enabled load_skill tool
There is no auto-preload path for companion skills. Availability in the inventory means “this instruction manual can be loaded”, not “this manual has already been injected”. Tool descriptions should describe the tool contract. Companion skills describe workflow behavior such as when to claim WorkGraph items, how to author schedules, or when to use builtin tasks versus durable work.

​
Activation paths

  • Preload at session creation: preload_skills: SkillKey[]; content is resolved into the system prompt before the first turn.
  • First-turn or per-turn injection: skill_refs: SkillRef[]; content is injected for that turn.
  • CLI preload convenience: rkat run --skill <skill-name> materializes a builtin-source key from a bare slug. It does not currently address a local filesystem source discovered from a path.
There is no slash-delimited public wire format. Use typed keys.

​
Discovery tools

Agent-facing discovery tools use typed key fields: These five tools are default-disabled in SkillToolSet. A custom BuiltinToolConfig must explicitly enable them. Current factory-built CLI, REST, and JSON-RPC sessions do not do so, and a later ToolScope allow-list cannot make an uncomposed tool callable.

​
Rendering

Flat inventory renders full key IDs:
Collection mode groups by source_uuid and currently instructs the agent to use browse_skills and load_skill. Those names are usable only when the embedding explicitly enables the tool implementations; otherwise use public introspection and typed activation. The default injection limit is 32 KiB and is configurable. Injection blocks render the same two typed attributes:
The public prompt and wire contracts never encode identity as a slash-delimited string that another component must parse.

​
Public Introspection

Current public introspection surfaces: List responses include key, source, is_active, and optional shadowed_by provenance. Inspect responses include the same typed identity and provenance plus body.

​
See also