Docs Connect

The KIFF skill for coding agents

Beta. The skills, plugins and their install steps may change between versions.

The KIFF skill is a SKILL.md file that teaches Claude Code, Codex and similar agents how to work with KIFF. With it installed, an agent can:

  • connect an agent or a remote MCP tool to KIFF, step by step, through the MCP gateway, kiff-guard or the decision API;
  • propose a Card: draft the terms an agent needs (which tool, the most per call, totals per day, hold or refuse, how long a hold waits) and explain each line, for the owner to issue;
  • handle a held call correctly: tell the person it is waiting, retry the identical call with the same kiff_operation_id, and never make the same change another way;
  • find the right place: the KIFF repositories, SDKs, endpoints and doc pages.

It is a plain markdown file, served at kiff.dev/skills/kiff.md. Read it before you install it.

What enforces the Card

The skill is not the security boundary. It is instructions to the agent. The KIFF MCP gateway (mcp.kiff.dev) enforces each agent’s Card on KIFF’s servers, for every call that goes through it, whatever the instructions say.

Installing the skill alone does not enforce anything. A Card applies only to calls that go through KIFF; a call the agent makes some other way is outside it.

Install it

Claude Code, as a plugin. It adds this skill, the domain skill and the KIFF MCP gateway as a server named kiff:

/plugin marketplace add kiff/kiff-plugins
/plugin install kiff-cards@kiff

Claude Code asks for this agent’s gateway key when you enable the plugin and keeps it in its secure storage (from the agent’s Tools tab, Claude Code or Codex). Leave it empty and the skills still work; the server just does not connect. The skill itself never reads or handles a key. Source: github.com/kiff/kiff-plugins.

Optional: Card status, notices and recovery in Claude Code

The marketplace contains two plugins. kiff-cards adds the gateway connection and skills described above. kiff adds the interface: Card status, notices for held calls, and the /kiff pane. It needs a gateway connection and a Claude Code version that runs plugin hooks modules. Install it after connecting kiff-cards:

/plugin install kiff@kiff

If you installed the former kiff-cards-ui plugin, uninstall it; kiff replaces it. The interface can also use a gateway connected through a KIFF connect link or the claude.ai KIFF connector.

For an existing installation, update the marketplace and plugin from your terminal, then restart Claude Code to apply the update:

claude plugin marketplace update kiff
claude plugin update kiff@kiff
  • Status line: shows what is left on the agent’s Card. While a call is held, it shows that the call is waiting for approval instead. Plugin 0.2.2 also distinguishes Approved, waiting for room from an unavailable read. Waiting for room does not start a collection turn.
  • Held-call notice: explains that nothing was sent and links to the call in KIFF Cloud, where the owner or an admin answers.
  • Owner-answer notice: while this session has an unanswered held call, the plugin reads kiff_pending every 15 seconds. When it finds an approval, refusal or ended hold, it shows one notice and submits one turn telling the agent. Claude Code runs the turn when idle. The agent decides whether to collect an approved call by calling the same tool again with the original arguments and operation id.
  • /kiff: opens this session’s KIFF calls and refreshes the Card and pending answers. It also provides a way to resume reads after a permission refusal.

The plugin reads kiff_card for the Card and kiff_pending for owner answers. Both are read-only: these reads send nothing to a connected business tool, use no approval and draw nothing from the Card. The plugin never approves a call or invokes the held business tool itself.

Allow the two read-only tools

Claude Code’s permissions apply to these reads. Type /kiff; if a read was refused, Claude Code asks whether to allow the tool. Choose to allow it for future reads. In auto mode, Claude Code decides without asking; you can instead add the rules below through /permissions → Allow.

Use the names matching your gateway connection. Each rule is just the tool name, with no allow prefix. Save under User settings to apply across folders, or under project settings for that project only.

Gateway connection Card read Pending-call read
kiff-cards plugin mcp__plugin_kiff-cards_kiff__kiff_card mcp__plugin_kiff-cards_kiff__kiff_pending
Connect link added as kiff mcp__kiff__kiff_card mcp__kiff__kiff_pending
claude.ai KIFF connector mcp__claude_ai_KIFF__kiff_card mcp__claude_ai_KIFF__kiff_pending

After a permission refusal, the plugin explains it once and stops background reads of that tool. Once you grant permission, run /kiff to read again and resume background checks. The plugin cannot grant itself permission.

Recovery after a delayed answer or outage

Pending reads are paginated. Each check reads a bounded number of pages and keeps its cursor for the next check, including checks started with /kiff. A hold behind more than 500 newer pending calls can still be found; recovery does not keep restarting at page one.

Two minutes after the hold’s expiry, the plugin finishes one last read before stopping automatic checks for that hold. A partial scan, failed read or unavailable answer does not finish that check. Recovery continues until the answer can be read, or a complete scan establishes that the hold is absent. An authoritative waiting answer counts as a completed read; unavailable does not. If the answer stays unavailable, checks can continue every 15 seconds for the rest of the session.

approved_no_room also completes the read without treating the hold as collectible. Background checks remain bounded as above; after they stop, /kiff reads again. Once KIFF reports a collectible approval, the plugin sends its usual single notice and turn. It never grants extra room itself.

An approval given before the hold expired still counts when read late. The plugin announces an answer once, however late it reads it. This does not extend the time the owner has to approve: a new approval after expiry is refused. After automatic checks have ended, /kiff checks again. See Held calls and approvals.

Install only the skill in another agent

Claude Code, the skill only:

mkdir -p ~/.claude/skills/kiff && curl -fsSL https://kiff.dev/skills/kiff.md \
  -o ~/.claude/skills/kiff/SKILL.md

Codex:

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills/kiff" && curl -fsSL https://kiff.dev/skills/kiff.md \
  -o "${CODEX_HOME:-$HOME/.codex}/skills/kiff/SKILL.md"

Any other agent that reads an instructions file (Cursor, Gemini CLI, Aider, Amp, OpenCode, Windsurf): save the skill as its own file, then point your instructions file at it once.

curl -fsSL https://kiff.dev/skills/kiff.md -o KIFF.md
echo "Read KIFF.md before working with KIFF." >> AGENTS.md

Use your agent’s own instructions file in place of AGENTS.md if it has one (for example GEMINI.md). Start a new session so the agent picks it up. To update, run the curl line again: it overwrites KIFF.md, and the line in AGENTS.md stays as it is.

What to ask

Connect my refund tool to KIFF and give this agent a Card.
What should this agent's Card be? It issues refunds of about 30 euros, about ten a day.
KIFF held my last call. What do I do?

What it will not do

The skill tells the agent to stay on its side of the Card. Where KIFF also enforces the rule on its servers, the line says so:

  • It never issues or changes a Card itself. It drafts the terms; the owner issues them in KIFF Cloud. An agent’s key is refused if it tries.
  • It never answers a held call. Only a person on the account who may approve, signed in at app.kiff.dev, can; an agent’s key is refused. A “yes” in the chat is not an approval.
  • It never asks for an owner or admin credential, and keeps keys out of files you commit.
  • When KIFF holds or refuses a call, it does not make the same change another way (a direct API call, a shell, a browser). It reports what happened and stops.

It also says plainly that KIFF governs only the calls that go through it, and suggests removing any direct route the agent still has to the same tool.

← Quickstart kiff-guard on GitHub ↗