Skip to content
Get packs

Guide · Agent skill

How to use the gentle-ai-branch-pr agent skill

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

gentle-ai-branch-pr is an agent skill for contributors and maintainers of the Gentleman-Programming/gentle-ai repository. Once it is installed, an AI agent that prepares branches or pull requests for that repository follows the project's contribution rules instead of improvising them. This guide explains what the skill does, how to install it, how to ask for it, and what it needs before you rely on it.

Gentle AI Branch and PR WorkflowGentleman-Programming/gentle-ai · MIT

Quick start

  1. 1Download and unzip the skill. Download the gentle-ai-branch-pr ZIP from this page and unzip it. Keep the SKILL.md file inside the skill folder.
  2. 2Place the skill folder. Move the folder to ~/.claude/skills/ for personal use or to .claude/skills/ in your project. Alternatively, upload it under Settings, Capabilities, Skills in the Claude apps.
  3. 3Prepare your gentle-ai checkout. Make sure Git and access to the repository are set up, and that CONTRIBUTING.md, PULL_REQUEST_TEMPLATE.md and the issue-creation SKILL.md are present.
  4. 4Make an approved issue. Confirm the base-repository issue you are working on has the status:approved label before you open a PR.
  5. 5Ask for the skill by describing the task. Tell the agent you want to create a branch or prepare a PR for gentle-ai and name the issue number.
  6. 6Answer the closing-intent question. When asked, state whether the PR should Close, Fix or Resolve the issue on merge, or only Refs it.
  7. 7Review before any action. Approve each commit, push, PR creation or label change yourself, since the skill is designed to stop and wait for you.

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

An agent skill is a folder containing a SKILL.md file with instructions that an AI agent loads when a request matches the skill's description. This skill's description says it applies when you are preparing branches or PRs for Gentleman-Programming/gentle-ai and that it applies the repository's issue-first contribution policy.

When the skill is active, the agent checks that a linked, approved issue exists, names branches with the required prefixes, keeps pull requests under about 400 changed lines, fills in the project's PR template, and avoids AI attribution trailers in commits. The skill is designed to stop and ask a human before it commits, pushes, creates PRs, or changes protected labels.

  • Requires a Status:approved base-repository issue referenced as Closes, Fixes, Resolves or Refs
  • Branch names must match the required type prefixes such as feat/, fix/ and docs/
  • Keeps changes within 400 changed lines (additions plus deletions) or documents a size:exception rationale
  • No Co-Authored-By trailers in commits
  • Never force-pushes to main or master

How do you install the gentle-ai-branch-pr skill?

Download the skill ZIP from this page and unzip it. For a personal setup, place the unzipped skill folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder instead.

If you use the Claude apps rather than a local folder, you can upload the skill under Settings, then Capabilities, then Skills, instead of copying files by hand.

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

What do you need before the skill works?

The skill assumes you already have Git and access to the gentle-ai repository. It uses the GitHub CLI or an equivalent authenticated session to read issue, label and branch protection metadata. The skill requires your explicit authorization before any remote read, so it will not reach GitHub on its own.

The skill references three repository files that are not included in the ZIP: CONTRIBUTING.md, PULL_REQUEST_TEMPLATE.md, and internal/assets/skills/issue-creation/SKILL.md. The agent needs those files to be present in your gentle-ai checkout to apply the full policy.

  • Git and access to Gentleman-Programming/gentle-ai
  • GitHub CLI or equivalent authenticated session for reading metadata
  • CONTRIBUTING.md, PULL_REQUEST_TEMPLATE.md and internal/assets/skills/issue-creation/SKILL.md in the repository
  • The skill runs no scripts but does use the network

How do you trigger the skill with a natural request?

You do not need a special command. Describe the task in plain words that mention Gentle AI and a branch, fix, feature or pull request. The skill is meant to load for contributions whose PR base is Gentleman-Programming/gentle-ai, including from forks.

For other repositories the skill does not apply, and the agent should follow that project's own contribution policy.

  • Create a branch for a Gentle AI fix that resolves issue 123
  • Prepare my Gentle AI changes for review and check the PR template
  • Open a pull request on gentleman-programming gentle-ai for this docs change
  • Help me name a branch for a feature in gentle-ai

What branch names does the skill require?

Branch names must start with one of the approved type prefixes, followed by a slash and a short description. Use only lowercase letters, numbers, dots, hyphens and underscores in the description. Spaces and uppercase letters are not allowed.

  • feat/user-login
  • fix/duplicate-observation-insert
  • docs/api-reference-update
  • chore/bump-bubbletea-v0.26
^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\/[a-z0-9._-]+$

What happens before a PR is ready to merge?

The skill asks you whether the PR should close the issue on merge. Closes, Fixes or Resolves closes the issue when the PR merges. Refs links the issue without closing it. The agent keeps the intent you choose and does not swap one for the other.

The agent also confirms that required CI checks pass, using the target branch rules and current run status. CodeRabbit is optional unless the target policy makes it required, and a pending optional run is not a blocker. Unknown requiredness is treated as not merge-ready. Labels such as status:approved and size:exception can only be changed by an actor with MAINTAIN or ADMIN permission and a direct human instruction for that exact action.

  • Ask whether the PR closes the issue or only references it
  • Keep the 400-line budget or document a size:exception rationale
  • Declare exactly one type:* label
  • Fill checkboxes only after you have observed the result

What people use it for

  • Starting a fix branch for a gentle-ai bug with a correctly prefixed name and a linked issue
  • Drafting a PR body from the project template with the test plan and checklist filled in only from observed results
  • Helping a maintainer keep branch names, issue links and PR types consistent across agent-made contributions
  • Checking whether a planned change stays under the 400-line review budget before opening a PR

Frequently asked questions

Is the gentle-ai-branch-pr skill free to use?

The listing states an MIT licence. The SKILL.md header inside the ZIP names Apache-2.0, so check the licence file in the source repository before you redistribute or rely on the terms.

What do I need to install the gentle-ai-branch-pr skill?

Download the ZIP, unzip it, and place the folder in ~/.claude/skills/ or a project's .claude/skills/ directory. You can also upload it in the Claude apps under Settings, Capabilities, Skills.

Does this skill work for repositories other than gentle-ai?

No. The rules, labels and template paths are specific to Gentleman-Programming/gentle-ai, so other projects should follow their own contribution policy.

Does the skill run scripts or access the network?

It runs no scripts but does use the network. It needs an authenticated GitHub CLI or equivalent session to read issue, label and branch protection metadata, and it requires your explicit authorization before any remote read.

Will the agent create my PR or push commits automatically?

No. The skill is designed to stop and ask a human before committing, pushing, creating PRs, merging, or changing protected labels, so it is not suited to fully automated publishing.

Why does the agent refuse to continue without an approved issue?

Every PR must visibly link an approved base-repository issue with status:approved, and CI rejects malformed or mixed closing and non-closing references. Ask a maintainer to approve the issue before you open the PR.

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

Use this skill if you contribute to Gentleman-Programming/gentle-ai and want an agent to follow its issue-first, branch-naming and PR-size rules with a human approving each step. Pick something else if you work on other projects, or if you want an agent to publish changes without sign-off.

Download the skill