GitHub Workflow Skill

Mechanics for GitHub Issue and PR operations using gh CLI. Agents decide when to use these operations and what content to include.

Authentication

All gh commands MUST be run through the authenticated wrapper script:

code

scripts/workflow/gh.sh <command> [args...]

The wrapper ensures a valid GitHub App token is available (generating and caching as needed), so there is no session-level token to manage or refresh. If the wrapper exits non-zero before reaching gh, authentication has failed — abort the operation.

Every gh command shown in this skill must be prefixed with scripts/workflow/gh.sh instead of bare gh. For example:

code

# Skill example says:
#   gh issue view 1
# You run:
#   scripts/workflow/gh.sh issue view 1

Issue Operations

Create

code

gh issue create --title "<title>" --body "<body>" --label "<label>" --label "<label>" ...

Issue body template: see references/templates.md § "Issue Body Template".

Read

code

gh issue view <number> --json number,title,body,labels,state,assignees,comments

Update

code

gh issue edit <number> --title "<title>" --body "<body>" --add-label "<label>" --remove-label "<label>"

For mutually exclusive label swaps, remove and add in a single command:

code

gh issue edit <number> --remove-label "status:in-progress" --add-label "status:review"

Close

code

gh issue close <number> --reason completed
gh issue close <number> --reason "not planned"

Closing is a GitHub state change -- no status label swap is needed.

Assign

code

gh issue edit <number> --add-assignee <username>
gh issue edit <number> --remove-assignee <username>

Comment

code

gh issue comment <number> --body "<comment>"
gh pr comment <number> --body "<comment>"

Comment templates (blocker, escalation): see references/templates.md.

PR Operations

Create

Build title in conventional commit format: <type>(<scope>): <description> Build body with Closes #<issueNumber>.

code

gh pr create --head <branch> --base <baseBranch> --title "<title>" --body "<body>"

Add --draft for draft PRs.

Read

Find PR linked to a task issue:

code

gh pr list --search "Closes #<N>" --json number,title,headRefName,url

View PR metadata:

code

gh pr view <number> --json number,title,body,state,isDraft,headRefName,baseRefName,files,reviewDecision,statusCheckRollup,reviews

View full diff:

code

gh pr diff <number>

Update

code

gh pr ready <number>
gh pr edit <number> --title "<title>" --body "<body>"

Merge

code

gh pr merge <number> --squash --delete-branch

Use --merge, --squash, or --rebase for merge strategy.

Review

code

gh pr review <number> --comment --body "<comment>"

All PR reviews use --comment because the workflow operates under a single GitHub App identity, and GitHub prevents self-review (--approve / --request-changes) on self-authored PRs. The canonical verdict is the task issue's status label (status:approved or status:needs-changes), not the GitHub review state.

CI Status

code

gh pr checks <number> --json name,state,conclusion

Label Management

Label definitions are maintained by docs/specs/workflow/script-label-setup.md.

Rules: see references/labels.md for mutually exclusive categories and valid status transitions.

Key rules:

•Mutually exclusive categories (type, status, priority): exactly one label per category
•Status transitions must follow the valid transition table
•Swap labels atomically: --remove-label "old" --add-label "new" in one command

Query Patterns

By status

code

gh issue list --label "task:implement" --label "status:<status>" --state open --limit 100 --json number,title,labels,assignees

By priority

code

gh issue list --label "task:implement" --label "priority:<level>" --state open --limit 100 --json number,title,labels,assignees

Refinement tasks

code

gh issue list --label "task:refinement" --state open --limit 100 --json number,title,labels,body

All open tasks

code

gh issue list --label "task:implement" --state open --limit 100 --json number,title,labels,assignees

By spec reference

code

gh issue list --state open --search "in:body docs/specs/<name>.md" --limit 100 --json number,title,labels,body

Dependencies

•gh CLI on PATH
•Authenticated wrapper: scripts/workflow/gh.sh (spec: docs/specs/workflow/github-cli.md)
•Labels created per docs/specs/workflow/script-label-setup.md
•Development protocol: docs/specs/workflow/workflow.md