Skip to main content
Skills inject domain-specific knowledge into the agent’s context. A skill is a SKILL.md document with YAML frontmatter, addressed at runtime by SkillKey { source_uuid, skill_name }, and included in the system prompt or per-turn context when its required capabilities are available.
This page is the task-first guide. For the low-level runtime vocabulary and identity model, see Skills reference.

What this guide is for

Use this guide when you want to:
  • create or configure skill sources
  • preload or inject skills into sessions
  • understand SkillKey identity and source provenance
  • understand when to use preload_skills vs skill_refs

Skill sources

Skills are discovered from multiple source transports:
  • Embedded builtin skills from component crates
  • Project context root (<context-root>/.rkat/skills/) when a context root is active
  • Configured filesystem sources
  • Git repositories cloned to local cache and refreshed on TTL
  • HTTP endpoints fetched from remote skill servers
  • Stdio sources
The canonical identity is the pair of source_uuid and skill_name. Two sources can both provide task-workflow without colliding because their source UUIDs differ. First-source-wins shadowing applies only when the same full SkillKey appears more than once.

Git sources

Configured in skills settings (typically in realm config.toml). Uses the system git executable:
Skill repository auth values are literal configuration values. The skills resolver does not expand ${ENV_VAR} references or ~ in these fields. Keep realm configuration access restricted, or materialize secrets and absolute paths before starting Meerkat. An HTTPS token goes to git for the repository’s host only. On Linux and macOS git asks for it through its own credential protocol: its credential-cache client asks a socket Meerkat serves for each git invocation, so the token is never on a command line or in a file (the checkout’s .git/config included), and no credential helper of your git configuration is asked for it or sent it. This needs a git built with credential-cache, as the usual Linux and macOS packages are; without it a refresh fails with an error naming the alternatives. On Windows the token is a header option on each git invocation’s own command line, for the configured repository URL alone and with redirects not followed (so the URL must be the repository’s final one). Processes of your user can read it there for that invocation, and it is never written to a file: prefer an ssh key, or a git credential manager configured for the repository host and no token.

HTTP sources

Filesystem and stdio sources

SKILL.md format

Each skill is a markdown file with YAML frontmatter:

Frontmatter fields

The frontmatter is delimited by --- markers. The body (everything after the closing ---) is stored as the skill’s body field. Since 0.9.4 the frontmatter is parsed as one YAML 1.2 document by a pure-Rust parser. yes, on and off stay strings, << is an ordinary key, not a merge, and a second document is refused. The parser also refuses frontmatter that 0.9.3 and earlier accepted: a key given twice at any level (0.9.3 kept the last value), a null (~ or an empty value) as description or as a metadata value (0.9.3 stored ~ or an empty string), an unrecognized tag such as !custom, a ... document end marker, nesting deeper than 64 levels, and 100 or more aliases that outnumber their anchors more than ten to one. A block scalar keeps its line breaks as YAML specifies, also at the end of the frontmatter, where 0.9.3 dropped the final one. Extension values reach SkillDocument.extensions as text: a string as written, and any other value as YAML rendered from its resolved value, not from your source text. 1.10 is 1.1, 1_000 is 1000, 017 is 17.0, tRUE is true, 6.02e23 is 6.02e+23, and a mapping or sequence is block YAML; parse a structured value as YAML to read it. Quote a number with leading zeros, such as a file mode (mode: '0755'): unquoted, 0755 resolves as the decimal 755.0.

Capability gating

Skills are filtered by their requires_capabilities field before being shown or injected:
  • A skill is included only if all its required capabilities are available in the current build/config.
  • A skill with an empty requires_capabilities list is always available.

Capability companion skills

Companion skills are the standard agent instruction-manual pattern for nontrivial Meerkat-owned tool families. They are:
  • embedded in the crate or tool family that owns the capability
  • gated with requires_capabilities
  • discoverable through the normal skills inventory
  • loadable through typed activation, and with load_skill when that default-disabled tool is explicitly policy-enabled
  • not automatically preloaded
Tool descriptions should stay short and schema-focused: what the tool does and what arguments it accepts. Companion skills explain when, how, and why to use a tool family. Every nontrivial agent-facing built-in tool family should have human docs plus a companion skill, or an explicit documented exemption.

Skill identity and resolution

Every runtime skill reference resolves to:
The source identity registry applies source lifecycle gates and lineage/remap rules before load. Disabled or retired sources fail resolution; configured source rotations, renames, splits, and merges require explicit lineage and per-skill remap entries where needed. Legacy slash-delimited strings are no longer accepted by wire skill_refs. rkat run --skill still accepts a bare embedded-builtin skill slug as a convenience, but API and tool surfaces should use structured keys.

