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

​
Frontmatter parsing

SKILL.md frontmatter is one YAML 1.2 document between --- markers, parsed by a pure-Rust parser since 0.9.4.
  • Fields: name and description (required), requires_capabilities, metadata (text values) and version (stored as metadata.version). Any other key must be a namespaced extension key (vendor.key); a mapping or sequence value needs a vendor.version key beside it.
  • yes, on and off stay strings; << is an ordinary key, never a merge; a second document is refused.
  • Refused since 0.9.4, accepted by 0.9.3 and earlier: a key given twice at any level, a null (~ or an empty value) as description or a metadata value, an unrecognized tag (!custom), a ... document end marker line, nesting deeper than 64 levels, and 100 or more aliases that outnumber their anchors more than ten to one. An alias expansion bomb is refused as before.
  • A block scalar (|, |+, >) that ends the frontmatter keeps its final line break.
  • SkillDocument.extensions values are text projected from the YAML data: a string as written, any other value as YAML rendered from its resolved value (1.10 is 1.1, 1_000 is 1000, 0x1F is 31, ~ is null, a mapping or sequence is block YAML). Quote values whose text matters, such as a file mode: unquoted, 0755 is 755.0.

​
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