How to use the Finish a Development Branch agent skill

What is an agent skill?

An agent skill is a folder containing a SKILL.md file. The file holds instructions that an AI agent reads when a request matches the skill's description. Instead of improvising the end of a task each time, the agent follows the same written routine.

This skill is taken from the obra/superpowers project, under the MIT licence. Its description reads: use when implementation is complete, all tests pass, and you need to decide how to integrate the work.

What the skill makes the agent do

The skill runs a fixed sequence: verify tests, detect the git environment, determine the base branch, present options, execute the chosen option, and clean up the workspace.

First the agent runs the project's full test suite. If any tests fail, it reports the failures and stops, so the menu only appears after a passing run. It then checks whether the work is in a normal repository, a git worktree on a named branch, or a detached HEAD, because each state offers a different menu.

The agent also confirms the base branch the work came from. If it does not already know, it asks before merging, since merging into the wrong base is hard to undo.

• Normal repo or named-branch worktree: merge back to the base branch locally, push and create a pull request, or keep the branch as-is.
• Detached HEAD: push as a new branch and create a pull request, or keep as-is. Local merge is not offered.
• Discarding work happens only if you explicitly ask for it and type the word discard to confirm.

How to install the skill

Download the ZIP file from this page and unzip it. You have two places to put the resulting folder, depending on how you want to use it.

For all your projects, unzip it into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder. You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.

• Personal install: ~/.claude/skills/finishing-a-development-branch/
• Project install: .claude/skills/finishing-a-development-branch/ inside your repository
• Claude apps: Settings → Capabilities → Skills, then upload the skill

What you need before using it

The routine assumes a git repository and an automated test suite. You also need a test command the agent can run for your project. The skill's own examples use npm test, cargo test, pytest, or go test ./..., so use whichever matches your stack.

If you choose the pull request option, the agent needs either the forge's command-line tool or web access so it can create the request. Without one, the skill says the forge usually prints a creation URL when you push, and the agent can report that URL.

• git
• A working test command for the project
• Forge CLI or web access to create a pull request, only if you choose that option

How to trigger the skill with natural requests

The skill activates when your request matches its description, so you do not need to name it. Describe the situation in plain words once the code is done and the tests pass.

Examples of requests that fit:

• "The feature is done and the tests pass. Help me finish this branch."
• "Wrap up this work and decide how to get it into main."
• "Open a pull request for this branch against develop."
• "I'm done with this worktree, what are my options?"

What to expect during a run

The agent announces that it is using the skill, runs the tests, and then shows a numbered menu. Choose an option by replying with its number or describing it. The agent waits for your answer before it merges, pushes, or deletes anything.

If the merged result fails tests after a local merge, the agent stops and leaves the branch and worktree in place. If a push is rejected, the skill tells the agent to investigate rather than force-push unless you explicitly ask.

• Option 1 merges locally, re-runs tests on the merged result, then deletes the feature branch with git branch -d.
• Option 2 pushes the branch with git push -u origin and creates a pull request against the base branch. The worktree is kept so you can fix review feedback there.
• Option 3 keeps the branch and reports where the worktree is.

Safety notes: scripts and network access

The skill runs scripts and uses the network. Its instructions include git commands that inspect and change your repository, the project's test command, and, for pull requests, git push and the forge's tooling or creation URL.

Worktree removal only applies to worktrees under .worktrees/ or worktrees/ that the skill created. Other worktrees are left to the host environment. If git refuses to remove a worktree because it has uncommitted files, the skill asks you before doing anything. It does not use --force on its own.

• Deleting a branch with force requires the typed word discard.
• The agent never force-pushes unless you explicitly request it.
• Read the menu before choosing, especially the base branch name.

Tips for getting good results

Make sure the tests you run cover the code you are integrating. The skill re-runs the suite on the tree it is about to integrate, and a passing run only proves the tree it ran on.

Confirm the base branch early in the conversation. Mentioning it when you start the task saves a question at the end.

• Name the base branch in your first message if it is not main.
• Keep worktrees you are still reviewing; the skill intentionally preserves them after a pull request.
• If you do not want the agent to delete anything, simply choose option 1 or 2 and do not type discard.