github-administration

name	github-administration
description	Technical guidance for GitHub issue and PR administration via gh, including command safety, quoting, verification, and recovery.

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.