How to use the Finish a Development Branch agent skill

What is an agent skill, and what does this one do?

An agent skill is a folder with a SKILL.md file that tells an AI coding agent how to handle a specific kind of task. When the task comes up, the agent reads the instructions and follows them.

This skill covers the last step of a piece of work. It runs the project's full test suite, checks whether you are in a normal repository, a named-branch worktree, or a detached HEAD, and confirms the base branch. Then it shows you a short menu: merge locally, push and open a pull request, or leave the branch alone. It does not discard work unless you explicitly ask for that and type the word 'discard'.

• Runs the test suite first and stops if tests fail; the menu only appears after a green run.
• Detects the git environment before choosing which menu to show.
• Asks you to confirm the base branch before any merge.
• Removes only worktrees it created under .worktrees/ or worktrees/.

Install the finishing-a-development-branch skill

Download the ZIP from this page and unzip it. The skill is a single file, SKILL.md, inside the finishing-a-development-branch folder.

For a personal install, place the folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.

You can also upload the ZIP 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 ZIP

How to trigger the skill with natural requests

You do not need a special command. Ask for the finish step in plain language when the implementation is done and the tests pass. Good triggers describe the state of the work and what you want next, such as deciding how to integrate it.

The skill's description says it applies when implementation is complete, all tests pass, and you need to decide how to integrate the work. Phrasing close to that tends to match best.

• "The feature is done and tests pass. Help me decide how to integrate this branch."
• "Finish this branch. Show me my options."
• "Tests are green on this worktree. What should we do with the work?"

What the agent does during a finish

The skill follows six steps in order. It announces that it is using the skill, runs the test suite, detects the environment, determines the base branch, shows the menu, carries out your choice, and cleans up the workspace when that choice requires it.

If you are in a plain repository, you see the standard three options. In a named-branch worktree you also see the three options, but cleanup depends on who created the worktree. In a detached HEAD, the menu shrinks to two options, because merging is not offered and the workspace is treated as externally managed.

• Plain repository or named-branch worktree: merge locally, push and create a PR, or keep the branch.
• Detached HEAD: push as a new branch and create a PR, or leave it as it is.
• Discard is only available when you explicitly request it and confirm with 'discard'.

Examples of each menu option

Option 1 merges into the base branch locally. The agent switches to the main repository root, checks out the base branch, pulls, and merges the feature branch. It runs tests on the merged result. If those tests fail, it stops and leaves the worktree and branch in place, since nothing has been pushed yet.

Option 2 pushes the branch with git push -u origin and creates a pull or merge request against the base branch. It uses the forge's CLI if one is available, otherwise the URL that git prints when you push. It keeps the worktree so you can respond to review feedback there.

Option 3 keeps the branch unchanged and reports the branch name and worktree path so you can handle it later.

What you need before using it

The skill assumes git is installed and that your project is a git repository with branches or worktrees. It needs a test command that the agent can run, such as npm test, cargo test, pytest, or go test. Creating pull requests needs a forge CLI or web access; without a CLI, the agent falls back to the URL git prints.

Because the skill runs scripts and uses the network, check what it will run before you rely on it. Its merge and push steps depend on your remote and your forge.

• git
• A project test command, for example npm test, cargo test, pytest, or go test ./...
• Optional: a forge CLI or web access for creating pull requests
• Runs scripts: yes. Uses network: yes.

Safety notes: scripts, network and deletion

The skill is built to stop and ask before anything irreversible. A discard requires the exact word 'discard'. A failed worktree removal that reports modified or untracked files is not forced; the agent lists those files and asks you what to do. A rejected push is treated as a reason to investigate, and force-pushing happens only if you explicitly ask.

Worktree removal is limited to paths under .worktrees/ or worktrees/. Other worktrees are treated as belonging to the host environment and are left alone.

• Read SKILL.md before installing so you know which commands the agent may run.
• Review the merge and push steps when they appear; they run in your repository and remote.
• Keep your worktree if you plan to revise a PR; the skill keeps it on purpose.

Tips for a smooth finish

Name the base branch in your request or in the plan. The skill asks for confirmation anyway, and a clear answer avoids a wrong merge target. Run the finish step only after the work is committed, because uncommitted files in a worktree block its removal.

Use the skill as a consistent checklist even when you choose to keep the branch. It is most useful for people who tend to skip the base-branch check.

• Commit planning notes and drafts before finishing a worktree.
• Make sure your test command runs the full suite in the directory you are finishing.
• Expect a short pause: the agent waits for your choice on purpose.