Rendering

The renderer produces two output formats:
Generates an <available_skills> XML block listing all available skills for the system prompt:
Identity is emitted as the two typed attributes that map 1:1 to the load_skill tool contract — never a single re-parseable slash id.When there are more than 12 skills, collection mode is used instead:
The inventory never names tools. When a session actually composes both browse_skills and load_skill, the factory appends one guidance line after the inventory telling the model to browse with browse_skills and activate with load_skill.This section is injected into the system prompt via the extra_sections parameter of assemble_system_prompt() in crates/meerkat/src/prompt_assembly.rs.

Size limits

The default injection limit is 32 KiB (32 * 1024 bytes), configurable through skills.max_injection_bytes. If an injection block exceeds the active limit, it is truncated with a warning log.

Built-in skills

The following skills are embedded in component crates:
Known issue, noted 2026-11-13. The four binaries in the Linux x86_64 release archives (rkat, rkat-rpc, rkat-rest, rkat-mcp) start without the built-in skills below and report an empty capability list, with no error: rkat skill list reports 0 skills, and a built-in slug given to rkat run --skill is accepted and has no effect. A skill of your own (.rkat/skills/) still loads on them for a session, unless it declares requires_capabilities: one that does is dropped without a message. Mob members run by these binaries are built without the built-in skills a mob preloads (mob-communication, and workgraph-workflow or task-workflow by profile): the spawn succeeds and the member still has its communication tools. A project copy of those skills does not change this: the workaround on the release page restores a built-in skill for a session, not for mob members. Members of a mob run by the published Meta rpc_gateway are not affected. See the known issue on the 0.9.14 release page for the releases and platforms that were checked, how each statement is known, and the workaround.

Configuration reference

Custom skills

Create a subdirectory under .rkat/skills/ with a SKILL.md file:
Example .rkat/skills/my-deployment/SKILL.md:

Discovery tools

When skills are active and general builtins are enabled, the runtime registers these implementations with CompositeDispatcher: All five implementations have default_enabled: false. A custom embedding must explicitly enable the desired names through BuiltinToolConfig. Current factory-built CLI, REST, and JSON-RPC sessions do not add that policy enable, so they do not advertise these tools even though skill inventory, preload, and typed skill_refs remain available. An allow-list applied later through ToolScope cannot compose a policy-disabled implementation. The skill inventory mentions browse_skills and load_skill only when both are composed for the session; on a normal factory-built session, use public skill introspection plus typed preload or skill_refs instead.

Invoking skills

Skills can be activated in three ways:

1. CLI preload convenience

The CLI --skill option accepts bare embedded-builtin skill slugs and materializes builtin-source SkillKey values for preload:
Use typed keys for API and tool surfaces.
Do not pass a filesystem path or a non-builtin source slug to rkat run --skill in the current release. The path resolver can discover the directory, but the preload carrier still materializes a builtin-source key and cannot address the derived filesystem source. Register the directory under skills.repositories (or with rkat skill add), inspect the registered source UUID, then use its typed SkillKey through an API surface.
Pass tagged skill_refs in API requests to resolve and inject skills for a specific turn:
Legacy skill_references strings are retired and rejected; use structured skill_refs. A nonempty skill_refs selection never silently downgrades to an ordinary turn. If the agent was built without a skill engine (for example, skills were disabled when the session was built, and the config was changed later without rebuilding it), the turn fails before any provider call. It fails with skill_resolution_failed and the typed reason no_skill_engine, which lists the requested keys.

3. Preloading at session creation

Pass preload_skills to inject skills into the system prompt at session creation:
See the Python SDK and TypeScript SDK for SDK wrappers. CLI --skill is a builtin-slug preload convenience; it is not the same surface as typed per-turn skill_refs.

Skill introspection

Skill introspection lets you see all skills — including shadowed ones — with their provenance information. This is useful for debugging skill resolution, understanding which source provides which skills, and inspecting shadowed skills before overriding them.

Surfaces

Shadowing

When multiple sources provide the same full SkillKey, the first source in the runtime composite wins. Introspection shows both the active skill and the shadowed entries. The common case is that matching skill_name values from different sources remain separate active skills because their source_uuid values differ:
Use a full SkillKey (skill_name plus source_uuid) when inspecting or loading a specific source.

Rust SDK

Configuration

Skills are configured through the realm’s SkillsConfig. Realm configuration composition is the single authority; the skills resolver consumes the resulting repository list with the realm’s explicit convention roots.

See also