github-ops

GitHub Ops Skill

提供使用 gh api 和 gh search 进行仓库侦察的结构化指导。

概述

当 Agent 猜测文件路径或盲目尝试获取大型文件时，仓库侦察往往会失败。此技能通过 GitHub CLI 强制执行结构化的“映射 → 识别 → 获取”流程，以减少令牌浪费并提高可靠性。

⚡ 核心侦察命令

在获取内容前，使用这些命令了解仓库结构。

1. 列出仓库根目录

gh api repos/{owner}/{repo}/contents --jq '.[].name'

2. 列出指定目录

gh api repos/{owner}/{repo}/contents/{path} --jq '.[].name'

3. 获取文件内容（Base64 解码）

gh api repos/{owner}/{repo}/contents/{path} --jq '.content' | base64 -d

4. 在仓库中搜索模式

gh search code "{pattern}" --repo {owner}/{repo}

5. 获取仓库元数据

gh repo view {owner}/{repo} --json description,stargazerCount,updatedAt

🔄 节省令牌的工作流

1. 映射目录树：列出根目录和核心目录（commands、src、docs）。
2. 识别入口点：查找 README.md、gemini-extension.json、package.json 或 SKILL.md。
3. 定向获取：先仅下载入口点。
4. 深入探索：使用 gh search code 查找逻辑模式，而不是逐个读取所有文件。

🛡️ 平台安全（Windows）

• 使用 base64 -d 时，如果输出内容较大，请确保使用 Write 工具将其重定向到文件。
• 在复杂管道中避免使用 Linux 风格的 /dev/stdin 模式。
• 在本地存储时使用原生路径。

铁律

1. 始终在读取任何文件前遵循“映射 → 识别 → 获取”的流程——盲目猜测路径并获取文件会浪费令牌、触发 404，并导致对仓库结构产生幻觉。
2. 绝不在未先列出父目录或通过 gh api 确认文件存在的情况下获取文件——不必要地获取大型文件可能会耗尽上下文窗口。
3. 始终使用 --jq 将 gh api 的 JSON 输出筛选为所需字段——未经筛选的 API 响应包含数百个无关字段，会增加令牌用量。
4. 绝不在未添加范围限定符（repo、org 或 path）的情况下使用 gh search code——未限定范围的代码搜索会返回整个 GitHub 的结果，产生无关信息。
5. 始终在需要仓库元数据时优先使用 gh api 结构化查询，而不是直接读取仓库文件——API 查询速度更快、结构化程度更高，而且查询公开仓库无需身份验证上下文。

反模式

反模式	失败原因	正确做法
猜测文件路径并直接获取	404 率高；在不存在的路径上浪费令牌	先映射根目录树：gh api repos/{owner}/{repo}/git/trees/HEAD --jq '.tree[].path'
为了单个字段而获取整个文件	大型文件会耗尽上下文；速度慢且不精确	使用 --jq 从 API 响应中提取所需字段
未限定范围的 gh search code 查询	返回整个 GitHub 的结果；无关信息淹没有用信息	始终添加 --repo owner/name 或 --owner org 范围限定符
读取二进制文件或生成文件	二进制内容无法读取；生成文件经常变化	先识别文件类型；跳过二进制文件；只读取源文件
针对每个文件依次调用 API	不必要的往返会增加延迟	批量处理：使用 gh api 树或搜索来识别多个目标，然后并行获取

GitHub MCP 服务操作

配置官方 GitHub MCP 服务（@modelcontextprotocol/server-github）后，可使用这些更高级别的工具进行仓库管理和自动化：

// settings.json configuration
"github": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" }
}

PR 自动化模式

# Create PR with auto-generated description
gh pr create \
  --title "feat: add feature X" \
  --body "$(gh api repos/{owner}/{repo}/compare/{base}...{head} --jq '.commits[].commit.message' | head -5)" \
  --base main \
  --head feature/x

# Auto-merge after CI passes
gh pr merge --auto --squash --delete-branch

Issue 管理

# List open issues by label
gh issue list --label "bug" --state open --json number,title,assignees

# Bulk-close resolved issues
gh issue list --label "stale" --json number --jq '.[].number' | \
  xargs -I{} gh issue close {} --comment "Closing as stale"

# Create issue from template
gh issue create \
  --title "Bug: [description]" \
  --body-file .github/ISSUE_TEMPLATE/bug_report.md \
  --label "bug,needs-triage"

发布自动化

# Create release with auto-generated notes
gh release create v1.2.0 \
  --generate-notes \
  --title "v1.2.0" \
  --target main

# Upload release assets
gh release upload v1.2.0 dist/*.tar.gz dist/*.zip

工作流管理

# Trigger workflow manually
gh workflow run deploy.yml --field environment=production

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

# Download workflow artifacts
gh run download --name=build-artifacts --dir=./artifacts

分配的 Agent

• artifact-integrator：负责仓库接入的主 Agent。
• developer：PR 管理与探索。

记忆协议（强制）

开始之前： 阅读 .claude/context/memory/learnings.md

完成之后：

• 新模式 -> .claude/context/memory/learnings.md
• 发现问题 -> .claude/context/memory/issues.md
• 做出决策 -> .claude/context/memory/decisions.md

假设工作会被中断：如果没有记录在记忆中，就等于没有发生。