Documentation menu
On this page

Explaining skep to a human — a guide for agents

SKILL.md teaches an agent to operate skep. This page is for the other half: a human asks what is this, why was that blocked, what can it do — and the agent answers. Answer from skep's own output, not from memory: every claim below has a command that shows it.

The one-sentence version

skep is a governor for coding agents: the agent works in a throwaway copy of your repo under rules you approved, skep checks its work itself, and the patch waits for your approval. Your main branch never moves without you.

Then stop and let them ask. Three ideas carry almost every follow-up.

1. The governor, not the agent

skep does not write code. It decides what an agent may do — Claude Code, Codex, Aider, pi, or skep's own worker on a model you choose — and records its decisions. Say it in their terms:

  • The agent is competent and untrusted. It never touches the real repo. It works in a disposable git worktree, often inside a sandbox.
  • Two results must agree. The agent says its tests passed; skep re-runs the verification itself. Either alone is not enough.
  • Landing is the approval. Finished work is a patch. skep review <task_id> shows it; skep review <task_id> --approve lands it as a commit on a new skep/<task_id> branch — never the default branch. Landing without a human is opt-in (the maintain phase or --unlocked): it takes only a patch skep re-verified, and only onto a skep/* branch.
  • Some things are never allowed. A worker cannot push, pull, fetch or switch branches, whatever the rules say. That is the floor.

2. The locked baseline

During onboarding the human picked a template — builder (coding, the default), operator (ops and audits) or assistant (least privilege) — and locked it. Locking stores its hash; skep checks the hash before every decision and refuses if the file changed underneath it.

  • Show them what they locked: skep policy explain baseline — an allow / ask / deny table, plus the floor rows no layer lifts.
  • Show them it is intact: skep policy baseline status (exit 1 = tampered), skep policy baseline diff for what changed.
  • Changing it is their act: skep policy approve --reapprove shows the diff and asks for a typed yes.

The useful framing: the baseline is a ceiling. Project settings, roles and delegation can only make it stricter.

3. Why was that blocked? — why and explain

When a run stops on a card or something is refused, run the same question skep asked:

skep policy why ~/workspace shell run "git push"

Read three fields back to them, in plain words:

  • operator.verdict — allow, deny, or require_approval (a human answers a card).
  • decided_by / rule_id — which rule decided: floor/... is the never-allowed list, a template rule id comes from the baseline, role:<name> is the role layer, grant:session/... / grant:global/... is a card someone approved with keep, global/operator-root is a read inside the operator's own roots, default/unmatched means no rule matched (so it asks).
  • floor (when present) — the reason in a sentence.

Example: "git push is denied by floor.worker-git-hard-denies. Workers never push; when the work is approved, skep can push the landing branch and open a pull request for you." Then look the rule up in skep policy explain baseline so they can see it in context.

A newly onboarded skep also prints a short why-line under every verdict card; skep onboard --quiet turns those off and skep onboard --verbose back on. skep policy decisions is the full ledger of past decisions, newest first.

4. Roles

A role is a prompt, a voice and a policy layer that sits under the baseline: builder, operator, assistant, or a custom one (skep role list, skep role show <name>). A role can only tighten — if the baseline says ask and the role says allow, it still asks. One exception the operator signed (ADR 0059): a role's catch-all ask (shell-learnable *, shell-gated *) is a default, not a ceiling — a command you approved with keep session/always runs again in that role without a card. The role's denies and named asks still bind. A chat runs in one role; skep role use <name> sets the default.

Say: "The role changes what the assistant is for and narrows what it may do. It can never give it more than you locked."

5. Delegation

When one agent dispatches another — the chat dispatching a worker, or a manager dispatching a team with skep team — the dispatched one holds the intersection of the two: its own role and what its delegator holds. A rule the delegator does not have counts as not granted. The floor sits above every chain, and a worker can never dispatch.

Show the chain for one action:

skep policy why ~/workspace shell run "npm test" --role builder --delegated-by queen@operator

The answer gains a delegation block naming the chain and what each hop holds. Under a builder baseline, the builder role allows npm test, but queen@operator would itself have to ask, so the worker asks too: rule_id: exceeds_delegator, verdict require_approval. Say: "Authority only shrinks as it is handed down."

What not to say

  • Don't promise an action will be allowed — run why and quote it.
  • Don't describe a workaround for a deny. The deny is the product working.
  • Don't approve, land, re-lock or tag on their behalf to "save them a step". Those are their decisions; a typed skep command is not carded, so typing it is deciding.