gh-cli
Use gh (GitHub CLI) for all GitHub operations — creating PRs, checking status, commenting, and capturing URLs. Prefer gh over GitHub MCP tools to minimize token usage.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 3
- Forks
- 0
01 前言 Front Matter
- name
- gh-cli
- description
- Use gh (GitHub CLI) for all GitHub operations — creating PRs, checking status, commenting, and capturing URLs. Prefer gh over GitHub MCP tools to minimize token usage.
03 SKILL.md 正文
gh-cli — GitHub CLI
Use gh for all GitHub operations. Never use GitHub MCP tools when gh can do the same job.
Why gh over MCP
MCP tool calls return full JSON payloads into context. gh runs in Bash, outputs only what you request, and exits. Token cost per operation: gh ≈ 10–50 tokens vs MCP ≈ 500–2000 tokens.
Authentication
gh reads credentials from ~/.config/gh/. Assume it is authenticated. If a command returns an auth error, stop and tell the user to run gh auth login.
Full PR creation workflow
Always follow this order — never skip steps:
# 1. Push branch to remote
git push -u origin "$(git branch --show-current)"
# 2. Check for existing PR — never create duplicates
existing=$(gh pr list --head "$(git branch --show-current)" --json url --jq '.[0].url // empty' 2>&1)
if [ -n "$existing" ]; then
echo "PR already exists: $existing"
exit 0
fi
# 3. Create PR — always use heredoc for body to avoid shell escaping issues
pr_url=$(gh pr create \
--title "feat(scope): description" \
--base develop \
--body "$(cat <<'EOF'
## Summary
- What this PR does (bullet points)
## Test plan
- [ ] Verification step
EOF
)" 2>&1)
echo "Created PR: $pr_url"
Create a PR (minimal form)
gh pr create \
--title "feat(scope): description" \
--base develop \
--body "$(cat <<'EOF'
## Summary
- <what changed and why>
## Test plan
- [ ] <how to verify>
EOF
)"
Shell escaping rule
Always use single-quoted <<'EOF' for PR bodies — prevents variable expansion inside the body:
# CORRECT — $ENTITY is treated as literal text
--body "$(cat <<'EOF'
## Summary
- Added $ENTITY support
EOF
)"
# WRONG — shell expands $ENTITY, breaks the body
--body "$(cat <<EOF
## Summary
- Added $ENTITY support
EOF
)"
Core commands
View PR (minimal output — never dump full view)
# State + title + URL
gh pr view --json url,state,title --jq '"\(.state) — \(.title) — \(.url)"'
# Review status
gh pr view --json reviewDecision,mergeable --jq '"\(.reviewDecision) / \(.mergeable)"'
List PRs for current branch
gh pr list \
--head "$(git branch --show-current)" \
--json number,title,url,state \
--jq '.[] | "\(.number) [\(.state)] \(.title) — \(.url)"'
Add comment to PR or issue
gh pr comment <number-or-url> --body "Spec ready: docs/superpowers/specs/CER-123-design.md"
gh issue comment <number> --body "Comment text"
Check CI status
gh pr checks --json name,state,conclusion \
--jq '.[] | "\(.name): \(.conclusion // .state)"'
Merge a PR (when authorized)
gh pr merge <number-or-url> --squash --delete-branch
Branch conventions
| Artifact | Branch pattern |
|---|---|
| Idea doc | ideas/<slug> |
| PRD | feature/prd-<slug> |
| Spec, plan | committed to feat/<JIRA-KEY>; they ship in the implementation PR (no PR of their own) |
| DB changes | feat/db/<feature> |
| Backend | feat/backend/<feature> |
| Sync | feat/sync/<feature> |
| Web | feat/web/<feature> |
| Mobile | feat/mobile/<feature> |
PR title conventions
| Phase | Title format |
|---|---|
| Idea doc | docs(idea): <concept title> |
| PRD | docs(prd): <feature title> |
| Spec | docs(spec): <JIRA-KEY> <story summary> |
| Plan | docs(plan): <JIRA-KEY> <feature title> |
| DB | feat(db): <description> |
| Backend | feat(backend): <description> |
| Sync | feat(sync): <description> |
| Web | feat(web): <description> |
| Mobile | feat(mobile): <description> |
PR body template per phase
Doc artifact PR (idea / PRD)
## Summary
- Adds <artifact type> for <feature/story name>
- Covers: <key decisions made>
## Review checklist
- [ ] Acceptance criteria are binary (done/not done)
- [ ] No open TBDs without a suggested default
- [ ] Scope boundaries are explicit
Implementation PR (DB / backend / sync / web / mobile)
## Summary
- Implements <story key>: <story summary>
- Changes: <list of key changes>
## Test plan
- [ ] Project typecheck passes (command from project-context)
- [ ] Project lint passes (command from project-context)
- [ ] <manual verification step>
## Jira
<JIRA-KEY>
Capturing PR URL
pr_url=$(gh pr create --title "..." --base develop --body "..." 2>&1)
echo "PR: $pr_url"
# Use $pr_url in follow-up acli comments or return value
Error handling
| Error | Fix |
|---|---|
| Auth error | Tell user: gh auth login |
| Branch not pushed | git push -u origin $(git branch --show-current) first |
| PR already exists | Report existing URL, do NOT create duplicate |
| No commits ahead of base | Nothing to PR — stop and report |
--base branch not found |
Confirm base branch: git branch -r | grep <configured-base-branch> |
04 同仓库更多 Skills
designing-in-patterns
Use when designing, planning or auditing UI against a component library — naming surfaces with the repo's pattern vocabulary, deciding reuse versus extend versus new, exploring compositions, or writing the reuse table (component-plan.md, a spec's `## Reuse`, a UI audit). Carries the design method; the repo's own vocabulary, bundle and board rules come from project-context and the designer override.
typeorm
Use when defining TypeORM entities, writing migrations, or building repository/query-builder code in TypeScript. Covers entity and relation decorators, the Data Mapper pattern, migrations, the query builder, transactions, and multi-database configuration.
hono-api
Use when building or extending REST APIs with Hono + @hono/zod-openapi. Covers schema-first route declaration with createRoute, feature-grouped composable routers, a class-based service layer behind interfaces, the strategy pattern for multi-event webhooks, typed request validation, and auto-generated OpenAPI docs.
electrodb
Use when defining DynamoDB entities, modeling indexes, or writing queries/mutations with the ElectroDB ORM. Covers entity schema, access patterns, CRUD operations, update expressions, and single-table design patterns.
atomic-design
Use when structuring or decomposing any frontend UI into reusable components, regardless of framework. Applies Brad Frost's atomic design methodology — atoms, molecules, organisms, templates, and pages — to guide consistent component hierarchy, naming, and composition decisions.
writing-docs
Use when writing, restructuring, or reviewing any prose documentation — a tutorial, how-to guide, reference page, or explanation/conceptual doc — for a public docs site (e.g. Mintlify MDX, docs/, README material), a getting-started guide, an API/CLI reference page, or a "why we built it this way" conceptual page. Applies the Diátaxis framework (see https://diataxis.fr/) — every document belongs to exactly one of the four quadrants (tutorial / how-to guide / reference / explanation), and mixing quadrants inside one document is the single most common documentation failure. Covers the four-quadrant compass for picking the right form, per-quadrant structure templates, an anti-pattern list for quadrant drift, and generic voice/craft rules — repo-specific voice and target output format (e.g. Mintlify MDX) are resolved from the repo's docs-manifest (falling back to project-context), never hardcoded here.