| name | github-contribution-workflow |
| description | Author GitHub contributions with the gh CLI โ open/merge PRs, open issues, create/edit files on GitHub, set repo secrets, configure contribution-flow repo settings. Use when running `gh pr create` / `gh pr merge` / `gh pr checks` / `gh issue create` / `gh secret set` / `gh api`, checking CI before merge, or bumping a submodule pin. Covers Conventional branch/PR-title conventions, Co-Authored-By trailer + ๐ค footer, squash+delete merge, CLEAN-before-merge, `gh secret set` without --body, `git update-index` submodule bumps, the --no-verify rule. Does NOT cover pure local git, diff-vs-commit verification (โ pr-diff-verification), security repo settings (โ apple-public-repo-security), worktree conflicts (โ subagent-conflict-detection), plugin distribution (โ claude-skill-plugin-packaging). |
GitHub Contribution Workflow
The gh-CLI contribution loop for an agent acting on a GitHub repo: branch โ
commit โ PR โ CI โ merge, plus issues, GitHub-side file ops, repo secrets, and
contribution-flow repo settings. Encodes conventions that keep an agent's
contributions reviewable and consistent. Tool-agnostic in spirit; concrete
commands are gh + git.
When to invoke
- Opening or merging a PR; opening or commenting on an issue.
- Creating or editing a file through GitHub (API / web flow) rather than a local clone.
- Setting a repo secret or configuring contribution-flow repo settings.
- Checking CI status before a merge; bumping a submodule pin.
- User says "open a PR / issue", "merge this", "set the secret", "configure the repo".
Scope โ what this does NOT own (route to sibling)
- Verifying the diff matches the commit's claims before push/PR โ
pr-diff-verification.
- Security repo settings (Secret Scanning, push protection, gitleaks,
.gitignore baseline) โ apple-public-repo-security.
- Parallel-session / submodule worktree conflicts โ
subagent-conflict-detection.
- Distributing or installing skill plugins (marketplace, depth-1 rule) โ
claude-skill-plugin-packaging.
- Pure local git with no GitHub surface โ out of scope.
Intent โ command
| Intent | Command |
|---|
| Open a PR | gh pr create --title "<conventional title>" --body "<body + ๐ค footer>" |
| Check CI before merge | gh pr checks <n> --repo <o/r> ; gh pr view <n> --json mergeStateStatus |
| Merge a PR | gh pr merge <n> --squash --delete-branch (only when status is CLEAN) |
| Open an issue | gh issue create --title "<title>" --body "<body>" |
| Comment on an issue | gh issue comment <n> --body "<text>" |
| Create/edit a file via GitHub | gh api -X PUT repos/<o/r>/contents/<path> -f message=โฆ -f content=$(base64) โฆ (no local clone needed) |
| Set a repo secret | gh secret set <NAME> --repo <o/r> (interactive paste; see Conventions) |
| List secrets | gh secret list --repo <o/r> (names only; values are write-only) |
| Configure merge / branch protection | gh api -X PATCH repos/<o/r> -F allow_squash_merge=true -F delete_branch_on_merge=true ; gh api -X PUT repos/<o/r>/branches/<b>/protection โฆ |
Conventions
- Branch names use Conventional prefixes:
feat/ fix/ chore/ docs/ ci/ refactor/ test/.
- PR titles follow Conventional Commits (some repos enforce this with a CI gate โ e.g. a "Validate PR title" check; a non-conforming title fails the PR).
- Commit trailer: end commit messages with the agreed
Co-Authored-By: trailer. PR body: end with the ๐ค footer.
- Merge:
--squash --delete-branch. Never merge unless gh pr checks / mergeStateStatus is CLEAN. BLOCKED is usually just pending required checks, not a failure โ poll until they finish, don't force-merge.
- Secrets:
gh secret set <NAME> without --body โ the interactive prompt keeps the value out of shell history. Never gh secret set X --body "$TOKEN". Verify presence (not value) with gh secret list.
- Submodule pin bump: set the gitlink surgically with
git update-index --cacheinfo 160000,<commit-sha>,<submodule-path> โ no submodule checkout needed (works in a fresh worktree). Confirm the target SHA is pushed/tag-reachable on the submodule's remote first (git ls-remote --tags <url> <tag>).
--no-verify: allowed ONLY for a commit with no code and no secrets (a submodule-pin bump, a .gitmodules/config-only change) when the repo's pre-commit gate is heavy and times out. Never for code or content commits โ those must pass the hooks.- Shared repo / submodule: edit via an isolated worktree branched from
origin/main + PR, never in place โ see subagent-conflict-detection.
Repo settings (contribution-flow only)
This skill owns the contribution-flow repo config: merge-button policy
(allow_squash_merge, delete_branch_on_merge), branch protection requiring CI,
required status checks, and labels. Security settings (Secret Scanning, push
protection) are owned by apple-public-repo-security โ set them there, not here.
Common Mistakes
- Merging on a non-CLEAN status โ treating
BLOCKED (pending checks) as a failure, or force-merging past a real red check. Poll; merge only on CLEAN.
gh secret set --body "$TOKEN" โ leaks the token into shell history. Use the interactive prompt.- Non-Conventional PR title โ fails a repo's title-lint gate; the PR can't merge.
- Editing a shared repo / submodule in place โ two writers clobber each other; use a worktree + PR.
--no-verify on a code/content commit โ bypasses the gate that protects the repo. Reserve it for no-code/no-secret commits only.- Hand-editing a submodule's checked-out files from the parent repo โ bump the pin instead (
git update-index --cacheinfo), and land the submodule's own change via its own PR.
- Duplicating a sibling's job โ re-doing diff verification, security settings, or worktree conflict checks here instead of routing to the owning skill.
Review Checklist
Related skills
pr-diff-verification โ verify git show --stat HEAD matches the commit's claims before push/PR.apple-public-repo-security โ security repo settings + secret-leak prevention.subagent-conflict-detection โ worktree + PR flow for parallel sessions / submodules.claude-skill-plugin-packaging โ distributing/installing skill plugins.
