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:
{
  "kind": "structured",
  "source_uuid": "dc256086-0d2f-4f61-a307-320d4148107f",
  "skill_name": "email-extractor"
}
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

TransportConfiguration shapeNotes
Embeddedcomponent crate registrationBuiltin skills registered through inventory.
Filesystemtype = "filesystem", path = "..."Recursively discovers directories containing SKILL.md.
Gittype = "git", url, git_ref, ref_typeUses local cache and refresh TTL for branch refs.
HTTPtype = "http", url, auth fieldsRequires the HTTP skills feature.
Stdiotype = "stdio", command, argsExternal skill source process.

​
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 load_skill
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> resolves a runtime-local slug to a builtin-source key.
There is no slash-delimited public wire format. Use typed keys.

​
Discovery tools

Agent-facing discovery tools use typed key fields:
ToolKey fieldsPurpose
browse_skillsoptional source_uuid filterList active skills, optionally filtered by source UUID or search query.
load_skillsource_uuid, skill_nameLoad a skill’s full instructions into the conversation.
skill_list_resourcessource_uuid, skill_nameList skill-owned resources/artifacts.
skill_read_resourcesource_uuid, skill_name, resource pathRead a specific skill-owned resource.
skill_invoke_functionsource_uuid, skill_name, function name, argumentsInvoke a skill-defined structured function.

​
Rendering

Flat inventory renders full key IDs: 
<available_skills>
  <skill id="00000000-0000-4b11-8111-000000000001/task-workflow">
    <description>How to use task tools</description>
  </skill>
</available_skills>
Collection mode groups by source_uuid and instructs the agent to use browse_skills and load_skill. Injection blocks are size-limited to 32 KiB and rendered as <skill id="source_uuid/skill_name">...</skill>.

​
Public Introspection

Current public introspection surfaces:
SurfaceOperation
CLIrkat skill list [--json]
CLI inspectrkat skill inspect <skill-name> --source-uuid <uuid> [--json]
RPCskills/list
RESTGET /skills
MCP listmeerkat_skills with action: "list"
MCP inspectmeerkat_skills with action: "inspect", typed skill_key, and optional source UUID
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