Skip to content
E. AguilarKeel Skillsdocs
Menu · Specification

Reference

The specification

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

spec v0.1 · 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 authorization 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 levels (§2) — L1 / L2 / L3, of which only L3 authorizes execution. See the authorization model.
  • The four-step test (§3) — run before every action; first step that applies wins; any doubt → L3.
  • Hot zones (§4) — the default categories a conforming implementation must treat as hot.
  • Mechanical propagation (§5) — the only way approval is inherited without a new L3, gated on all four conditions.
  • Delegation (§6) — subagents never grant L3; 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 test before every action.
  3. Treats every default hot-zone category as hot unless the policy concretely refines it.
  4. Only inherits approval through mechanical propagation when all four conditions hold.
  5. Never lets a subagent grant L3 (if it supports delegation).
  6. Resolves any doubt toward L3.

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.