Guide · Agent skill
How to use the gentle-ai-collab-perfect agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
gentle-ai-collab-perfect is an agent skill, a folder with a SKILL.md instruction file that an AI agent loads when a task matches its description. It applies only when you contribute to the Gentleman-Programming/gentle-ai repository as an outside collaborator. This guide explains what the skill changes in the agent's behaviour, how to install it, how to trigger it with plain requests, and what it needs and touches so you can use it safely.
gentle-ai Contributor WorkflowGentleman-Programming/gentle-ai · MIT Download the skill Quick start
- 1Install the skill folder. Download the ZIP, unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings, Capabilities, Skills in the Claude apps.
- 2Confirm your tools. Make sure git and the GitHub CLI (gh) are installed and authenticated to the repository you will contribute to.
- 3Open the gentle-ai repository. Work with Gentleman-Programming/gentle-ai as the active repo so the skill's trigger condition matches.
- 4Make an approved issue first. Open or find an issue and make sure it has status:approved before any pull request work begins.
- 5Ask for a drafted PR body. Describe your change and ask the agent to draft the PR body, then check that every checkbox matches what gh reports.
- 6Audit before review. Ask the agent to check the title, labels, size budget and branch name against the project rules before you request review.
What the skill makes the agent do
When the active repository is Gentleman-Programming/gentle-ai and you are an external contributor, the skill tells the agent to check the repository's own contribution files before acting. Those files include CONTRIBUTING.md, the pull request template, the issue templates and the workflow files. The skill does not rely on the agent's memory of the project's rules.
The skill enforces an issue-first workflow. No pull request should open until its issue already has the status:approved label. It also keeps pull request descriptions accurate to what GitHub shows, splits large changes into chained or stacked pull requests, and states which actions belong to contributors and which belong to maintainers.
- Opening or commenting on issues
- Drafting, editing or auditing pull request bodies
- Choosing between Stacked and Feature Branch Chain strategies for chained PRs
- Checking PR claims against the GitHub API
- Deciding whether an action is contributor-scope or maintainer-scope
Install the skill in Claude
Download the skill ZIP from the page where you found this guide and unzip it. For a personal setup, place the skill folder inside ~/.claude/skills/. For a single project, place it inside that project's .claude/skills/ folder.
If you use the Claude apps instead of Claude Code, upload the ZIP under Settings, then Capabilities, then Skills. Either way, the folder should contain SKILL.md, which is the only file listed for this skill.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside the project
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Check the requirements before you start
The skill expects four things: git, the GitHub CLI (gh) authenticated to the repository you are targeting, read access to the gentle-ai repository files (CONTRIBUTING.md, PR templates and workflows), and network access, because the agent uses GitHub to check issues, labels and pull requests.
The skill does not assume you have a fork. The source says it works whether you push to the upstream repository, a personal fork or a contributor organisation, as long as you have write access to where you push.
- git installed
- GitHub CLI (gh) installed and authenticated to the target repository
- Access to the Gentleman-Programming/gentle-ai repository files
- Network access is required
Trigger the skill with natural requests
You do not need a special command. Describe the contribution task in plain language while the gentle-ai repository is the active repo. The skill's description covers opening an issue, drafting or editing a PR body, splitting a change into chained PRs, and auditing a PR before review.
Requests that will load the skill include the following. Mention the repository and the stage of the contribution so the agent can match the task to the skill.
- Open an issue for this bug in gentle-ai, following the project's workflow.
- Draft the PR body for my branch and check it against the PR template.
- Split this change into chained PRs under the 400-line budget.
- Audit my open PR before I request review. Check the labels and title against the project rules.
- Which of these actions can I take as a contributor, and which need a maintainer?
Know the rules the skill enforces
The skill lists hard rules that the agent must follow. Several are checked automatically by the repository's pr-check workflow. Understanding them prevents most failed checks.
The agent must not add or remove protected labels such as status:approved or size:exception on its own. These need explicit human instruction and the right repository permission. The skill also forbids Co-Authored-By trailers on commits, forbids force-pushing to main, and asks the human whether a pull request should close its issue on merge.
- Each PR needs an issue with status:approved before it opens.
- Each PR is limited to 400 lines of additions plus deletions, unless size:exception is justified and chosen by a human.
- Commits must not include Co-Authored-By trailers.
- Pull request titles must have exactly one scope, for example type(scope): description.
- Checkboxes in the PR body must reflect the real label state shown by the API.
^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\/[a-z0-9._-]+$Understand contributor and maintainer boundaries
Contributors can open and comment on issues, open pull requests, edit their own PR body and push to their own branches. Maintainers alone approve action_required fork-PR workflows, review pull requests, merge them and push slice branches to upstream.
Label changes are the grey area. Ordinary type labels may be changed only under the canonical issue-creation workflow, with a current direct instruction and verified permission. If that instruction or permission is missing, the agent should wait without changing anything.
What people use it for
- Drafting an honest pull request body that matches what GitHub shows for labels and checks.
- Splitting a large change into smaller chained pull requests to stay within the 400-line budget.
- Checking a pull request's title and branch name against the project's regular expressions before review.
- Helping a maintainer confirm that a contributor's PR followed the issue-first workflow.
- Working out which steps need a maintainer, such as merging or approving fork workflows.
Frequently asked questions
Is gentle-ai-collab-perfect free to use?
The listing states an MIT licence. Note that the SKILL.md file's own metadata says Apache-2.0, so check the licence text in the download before you rely on either one. The skill itself is not a paid product in the source material.
What do I need to install gentle-ai-collab-perfect?
You need the skill's ZIP download and a Claude setup that supports skills. Unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings, Capabilities, Skills. The skill also needs git and an authenticated GitHub CLI (gh).
Do I need to be a gentle-ai maintainer to use this skill?
No. The skill is written for external contributors. It explicitly states which actions need maintainer permission and tells the agent to wait instead of performing them.
Will the agent merge my pull request or change labels automatically?
No. The skill forbids automatic label mutation and merging. Protected labels such as status:approved and size:exception need explicit human instruction and repository permission.
Can I use this skill if I don't have a fork of gentle-ai?
Yes. The source says the skill does not assume a fork. You can push to the upstream repository, a personal fork or a contributor organisation, as long as you have write access.
Why won't the agent open a pull request before my issue is approved?
The issue-first rule is mandatory. The pr-check workflow checks that the linked issue has status:approved, so the skill stops pull request work until that label is present.
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 are an outside contributor preparing a pull request for gentle-ai and want an agent to follow the project's issue-first and PR-body rules. Do not use it to install or run gentle-ai itself, or on other repositories, and do not expect it to merge or relabel anything without your explicit instruction.
Download the skill