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> --approvelands it as a commit on a newskep/<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 askep/*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 difffor what changed. - Changing it is their act:
skep policy approve --reapproveshows the diff and asks for a typedyes.
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, orrequire_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-rootis a read inside the operator's own roots,default/unmatchedmeans 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
whyand 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.