Guide · Agent skill

How to use the Signed Audit Trails Recipe agent skill

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

The signed-audit-trails-recipe skill is a step-by-step guide for adding a verifiable record of what an AI coding agent did. Once set up, each tool call is checked against a written policy and then saved as a signed receipt that anyone with the public key can check later. This guide is for readers new to agent skills who want to install the skill, follow its steps, and understand what it does and does not prove.

Signed Audit Trails Recipewshobson/agents · MIT Download the skill

Quick start

1Download and unzip the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. You can also upload the ZIP under Settings, then Capabilities, then Skills in the Claude apps.
2Install protect-mcp. In Claude Code, run /plugin install protect-mcp. Its hooks run evaluate.sh before each tool call and sign.sh after it.
3Create the signing key. Run the guarded init command to create ./protect-mcp.key once. Keep the file out of version control and share only its publicKey value.
4Write the Cedar policy. Create ./protect.cedar from the skill's example policy and adjust the allowed tools and Bash commands for your project.
5Work with Claude Code. Use Claude Code normally. Each tool call adds one receipt to ./receipts/receipts.jsonl.
6Verify the receipts. Run the verifier with the public key. Exit code 0 means every receipt verified; code 1 means a receipt failed.

What the skill makes the agent do

The skill walks you through a pattern where every Claude Code tool call (Bash, Edit, Write, WebFetch) is first evaluated against a Cedar policy. If the policy denies the call, the tool does not run. After the tool runs, the call is recorded as an Ed25519 signed receipt.

An auditor or counterparty holding the public key can verify the receipts offline, without a network call and without trusting the person who ran the agent. The skill is mainly a teaching and demonstration guide. The runtime hooks come from a separate protect-mcp plugin.

How to install the signed-audit-trails-recipe skill

Download the ZIP from this page and unzip it into one of these locations. Use ~/.claude/skills/ to make the skill available in all your projects, or use a project's .claude/skills/ folder to limit it to that project.

You can also upload the ZIP in the Claude apps under Settings, then Capabilities, then Skills.

Personal: ~/.claude/skills/signed-audit-trails-recipe/
Project: .claude/skills/signed-audit-trails-recipe/ inside your project

Install the protect-mcp plugin and create a signing key

The skill depends on the protect-mcp plugin. Install it inside Claude Code. The plugin's hooks run evaluate.sh before each tool call and sign.sh after it.

protect-mcp does not create the signing key, and without a key the receipts are unsigned. The command below creates ./protect-mcp.key once and never replaces an existing key. Give auditors the publicKey value from that file. Do not commit the file, because it also holds the private key.

Add the key and receipt directory to .gitignore so Git does not track them.

/plugin install protect-mcp
if [ ! -e ./protect-mcp.key ]; then
  d=$(mktemp -d) && npx protect-mcp@0.7.4 init --dir "$d" && mv "$d/keys/gateway.json" ./protect-mcp.key
fi
echo "/protect-mcp.key" >> .gitignore
echo "/receipts/" >> .gitignore

Write the Cedar policy and use Claude Code normally

Create ./protect.cedar from the example in the skill's cedar-policy reference. The example allows read-oriented tools and a short list of Bash commands. It denies shell chaining and destructive commands, and it limits writes to the project by denying '..' path segments.

Start Claude Code and work as usual. Every tool call goes through both hooks, and each one adds a receipt. A session of 20 tool calls appends 20 receipts to ./receipts/receipts.jsonl.

Read-oriented tools (Read, Glob, Grep, WebSearch) are allowed by default in the example policy.
Package-manager and build commands run arbitrary code, so they are only as safe as the project's own scripts.

Inspect and verify the receipts

Each receipt is one line in receipts.jsonl. The command below prints the newest one in readable form. A receipt is a signed envelope that names the tool and holds no public key.

To verify, pass the publicKey value from ./protect-mcp.key to the verifier. The verifier exits with 0 if every receipt verifies, 1 if a receipt fails (tampered, wrong key, or malformed line), and 2 if the file cannot be read.

