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

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

1. 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.
2. `gh secret set --body "$TOKEN"` — leaks the token into shell history. Use the interactive prompt.
3. Non-Conventional PR title — fails a repo's title-lint gate; the PR can't merge.
4. Editing a shared repo / submodule in place — two writers clobber each other; use a worktree + PR.
5. `--no-verify` on a code/content commit — bypasses the gate that protects the repo. Reserve it for no-code/no-secret commits only.
6. 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.
7. 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

• [ ] Branch name uses a Conventional prefix; PR title is Conventional Commits.
• [ ] Commit carries the Co-Authored-By: trailer; PR body ends with the 🤖 footer.
• [ ] gh pr checks is CLEAN before merge; merged with --squash --delete-branch.
• [ ] Any secret was set via interactive gh secret set (no --body); verified with gh secret list.
• [ ] A submodule bump used git update-index --cacheinfo against a remote-reachable SHA.
• [ ] --no-verify used only on a no-code/no-secret commit, with the reason stated.
• [ ] Shared-repo/submodule edits went through a worktree + PR.
• [ ] Nothing here duplicates a sibling skill's scope.

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.