Skills examples

For the full guide, see Skills.

Recommended progression on this page:

discover skills
inspect a skill
preload skills for a session
inject typed skills for the first turn if you do not want a session-level preload
inject skills for one specific turn

List available skills

Discover all skills from every source (project, user, filesystem, git, HTTP, stdio, embedded) with provenance and shadowing info.

# Human-readable table
rkat skill list

# Machine-readable JSON
rkat skill list --json

{
  "jsonrpc": "2.0", "id": 1,
  "method": "skills/list",
  "params": {}
}

curl http://127.0.0.1:8080/skills

{
  "name": "meerkat_skills",
  "arguments": { "action": "list" }
}

skills = await client.list_skills()
for s in skills:
    key = s.key
    print(f"{key.source_uuid}/{key.skill_name}: {s.name}")

const skills = await client.listSkills();
for (const s of skills) {
  const key = s.key as { source_uuid: string; skill_name: string };
  console.log(`${key.source_uuid}/${key.skill_name}: ${s.name}`);
}

let entries = skill_runtime
    .list_all_with_provenance(&SkillFilter::default())
    .await?;
for entry in &entries {
    println!("{}: active={}", entry.descriptor.key, entry.is_active);
}

Inspect a skill

View the full body and metadata of a specific skill by canonical key.

CLI
MCP
Rust

# Inspect the active version
rkat skill inspect task-workflow \
  --source-uuid 00000000-0000-4b11-8111-000000000001

# JSON output
rkat skill inspect task-workflow \
  --source-uuid 00000000-0000-4b11-8111-000000000001 \
  --json

{
  "name": "meerkat_skills",
  "arguments": {
    "action": "inspect",
    "skill_key": {
      "source_uuid": "00000000-0000-4b11-8111-000000000001",
      "skill_name": "task-workflow"
    },
    "source": "00000000-0000-4b11-8111-000000000001"
  }
}

let key = SkillKey::new(
    SourceUuid::parse("00000000-0000-4b11-8111-000000000001")?,
    SkillName::parse("task-workflow")?,
);
// The SkillKey pins the source UUID. In the factory-built runtime, the
// optional `source_name` selector is a UUID string resolved through
// source lineage, not a repository display name.
let doc = skill_runtime.load_from_source(&key, None).await?;
println!("{}", doc.body);

Preload skills for a session

Use this when the skill should shape the whole session from the start. CLI --skill is a preload-oriented builtin-slug convenience. preload_skills is the explicit session-build surface on the APIs. Local filesystem paths are not a supported rkat run --skill preload in the current release, and custom-source slugs do not become builtin keys. Configure a filesystem repository and use its typed key instead.

rkat run "Track the implementation and use the shell safely" \
  --tools workspace \
  --skill task-workflow \
  --skill shell-patterns

{
  "jsonrpc": "2.0", "id": 1,
  "method": "session/create",
  "params": {
    "prompt": "Extract emails",
    "preload_skills": [
      {
        "source_uuid": "dc256086-0d2f-4f61-a307-320d4148107f",
        "skill_name": "email-extractor"
      },
      {
        "source_uuid": "dc256086-0d2f-4f61-a307-320d4148107f",
        "skill_name": "markdown-formatter"
      }
    ]
  }
}

curl -X POST http://127.0.0.1:8080/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Extract emails",
    "preload_skills": [
      {
        "source_uuid": "dc256086-0d2f-4f61-a307-320d4148107f",
        "skill_name": "email-extractor"
      },
      {
        "source_uuid": "dc256086-0d2f-4f61-a307-320d4148107f",
        "skill_name": "markdown-formatter"
      }
    ]
  }'

{
  "name": "meerkat_run",
  "arguments": {
    "prompt": "Extract emails",
    "preload_skills": [
      {
        "source_uuid": "dc256086-0d2f-4f61-a307-320d4148107f",
        "skill_name": "email-extractor"
      },
      {
        "source_uuid": "dc256086-0d2f-4f61-a307-320d4148107f",
        "skill_name": "markdown-formatter"
      }
    ]
  }
}

from meerkat import SkillKey

