gh
Install and configure the GitHub CLI (gh) for AI agent environments where gh may not be pre-installed and git remotes use local proxies instead of github.com. Provides auto-install script with SHA256 verification and GITHUB_TOKEN auth with anonymous fallback. Use when gh command not found, shutil.which("gh") returns None, need GitHub API access (issues, PRs, releases, workflow runs), or repository operations fail with "failed to determine base repo" error. Documents required -R flag for all gh commands in proxy environments. Includes project management: GitHub Projects V2 (gh project), milestones (REST API), issue stories (lifecycle and templates), and label taxonomy management.
- License 许可
- MIT
- 所属仓库
- cmetech/otto-cli
- 最近更新
- 2026-06-17
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- gh
- description
- Install and configure the GitHub CLI (gh) for AI agent environments where gh may not be pre-installed and git remotes use local proxies instead of github.com. Provides auto-install script with SHA256 verification and GITHUB_TOKEN auth with anonymous fallback. Use when gh command not found, shutil.which("gh") returns None, need GitHub API access (issues, PRs, releases, workflow runs), or repository operations fail with "failed to determine base repo" error. Documents required -R flag for all gh commands in proxy environments. Includes project management: GitHub Projects V2 (gh project), milestones (REST API), issue stories (lifecycle and templates), and label taxonomy management.
02 资源文件 8
- 参考文档references/issue-stories.md5.5 KB
- 参考文档references/labels.md5.0 KB
- 参考文档references/milestones.md4.1 KB
- 参考文档references/projects-v2.md4.4 KB
- 脚本scripts/experiment_cleanup.py6.2 KB
- 脚本scripts/github_project_setup.py30.9 KB
- 脚本tests/__init__.py—
- 脚本tests/test_github_project_setup.py24.3 KB
03 SKILL.md 正文
GitHub CLI (gh) — Setup and Usage
Purpose
Ensures the GitHub CLI (gh) is available and provides correct usage patterns for AI agents operating in environments where gh may not be pre-installed and where git remotes point to local proxies instead of github.com.
When to Use
ghcommand not found orshutil.which("gh")returns None- Need to interact with GitHub API (issues, PRs, releases, workflows)
- Repository remote does not point to
github.com(proxy environments) - Need authenticated GitHub operations with
GITHUB_TOKEN - Managing GitHub Issues, Projects V2, Milestones, or Labels
Installation
gh is assumed to be already installed via the system package manager:
- macOS:
brew install gh - Windows:
winget install GitHub.cli - Linux (Debian/Ubuntu):
apt install gh
For CI monitoring operations (watching workflow runs, checking statuses, waiting for jobs), use ci_monitor.cjs:
node src/resources/skills/github-workflows/references/gh/scripts/ci_monitor.cjs
Authentication
GITHUB_TOKEN environment variable provides automatic authentication. No manual gh auth login needed.
# Verify authentication
gh auth status
If GITHUB_TOKEN is set, gh authenticates automatically for all API calls.
Repository Detection
<repo_detection>
Git remote points to a local proxy (127.0.0.1), NOT github.com. Every gh command fails without explicit repo specification:
failed to determine base repo: none of the git remotes configured for this
repository point to a known GitHub host.
RULE: Pass -R (or --repo) on EVERY gh command:
gh <command> -R cmetech/otto-cli
This applies to ALL gh subcommands: pr, issue, run, api, release, project, etc.
</repo_detection>
Common Commands (v2.87.0)
<gh_commands>
Pull Requests
# List open PRs
gh pr list -R cmetech/otto-cli
# View PR details
gh pr view <number> -R cmetech/otto-cli
# Check PR CI status
gh pr checks <number> -R cmetech/otto-cli
# Create PR
gh pr create -R cmetech/otto-cli --title "title" --body "body"
# View PR comments
gh api repos/cmetech/otto-cli/pulls/<number>/comments
Issues
# List issues
gh issue list -R cmetech/otto-cli
# List by label
gh issue list -R cmetech/otto-cli --label "priority:p1" --state open
# Create issue with labels and milestone
# NOTE: Do NOT use labels for issue classification (bug, feature, etc.)
# Use labels for metadata (priority, status, auto-generated) only.
# Issue classification uses GitHub Issue Types, set via GraphQL after creation.
gh issue create -R cmetech/otto-cli \
--title "feat: add feature X" \
--label "priority:p1" \
--milestone "v1.0"
# View issue
gh issue view <number> -R cmetech/otto-cli
# Close issue with comment
gh issue close <number> -R cmetech/otto-cli --comment "Implemented in PR #N"
# Edit labels on issue
gh issue edit <number> -R cmetech/otto-cli \
--add-label "status:in-progress" \
--remove-label "status:needs-grooming"
Issue Types (Classification)
gh issue create has no --type flag. Issue types (Bug, Feature Request, etc.) are set via GraphQL after creation:
# Step 1: Create the issue (returns URL)
ISSUE_URL=$(gh issue create -R cmetech/otto-cli \
--title "..." --body "...")
# Step 2: Set the issue type via GraphQL
ISSUE_NUM=$(echo "$ISSUE_URL" | grep -oE '[0-9]+$')
ISSUE_ID=$(gh api graphql -f query='{ repository(owner:"cmetech",name:"otto-cli") { issue(number:'"$ISSUE_NUM"') { id } } }' --jq '.data.repository.issue.id')
TYPE_ID=$(gh api graphql -f query='{ repository(owner:"cmetech",name:"otto-cli") { issueTypes(first:20) { nodes { id name } } } }' --jq '.data.repository.issueTypes.nodes[] | select(.name=="Bug") | .id')
gh api graphql -f query='mutation { updateIssue(input:{id:"'"$ISSUE_ID"'",issueTypeId:"'"$TYPE_ID"'"}) { issue { number } } }'
Replace "Bug" with the appropriate type name ("Feature Request", "Task", etc.).
Labels
# List all labels
gh label list -R cmetech/otto-cli
# Create label
gh label create "priority:p1" --color "E99695" \
--description "High priority" -R cmetech/otto-cli
See labels.md for the full taxonomy and color codes.
Projects V2
# List projects
gh project list --owner cmetech
# Create project
gh project create --owner cmetech --title "OTTO Backlog"
# Add issue to project
gh project item-add 1 --owner cmetech \
--url https://github.com/cmetech/otto-cli/issues/42
See projects-v2.md for field creation and item editing commands.
Milestones
gh has no native milestone subcommand — use gh api with the REST endpoint:
# List milestones
gh api repos/cmetech/otto-cli/milestones
# Create milestone
gh api repos/cmetech/otto-cli/milestones \
-X POST -f title="v1.0" -f due_on="2026-03-31T00:00:00Z"
# Assign milestone to issue
gh api repos/cmetech/otto-cli/issues/42 \
-X PATCH -F milestone=1
See milestones.md for full CRUD reference.
Workflow Runs
# List recent runs
gh run list -R cmetech/otto-cli --limit 5
# View specific run
gh run view <run-id> -R cmetech/otto-cli
# View failed job logs
gh run view <run-id> -R cmetech/otto-cli --log-failed
Releases
# List releases
gh release list -R cmetech/otto-cli
# View latest release
gh release view --repo cmetech/otto-cli
API (Direct)
# GET request
gh api repos/cmetech/otto-cli
# POST with fields
gh api repos/cmetech/otto-cli/issues -f title="Bug" -f body="Details"
# GraphQL
gh api graphql -f query='{ viewer { login } }'
# Paginated results
gh api repos/cmetech/otto-cli/contributors --paginate
Repository
# Clone
gh repo clone cmetech/otto-cli
# View repo info
gh repo view -R cmetech/otto-cli
</gh_commands>
Output Formatting
# JSON output
gh pr list -R cmetech/otto-cli --json number,title,state
# JQ filtering
gh pr list -R cmetech/otto-cli --json number,title --jq '.[].title'
# Template formatting
gh pr list -R cmetech/otto-cli --json number,title \
--template '{{range .}}#{{.number}} {{.title}}{{"\n"}}{{end}}'
Reference Files
- labels.md — Label taxonomy (priority, type, status), color codes, bulk setup
- milestones.md — Milestone CRUD via REST API, naming conventions
- projects-v2.md — GitHub Projects V2 commands, custom fields, GraphQL queries
- issue-stories.md — Issue as story format, body template, lifecycle, backlog item field mapping
Sources
- GitHub CLI Manual — official reference
- GitHub CLI Releases — binary downloads
- GitHub REST API — Issues — milestones, labels, issues
- GitHub Projects V2 API — GraphQL API
gh version 2.87.2 (2026-02-20)— version verified by installation test
04 同仓库更多 Skills
write-milestone-brief
Synthesize the current conversation into a milestone brief (PRD). Writes to `M###-CONTEXT.md` by default, or files a GitHub issue only with explicit user confirmation. Use when asked to "turn this into a PRD", "draft a milestone brief", "capture this context", "write it up", or when enough has been discussed to commit the plan to paper. Does not interview — it synthesizes what is already known.
write-docs
Collaborative document authoring workflow for proposals, technical specs, decision docs, README sections, ADRs, and long-form prose that must work for fresh readers. Use when asked to "write the docs", "draft a proposal", "write a spec", "write an RFC", "write the README", or when a document needs to be understandable by someone without this session's context. Three stages: gather context, iterate on structure, reader-test for a stranger.
web-quality-audit
Comprehensive web quality audit covering performance, accessibility, SEO, and best practices. Use when asked to "audit my site", "review web quality", "run lighthouse audit", "check page quality", or "optimize my website".
web-design-guidelines
Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".
verify-before-complete
Block completion claims until verification evidence has been produced in the current message. Use before marking a task/slice/milestone complete, before creating a commit or PR, before saying "it works" or "tests pass", and any time you are about to claim work is done. The rule is: evidence before claims, always — running the verification must happen now, not "earlier in the session". Fresh output or no claim.
userinterface-wiki
UI/UX best practices for web interfaces. Use when reviewing animations, CSS, audio, typography, UX patterns, prefetching, or icon implementations. Covers 11 categories from animation principles to typography. Outputs file:line findings.