Menu
create a pull request with standardized description template
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | create-pr |
| description | create a pull request with standardized description template |
| disable-model-invocation | true |
Create a pull request with a well-structured description based on the branch changes.
Do not draft or run gh pr create until each step passes.
git branch --show-current is not the default branch (main, master, or the repo’s documented default). Pass: branch name is printed and satisfies this.main..HEAD (or origin/main..HEAD if local main is missing) range you will summarize. Pass: you can name at least one commit subject and one area of files changed without inventing details.<...>, TODO, TBD). Optional sections with no content are removed, not left as stubs. Pass: a quick scan finds no angle-bracket placeholders or filler tokens.gh pr create exits successfully and prints a PR URL (or the PR number/URL from gh output). Pass: URL (or id) is recorded; if the command fails, do not claim the PR was created.First, collect information about the changes:
# Get current branch and verify it's not main
git branch --show-current
# Get commit history for this branch
git log --oneline main..HEAD
# Get detailed commit messages for context
git log --format="### %s%n%n%b" main..HEAD
# Get file change statistics
git diff --stat main..HEAD
# Get the actual diff for understanding changes
git diff main..HEAD
Based on the gathered information, determine:
Look for issue references:
fix/issue-123-description)Create the PR using this template structure:
gh pr create --title "<type>(<scope>): <description>" --body "$(cat <<'EOF'
## Summary
<1-3 sentence overview of what this PR does and why>
## Changes
<Categorized bullet list of changes>
### Added
- <new features or capabilities>
### Changed
- <modifications to existing functionality>
### Fixed
- <bug fixes>
### Removed
- <deprecated or removed functionality>
## Motivation
<Why were these changes needed? What problem does this solve?>
## Testing
<How was this tested?>
- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [ ] Manual testing performed
### Manual Testing Steps
<If applicable, steps to manually verify the changes>
## Breaking Changes
<If any, describe what breaks and migration path. Remove section if none.>
## Related Issues
<Link to related issues. Remove section if none.>
- Closes #<issue_number>
- Related to #<issue_number>
## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Tests pass locally
- [ ] Linting passes
- [ ] Documentation updated (if needed)
EOF
)"
Optionally append a footer trailer per project convention (e.g. a tool-attribution line). Omit it when the project has no such convention.
Use conventional commit format for the PR title:
feat(scope): add new featurefix(scope): correct bug behaviorrefactor(scope): restructure without behavior changedocs(scope): update documentationtest(scope): add or modify testschore(scope): maintenance tasksAfter creating the PR, apply appropriate labels based on the changes. Use gh pr edit <number> --add-label <label>.
Check the repository's available labels first:
gh label list
| Label | When to Use |
|---|---|
enhancement | New features, capabilities, or improvements |
bug | Bug fixes |
documentation | Documentation-only changes |
breaking-change | User-facing breaking changes requiring migration |
Only apply breaking-change for user-facing changes that require users to modify their:
Do NOT apply for internal refactors unless they affect external consumers.
After creating the PR:
DO:
DON'T:
Use when you need a bite-sized, TDD-driven implementation plan but do NOT have a brainstorm-beagle spec to plan against. quick-plan reconstructs intent from the current conversation, fans out domain-expert exploration subagents across the codebase, and synthesizes the same plan format write-plan produces — without requiring `.beagle/concepts/<slug>/spec.md`. Triggers on: "quick plan", "plan this out", "plan what we just discussed", "turn this into an implementation plan", "plan this without a spec", "I don't have a spec, just plan it", "write-plan but no spec". Make sure to use this skill whenever the user wants an implementation or TDD plan and there is no spec to plan against — even if they just say "plan it" after discussing a feature. Writes to `.beagle/plans/<slug>/plan.md`. If a finalized spec already exists at `.beagle/concepts/<slug>/spec.md`, prefer write-plan. Does NOT brainstorm specs, write code, or execute the plan — produces the plan document (and an optional handoff prompt) only.
Use when the user has a fuzzy idea and wants to shape it into a concrete project spec before planning or building. Triggers on: "brainstorm this", "I have an idea for...", "help me think through this project", "what should I build", "spec this out". Also catches vague feature descriptions needing structured questioning to clarify scope. Does NOT write code, plan implementation, review strategy docs, or run strategy interviews — produces a WHAT/WHY spec through dialogue, not a HOW plan.
Use as the follow-up to brainstorm-beagle when a spec has an Open Questions section (or quietly carries latent gaps) that need closing before planning or implementation can begin. Triggers on: "resolve the open questions", "close the gaps in this spec", "research the open items", "finalize my spec", "make this spec implementation-ready", "answer the TBDs". Also triggers whenever the user points at a brainstorm-beagle spec and asks for research, proposals, or answers to unresolved items. Orchestrates parallel research subagents when available (falls back to inline sequential research otherwise), proposes answers one at a time for user approval, then rewrites the spec in place so it arrives at planning with no known gaps. Does NOT write code, design implementation, or create plans — it only produces a complete spec.
Use when you have a finalized brainstorm-beagle spec at `.beagle/concepts/<slug>/spec.md` and need a bite-sized, TDD-driven implementation plan before any code is written. Triggers on: "write a plan", "plan this spec", "turn the spec into a plan", "now plan the implementation", "write-plan". Reads the spec, designs the file structure, decomposes work into 2-5 minute TDD steps with exact paths and commands, self-reviews against the spec, gets user approval, then writes to `.beagle/concepts/<slug>/plan.md` and offers to generate an execution handoff prompt via the subagent-prompt skill. Does NOT brainstorm specs, write code, or execute the plan — produces the plan document (and an optional handoff prompt) only.
Core technical documentation writing principles for voice, tone, structure, and LLM-friendly patterns. Use when writing or reviewing any documentation.
Generate first-draft technical documentation from code analysis