Skills

[[repositories]]
name = "company"
source_uuid = "11111111-1111-1111-1111-111111111111"
type = "git"
url = "https://github.com/company/meerkat-skills.git"
git_ref = "main"
ref_type = "branch"    # "branch", "tag", or "commit"
refresh_seconds = 300  # TTL for branch refs (tags/commits are immutable)
depth = 1              # shallow clone depth
# auth = { scheme = "token", token = "${GITHUB_TOKEN}" }    # optional HTTPS token; env vars expanded
# auth = { scheme = "ssh-key", path = "~/.ssh/id_ed25519" } # or an SSH private key path

[[repositories]]
name = "remote"
source_uuid = "22222222-2222-2222-2222-222222222222"
type = "http"
url = "https://skills.example.com/api"
auth = { scheme = "bearer", token = "${SKILLS_API_KEY}" }  # or { scheme = "header", name = "...", value = "..." }
refresh_seconds = 300
timeout_seconds = 15

[[repositories]]
name = "local-shared"
source_uuid = "33333333-3333-3333-3333-333333333333"
type = "filesystem"
path = "/opt/meerkat-skills"

[[repositories]]
name = "generated"
source_uuid = "44444444-4444-4444-4444-444444444444"
type = "stdio"
command = "my-skill-server"
args = ["--json"]

---
name: shell-patterns
description: "Background job workflows: patterns and tips"
requires_capabilities: [builtins, shell]
---

# shell-patterns

When running background jobs...

{
  "source_uuid": "dc256086-0d2f-4f61-a307-320d4148107f",
  "skill_name": "email-extractor"
}

rkat run "Extract emails" --skill email-extractor

{
  "method": "turn/start",
  "params": {
    "session_id": "...",
    "prompt": "Extract emails from this text",
    "skill_refs": [
      {
        "kind": "structured",
        "source_uuid": "dc256086-0d2f-4f61-a307-320d4148107f",
        "skill_name": "email-extractor"
      }
    ]
  }
}

{
  "method": "session/create",
  "params": {
    "prompt": "Hello!",
    "preload_skills": [
      {
        "source_uuid": "dc256086-0d2f-4f61-a307-320d4148107f",
        "skill_name": "extraction-email"
      },
      {
        "source_uuid": "dc256086-0d2f-4f61-a307-320d4148107f",
        "skill_name": "formatting-markdown"
      }
    ]
  }
}

[
  {
    "key": {
      "source_uuid": "00000000-0000-4b11-8111-000000000001",
      "skill_name": "task-workflow"
    },
    "name": "Task Workflow",
    "scope": "builtin",
    "is_active": true
  },
  {
    "key": {
      "source_uuid": "dc256086-0d2f-4f61-a307-320d4148107f",
      "skill_name": "task-workflow"
    },
    "name": "Custom Task Workflow",
    "scope": "project",
    "is_active": true
  }
]

use meerkat::{AgentFactory, SkillRuntime, SkillFilter};
use meerkat_core::{Config, skills::{SkillKey, SkillName, SourceUuid}};

let config = Config::load().await?;
let factory = AgentFactory::new(store_path);

// Build a SkillRuntime (requires "skills" feature)
if let Some(runtime) = factory.build_skill_runtime(&config).await? {
    // List all skills with provenance
    let entries = runtime.list_all_with_provenance(&SkillFilter::default()).await?;
    for entry in &entries {
        println!(
            "{}: active={}, source={}",
            entry.descriptor.key,
            entry.is_active,
            entry.descriptor.source_name,
        );
    }

    // Load a specific skill's body. The SkillKey already pins the source
    // UUID; the optional second argument filters by repository *name*.
    let key = SkillKey::new(
        SourceUuid::parse("dc256086-0d2f-4f61-a307-320d4148107f")?,
        SkillName::parse("task-workflow")?,
    );
    let doc = runtime.load_from_source(&key, None).await?;
    println!("{}", doc.body);
}

# realm config (or ~/.rkat/skills.toml and .rkat/skills.toml in layered compatibility mode)
enabled = true
max_injection_bytes = 32768    # max size of injected skill content
inventory_threshold = 12       # flat listing below, collection mode above

[[repositories]]
name = "company"
source_uuid = "55555555-5555-5555-5555-555555555555"
type = "git"
url = "https://github.com/company/skills.git"