Skip to content
E. AguilarKeel Skillsdocs
Menu · Specification

Reference

The specification

The permission model written down independently of any runtime — so it can be cited, audited, and reimplemented outside Claude Code.

spec v0.2 · draft MIT

The Keel Skills plugin for Claude Code is the reference implementation. The spec itself is runtime-neutral: an Agent SDK app, another harness, or a CI gate can implement it too. It specifies two portable things — the permission model and the AGENT_POLICY.md format. The canonical document is SPEC.md in the repo.

What the spec pins down#

  • Terminology — what counts as an action (writes, edits, commits, pushes, deploys, sends, deletes, reconfigures); reading and analysis are not actions.
  • The three things (§2) — a goal, a method, a green light, of which only a green light means go. See the permission model.
  • The four-step check (§3) — run before every action; first step that applies wins; any doubt → ask.
  • Hot zones (§4) — the default categories a conforming implementation must treat as hot.
  • Following through (§5) — the only way a green light carries over without asking again, gated on all four conditions.
  • Delegation (§6) — subagents never grant a green light; shallow nesting; no self-escalation.
  • The AGENT_POLICY.md format (§7) — the six sections and the rules that keep them honest.

Conformance#

An implementation is Keel-compatible if it:

  1. Reads AGENT_POLICY.md from the project root (or a path the user designates) and treats it as authoritative over the defaults.
  2. Runs the four-step check before every action.
  3. Treats every default hot-zone category as hot unless the policy concretely refines it.
  4. Only lets a green light carry over through following-through when all four conditions hold.
  5. Never lets a subagent grant a green light (if it supports delegation).
  6. Resolves any doubt toward stopping and asking.

Key idea

An implementation may add stricter rules. It must not relax §3–§5 below what the spec requires.

Versioning & changes#

The spec uses MAJOR.MINOR. A MINOR bump adds or clarifies without breaking a conforming implementation; a MAJOR bump may change required behavior. Implementations should declare which spec version they target.

It's a draft, and proposals to clarify, tighten, or extend it are welcome via issues and PRs. If you build a Keel-compatible implementation for another runtime, open an issue so it can be listed.