Github

GitHub

GitHub operations via gh.

Router

Safety Rules

• Confirm before any state-changing operation (create/edit/delete/merge/close).
• Never upload secrets as assets.
• Treat gh api as powerful: confirm before any write operation.
• Never delete or move published releases/tags unless explicitly requested.
• When creating PRs, always set an assignee: default to @me unless the user explicitly names someone else.
• When creating PRs, apply relevant existing labels when possible; auto-pick from PR context (title/body/branch + changed paths) and avoid creating new labels unless truly necessary.
• If labels must be created, retrieve existing labels first (gh label list), propose the minimal set consistent with repo naming, and confirm before gh label create.

Confirmation Policy

Read-only commands are always OK.

Require confirmation:

• gh issue create/edit/close/reopen/delete
• gh pr create/edit/close/merge/review
• gh repo create/edit/rename/archive/delete/sync
• gh release create/edit/delete, gh release upload, gh release delete-asset
• gh secret set/delete, gh variable set/delete
• gh run rerun, gh run cancel
• gh api calls that mutate state (POST/PATCH/PUT/DELETE)

Read-Only (No Confirmation Needed)

gh auth status
gh release list
gh release view <tag>
gh release view <tag> --web
gh help
gh pr checks <number> --json ...
gh run list --branch <branch> --json ...
gh run view <run-id>
gh run view <run-id> --log-failed

GitHub

GitHub skill using GitHub CLI (gh): repos, issues, pull requests, Actions, releases, and more.

Quick Start

• Home/router: github/SKILL.md
• Auth: github/references/auth.md
• Repos: github/references/repo.md
• Issues: github/references/issue.md
• PRs: github/references/pr.md
• Actions: github/references/actions.md
• Releases: github/references/release.md
• Release strategy + naming + preview guidance: github/references/release-strategy.md
• Advanced API: github/references/api.md

Release deep dives:

• Create: github/references/release-create.md
• Manage: github/references/release-manage.md
• Assets: github/references/release-assets.md

Use github/references/release-strategy.md for title quality, dominant-change selection, release-note opening lines, and GitHub preview / OG-image considerations.

Requirements

• gh (GitHub CLI)
• Authenticated session: gh auth login

Install

npx skills add bntvllnt/agent-skills --skill github

Manual install (download this folder only):

• Copy the github/ folder into your agent's skills directory.
• Ensure the folder name is github and includes SKILL.md.

Actions (gh workflow / gh run)

List workflows:

gh workflow list

View a workflow:

gh workflow view <workflow>

Run a workflow (confirm first):

gh workflow run <workflow>

List runs:

gh run list

View a run:

gh run view <run-id>

Download artifacts:

gh run download <run-id>

Rerun or cancel (confirm first):

gh run rerun <run-id>
gh run cancel <run-id>

API (gh api)

gh api is powerful and can mutate GitHub state. Confirm before any write.

Read-only example

gh api repos/OWNER/REPO

Notes

• Prefer the dedicated gh subcommands (issue/pr/release/repo) when they exist.
• Use -R OWNER/REPO with other commands instead of hardcoding URLs.

Authentication (gh)

Goal: ensure gh is authenticated for the correct host/account.

Read-only checks

gh auth status

Interactive login

gh auth login

Notes (from the official gh docs):

• Default host is github.com; enterprise hosts can be selected with --hostname.
• For headless/automation, gh can use tokens from environment variables (see gh help environment).

Example: authenticate to a specific host:

gh auth login --hostname enterprise.internal

Safety

• Never paste tokens into logs or commit them.
• Prefer gh auth login browser flow when possible.

CI Monitor

Monitor CI check status for a PR or branch with live polling.

Trigger

ci, monitor ci, check ci, ci status, watch ci

Workflow

1. Resolve Target

Determine what to monitor. Try in order:

1. User provided PR number → use it 2. User provided branch → find latest run for that branch 3. Neither → auto-detect current branch, then find its PR or latest run

# Current branch:
git branch --show-current

# Find PR for current branch:
gh pr view --json number,headRefName --jq '.number'

# If PR exists:
gh pr checks <number> --json name,bucket,startedAt,completedAt,link,workflow

# If no PR (branch-only):
gh run list --branch <branch> --limit 5 --json status,conclusion,name,databaseId,url

2. Poll Loop

Poll every 30s. Max duration: 10 minutes. Each iteration: fetch status, display table.

