branch-pr

Create Gentle AI pull requests with issue-first checks. Trigger: creating, opening, or preparing PRs for review.

Quality

61%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./internal/assets/skills/branch-pr/SKILL.md

Quality

Content

65%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The content is highly actionable with concrete commands, regexes, and templates, and is well sectioned, but it suffers from label-mapping redundancy across tables, an only-implied failure-recovery loop, and a monolithic single-file structure with inline reference material that could be externalized.

Suggestions

Consolidate the three type-to-label mappings into a single canonical table and have the Branch Naming and PR Body sections reference it, removing redundant prose restatements.

Make the failure-recovery loop explicit in the Workflow, e.g. step 7: "If checks fail, fix the reported issues, commit, and re-push until all checks pass."

Move the lengthy branch-naming and conventional-commit specifications into reference files (e.g. references/branch-naming.md, references/conventional-commits.md) and keep SKILL.md as a concise overview that links to them.

Dimension	Reasoning	Score
Conciseness	The body is dense with specs, regexes, and tables rather than concept filler, but the type-to-label mapping recurs across three tables (Branch Naming, PR Body Format, Conventional Commits) and the commit type list is restated in prose after the regex, so it could be tightened.	2 / 3
Actionability	It provides executable regexes for branch and commit naming, a copy-paste-ready Commands section (git checkout, shellcheck, gh pr create/edit with real flags), and concrete PR body templates with exact markdown, satisfying fully executable guidance.	3 / 3
Workflow Clarity	A clear 7-step sequence with validation checkpoints (shellcheck before push, wait for CI) is present, but the error-recovery feedback loop (check fails -> fix -> re-push) is only implied by "Wait for automated checks to pass" rather than explicitly spelled out.	2 / 3
Progressive Disclosure	Sections are well-organized and there are no broken or deeply nested references, but the ~190-line body is monolithic with large inline reference tables (branch/commit specs, label mappings) that could be split into one-level-deep reference files, missing the score-3 "content appropriately split" bar.	2 / 3
	Total	9 / 12 Passed

Description

57%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description correctly includes explicit trigger guidance and a distinctive niche via the "Gentle AI" qualifier, but its capability statement is abstract and its trigger term coverage is narrow. Tightening the action list and broadening natural trigger phrases would raise specificity and trigger_term_quality.

Suggestions

Replace the abstract "issue-first checks" with concrete enumerated actions, e.g. "Create PRs that link an approved issue, add a type label, and pass shellcheck and CI checks".

Broaden trigger terms to natural user phrasings such as "open a pull request", "submit a PR", or "prepare a branch for review".

Keep the explicit Trigger clause but merge it into a "Use when..." form that pairs naturally with the broader capability list.

Dimension	Reasoning	Score
Specificity	It names the domain (pull requests) and an action ("Create") plus the constraint "issue-first checks", but does not enumerate multiple concrete actions like linking issues, adding labels, or running checks, so it stops at naming a domain and some actions.	2 / 3
Completeness	Both a "what" (create PRs with issue-first checks) and an explicit "when" (the Trigger clause) are present, but the "what" is thin and abstract rather than clearly enumerating concrete capabilities, falling short of the score-3 anchor's clearly-answered both.	2 / 3
Trigger Term Quality	The explicit "Trigger: creating, opening, or preparing PRs for review" provides relevant natural phrases, but the term set is limited to verb variations of "PR" and omits common variations a user would actually say (e.g. "open a pull request", "submit a PR", "make a PR").	2 / 3
Distinctiveness Conflict Risk	The "Gentle AI" project qualifier combined with the distinctive "issue-first checks" constraint carves a clear niche that is unlikely to trigger for generic PR skills.	3 / 3
	Total	9 / 12 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: Gentleman-Programming/gentle-ai
Path: internal/assets/skills/branch-pr/SKILL.md
Commit: e01b114

Reviewed: about 13 hours ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.