Keel Skills is a portable governance framework for Claude Code agents that solves a specific, expensive problem: autonomous agents act on vague instructions as though they were permission, and the results — a force-push, a deleted migration, a deploy to production — often can’t be undone. The framework ships as three skills, two hooks, and one config file. Together they give the agent a written rule for when it may act alone and when it must stop and ask, enforced at two independent layers so compliance doesn’t depend entirely on the model choosing to cooperate.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/quitohooded/keel-skills/llms.txt
Use this file to discover all available pages before exploring further.
The problem it solves
Most teams have no explicit rule for when an agent may act alone and when it must stop and get a clear yes. The agent is told to “clean it up and push” or “handle it” — and it does. It interprets a goal as permission, reaches into production, force-pushes a branch, or deletes data it wasn’t meant to touch. The Keel permission model draws a hard line between three things that get confused with permission:- A goal — a direction with no specific scope (“improve this”, “do what’s needed”, “handle it”). A goal lets the agent look into something and write a clearly labeled proposal. It does not let the agent act.
- A method — the human names how (“use a migration”, “edit the config”). Naming the method is not approving the action. It does not let the agent act.
- A green light — either an explicit scoped approval, or a written-down, still-current decision that already covers the scope. Only a green light means go.
What’s inside
Authorization Protocol
Decides whether the agent may act or must stop and ask. Sorts instructions into a goal, a method, or a green light, then runs the four-step check before any action that writes or changes something.
Model Delegation
Assigns the cheapest model that still preserves quality and risk control. Enforces tier-by-task, a maximum subagent depth of two, no self-escalation, and a cheapest-first tool ladder.
Context Discipline
Keeps the session anchored in files rather than chat. Defines when to end a long session, what to record, and how to leave a resumable handoff for the next session.
AGENT_POLICY.md
The per-project config file you control. Declares hot zones, source-of-truth files, where decisions are recorded, and any standing approvals — all the specifics the generic skills need.
Two layers of protection
Keel operates in two complementary layers. You want both: the soft layer gives the agent context-aware judgment; the hard layer fires regardless of what the model decided.| Soft layer (skills / reasoning) | Hard layer (enforcement hook) | |
|---|---|---|
| What it is | Three skills that make the agent apply the four-step check before acting | PreToolUse hook (enforce-policy.cjs) that intercepts tool calls before they run |
| Strength | Context-aware; understands nuance and project-specific circumstances | Deterministic; fires unconditionally before every matched tool call |
| Weakness | Depends on the model choosing to comply | Pattern-matches commands and paths; a sophisticated adversarial agent can route around it |
| Covers headless? | No — a model running without a human present still needs to reason its way to a stop | Yes — in CI or KEEL_NONINTERACTIVE=1 mode, any ask verdict is automatically escalated to deny |
Key separation: mechanism vs. your data
The three skills are generic. They describe the pattern — what a risky zone is, what following through on a green light means, how a model gets chosen — without any of your project’s specifics embedded in them. Everything particular to your work lives in a single file you control:AGENT_POLICY.md at your project root.
The result is that the framework ships clean and the same plugin installation works across all your projects. Each project gets its own AGENT_POLICY.md declaring its hot zones, source-of-truth files, and standing approvals. The SessionStart hook auto-injects that file into context at the start of every session, so the policy doesn’t depend on the agent choosing to read it.
Keel Skills is a backstop, not a sandbox. It catches accidents, drift, and hallucinated actions — a large lift in assurance — but a determined or jailbroken agent with shell access can evade command-pattern matching. Pair it with scoped credentials and a sandbox for real isolation.
Quickstart
Install the plugin, run
policy-init, and have enforcement active in under five minutes.Permission Model
A deep dive into the goal / method / green light distinction and the four-step check.