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.
Customer-readable description
What this skill can do
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
| Customer wants | Skill will do | Customer can see |
|---|---|---|
| Complete the work covered by this skill | Read the user request, necessary context and this skill's main workflow, and execute the minimal reliable steps | The customer will see the execution plan, command output summaries, code/document changes, verification results and risk notes. |
| Add/check/revoke repository collaborator permissions for someone | First confirm the target repository, username and permission level, then execute gh api write operations and verify they took effect |
Permission level explanation, confirmation checklist, verification results |
| Want to know whether this PR complies with the rules before merging | Pull the diff + this repository's own rules files, cross-check and give tiered recommendations; do not auto-merge | One-sentence conclusion, findings list tiered by blocking/should-fix/no-objection, CI and mergeable status |
| Receive review comments (paste PR/review URL and say "help me fix") | Pull the review (including inline + conversation comments) → checkout the branch → delegate to fix-loop to fix item by item → push back to the original branch and request re-review; do not auto-merge | Handling status of each comment, verification evidence, push results, re-review request receipt |
| Missing dependencies, permissions, configuration or keys | Stop actions that require external state, and clearly state what is missing | Install commands, application addresses, configuration paths or questions requiring customer confirmation |
| Execution complete | Summarize successes, skips, failures, file changes and verification results | A completion receipt that can be copied into a ticket/log |
How customers use it
- Describe the goal in natural language and provide the necessary inputs: files, URLs, repo, workspace, proposal, vault or platform account status.
- For actions that can be dry-run or previewed, provide a preview first; for actions involving deletion, overwriting, sending, publishing or writing remote state, ask the customer for confirmation first.
Dependencies and installation
Installation (recommended: install the entire domain plugin, setting up all skills in this repository at once):
claude plugin marketplace add soia-team/soia-open-skills
claude plugin install soia-dev@soia
If you only want this one skill, you can use the npx route. Note that the skill will land in the shared source of truth ~/.agents/skills; if the plugin is also installed, the same skill will appear in two indexes and drift separately, so it is recommended to choose one of the two:
npx skills add soia-team/soia-open-dev-skills -g -a '*' -s soia-dev-github-ops -y
Copy assets/config.example.yml and fill in non-secret defaults as needed. Configuration conventions:
~/.config/soia-skills/soia-dev-github-ops/config.yml
SOIA_DEV_GITHUB_OPS_CONFIG_FILE=<custom-config-path>
- If this skill does not need private configuration, you can skip creating
config.yml。 - Ordinary
config.ymlonly stores non-secret defaults, such as repository names or profile pointers. GitHub tokens, cookies and sessions must remain ingh auth loginthe official credential store or system credential vault it manages, and must not be written into configuration, repositories, main text or logs. - Third-party skills can only declare dependencies and installation methods, and do not directly modify third-party skill files.
WorkBuddy is loaded as role-based experts rather than plugins,npx skills add -a '*' cannot cover it, and it needs to be installed separately, see docs/install/workbuddy.md。
Private information and intermediate data
ghQuery results may contain private repository names, issue/PR bodies, member information, and logs; read only the fields required for this operation, process via structured stdout by default, and do not persistently store the full response.- GitHub credentials are managed only by
gh auth login's official storage or the system credential store; tokens, cookies, sessions, full authentication output, or secret environment variables must not be written into ordinary configuration, command arguments, issues, PRs, comments, or logs. - Remote issues, PRs, reviews, releases, and permissions are GitHub product state, not private caches of this skill; any creation or modification must obtain authorization per the Safety Model and query the remote afterward to verify.
- This skill does not create local state or cache by default. When the customer explicitly requests exporting a report, write it to their specified path; place temporary responses in the operating system temporary directory and clean them up after the task ends.
- Receipts record only the repo, object number, status, URL, and necessary error summary; private bodies, collaborator information, and log content are redacted per the principle of minimal disclosure.
Logging and Completion Receipts
Every execution must let the customer see the process and results. Minimum receipt format:
完成:<一句话说明本次完成了什么>。
日志摘要:
- started: <检查到的输入/配置/依赖,不打印秘密值>
- processed: <数量或范围>
- created/updated: <数量或路径>
- skipped/failed: <数量和原因>
文件变化:
- <绝对路径或“未改动文件”>
验证:
- <运行过的检查、命令或人工核对点>
问题与下一步:
- <缺 key / 缺依赖 / 需要客户确认 / 建议下一条命令;没有则写“无”>
Safety Model
- Read-only
ghqueries 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 statusbefore 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. Usegh auth loginfor credentials; keep only non-token defaults in the skill-specific private config.
Repo Resolution
Resolve the target repository in this order:
- Explicit command argument:
--repo <owner>/<repo>. - Current git remote if the command runs inside a GitHub checkout.
- Environment variable:
GITHUB_REPOSITORY=<owner>/<repo>. - Optional private config:
~/.config/soia-skills/soia-dev-github-ops/config.yml. - 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:
- Identify the failing run and job.
- Read the first actionable error in the failed log.
- Classify the failure.
- Reproduce locally only if the repo has enough context and the command is safe.
- 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:
| Class | Signal | Next step |
|---|---|---|
| Compile | compiler, typecheck, or lint error | Read the first error and map to file/line |
| Test | assertion failure or failing test name | Reproduce that test locally if possible |
| Environment | missing tool, package, or cache | Check setup steps and runner image |
| Permission | Resource not accessible or denied secret |
Check workflow permissions and fork context |
| Quota/timeout | quota message or cancelled after timeout | Report external limit or split work |
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
ghcommand failed and what the user must configure.
Real Forward Acceptance
Perform read-only queries against real objects in known repositories, and verify the output content rather than just the exit code:
gh pr view <number> --repo <owner>/<repo> \
--json number,state,mergeable,baseRefName,headRefName,url
Acceptance must at least confirm: the number matches the target, the URL belongs to the target repository, the base/head branches match the request, the status field is explainable, and the output contains no tokens or authentication details. For a nonexistent number, add an expected-failure check to confirm the error is not packaged as success.
Write operations are tested only after explicit customer authorization; after completion, an independent read-only gh view/gh api GET query must be used to query the remote object and verify the expected state field by field. For permission changes, also recheck the actual role per the collaborator manual; for releases, recheck the tag, draft/prerelease, and publication time. A write command exiting 0 must not be treated as acceptance.
Per-Workflow Manuals
The following workflows are mutually exclusive; a single task will follow only one of them; simply read the corresponding file as needed.
- Pre-Merge Rule Review — pre-merge-rule-review.md
- Address Review Feedback (author side) — address-review-feedback.md
- Collaborator Access Management — collaborator-access.md