┌─────────────────────────────────────────────────────┐
│                CI STATUS — PR #42                    │
├─────────────────────────────────────────────────────┤
│  Branch:  feature/auth-middleware                    │
│  PR:      https://github.com/owner/repo/pull/42     │
│  Poll:    30s interval | 1m30s elapsed | 10m max    │
└─────────────────────────────────────────────────────┘

 Check            Status        Duration
───────────────  ────────────  ────────
 lint             PASS          12s
 typecheck        PASS          28s
 test-unit        IN_PROGRESS   1m02s
 test-e2e         QUEUED        —

Links:
  lint:       <link field from gh pr checks>
  typecheck:  <link field from gh pr checks>
  test-unit:  <link field from gh pr checks>
  test-e2e:   <link field from gh pr checks>

Status: QUEUED | IN_PROGRESS | PASS | FAIL | SKIPPED

URL Rules

All URLs MUST be real values from gh JSON output. Never fabricate or construct URLs.

3. Exit Conditions

4. Final Summary

On success:

CI RESULT: PASS — 4/4 checks green (2m14s)
  PR: https://github.com/owner/repo/pull/42

On failure — list each failed check with its link value, then auto-fetch logs:

CI RESULT: FAIL — 1/4 checks failed

  FAILED:
   test-e2e  <link value from gh pr checks>

  Logs (last 50 lines of failed output):
  ─────────────────────────────────────
  [truncated output from gh run view <run-id> --log-failed]
  ─────────────────────────────────────

Auto-fetch failed logs via gh run view <run-id> --log-failed.

5. Retry (Confirm First)

Only if user asks. This is a write operation — confirm before running.

gh run rerun <run-id>

Then resume polling loop.

Defaults

Read-Only (No Confirmation)

gh pr checks <number> --json ...
gh run list --branch <branch> --json ...
gh run view <run-id>
gh run view <run-id> --log-failed

Write (Confirm First)

gh run rerun <run-id>
gh run cancel <run-id>

CLI Help (gh)

Goal: show the official CLI help for a command.

These commands are read-only.

gh help
gh help release
gh help auth

Per-command flag help:

gh release create --help
gh release edit --help
gh release upload --help
gh release download --help
gh release verify --help
gh auth login --help

Config (gh config)

List configuration:

gh config list

Get/set (confirm first for set):

gh config get <key>
gh config set <key> <value>

Extensions (gh extension)

List extensions:

gh extension list

Browse available extensions:

gh extension browse

Install/remove (confirm first):

gh extension install OWNER/REPO
gh extension remove <name>

Gists (gh gist)

Create:

gh gist create <file>

List:

gh gist list

View:

gh gist view <id>
gh gist view <id> --web

Issues (gh issue)

List issues:

gh issue list

View an issue:

gh issue view <number>
gh issue view <number> --web

Create:

gh issue create

Comment:

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

Close / reopen (confirm first):

gh issue close <number>
gh issue reopen <number>

PR Dashboard

Overview of all open PRs with status classification and next actions.

Trigger

pr dashboard, pr overview, open prs, my prs, pr status

Workflow

1. Fetch Open PRs

# Default: current user's PRs
gh pr list --state open --author "@me" \
  --json number,title,state,isDraft,author,labels,reviewRequests,reviewDecision,statusCheckRollup,updatedAt,comments,url

# All authors (user says "all prs" or "team prs"):
gh pr list --state open \
  --json number,title,state,isDraft,author,labels,reviewRequests,reviewDecision,statusCheckRollup,updatedAt,comments,url

2. Classify Each PR

Priority order (show highest priority classification per PR):

3. Output — Summary + Table

┌────────────────────────────────────────────────────┐
│                  PR DASHBOARD                       │
├────────────────────────────────────────────────────┤
│  Repo:   owner/repo                                │
│  Total:  5 open (1 ready, 1 failing, 1 review,    │
│          1 draft, 1 stale)                          │
└────────────────────────────────────────────────────┘

 PR     Title                   Status    CI     Age  Action
─────  ──────────────────────  ────────  ─────  ───  ─────────────────────
 #27    Add caching             Ready     PASS   1d   Merge now
 #38    Fix rate limiter        Approved  FAIL   5d   Fix CI then merge
 #29    Refactor auth           Changes   PASS   3d   Address feedback
 #42    Add auth middleware     Review    PASS   2d   Request reviewer
 #35    Update docs             Draft     —      8d   Stale — finish or close

Links:
  #27  <url from gh pr list>
  #38  <url from gh pr list>
  #29  <url from gh pr list>
  #42  <url from gh pr list>
  #35  <url from gh pr list>

