AGENT SKILL

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

whimzyLive
whimzyLive/nightshift-ai

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.

★ 3
whimzyLive
whimzyLive/nightshift-ai

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.

★ 3
whimzyLive
whimzyLive/nightshift-ai

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.

★ 3
whimzyLive
whimzyLive/nightshift-ai

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.

★ 3
whimzyLive
whimzyLive/nightshift-ai

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.

★ 3
whimzyLive
whimzyLive/nightshift-ai

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.

★ 3