github

GitHub 技能

此技能通过官方 gh CLI 工具提供 GitHub 集成功能。Python 包装脚本会将读取／查看操作的输出格式化为 Markdown。操作命令（创建、合并、关闭、评论）应直接使用 gh。

网络访问

GitHub 命令（gh 和 Python 包装脚本）需要通过出站 HTTPS 访问 GitHub API 和身份验证端点，或已配置的 GitHub Enterprise 主机。Git 获取／推送需要通过 HTTPS 或 SSH 访问仓库主机。远程操作需要出站网络访问。如果 Agent 环境对此有限制，请先通过该环境的审批或网络控制获取访问权限，然后再执行第一个远程命令，并复用已获授权。查看本地帮助和处理文件不需要网络访问。技能说明不会授予网络权限。遇到 DNS、连接和超时故障时，请报告为网络错误；不要通过重置凭据来解决。如果已获批准的访问仍然失败，请停止操作并报告。身份验证和权限错误需要用户处理。

解析脚本路径

示例中的 SKILL_DIR 是当前加载的 SKILL.md 所在目录。 运行命令前，将其设为该目录的绝对路径；不要假设 Agent 已设置此 shell 变量。如果脚本路径包含空格，请用引号括起来。

先决条件

安装 gh CLI：安装指南

身份验证

# Authenticate with GitHub
gh auth login

# Verify authentication
gh auth status

详情请参阅 GitHub CLI 身份验证。

脚本用法

包装脚本（scripts/github.py）会将输出格式化为 Markdown。读取／查看操作请使用此脚本，以获取 Agent 可使用的输出。操作命令（创建、合并、关闭、评论）请直接使用 gh。各命令的读／写分类请参阅 permissions.md。

# Check gh CLI is installed and authenticated
$SKILL_DIR/scripts/github.py check

# Issues
$SKILL_DIR/scripts/github.py issues list --repo OWNER/REPO
$SKILL_DIR/scripts/github.py issues view 123 --repo OWNER/REPO

# Pull Requests
$SKILL_DIR/scripts/github.py prs list --repo OWNER/REPO
$SKILL_DIR/scripts/github.py prs view 456 --repo OWNER/REPO
$SKILL_DIR/scripts/github.py prs checks 456 --repo OWNER/REPO
$SKILL_DIR/scripts/github.py prs status --repo OWNER/REPO

# Workflow Runs
$SKILL_DIR/scripts/github.py runs list --repo OWNER/REPO
$SKILL_DIR/scripts/github.py runs view 12345 --repo OWNER/REPO

# Repositories
$SKILL_DIR/scripts/github.py repos list
$SKILL_DIR/scripts/github.py repos view OWNER/REPO

# Search
$SKILL_DIR/scripts/github.py search repos "machine learning"
$SKILL_DIR/scripts/github.py search issues "label:bug is:open"
$SKILL_DIR/scripts/github.py search prs "is:open review:required"

所有列表命令均支持 --limit N（默认值为 30）。

命令（直接使用 gh）

操作命令请直接使用 gh：

问题

gh issue list                    # List issues
gh issue view 123                # View issue details
gh issue create                  # Create new issue
gh issue comment 123             # Add comment
gh issue close 123               # Close issue
gh issue edit 123 --add-label bug  # Edit issue

完整参考：gh issue

拉取请求

gh pr list                       # List PRs
gh pr view 456                   # View PR details
gh pr create                     # Create new PR
gh pr review 456 --approve       # Approve PR
gh pr merge 456 --squash         # Merge PR
gh pr checkout 456               # Checkout PR branch
gh pr diff 456                   # View PR diff
gh pr checks 456                 # View CI status

完整参考：gh pr

工作流与 Actions

gh workflow list                 # List workflows
gh workflow run "CI"             # Trigger workflow
gh run list                      # List workflow runs
gh run view 123456               # View run details
gh run watch 123456              # Watch run progress
gh run download 123456           # Download artifacts
gh run rerun 123456 --failed     # Rerun failed jobs

