soia-dev-github-ops

Use this skill when the user asks to inspect or operate GitHub state: issues, pull requests, checks, reviews, workflow run logs, labels, releases, or PR lifecycle actions.

Do not use it for local-only git work such as commits, rebases, branch cleanup, or worktree management unless a GitHub operation is also required.

客户可读说明

这个技能可以做什么

Use gh CLI for GitHub issue, PR, checks, review, workflow run, release, and collaborator-permission operations, plus a pre-merge rule-review procedure and an author-side "address a review and fix it" procedure, with structured JSON output and safety gates

客户如何使用

1. 用自然语言说明目标，并提供必要输入：文件、URL、repo、workspace、proposal、vault 或平台账号状态。
2. 能 dry-run 或预览的动作先给预览；涉及删除、覆盖、发送、发布、写远端状态时先征求客户确认。

依赖与安装

安装（推荐：装整个领域插件，一次装好本仓全部技能）：

claude plugin marketplace add soia-team/soia-open-skills

claude plugin install soia-dev@soia

只要这一个技能时，可用 npx 路线。注意技能会落进共享真源 ~/.agents/skills；若同时装了插件，同一技能会出现两份索引且各自漂移，建议二选一：

npx skills add soia-team/soia-open-dev-skills -g -a '*' -s soia-dev-github-ops -y

复制 [assets/config.example.yml](assets/config.example.yml) 后按需填写非秘密默认值。配置约定：

~/.config/soia-skills/soia-dev-github-ops/config.yml
SOIA_DEV_GITHUB_OPS_CONFIG_FILE=<custom-config-path>

• 如果本技能不需要私有配置，可以不创建 config.yml。
• 普通 config.yml 只保存非秘密默认值，例如仓库名或 profile 指针。GitHub token、cookie 和 session 必须留在 gh auth login 管理的官方凭据存储或系统凭据库，不能写进配置、仓库、正文或日志。
• 第三方 skill 只能声明依赖和安装方式，不直接修改第三方 skill 文件。

WorkBuddy 的装载单位是角色化专家而不是插件，npx skills add -a '*' 覆盖不到它，需要单独安装，见 docs/install/workbuddy.md。

私密信息与中间数据

• gh 查询结果可能包含私有仓库名、issue/PR 正文、成员信息和日志；只读取本次操作所需字段，默认通过结构化 stdout 处理，不持久保存完整响应。
• GitHub 凭据只由 gh auth login 的官方存储或系统凭据库管理；不得把 token、cookie、session、完整认证输出或秘密环境变量写入普通配置、命令参数、issue、PR、评论或日志。
• 远端 issue、PR、review、release 和权限是 GitHub 产品状态，不是本技能私有缓存；任何创建或修改都按 Safety Model 取得授权并在完成后查询远端复核。
• 本技能默认不创建本地 state 或 cache。客户明确要求导出报告时写入其指定路径；临时响应放操作系统临时目录并在任务结束后清理。
• 回执只记录 repo、对象编号、状态、URL 和必要错误摘要；私有正文、协作者信息和日志内容按最小披露原则脱敏。

日志与完成回执

每次执行都要让客户看见过程和结果。最低回执格式：

完成：<一句话说明本次完成了什么>。

日志摘要：
- started: <检查到的输入/配置/依赖，不打印秘密值>
- processed: <数量或范围>
- created/updated: <数量或路径>
- skipped/failed: <数量和原因>

文件变化：
- <绝对路径或“未改动文件”>

验证：
- <运行过的检查、命令或人工核对点>

问题与下一步：
- <缺 key / 缺依赖 / 需要客户确认 / 建议下一条命令；没有则写“无”>

Safety Model

• Read-only gh queries may run once the target repo is known.
• Mutating operations require clear user intent in the current request.
• High-impact operations require an explicit final confirmation before running:

gh pr merge, gh release create, branch deletion, label deletion, workflow dispatch against production, granting/revoking a collaborator's permission, or any action that closes public work or changes who can write to a repo.

• Collaborator permission changes are the single most sensitive operation this

skill performs — more sensitive than gh pr merge. A bad merge affects one change; a wrong permission grant is a standing capability the person keeps using until someone notices and revokes it. Never infer the target repo, username, or permission level from prior conversation turns alone — restate all three and get explicit confirmation in the current exchange before the write call. See "Collaborator Access Management" below for the full gate.

• Use gh auth status before operations. If auth is missing or expired, stop

and tell the user what needs to be configured.

• Never put GitHub tokens in SKILL.md, shell history, scripts, issue bodies,

PR bodies, or comments. Use gh auth login for credentials; keep only non-token defaults in the skill-specific private config.

Repo Resolution

Resolve the target repository in this order:

