Claude Code Skills

Kanoniv Auth ships five skills that turn Claude Code into a scope-enforced agent. Install them once, and every tool call is verified against the active delegation token before execution. Denied actions never run. Every allowed action is logged to an append-only audit trail.

Install

kanoniv-auth install-skill
# Installed 5 kanoniv-auth skills:
#
#   /delegate  - Start a scoped session (with enforcement hooks)
#   /scope     - Change scopes mid-session
#   /ttl       - Extend session TTL
#   /status    - Check current delegation status
#   /audit     - View the agent audit trail
#
# Start Claude Code and type /delegate to begin.

This copies the skill definitions and hook scripts to ~/.claude/skills/. Five directories are created: delegate, scope, ttl, status, and audit.

The Five Skills

Skill	Purpose
/delegate	Start a scoped session with enforcement hooks
/scope	Change scopes mid-session without restarting
/ttl	Extend or change session TTL without changing scopes
/status	Check current delegation status, agent identity, and TTL
/audit	View the local audit trail with optional filters

/delegate

The primary skill. Starts a delegation session and activates PreToolUse hooks that enforce scope on every subsequent tool call.

Usage

Type /delegate in Claude Code. The skill asks two questions:

1. Agent name and TTL

Name this agent and set the session duration.

  A) claude-code, 4h (Recommended)
  B) Custom - I'll specify name and TTL

If you choose B, provide a name (e.g. deploy-bot) and a TTL (e.g. 2h, 30m, 8h). The name gives the agent a persistent did:agent: identity - same name produces the same DID across sessions.

2. Scopes

What should claude-code be allowed to do this session?

  A) Full dev - code.edit, test.run, git.commit, git.push (Recommended)
  B) Read-only + test - code.read, test.run
  C) Repo-scoped - code.edit, test.run, git.push.{repo}.{branch}
  D) Custom scopes - I'll specify

Option C auto-detects the current repository and branch.

What Happens

1. Generates (or reuses) an agent keypair based on the --name value
2. Issues a delegation token with the specified scopes and TTL
3. Saves the token to ~/.kanoniv/session-token
4. Activates PreToolUse hooks on Bash, Edit, and Write tools
5. Activates a PostToolUse hook that logs every action to ~/.kanoniv/audit.log

INFO

The /delegate skill uses ~/.kanoniv/session-token for the active session. This is separate from the token store at ~/.kanoniv/tokens/ used by the CLI. The hooks re-read the session token file on every tool call, so re-delegation takes effect immediately.

How Enforcement Works

Three PreToolUse hooks intercept tool calls before execution:

Hook Script	Intercepts	Purpose
check-scope.sh	Bash	Maps commands to scopes, verifies against token
check-edit-scope.sh	Edit, Write	Verifies code.edit scope
log-action.sh	All (PostToolUse)	Logs action to ~/.kanoniv/audit.log

Verification Flow

1. Hook reads tool input from stdin (JSON with tool_input)
2. Maps the operation to a scope string (see table below)
3. Reads ~/.kanoniv/session-token
4. Calls kanoniv-auth verify --scope <required> --token <token>
5. PASS: returns {} - tool call proceeds normally
6. DENIED: returns {"permissionDecision":"block","message":"SCOPE DENIED: ..."} - tool call is blocked

When denied, Claude Code displays:

SCOPE DENIED: requires git.push.myrepo.main

You have: ['code.edit', 'test.run']

Re-delegate with: kanoniv-auth delegate --scopes ...,git.push.myrepo.main --ttl 4h

The command never executes.

Scope Mapping

The check-scope.sh hook maps Bash commands to scope strings:

Operation	Mapped Scope
git push origin main	git.push.{repo}.main
git push origin feature-x	git.push.{repo}.feature-x
git commit, git add, git rebase	git.commit.{repo}
cargo test, pytest, npm test, vitest, jest	test.run
cargo build, cargo check, npm run build	code.edit
File edits (Edit tool)	code.edit
File writes (Write tool)	code.edit
Compound commands (&&, ||, ;, $(...))	code.edit
kanoniv-auth commands	Always allowed
Read-only git (git status, git log, git diff)	Always allowed
Read-only shell (cat, ls, grep, head, echo)	Always allowed
Read tool	Always allowed
Everything else	code.edit

