Guide · Agent skill
How to use the Surgical Patch agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
Surgical Patch is an agent skill: a set of written instructions that an AI agent loads and follows when it works on a bug fix or a small behavior change. This guide explains what the skill changes about the agent's behavior, how to install it, how to ask for it in plain language, and what to check before relying on it. By the end you will be able to add the skill to your setup and get smaller, more focused patches from your agent.
Surgical PatchJuliusBrussee/caveman · Apache-2.0 Download the skill Quick start
- 1Download the ZIP. Get the surgical-patch skill ZIP from this page and unzip it so you have the skill folder containing SKILL.md.
- 2Choose a location. Move the folder to ~/.claude/skills/ for all projects, or to .claude/skills/ inside one project. Alternatively, upload it under Settings → Capabilities → Skills in the Claude apps.
- 3Make sure checks exist. Confirm the project has a test suite or build command the agent can run, since the skill relies on them.
- 4Ask for a focused fix. Describe the bug in plain words and ask for the smallest responsible change with a regression test.
- 5Review the diff. Read the patch to confirm it changes only the responsible layer and leaves unrelated code alone.
What the surgical-patch skill makes the agent do
The skill tells the agent to handle bug fixes and small behavior changes in a disciplined way. It asks the agent to reproduce the failure first when that is economical, and otherwise to capture the strongest available evidence. It asks the agent to trace the symptom back to the mechanism that causes it, then change only the narrowest layer that owns the incorrect behavior.
The skill also limits side effects. It asks the agent to preserve unrelated behavior and your own edits, to avoid cleanup, renaming and new abstractions outside the fix, and to add only the regression proof relevant to the task. The agent is told to run a focused check plus the nearest affected gate, and to stop once the failure is fixed and the regression proof passes.
- Reproduce the failure first when practical
- Trace the symptom to the responsible mechanism
- Change the narrowest layer that owns the bug
- Leave unrelated behavior and user changes alone
- Avoid unnecessary cleanup, renaming and abstraction
- Add only the tests needed to prove the fix
Install the surgical-patch skill
Download the skill ZIP from the skill's page on this directory and unzip it. The package contains agents/openai.yaml and SKILL.md. Place the unzipped skill folder in one of two locations: ~/.claude/skills/ to make it available across your projects, or a project's .claude/skills/ folder to limit it to that project.
If you use the Claude apps instead of files on disk, you can upload the skill under Settings → Capabilities → Skills.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside your project
- Claude apps: Settings → Capabilities → Skills, then upload
Trigger the skill with natural requests
You do not need a special command. The skill's description says it applies when fixing bugs and small behavior changes where regression proof, preserved surrounding behavior and task-relevant tests matter. Describe your task in ordinary words and mention what you want from the change.
Being explicit about scope helps. Saying that you want a minimal fix, or that the change should not touch other behavior, gives the agent the same signal the skill is designed around.
- Use surgical-patch to fix the off-by-one error in the pagination helper.
- Fix this bug with the smallest change possible and add a regression test.
- Make a small behavior change to the login redirect and don't touch anything else.
- Review the failing test, trace the cause and patch only the responsible code.
Examples of good and poor fits
The skill suits work where the diff should stay small and each change should be backed by a test. It is a poor fit for large feature work or architectural redesigns, because the skill intentionally limits scope and broader changes are expected in those cases.
The skill relies on running the project's existing checks. If your project has no test suite or build commands, or the agent does not know how to run them, the skill's proof steps will have little to work with.
- Good fit: fixing a rounding bug in a billing calculation with a regression test
- Good fit: a one-line change to a validation rule, with the nearest test run
- Poor fit: rebuilding an authentication system or splitting a monolith
- Poor fit: a repository with no tests or build commands
What the skill needs and its safety notes
The skill lists no required dependencies. It does not run scripts and does not use the network, according to the skill's listing. Its contents are two files: agents/openai.yaml and SKILL.md. Because it is only instructions, its effect comes from the agent following them against your code and the checks you already have.
The agent will still execute whatever test and build commands it chooses to run in your project, so review those as you would any agent action. Check the diff the agent produces before committing it.
- Requires: nothing listed
- Runs scripts: no
- Uses network: no
- Licence: Apache-2.0
What people use it for
- Fixing an off-by-one error in a helper function with a regression test that fails before the fix
- Correcting a small validation rule without touching surrounding validation
- Adjusting one behavior, such as a redirect, while keeping the rest of the flow unchanged
- Reviewing AI-generated patches that should be minimal and easy to read
Frequently asked questions
How do I install the surgical-patch skill?
Download the skill ZIP from this page and unzip it. Place the folder in ~/.claude/skills/ for personal use, or in .claude/skills/ inside a project. In the Claude apps you can instead upload it under Settings → Capabilities → Skills.
Does surgical-patch require anything else to run?
The skill lists no required dependencies, runs no scripts and uses no network access. It is made of instructions in SKILL.md and agents/openai.yaml, so it depends on your agent and your project's existing tests and build commands.
Is surgical-patch free to use?
The skill is licensed under Apache-2.0, as listed on this page. Check the licence file in the source repository for the full terms.
Why won't the skill work well for big feature changes?
The skill intentionally limits scope to narrow bug fixes and small behavior changes. Large feature work or architectural redesigns need broader changes, so this skill is the wrong tool for them.
What if my project has no tests?
The skill relies on running existing checks to prove a fix. Without a test suite or build commands, or if the agent does not know how to run them, the proof steps have little to work with, so you may get weaker results.
How is this different from asking an agent to just fix a bug?
Without guidance, an agent may refactor, rename or clean up code around the bug. This skill asks it to trace the cause, change only the responsible layer, leave your edits alone and add only the regression proof the task needs.
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
Surgical Patch is a good choice for developers and maintainers who want small, test-backed bug fixes and minimal diffs from an AI agent. Skip it for large feature work or architectural redesigns, or for projects that have no tests or build commands for the agent to run.
Download the skill