Github Administration

GitHub Administration Skill

Purpose

Use this skill whenever you interact with GitHub issues or pull requests through the gh CLI.

This skill is technical-only and focuses on execution mechanics:

• selecting and running the correct gh commands
• handling quoting safely
• applying metadata (assignee, labels)
• verifying outcomes and fixing command/result issues

Issue content design is out of scope here and belongs to github-issue-designer.

Mandatory Usage

Always use github-administration whenever you want to interact with a GitHub issue.

Pairing Rule

When an issue should be created or updated, use:

• github-issue-designer for issue content design
• github-administration for command execution via gh

Preflight

Before mutating issues/PRs:

gh api user --jq .login
gh repo view --json nameWithOwner
gh label list --json name --limit 100

Safe Command Rules

1. Prefer one mutation per command.
2. Always use --body-file for issue/comment/PR bodies (single-line or multi-line).
3. Use double quotes for arguments with spaces.
4. Verify immediately after create/edit/close operations.
5. Store temporary body files under a non-versioned workspace path (for this repo: .tmp/) and pass them via --body-file.
6. In persistent terminals, avoid heredoc for long multi-line bodies; write a temporary file first and pass it via --body-file.
7. Do not auto-assign newly created issues unless the navigator explicitly requests assignment at creation time.

Command Recipes

Create issue

mkdir -p .tmp
gh issue create --title "<title>" --body-file .tmp/issue.md --label <label> --assignee <login>

View/verify issue

gh issue view <number> --json number,title,assignees,labels,url

Edit issue

gh issue edit <number> --title "<new-title>" --body-file .tmp/issue-updated.md

Comment on issue

gh issue comment <number> --body-file .tmp/comment.md

Close issue

gh issue close <number> --comment "<closure note>"

Create PR linked to issue

git push origin <branch>
gh pr create --title "Fix #<issue>: ..." --body "...\n\nFixes #<issue>" --head <branch>

Troubleshooting

Label not found

Error: could not add label: '<label>' not found

Fix:

• choose an existing label from gh label list, or
• create the missing label in GitHub UI and retry.

PR push prompt appears

Cause: branch is not pushed.

Fix:

git push origin <branch>
gh pr create --head <branch> ...

Shell quoting breaks (dquote>)

Fix:

• reset shell or open a new terminal

Prevention:

• use --body-file for multiline input

Heredoc gets stuck (heredoc>)

Cause: unterminated or corrupted heredoc input in a persistent shell session.

Fix:

• abort and recover shell state
• avoid reusing heredoc for long content
• create the body in a temporary/workspace file and retry with --body-file

Post-action Checklist

After each mutation:

• verify issue/PR metadata and links
• correct mistakes immediately

Retrospective Requirement

After creating an issue and after closing a merged issue, run self-learning-skills retrospective automatically.