Scopes are hierarchical. A token with git.push satisfies git.push.myrepo.main. The hook tries the exact scope first, then strips segments from the right until it finds a match or exhausts the hierarchy.

INFO

The {repo} in git scopes is the repository directory name, detected via git rev-parse --show-toplevel. The {branch} for push commands is extracted from the push arguments, or falls back to the current branch.

/scope

Change scopes without restarting the session. Keeps the same agent name and resets the TTL to 4h.

Usage

/scope code.edit,test.run,git.push

The skill reads the current agent name from the session token, then re-delegates with the new scopes. No questions asked.

Scopes updated to: code.edit,test.run,git.push

WARNING

/scope requires an active session. If no session token exists, it tells you to run /delegate first.

/ttl

Extend or change the session TTL. Keeps the same agent name and scopes.

Usage

/ttl 8h

Re-delegates with the new TTL. The agent identity and scopes remain unchanged.

TTL updated to: 8h

/status

Quick status check showing agent identity, scopes, and remaining time.

Usage

/status

Output

When active:

ACTIVE
  Agent:  claude-code
  DID:    did:agent:5e06a3...
  Scopes: code.edit, test.run
  TTL:    1h 42m

When expired:

EXPIRED
  Agent:  claude-code
  Died:   23m ago

  Re-delegate:
    kanoniv-auth delegate --name claude-code --scopes code.edit,test.run --ttl 4h

When no delegation exists:

NO TOKEN
  No active token. Delegate one:
    kanoniv-auth delegate --name <agent> --scopes <scopes> --ttl 4h

The /status skill also shows the last 5 audit log entries for the active agent, if any exist.

/audit

View the local audit trail with optional filters.

Usage

/audit

With filters:

/audit --agent claude-code --since 2026-03-22 --limit 20

The skill runs kanoniv-auth audit-log with the appropriate flags and presents the results as a formatted table.

Filter Options

Filter	Flag	Example
Agent name	--agent	--agent claude-code
Action type	--action	--action verify
Since date	--since	--since 2026-03-22
Max entries	--limit	--limit 100 (default: 50)

Audit Log Format

All actions are logged to ~/.kanoniv/audit.log as an append-only file. Each line is a fixed-width record:

TIMESTAMP           AGENT_NAME        AGENT_DID                 ACTION        DETAIL                                    RESULT
2026-03-22 19:15:03  claude-code       did:agent:5e06a3...       tool:bash     git commit -m "feat: add caveats"         ok
2026-03-22 19:15:05  claude-code       did:agent:5e06a3...       tool:bash     cargo test --lib                          ok
2026-03-22 19:15:08  claude-code       did:agent:5e06a3...       tool:edit     delegation.rs                             ok
2026-03-22 19:15:12  claude-code       did:agent:5e06a3...       tool:bash     git push origin main                      DENIED
2026-03-22 19:17:00  claude-code       did:agent:5e06a3...       delegate      scopes=[code.edit,test.run] ttl=4h        ok
2026-03-22 19:17:01  claude-code       did:agent:5e06a3...       verify        scope=code.edit                           PASS
2026-03-22 19:18:30  claude-code       did:agent:5e06a3...       sign          action=code.edit target=src/lib.rs        ok

Actions logged by the PreToolUse/PostToolUse hooks use the tool:bash, tool:edit, and tool:write action types. Actions from direct CLI usage use delegate, verify, sign, and exec.

The log file is plain text, one line per event, grep-friendly. Fields are separated by double-space.

Uninstalling Skills

To remove the skills, delete the directories:

rm -rf ~/.claude/skills/delegate
rm -rf ~/.claude/skills/scope
rm -rf ~/.claude/skills/ttl
rm -rf ~/.claude/skills/status
rm -rf ~/.claude/skills/audit

Next Steps

• Getting Started - Install, delegate, verify, sign
• wrap-mcp - MCP proxy for server-side enforcement
• Caveats - All six caveat types and scope narrowing
• Verification - How offline chain verification works
• Overview - Back to Kanoniv Auth overview