Exit 0: every receipt verified
Exit 1: a receipt failed verification
Exit 2: the receipts file could not be read

tail -n 1 ./receipts/receipts.jsonl | python3 -m json.tool

PUB=$(node -p 'JSON.parse(require("fs").readFileSync("./protect-mcp.key")).publicKey')
npx @veritasacta/verify@0.9.2 --replay-chain ./receipts/receipts.jsonl --key "$PUB"

Demonstrate tamper detection

To see the verifier catch a change, edit the newest receipt's decision from allow to deny, then run verification again. The verifier exits with code 1 and reports which line failed, because the Ed25519 signature no longer matches the canonical bytes of the changed payload.

Restore the field and verification passes again. Note that receipts carry no link to the previous receipt, so deleting a receipt is not detected by this method.

python3 -c "
import json
path = './receipts/receipts.jsonl'
lines = open(path).read().splitlines()
r = json.loads(lines[-1])
r['payload']['decision'] = 'deny'
lines[-1] = json.dumps(r)
open(path, 'w').write('\n'.join(lines) + '\n')
"

nnpx @veritasacta/verify@0.9.2 --replay-chain ./receipts/receipts.jsonl --key "$PUB"

Use the CI/CD workflow carefully

The skill includes a GitHub Actions workflow in its ci-cd reference that verifies receipts so a tampered receipt fails the build. The signing key is gitignored, so the job reads it from a secret in an environment named receipt-signing, with deployment branches limited to the default branch.

Run this job only on reviewed code, such as pushes to the default branch. Do not run it on pull requests. GitHub does not pass secrets to fork pull requests, and on same-repository branches the job would run that branch's code after the key is written to disk, which exposes the private key to unreviewed code.

Store the contents of protect-mcp.key as the environment secret PROTECT_MCP_KEY
Store the publicKey value as the repository variable PROTECT_MCP_PUBLIC_KEY

What people use it for

Showing a compliance team what an agent read, edited, and ran during a session, with evidence that the log was not altered.
Demonstrating to a counterparty how an agent's actions can be checked without trusting the operator.
Checking that a policy gate held for each automated build step in a CI/CD pipeline, using the reviewed-code workflow.
Evaluating whether tamper-evident logging of agent actions is worth adopting before adding runtime hooks.

Frequently asked questions

Is the signed-audit-trails-recipe skill free to use?

The skill is published under the MIT licence, as listed on this page. Its setup also uses npx to run protect-mcp and @veritasacta/verify, which are fetched from the network when you run them.

What do I need before installing this skill?

You need Node.js and npm, Python 3, Claude Code with the protect-mcp plugin installed, and Git for the .gitignore setup. GitHub Actions is only needed if you use the CI workflow.

Does the skill run scripts and use the network?

Yes on both counts. The hooks run scripts before and after each tool call, and the setup uses npx to fetch and run protect-mcp and the verifier. Review the scripts and keep the signing key out of version control.

Why does verification fail after I edit a receipt?

The Ed25519 signature covers the canonical bytes of the receipt payload. Changing any signed field, such as decision from allow to deny, makes the signature stop matching, so the verifier exits with code 1 and reports the failing line.

Can this skill detect a deleted receipt?

Not by itself. The source states that receipts carry no link to the previous receipt, so a deleted receipt goes undetected.

Should I use this skill or just the protect-mcp plugin?

The skill is a teaching and demonstration guide for the pattern. The runtime hooks come from the separate protect-mcp plugin, which you need installed for the receipts to be produced. If you only want a summary of agent activity, this setup is more than you need.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill suits developers evaluating tamper-evident logging of agent actions, regulated teams that need evidence of what an agent did, and CI owners who want proof a policy gate ran. It is overkill for casual users who only want an activity summary, and it should not be used with the signing key in a repository or with the CI workflow on pull requests.

Download the skill