result = await client.create_session(
    "Extract emails",
    preload_skills=[
        SkillKey(
            source_uuid="dc256086-0d2f-4f61-a307-320d4148107f",
            skill_name="email-extractor",
        ),
        SkillKey(
            source_uuid="dc256086-0d2f-4f61-a307-320d4148107f",
            skill_name="markdown-formatter",
        ),
    ],
)

const result = await client.createSession("Extract emails", {
  preloadSkills: [
    {
      sourceUuid: "dc256086-0d2f-4f61-a307-320d4148107f",
      skillName: "email-extractor",
    },
    {
      sourceUuid: "dc256086-0d2f-4f61-a307-320d4148107f",
      skillName: "markdown-formatter",
    },
  ],
});

let build_opts = SessionBuildOptions {
    preload_skills: Some(vec![
        SkillKey::new(
            SourceUuid::parse("dc256086-0d2f-4f61-a307-320d4148107f")?,
            SkillName::parse("email-extractor")?,
        ),
        SkillKey::new(
            SourceUuid::parse("dc256086-0d2f-4f61-a307-320d4148107f")?,
            SkillName::parse("markdown-formatter")?,
        ),
    ]),
    ..Default::default()
};

First-turn skill injection

Use skill_refs when the skill should be injected for the first turn rather than preloaded into the session system prompt.

{
  "jsonrpc": "2.0", "id": 1,
  "method": "session/create",
  "params": {
    "prompt": "Extract emails",
    "skill_refs": [
      {
        "kind": "structured",
        "source_uuid": "dc256086-0d2f-4f61-a307-320d4148107f",
        "skill_name": "email-extractor"
      },
      {
        "kind": "structured",
        "source_uuid": "dc256086-0d2f-4f61-a307-320d4148107f",
        "skill_name": "markdown-formatter"
      }
    ]
  }
}

curl -X POST http://127.0.0.1:8080/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Extract emails",
    "skill_refs": [
      {
        "kind": "structured",
        "source_uuid": "dc256086-0d2f-4f61-a307-320d4148107f",
        "skill_name": "email-extractor"
      },
      {
        "kind": "structured",
        "source_uuid": "dc256086-0d2f-4f61-a307-320d4148107f",
        "skill_name": "markdown-formatter"
      }
    ]
  }'

{
  "name": "meerkat_run",
  "arguments": {
    "prompt": "Extract emails",
    "skill_refs": [
      {
        "kind": "structured",
        "source_uuid": "dc256086-0d2f-4f61-a307-320d4148107f",
        "skill_name": "email-extractor"
      },
      {
        "kind": "structured",
        "source_uuid": "dc256086-0d2f-4f61-a307-320d4148107f",
        "skill_name": "markdown-formatter"
      }
    ]
  }
}

from meerkat import SkillKey

result = await client.create_session(
    "Extract emails",
    skill_refs=[
        SkillKey(
            source_uuid="dc256086-0d2f-4f61-a307-320d4148107f",
            skill_name="email-extractor",
        ),
        SkillKey(
            source_uuid="dc256086-0d2f-4f61-a307-320d4148107f",
            skill_name="markdown-formatter",
        ),
    ],
)

const result = await client.createSession("Extract emails", {
  skillRefs: [
    {
      sourceUuid: "dc256086-0d2f-4f61-a307-320d4148107f",
      skillName: "email-extractor",
    },
    {
      sourceUuid: "dc256086-0d2f-4f61-a307-320d4148107f",
      skillName: "markdown-formatter",
    },
  ],
});

// Embedded Rust has no create-time `skill_refs` field. Create the
// session deferred, then run the first turn with per-turn skill
// references carried in `RuntimeTurnMetadata`.
let created = service.create_session(CreateSessionRequest {
    model: "gpt-5.6-sol".into(),
    prompt: "".into(),
    injected_context: Vec::new(),
    system_prompt: SystemPromptOverride::Inherit,
    max_tokens: None,
    event_tx: None,
    initial_turn: InitialTurnPolicy::Defer,
    deferred_prompt_policy: DeferredPromptPolicy::Discard,
    build: None,
    labels: None,
}).await?;

