josedowski/axioma/gentle-ai-collab-perfect
Claude Code and agent skill by josedowski/axioma
- community
Checking that the SKILL.md file is still in the repository.
Trigger: contributing to Gentleman-Programming/gentle-ai as an external collaborator. Strict issue-first workflow, honest PR bodies, contributor-vs-maintainer scope, chained-PR strategy, verification protocol, docstring coverage. Load whenever the active repo is Gentleman-Programming/gentle-ai and any part of the contribution flow is in scope: opening an issue, drafting or editing a PR body, splitting a change into chained/stacked PRs, or auditing a PR before requesting review.
Install
npx vskill@latest install josedowski/axioma/gentle-ai-collab-perfectSKILL.md
The same SKILL.md was published earlier as josedowski/axioma/gentle-ai-collab-perfect.
When to use
Use this skill when the active repo is Gentleman-Programming/gentle-ai and the contributor is an external collaborator (not the maintainer). Scope of the skill:
- Opening or commenting on issues
- Drafting, editing, or auditing PR bodies
- Choosing a chained-PR strategy (Stacked vs Feature Branch Chain)
- Cross-checking PR claims against the GitHub API
- Deciding whether an action is contributor-scope or maintainer-scope
Do NOT load this skill for:
- Using gentle-ai as an installer (Gentleman-Programming/gentle-ai is the installer itself; not this skill)
- Reading docs, debugging tests, or reviewing the codebase in general
- Tasks on a different repository
The skill assumes the contributor is working from wherever they push — a fork, a personal working repo, or anywhere they have write access. It deliberately does not assume a fork. Use it whether you push to ardelperal/gentle-ai, to a personal fork, or to a contributor org.
Source of truth — read the repo, don't infer
Before recommending any contribution action, read the relevant local file. The repo documents every constraint; pulling rules verbatim beats guessing.
| File | What it tells you | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
CONTRIBUTING.md | Issue-first workflow, label taxonomy, branch naming regex `^(feat\ | fix\ | chore\ | docs\ | style\ | refactor\ | perf\ | test\ | build\ | ci\ | revert)\/[a-z0-9._-]+$`, Conventional Commits format, 400-line review budget | |
.github/PULL_REQUEST_TEMPLATE.md | Required PR body sections (Linked Issue, PR Type, Summary, Changes, Test Plan, Automated Checks, Contributor Checklist, Notes for Reviewers) | |||||||||||
.github/ISSUE_TEMPLATE/bug_report.yml | Bug report structure + status:needs-review auto-label + status:approved blocking gate | |||||||||||
.github/ISSUE_TEMPLATE/feature_request.yml | Feature request structure + same gates | |||||||||||
.github/workflows/pr-check.yml | Automated gates: Check Issue Reference, Check Issue Has status:approved, Check PR Has type:* Label, Check PR Cognitive Load | |||||||||||
.github/ISSUE_TEMPLATE/config.yml | Issue-template routing rules; do not bypass | |||||||||||
skills/branch-pr/SKILL.md | Branch + PR creation mechanics | |||||||||||
skills/chained-pr/SKILL.md | Chained vs Stacked PR strategy mechanics | |||||||||||
skills/issue-creation/SKILL.md | Issue creation mechanics | |||||||||||
skills/cognitive-doc-design/SKILL.md | Doc-writing principles | |||||||||||
skills/comment-writer/SKILL.md | Tone for comment replies |
These files evolve. Re-read them at the start of every contribution.
Hard rules (do not negotiate)
- Issue-first is mandatory. No PR opens without an issue that already has
status:approvedfrom a maintainer. Enforced bypr-check.ymland CONTRIBUTING.md. - Use `Closes/Fixes/Resolves #N` in the PR body.
Refs #Ndoes NOT satisfyCheck Issue Reference. Verified empirically on this repo. - Exactly one `type:*` label per PR. Two
type:*labels fail the check. Notype:*label fails the check. - 400-line budget per PR (
additions + deletions). Above that, requestsize:exceptionfrom a maintainer with rationale documented in the PR body. - No `Co-Authored-By` trailers on commits. AI attribution is not acceptable in this repo.
- No force-push to `main`. It is protected.
- PR body checkboxes must reflect API state. If
gh pr view --json labelsshowslabels: [], do not check the "type:* added" box — write a## Pending maintainer actionssection instead. - PR titles follow `^(type)(\(scope\))?!?: <description>` with exactly one scope (no comma). See
skills/branch-pr/SKILL.mdfor the regex. - Pre-existing test failures are named honestly. This repo has pre-existing failures in
pi_codegraph,tui/sync, and similar packages. Acknowledging them with the verification method (e.g.git stashbaseline) is mandatory. Claiming "all tests pass" without that context is dishonest.
Contributor vs maintainer scope
This split catches external contributors most often. Verify with gh before recommending any action that requires elevated permissions.
| Action | Contributor | Maintainer | |
|---|---|---|---|
| Open / comment on issues | ✅ | — | |
| Open a PR from a working branch (wherever they push from) | ✅ | — | |
| Edit own PR body | ✅ | — | |
| Push commits to own branches | ✅ | — | |
Add status:approved to an issue | ❌ | ✅ | |
Apply type:* label to a PR | ❌ | ✅ | |
Apply size:exception label | ❌ | ✅ | |
Approve action_required fork-PR workflows (fork approval gate) | ❌ | ✅ | |
| Review a PR (approve / request changes) | ❌ | ✅ | |
| Merge a PR | ❌ | ✅ | |
| Push slice/* branches to upstream so cross-fork base refs work | ❌ | ✅ |
If the contributor's PR is "stuck" on something, the next step is almost always a maintainer action — not the contributor trying it. Trying it surfaces GraphQL 403 (AddLabelsToLabelable, requestReviewsByLogin, deployment-protection API) and makes the contributor look unaware of the workflow.
Verified empirically in this repo (July 2026): gh pr edit --add-label type:feature returns 403 ardelperal does not have the correct permissions to execute AddLabelsToLabelable. Treat that error as policy, not as a bug.
Issue workflow
End-to-end steps to open an issue that becomes a viable PR.
- Search first. Confirm the issue does not already exist (
gh search issuesor the issue list). Avoid duplicates —CONTRIBUTING.mdsays PRs on duplicates will be rejected. - Pick the template.
.github/ISSUE_TEMPLATE/bug_report.ymlfor bugs,feature_request.ymlfor changes. Each auto-appliesstatus:needs-reviewvia the template'slabels:field. - Fill every required field. Don't skip the Pre-flight Checklist. The two self-attestations (not a duplicate; understand
status:approvedis required) are present for a reason. - After submission, watch for `status:approved`. Comment clarifications promptly. This is the gate before any PR opens.
- If the maintainer asks for technical sub-slices (e.g.
slice/journal-cas,slice/four-layer-engine,slice/tui-cli), keep them as technical slices of one approved issue. The umbrella issue keepsstatus:approved; the sub-issues should also get approved if you wantCheck Issue Has status:approvedto pass per slice.
PR workflow
End-to-end steps once the issue (or chain of sub-issues) is approved.
- Branch.
`` git checkout main && git pull git checkout -b <type>/<short-description> ` Branch name matches the regex in CONTRIBUTING.md. <short-description>` is kebab-case, max a few words.
- Implement. Work-unit commits: each commit is one deliverable unit with its code + tests + docs. Keep rollback reasonable — reverting one commit should not remove unrelated work.
- Local validation.
go build ./...cleango vet ./...cleango test ./internal/...with pre-existing failures acknowledged viagit stashbaseline. The repo has known pre-existing failures ininternal/components/communitytool/pi_codegraph,internal/tui/sync, and similar — confirm they exist withgit stashANDgit stash pop, then name them in the PR body's Test Plan.
- Open the PR with `gh pr create`. Body matches
.github/PULL_REQUEST_TEMPLATE.md:
## 🔗 Linked Issue→Closes #N(orFixes/Resolves). NeverRefs.## 🏷️ PR Type→ exactly one[x] type:*matching the actual type## 📝 Summary→ one paragraph: what + why## 📂 Changes→ file table with line counts fromgh pr view --json additions,deletions,changedFiles## 🧪 Test Plan→ everygo testcommand actually run + result, including pre-existing failures with verification method## ✅ Contributor Checklist→[x]only where verifiable;[ ] pending maintainerfor the rest## 💬 Notes for Reviewers→ chain position, merge order, blockers
- For chained PRs, add a brief dependency diagram showing your sibling PRs and the merge order. Mark the current PR with
📍.
- After opening: check
gh pr checks --jsonand address anypending contributor follow-upitems you documented in the body.
PR body honesty — the single most often-abused rule
Every [x] in the Contributor Checklist is a public claim that pr-check.yml and the maintainer will verify. Three rules:
- Mark `[x]` only when the assertion is true against the API.
``bash gh pr view <N> --json labels,closingIssuesReferences,additions,deletions,changedFiles ` If labels: [], do not check the "type:* added" box. Instead: ``markdown ## Pending maintainer actions
The following are maintainer-applied per `pr-check.yml` and CONTRIBUTING.md in this repo — not within contributor scope:
- [ ]
type:featurelabel applied to this PR — pending Alan - [ ]
size:exceptionconsideration — see rationale below - [ ] Fork workflow approval — 4 runs in
action_requiredawaiting Alan
```
- Numbers and file counts must match the API. If you can't trust the API, recount locally:
git diff --stat <base>..<head>.
- Pre-existing failures must be named and methodology stated. "Tests pass" is dishonest if four packages fail in the
git stash-absent baseline. State them:
``markdown > **Known pre-existing failures (not blocking this PR):** internal/components/communitytool/pi_codegraph, internal/tui/sync, internal/tui/sddmode clusters present on main are not introduced by this slice; verified identical via git stash baseline. ``
Honest rewrites often look like adding content, not removing. Adding ## Pending maintainer actions and a quoted callout for pre-existing failures is normal and expected.
Standard honest-rewrite pattern
When the contributor checks a box that doesn't reflect reality:
- Move the unfulfillable contributor-side check into
## Pending maintainer actionswithpending Alansuffix - Update diff numbers to match the API exactly; if a qualifier is needed (e.g. "slice-specific commits only"), state it explicitly
- For test claims, state the exact local commands run and the count of PASS/SKIP observed; don't aggregate to "all pass" if any were skipped on Windows
- Always name pre-existing repo failures that the contributor observed but did not fix, with the verification method (
git stashbaseline) - For process claims (e.g. "blind dual review approved"), reference the artifact (round-1 → round-2 polish commits ARE that evidence)
Chained PR strategy
This repo supports two strategies via gentle-ai-chained-pr:
Stacked to main
Use when each slice can land independently. Branches are independent stacks that each target main. The diff "pollutes" with previous-slice commits because GitHub does not allow cross-fork base refs (slice branches live only in the contributor's working repo).
- Pros: simple, each PR is its own atomic change.
- Cons: large chained diffs; reviewers must mentally isolate slice-specific changes; needs
size:exceptionfor anything past 400 lines of slice-specific additions.
Feature Branch Chain (tracker PR)
Use when the feature integrates as one atomic unit. The maintainer pushes the slice/* branches to the upstream as branch (not PR); child PR #1 targets the tracker branch, child #2 targets the child #1 branch, child #3 targets child #2. The tracker PR stays draft / no-merge until all children are reviewed and merged.
- Pros: clean per-slice diffs; atomic integration; reversible as a unit.
- Cons: requires maintainer cooperation to push slice branches upstream; slower.
Critical limitation: GitHub does NOT support cross-fork base refs. If your slice branches live only in your working repo, the only options are:
- Stacked to main (with polluted diffs) — accept the reality
- Ask the maintainer to push slice branches upstream so you can do Feature Branch Chain
This is the start of the file. Read the full SKILL.md on GitHub.
Security
- Security scanPassed, 100 of 100Pattern checks on the skill's files.
- Model reviewNot runA model review is scheduled for the next rescan.
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskills/gentle-ai-collab-perfect/SKILL.md
Popularity
- 7-day trend score
- 0
Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/josedowski/axioma/gentle-ai-collab-perfect)