Agent skill

Drop krabs into your agent in one file. skill.md contains everything an agent needs to operate krabs end-to-end — primitives, transports, auth, voice rules, common operations, and error recovery.

What's a skill

A skill is a single Markdown file with a YAML frontmatter that an agent host can ingest as durable knowledge. The format originated with Claude Code (Anthropic's CLI), but the convention is generic enough that you can load it into any agent runtime as a system message, a tool description, or static context.

krabs-skill.md is the one we publish — it carries the verb/noun vocabulary, the three transports, the auth flow, the voice rules, and the common operations agents will need most.

Install in Claude Code

Drop the file into your Claude Code skills directory:

mkdir -p ~/.claude/skills/krabs
curl -fsSL https://krabs.dev/skill.md -o ~/.claude/skills/krabs/SKILL.md

Claude Code picks it up next time you start a session. Invoke the skill with /krabs or let Claude decide based on the description in the frontmatter.

Use as a raw prompt

For hosts that don't natively support skills (custom agents, raw API calls, LangChain, etc.) prepend the file to your system message:

SKILL = fetch("https://krabs.dev/skill.md").text()
messages = [
  { role: "system", content: SKILL },
  { role: "user",   content: userPrompt },
]

The agent now has the full krabs vocabulary in context. Token cost is ~2k tokens.

Fetch at runtime

The skill changes with each minor version. If your agent calls krabs in production and you want to track the latest contract automatically, fetch the skill at startup and cache it for the session:

# Bash
SKILL=$(curl -fsSL https://krabs.dev/skill.md)

# Node
const skill = await (await fetch("https://krabs.dev/skill.md")).text()

# Python
skill = httpx.get("https://krabs.dev/skill.md").text

What's inside

The skill covers everything an agent needs to operate krabs without prior context:

• How to invoke krabs over each transport (MCP, CLI, HTTP) with copyable snippets.
• The 7 primitives (contact, identity, interaction, deal, task, note, tag) with id prefixes.
• How to mint and rotate auth tokens. Where to send the user for the device flow when the agent doesn't have one.
• The five contract guarantees: intent, idempotency, dry-run, schema introspection, reversible audit.
• Common operations with concrete commands (upsert, attach identity, create deal, undo).
• All error codes (auth_*, rate_limited, not_found, conflict, validation) with recovery hints.
• krabs voice rules so user-facing copy the agent writes stays on-brand (lowercase product name, no marketing softeners, sentence case, no emoji).

Prefer MCP for live tools

The skill is static knowledge. The MCP server (mcp.krabs.dev) is live execution. If your host supports both, do both:

• Mount the MCP server so the agent has actual callable tools.
• Load the skill so the agent has the conceptual model, voice rules, and recovery logic.

MCP without the skill works — but the agent will likely call tools without the voice or error-handling sophistication krabs expects.