How to use the Bug Receipt agent skill (bug-receipt)

What is an agent skill, and what does Bug Receipt make the agent do?

An agent skill is a folder of instructions and supporting files that an AI agent loads when a task matches the skill. Bug Receipt is one such skill. Its main job is to control how an agent reports the end of a bug or incident fix.

After the agent diagnoses, repairs, or recovers from a software defect, the skill requires a complete receipt as the whole user-facing result. Each receipt uses one of three statuses: VERIFIED, PARTIAL, or BLOCKED. The skill also tells the agent to keep sensitive data such as tokens and personal details out of the evidence, and not to call a fix proven unless the actual user-visible behavior was checked.

• VERIFIED: the baseline was observed, the cause is concrete, the change is responsible, all declared checks passed, and no material gap remains.
• PARTIAL: useful evidence exists, but a required proof layer is missing or inconclusive.
• BLOCKED: a specific external condition prevents reproduction, repair, or proof.

How do you install the Bug Receipt skill?

Download the bug-receipt ZIP from this page. You can install it in one of two ways.

Option 1 is a personal install for all your projects: unzip the download into ~/.claude/skills/. Option 2 is a project install: unzip it into the .claude/skills/ folder of a specific project.

Option 3 is to upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

• Personal folder: ~/.claude/skills/
• Project folder: .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

How do you trigger Bug Receipt with a natural request?

You do not need a special command. Ask the agent to fix or recover from a bug and to close it out, and the skill applies when the work is a bug or incident closeout. The skill is meant for the end of a diagnosis, repair, or recovery, so make the closeout part of your request.

The skill says to return the receipt even when you ask for a short answer. Asking for brevity shortens the field values, but it does not remove any rows.

• Fix the checkout bug where the discount is applied twice, then close it out with a receipt.
• The login timeout is fixed. Give me the bug receipt with proof, and list any gaps.
• Recover from last night's sync incident and report the closeout as a receipt, status included.
• Diagnose why the export API returns 500 and give me a closeout receipt. Keep it brief.

What does a Bug Receipt look like?

Every closeout uses the same seven rows, in the same order. Rows that do not apply are written as not run, unproven, or none, so no row is silently dropped. The Source row says whether the evidence was executed now, supplied by someone else, or mixed.

• Problem: the observed defect and the intended behavior.
• Baseline: the failing interaction or command and its decisive result, or not run.
• Root cause: the proven mechanism, or an unproven hypothesis.
• Change: the responsible change, or none.
• Proof: each supplied or executed check and its result.
• Gaps: none, or the exact missing proof and the single next experiment.
• Source: executed now, supplied, or mixed.

How do you get a machine-readable JSON receipt and validate it?

Use JSON only when a user, a CI job, or another tool needs a structured artifact. Otherwise the normal human-readable receipt is enough. When JSON is requested, the skill starts from its template file, writes the receipt to a path owned by the task, and checks it with the included validator.

The validator needs Node.js. The skill's contract file lists the required JSON fields and the rules for each status. The skill also says not to commit the generated receipt unless you ask for it.

• Template: assets/receipt.template.json
• Contract and fields: references/receipt-contract.md
• Schema: references/receipt.schema.json
• Validator: scripts/validate-receipt.mjs

What should you know about safety, scripts and network access?

The skill runs a script, scripts/validate-receipt.mjs, but only when a JSON receipt is requested. It does not use the network. Because it runs a script, you need Node.js installed for that step.

The skill also asks the agent to minimise private data in evidence. Credentials, tokens, cookies, personal data, private URLs, and sensitive payloads should be redacted. Only the identifiers and excerpts needed to reproduce or correlate the failure should be kept. Review receipts before you share them, because the agent's wording is not checked for secrets beyond these instructions.

• Scripts: yes, the validator runs only for JSON receipts.
• Network: the source states it does not use the network.
• Node.js: required only for the validator step.

What tips help you get the most from Bug Receipt?

Bug Receipt works best when the agent has a real reproduction path. The skill says to reproduce the failure with the narrowest safe check when possible, and it caps the status at PARTIAL or BLOCKED when reproduction is not available. Give the agent access to the failing case, or say clearly what you already checked yourself.

Label supplied evidence as supplied. If you paste logs from someone else, the receipt should say so, and it should not present them as something the agent ran.

• Name the intended behavior in your request so the Problem row is precise.
• Ask for the real user-visible check, such as a UI interaction or a request and response, when the claim depends on it.
• Read the Gaps row first when a receipt is PARTIAL or BLOCKED, since it names the next experiment.
• Do not use this skill for quick questions or non-bug tasks.