let result = service.start_turn(&created.session_id, StartTurnRequest {
    prompt: "Extract emails".into(),
    injected_context: Vec::new(),
    system_prompt: None,
    event_tx: None,
    runtime: StartTurnRuntimeSemantics::runtime_metadata(RuntimeTurnMetadata {
        skill_references: Some(vec![
            SkillKey::new(
                SourceUuid::parse("dc256086-0d2f-4f61-a307-320d4148107f")?,
                SkillName::parse("email-extractor")?,
            ),
            SkillKey::new(
                SourceUuid::parse("dc256086-0d2f-4f61-a307-320d4148107f")?,
                SkillName::parse("markdown-formatter")?,
            ),
        ]),
        ..Default::default()
    }),
}).await?;

Per-turn skill injection

Request skill activation for a specific input on an existing session using skill_refs. The materialized SkillContext blocks become transcript/history content and can remain available on later turns, subject to ordinary compaction or other history changes; they do not automatically expire at the end of the turn. This differs from preloading skills into the initial system prompt. On the CLI, --skill remains the embedded-builtin slug preload convenience.

rkat run --resume <session-id> "Now update the task plan" \
  --skill task-workflow

{
  "jsonrpc": "2.0", "id": 2,
  "method": "turn/start",
  "params": {
    "session_id": "019467d9-7e3a-7000-8000-000000000000",
    "prompt": "Now format the output",
    "skill_refs": [
      {
        "kind": "structured",
        "source_uuid": "dc256086-0d2f-4f61-a307-320d4148107f",
        "skill_name": "markdown-formatter"
      }
    ]
  }
}

curl -X POST http://localhost:8080/sessions/019467d9-7e3a-7000-8000-000000000000/messages \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "019467d9-7e3a-7000-8000-000000000000",
    "prompt": "Now format the output",
    "skill_refs": [
      {
        "kind": "structured",
        "source_uuid": "dc256086-0d2f-4f61-a307-320d4148107f",
        "skill_name": "markdown-formatter"
      }
    ]
  }'

{
  "name": "meerkat_resume",
  "arguments": {
    "session_id": "019467d9-7e3a-7000-8000-000000000000",
    "prompt": "Now format the output",
    "skill_refs": [
      {
        "kind": "structured",
        "source_uuid": "dc256086-0d2f-4f61-a307-320d4148107f",
        "skill_name": "markdown-formatter"
      }
    ]
  }
}

from meerkat import SkillKey

result = await session.turn(
    "Now format the output",
    skill_refs=[
        SkillKey(
            source_uuid="dc256086-0d2f-4f61-a307-320d4148107f",
            skill_name="markdown-formatter",
        )
    ],
)

const result = await session.turn("Now format the output", {
  skillRefs: [
    {
      sourceUuid: "dc256086-0d2f-4f61-a307-320d4148107f",
      skillName: "markdown-formatter",
    },
  ],
});

let result = service.start_turn(&session_id, StartTurnRequest {
    prompt: "Now format the output".into(),
    injected_context: Vec::new(),
    system_prompt: None,
    event_tx: None,
    runtime: StartTurnRuntimeSemantics::runtime_metadata(RuntimeTurnMetadata {
        skill_references: Some(vec![SkillKey::new(
            SourceUuid::parse("dc256086-0d2f-4f61-a307-320d4148107f")?,
            SkillName::parse("markdown-formatter")?,
        )]),
        ..Default::default()
    }),
}).await?;

If you need the deeper source/precedence model, continue to the main Skills guide.

Getting started

Concepts

Guides: Models And Hosting

Guides: Runtime Behavior

Guides: Orchestration

Examples: Foundations

Examples: Capabilities

Examples: Orchestration And Deployment

Skills examples

List available skills

Inspect a skill

Preload skills for a session

First-turn skill injection

Per-turn skill injection

Next step

​List available skills

​Inspect a skill

​Preload skills for a session

​First-turn skill injection

​Per-turn skill injection

​Next step

List available skills

Inspect a skill

Preload skills for a session

First-turn skill injection

Per-turn skill injection

Next step