SuperAPI AI Directory

soia-dev-github-ops

General & other

View repository

Updated 10-16 08:45

About this skill

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.

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

  1. Describe the goal in natural language and provide the necessary inputs: files, URLs, repo, workspace, proposal, vault or platform account status.
  2. 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.yml only stores non-secret defaults, such as repository names or profile pointers. GitHub tokens, cookies and sessions must remain in gh auth login the 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

  • gh Query 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 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:

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 gh command 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.