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
SkillKeyidentity and source provenance - understand when to use
preload_skillsvsskill_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 realmconfig.toml). Uses the system git executable:
${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 theirrequires_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_capabilitieslist 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_skillwhen that default-disabled tool is explicitly policy-enabled - not automatically preloaded
Skill identity and resolution
Every runtime skill reference resolves to: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:- Inventory section
- Injection block
Generates an Identity is emitted as the two typed attributes that map 1:1 to the The inventory never names tools. When a session actually composes both
<available_skills> XML block listing all available skills for the system prompt:load_skill tool contract — never a single re-parseable slash id.When there are more than 12 skills, collection mode is used instead: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 throughskills.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:Configuration reference
Custom skills
- Project-level
Create a subdirectory under Example
.rkat/skills/ with a SKILL.md file:.rkat/skills/my-deployment/SKILL.md:Discovery tools
When skills are active and general builtins are enabled, the runtime registers these implementations withCompositeDispatcher:
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:
2. Programmatic typed skill_refs (per-turn, recommended)
Pass tagged skill_refs in API requests to resolve and inject skills for a specific turn:
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
Passpreload_skills to inject skills into the system prompt at session creation:
--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 fullSkillKey, 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:
SkillKey (skill_name plus source_uuid) when inspecting or loading a specific source.
Rust SDK
Configuration
Skills are configured through the realm’sSkillsConfig. Realm configuration
composition is the single authority; the skills resolver consumes the resulting
repository list with the realm’s explicit convention roots.