1. Explicit command argument: --repo <owner>/<repo>.
2. Current git remote if the command runs inside a GitHub checkout.
3. Environment variable: GITHUB_REPOSITORY=<owner>/<repo>.
4. Optional private config: ~/.config/soia-skills/soia-dev-github-ops/config.yml.
5. Ask the user if the repo is still ambiguous.

The optional config file is a user-owned YAML file with an env: mapping, for example:

env:
  GITHUB_REPOSITORY: "<owner>/<repo>"

Do not hardcode maintainer-specific repositories in reusable commands.

Query Patterns

Prefer --json and --jq for agent-readable output.

# Auth and repo sanity checks
gh auth status
gh repo view --json nameWithOwner,defaultBranchRef,isPrivate

# Open PRs
gh pr list --repo <owner>/<repo> --state open \
  --json number,title,state,author,headRefName,baseRefName,updatedAt

# Single PR status
gh pr view <number> --repo <owner>/<repo> \
  --json number,title,state,mergeable,mergeStateStatus,reviewDecision,headRefName,baseRefName

# PR checks
gh pr checks <number> --repo <owner>/<repo> \
  --json name,state,bucket,startedAt,completedAt,link

# Issues
gh issue list --repo <owner>/<repo> --state open \
  --json number,title,state,labels,assignees,updatedAt

# Workflow runs
gh run list --repo <owner>/<repo> --limit 20 \
  --json databaseId,status,conclusion,workflowName,headBranch,createdAt,url

When reporting results, include:

• repo: <owner>/<repo>
• object: PR / issue / run / release
• identifier: number, run id, or tag
• status: open / closed / merged / passing / failing / cancelled
• next action or blocker

PR Lifecycle

Create PRs with a concise body containing summary and verification evidence.

gh pr create --repo <owner>/<repo> \
  --base <base-branch> \
  --head <feature-branch> \
  --title "<type>: <short change>" \
  --body "$(cat <<'EOF'
## Summary
- <what changed>

## Verification
- <command>: <result>
EOF
)"

Review operations:

gh pr review <number> --repo <owner>/<repo> --approve --body "<review note>"
gh pr review <number> --repo <owner>/<repo> --request-changes --body "<required changes>"
gh pr comment <number> --repo <owner>/<repo> --body "<comment>"

Before merge:

gh pr view <number> --repo <owner>/<repo> \
  --json mergeable,mergeStateStatus,reviewDecision,statusCheckRollup \
  --jq '{mergeable, mergeStateStatus, reviewDecision, checks: .statusCheckRollup}'

Only merge after explicit confirmation:

gh pr merge <number> --repo <owner>/<repo> --squash --delete-branch

CI Failure Triage

Use this order:

1. Identify the failing run and job.
2. Read the first actionable error in the failed log.
3. Classify the failure.
4. Reproduce locally only if the repo has enough context and the command is safe.
5. Report the exact failing command, file, or external blocker.

gh run view <run-id> --repo <owner>/<repo> --json status,conclusion,workflowName,jobs,url
gh run view <run-id> --repo <owner>/<repo> --log-failed

Common classes:

Release Operations

Release creation is a publish action. Prepare the command, show the tag/name/body summary, and ask for explicit confirmation before running:

gh release create <tag> --repo <owner>/<repo> \
  --title "<release title>" \
  --notes-file <notes-file>

After release, verify:

gh release view <tag> --repo <owner>/<repo> \
  --json tagName,name,isDraft,isPrerelease,publishedAt,url

Output Checklist

Before final response:

• State the resolved repo and how it was resolved.
• Separate facts from inference when summarizing failures.
• Include exact PR/issue/run/release identifiers.
• For mutating operations, say what changed and include the resulting URL or id.
• For blocked auth or permission, say which gh command failed and what the user

must configure.

真实前向验收

对已知仓库中的真实对象执行只读查询，并核对输出内容而不只看退出码：

gh pr view <number> --repo <owner>/<repo> \
  --json number,state,mergeable,baseRefName,headRefName,url

验收至少确认：编号与目标一致、URL 属于目标仓库、base/head 分支符合请求、状态字段可解释，且输出不含 token 或认证详情。对不存在的编号补一条预期失败检查，确认错误没有被包装成成功。

写操作仅在客户明确授权后测试；完成后必须用独立的只读 gh view/gh api GET 查询远端对象，逐字段核对预期状态。权限变更还要按协作者手册复查实际 role，release 要复查 tag、draft/prerelease 和发布时间，不能把写命令退出 0 当作验收。

分流程手册

以下流程互斥，一次任务只会走其中一条；按需读取对应文件即可。

• Pre-Merge Rule Review — [pre-merge-rule-review.md](references/pre-merge-rule-review.md)
• Address Review Feedback (author side) — [address-review-feedback.md](references/address-review-feedback.md)
• Collaborator Access Management — [collaborator-access.md](references/collaborator-access.md)