Table sorted by priority (most actionable at top).

4. Per-PR Detail

For PRs with CI failures, fetch check details to get clickable failure links:

gh pr checks <number> --json name,state,link,bucket

Show for each PR that needs action:

#42 — Add auth middleware
  URL:      <url from gh pr list>
  Author:   @me
  Labels:   enhancement, backend
  Reviews:  0/1 required
  CI:       3/3 passed
  Updated:  2 days ago
  Action:   Request review from @teammate

#38 — Fix rate limiter
  URL:      <url from gh pr list>
  Author:   @me
  Labels:   bug
  Reviews:  1/1 approved
  CI:       2/4 failed
  Failed:   test-e2e  <link from gh pr checks>
            lint      <link from gh pr checks>
  Updated:  5 days ago
  Action:   Fix CI, then merge

5. Action Map

URL Rules

All URLs MUST be real values from gh JSON output. Never fabricate or construct URLs.

Flags

Read-Only (No Confirmation)

gh pr list --state open --json ...
gh pr checks <number> --json ...
gh pr view <number> --json ...

Write (Confirm First)

gh pr merge <number>
gh pr close <number>
gh pr ready <number>
gh pr edit <number> --add-reviewer <user>

Pull Requests (gh pr)

List PRs:

gh pr list

View PR:

gh pr view <number>
gh pr view <number> --comments
gh pr view <number> --web

Create PR (always assign; label when possible):

Prefer a two-step flow so PR creation never fails if a label doesn't exist:

gh pr create --assignee "@me"
gh pr edit --add-label "<label1>,<label2>"

If the user explicitly names a different assignee (e.g. @alice), use that instead of @me:

gh pr create --assignee "@alice"

If the user doesn't specify labels, auto-pick from existing repo labels using PR context (title/body/branch + changed paths).