完整参考：

• gh workflow
• gh run

仓库

gh repo list                     # List repositories
gh repo view OWNER/REPO          # View repository
gh repo create                   # Create repository
gh repo clone OWNER/REPO         # Clone repository
gh repo fork OWNER/REPO          # Fork repository

完整参考：gh repo

搜索

gh search repos "machine learning"   # Search repositories
gh search issues "is:open label:bug" # Search issues
gh search prs "is:open"              # Search pull requests
gh search code "function auth"       # Search code

完整参考：gh search

示例

每日 PR 审查

# Show PRs needing your attention
$SKILL_DIR/scripts/github.py prs status

# Review a specific PR
$SKILL_DIR/scripts/github.py prs view 456
$SKILL_DIR/scripts/github.py prs checks 456
gh pr diff 456
gh pr review 456 --approve

# Verify approval was recorded
$SKILL_DIR/scripts/github.py prs view 456  # check review status

创建问题并关联 PR

# Create issue
gh issue create --title "Bug: Login fails" --body "Description" --label bug
# Verify: note the issue number from output

# Create PR that fixes it (use issue number from above)
gh pr create --title "Fix login bug (#123)" --body "Fixes #123"
# Verify PR was created and linked
$SKILL_DIR/scripts/github.py prs view <number>

监控 CI 流水线

# Watch latest workflow run
gh run watch $(gh run list --limit 1 --json databaseId --jq '.[0].databaseId')

# Check failed runs
gh run list --status failure

# Rerun failed jobs
gh run rerun RUNID --failed
# Verify rerun started
$SKILL_DIR/scripts/github.py runs view RUNID

更多示例请参阅 common-workflows.md。

高级用法

用于脚本的 JSON 输出

# Get specific fields
gh issue list --json number,title,author

# Process with jq
gh pr list --json number,title | jq '.[] | "\(.number): \(.title)"'

# Export to CSV
gh issue list --json number,title,author | jq -r '.[] | @csv'

GitHub API 访问

对于 gh 命令未涵盖的操作：

# Make authenticated API request
gh api repos/OWNER/REPO/issues

# POST request
gh api repos/OWNER/REPO/issues -X POST -f title="Issue" -f body="Text"

# Process response
gh api repos/OWNER/REPO | jq '.stargazers_count'

完整参考：gh api

高频操作的别名

# Create shortcuts
gh alias set prs 'pr list --author @me'
gh alias set issues 'issue list --assignee @me'
gh alias set review 'pr list --search "review-requested:@me"'

# Use them
gh prs
gh issues
gh review

配置

# View configuration
gh config list

# Set default editor
gh config set editor vim

# Set git protocol
gh config set git_protocol ssh

配置存储于 ~/.config/gh/config.yml

模型建议

此技能封装了官方 CLI。快速、轻量的模型即可胜任。

故障排查

# Check authentication
gh auth status

# Re-authenticate
gh auth login

# Enable debug logging
GH_DEBUG=1 gh issue list

# Check gh version
gh --version

官方文档

• GitHub CLI 手册：https://cli.github.com/manual/
• GitHub CLI 仓库：https://github.com/cli/cli
• GitHub API 文档：https://docs.github.com/en/rest
• GitHub Actions：https://docs.github.com/en/actions

总结

GitHub 技能使用官方 gh CLI，并通过 Python 包装脚本将读取／查看命令的输出格式化为 Markdown。

快速开始：

1. 安装：brew install gh（或适用于你的操作系统的等效命令）
2. 身份验证：gh auth login
3. 验证：$SKILL_DIR/scripts/github.py check
4. 读取：$SKILL_DIR/scripts/github.py issues list --repo OWNER/REPO
5. 写入：gh issue create、gh pr create 等（直接使用 gh）

如需详细的命令参考，请使用 gh <command> --help 或访问 https://cli.github.com/manual/。