Heuristics (best-effort; don't block PR creation):

• Prefer labels that match touched areas (e.g. docs, backend, frontend, ci, infra, api) or package/app names.
• If the repo uses standard labels, map PR intent:
• bugfix -> bug
• docs-only -> documentation
• feature -> enhancement
• If it's ambiguous, add fewer labels rather than the wrong ones.

Retrieve existing labels:

gh label list --limit 200
gh label list --search "docs" --limit 200
gh label list --search "backend" --limit 200

If you must create new labels (confirm first), keep it minimal and consistent with the repo's naming style:

gh label create "<label>" --description "<description>" --color 0E8A16

Then apply labels to the PR:

gh pr edit --add-label "<label1>,<label2>"

Checks:

gh pr checks

Review / comment:

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

Merge (confirm first):

gh pr merge <number>

Auto-Monitor CI After PR Creation

After gh pr create succeeds, check if repo has CI workflows:

gh workflow list

If workflows exist, ask the user:

CI detected. Monitor checks? [Y/n]

If yes, run the CI Monitor workflow (ci status for the new PR number). If no, return control immediately.

Projects (gh project)

List projects:

gh project list

View a project:

gh project view <number>

Create a project (confirm first):

gh project create

Release Assets (upload/download/verify)

Requires confirmation for upload/delete-asset.

Upload assets

Upload a file:

gh release upload vX.Y.Z <file>

Overwrite existing asset name:

gh release upload vX.Y.Z <file> --clobber

Add a display label by appending #:

gh release upload vX.Y.Z "dist/app.zip#macOS build"

Delete an asset (confirm first)

gh release delete-asset vX.Y.Z <asset-name>

Download assets

All assets from a tag:

gh release download vX.Y.Z

Latest release by pattern:

gh release download --pattern '*.tgz'

Download source archive:

gh release download vX.Y.Z --archive=zip

Verify release attestation

If your repo uses GitHub release attestations:

gh release verify vX.Y.Z

JSON output:

gh release verify vX.Y.Z --format json

Create Release (gh)

Goal: create a GitHub Release for a specific tag with correct notes and safe defaults.

MANDATORY: Follow `release-strategy.md` for versioning, title format, and description format. Never publish a release without the enforced description structure (summary + New Files table + Changed Files table).

Requires confirmation before running gh release create.

Important Safety Fact

Per the official gh release create docs: if the tag does not exist yet, gh may create it automatically from the default branch.

Default safe behavior for this skill:

• Prefer creating the git tag first (outside this workflow), then create the release.
• Use --verify-tag to abort if the tag doesn't already exist in the remote.

Pre-flight (read-only)

gh auth status
gh release list

Create a release (recommended)

Generated notes:

gh release create vX.Y.Z --verify-tag --title "vX.Y.Z" --generate-notes

Custom notes:

gh release create vX.Y.Z --verify-tag --title "vX.Y.Z" --notes "<notes>"

Notes from annotated tag (or commit message if lightweight tag):

gh release create vX.Y.Z --verify-tag --notes-from-tag

Common options

• Pre-release:

gh release create vX.Y.Z --verify-tag --prerelease --generate-notes

• Draft (publish later):

gh release create vX.Y.Z --verify-tag --draft --generate-notes

• Fail when there are no new commits since last release:

gh release create vX.Y.Z --verify-tag --generate-notes --fail-on-no-commits

• Control "Latest":

gh release create vX.Y.Z --verify-tag --generate-notes --latest=false

• Create a discussion:

gh release create vX.Y.Z --verify-tag --generate-notes --discussion-category "General"

Different repository

Use -R / --repo to target a different repo:

gh release create vX.Y.Z --verify-tag --generate-notes -R OWNER/REPO

Verify

gh release view vX.Y.Z

Manage Releases (list/view/edit/delete)

List releases (read-only)

gh release list

Common filters:

gh release list --exclude-drafts
gh release list --exclude-pre-releases
gh release list --limit 50

View a release (read-only)

gh release view vX.Y.Z
gh release view vX.Y.Z --web

Edit a release (confirm first)

MANDATORY: When editing release descriptions, follow `release-strategy.md` format. Read actual git diffs to produce accurate file-level change descriptions.

Update notes from a file:

gh release edit vX.Y.Z --notes-file release-notes.md

Publish a draft:

gh release edit vX.Y.Z --draft=false

Set prerelease:

gh release edit vX.Y.Z --prerelease

Delete a release (confirm first)

gh release delete vX.Y.Z

If you explicitly want to also delete the tag:

gh release delete vX.Y.Z --cleanup-tag

Release Strategy (MANDATORY)

Strict release management. Every release must be well-documented, consistently formatted, and traceable to file-level changes.

Versioning: Semantic Versioning (SemVer)

Format: vMAJOR.MINOR.PATCH

Rules:

• Tag format: vX.Y.Z (always prefixed with v)
• Create git tag BEFORE creating GitHub release
• Use --verify-tag on every gh release create
• Never skip versions

Release Title Prerequisites (ENFORCED)

Before writing a release title, confirm all of these:

• Stable scope: the merged diff is settled; do not title from an outdated PR description
• Dominant change identified: pick the main user-facing change, not the most recent internal task
• Audience identified: know whether the release is mainly for users, contributors, or operators
• Title/body alignment: the first lines of the release notes reinforce the same story as the title
• Truthfulness: the title is strong but not inflated beyond what the release actually changed
• Social-card awareness: assume the title and opening lines may appear alone on GitHub release cards or preview images

Release Title Format (ENFORCED)

vX.Y.Z — {Short Description}

Examples:

• v1.0.0 — Analyze skill
• v1.13.1 — Code review, supercharged
• v1.14.0 — Portable review specs

Weak examples:

• v1.3.1 — GitHub PR Workflow Improvements
• v1.3.1 — Updates
• v1.3.1 — Misc fixes

Rules:

• Use em dash — (not - or –)
• Title ≤ 70 characters
• Lead with the dominant outcome, not the implementation detail
• Be specific enough that the reader can infer what changed in one glance
• Prefer user-facing capability over internal process wording
• Avoid filler like updates, improvements, misc, cleanup, refactors
• If two candidates exist, choose the one that better survives being seen without context on a release card

Practical title heuristic:

vX.Y.Z — {specific outcome}

Good:

• v1.13.1 — Code review, supercharged
• v0.8.0 — Faster local inference
• v2.4.0 — Rules discovery everywhere

Bad:

• v1.13.1 — Workflow changes
• v0.8.0 — Performance updates
• v2.4.0 — Internal improvements

Release Description Format (ENFORCED)

Every release description MUST follow this exact structure:

{1-3 sentence summary of what changed and why}

### New Files

| File | Description |
|------|-------------|
| `{path}` | {What this file is — purpose, key content} |

### Changed Files

| File | Change |
|------|--------|
| `{path}` | {What specifically changed — bold key changes, use → for before/after} |

### Summary

- {Bullet point per notable change — active voice, past tense, no period at end}

Section Rules

Writing Style

• Active voice, past tense: "Added rate limiting" not "Rate limiting was added"
• No periods at end of bullet points or table cells
• Bold key changes in Changed Files: **Action count**: 7 → 8
• Use `→` for before/after: old format → new format
• File paths in backticks: always wrap paths in ` ``
• No filler: no "various improvements", "minor updates", "miscellaneous changes"
• Every file listed must have a specific, meaningful description
• Group related changes when describing (e.g., "Updated routing table, references section, and output template links")

Opening Lines / Preview Rules

Assume the release title plus the opening summary / first bullets may be the only text visible in:

• GitHub release cards
• Open Graph preview images
• link unfurls in chat tools
• social post screenshots

Therefore:

• The opening summary must reinforce the title immediately
• The first bullet should restate the dominant change in concrete terms
• Do not lead with internal maintenance work if the release is mainly about a user-facing capability
• Do not bury the dominant change below less important items

Changed Files Detail Level by Bump

Release Description Generation Protocol

When creating or updating a release description, follow this exact process:

Step 1: Identify Changes

# For first release
git ls-tree -r --name-only vX.Y.Z

# For subsequent releases
git diff --stat vPREVIOUS..vX.Y.Z
git log --oneline vPREVIOUS..vX.Y.Z

Step 2: Analyze Each File

For every file in the diff:

1. Read the actual diff: git diff vPREVIOUS..vX.Y.Z -- path/to/file 2. Summarize what changed specifically (not "updated file") 3. For new files: describe purpose and key content 4. For changed files: describe what was added/removed/modified

Step 3: Write Description

Follow the enforced format above. No shortcuts.

Step 4: Verify

Before publishing, check:

• [ ] Title follows vX.Y.Z — {Description} format
• [ ] Title is specific, outcome-first, and brief
• [ ] Title matches the dominant user-facing change in the merged diff
• [ ] Summary paragraph is present and specific
• [ ] Opening lines reinforce the same story as the title
• [ ] Every new file is listed with description
• [ ] Every changed file is listed with specific change details
• [ ] No vague descriptions ("minor updates", "various fixes")
• [ ] File paths are in backticks
• [ ] Active voice, past tense throughout
• [ ] Key changes are bolded in Changed Files table

Batch Update Protocol

When updating descriptions for multiple releases at once:

1. Process releases in chronological order (oldest first) 2. Use git diff vPREVIOUS..vCURRENT for each pair 3. Read actual diffs — never guess what changed 4. Apply the same format to every release 5. Verify each before publishing

# Update a release
gh release edit vX.Y.Z --title "vX.Y.Z — {Title}" --notes "$(cat <<'EOF'
{description}
EOF
)"

Anti-Patterns (NEVER)

• NEVER use auto-generated notes without manual review and reformatting
• NEVER write "updated X" without saying WHAT changed in X
• NEVER skip files in the diff — every file gets documented
• NEVER use --generate-notes as the final description (use as starting point only)
• NEVER publish a release without the New Files / Changed Files tables
• NEVER mix description styles across releases — consistency is mandatory
• NEVER use passive voice ("was added", "has been updated")
• NEVER leave the description empty or use placeholder text

Sources

Format based on:

• Semantic Versioning 2.0.0
• Keep a Changelog
• GitHub Auto-Generated Release Notes
• GitHub Release Note Content Type

Releases (gh release)

Use this section as the entry point for release operations.

MANDATORY: Read `release-strategy.md` before creating or editing any release. It defines versioning rules, title format, dominant-change selection, description format, preview/OG-card guidance, and the generation protocol.

Read-only quick checks

gh release list
gh release view vX.Y.Z

Repos (gh repo)

Common repo operations.

Read-only:

gh repo view
gh repo view --web

Clone:

gh repo clone OWNER/REPO

Fork:

gh repo fork OWNER/REPO

Create:

gh repo create

Sync fork:

gh repo sync

Note: for operations that change repo settings (rename, delete, archive), confirm first.

Search (gh search)

Repo search:

gh search repos "<query>"

Issue search:

gh search issues "<query>"

PR search:

gh search prs "<query>"

Code search:

gh search code "<query>"

Secrets and Variables

Use these for GitHub Actions and repository configuration.

List:

gh secret list
gh variable list

Set (confirm first):

gh secret set NAME
gh variable set NAME

Delete (confirm first):

gh secret delete NAME
gh variable delete NAME

Safety:

• Never print secret values.
• Avoid using command history to pass secrets inline.