agentleFS
Sign inStart free
Mathews-TomMathews-Tom/armory/skills/github/SKILL.md

github

Skill340 starsChanged 7 months agoMITView on GitHub

GitHub CLI operations via `gh` for issues, PRs, Actions, releases, and REST/GraphQL API with `--json`/`--jq` parsing. Triggers on: "create an issue", "submit a PR", "check CI status", "why did CI fail", "merge a PR", or pasted GitHub URLs.

  • Installs packages

We split this skill into the rules it gives an agent

4 rules. 0 are common, 1 is distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 143 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    All GitHub operations use the gh CLI.

    line 13
  2. Distinctive:

    Add missing scopes without re-authenticating from scratch:

    line 46
  3. Very specific:

    Prefer higher-level commands over raw API: Use gh issue create instead of gh api repos/.../issues -X POST.

    line 106
  4. Very specific:

    Use --repo consistently when outside a git directory: Never rely on implicit repo detection in scripts or CI environments.

    line 107

“Common” is measured: kept by at least 6 in 10 of the 143 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

GitHub

All GitHub operations use the gh CLI. Prefer --json with --jq for structured, parseable output. Use --repo owner/repo when not inside a git repository with a configured remote. Use --web to open any resource in the browser.

Prerequisites and Auth

Installation

PlatformCommand
macOSbrew install gh
Debian/Ubuntusudo apt install gh
Windowswinget install GitHub.cli

Authentication

gh auth login           # interactive OAuth login
gh auth status          # check current auth and active account

Required OAuth Scopes

ScopeGrants Access To
repoPrivate repos, issues, PRs, commits, status
read:orgOrg membership, team listing
workflowTrigger and manage GitHub Actions workflows
gistCreate and manage gists
delete_repoDelete repositories (not granted by default)
admin:orgManage org settings, teams, members
projectRead/write access to ProjectV2 boards

Add missing scopes without re-authenticating from scratch:

gh auth refresh --scopes repo,read:org,workflow

Reference Routing

User intentLoad
Create/list/view/edit/close issues, add commentsreferences/issues.md
Create/list/view/review/merge/edit/close pull requestsreferences/pull-requests.md
List runs, view logs, trigger/rerun/watch workflows, artifactsreferences/ci-actions.md
Create/fork/clone/view/edit/archive/delete repositoriesreferences/repos.md
Create/list/view/edit/upload/delete releasesreferences/releases.md
Search repos, issues, PRs, code, commitsreferences/search.md
Raw REST/GraphQL via gh api, pagination, rate limitreferences/api.md
GraphQL cost model, bulk queries, mutations, rate limitsreferences/graphql-queries.md
Multi-step workflow recipes (PR lifecycle, CI triage, releases)references/automation-workflows.md
Create/list/view/edit/delete gistsreferences/gists.md
List orgs, teams, membersreferences/orgs.md

Workflow Pattern

  1. Identify user intent from the routing table above.
  2. Load the matching references/<file>.md for command syntax and examples.
  3. Execute the gh command with --repo owner/repo and --json/--jq as needed.
  4. On error, consult the Error Handling table below.

Error Handling

ErrorCauseResolution
HTTP 401 UnauthorizedToken expired or revokedRun gh auth login to re-authenticate
HTTP 403 ForbiddenInsufficient permissions or rate limitedCheck gh auth status for scopes; check gh api rate_limit
HTTP 404 Not FoundRepo does not exist, is private without repo scope, or resource deletedVerify repo name; run gh auth refresh --scopes repo
HTTP 422 Unprocessable EntityInvalid payload — missing required field, validation errorCheck request body fields match API schema
HTTP 429 Too Many RequestsREST rate limit exceeded (5000 req/hr authenticated)Wait for X-RateLimit-Reset timestamp; reduce request frequency
GraphQL rate limit exceededUsed more than 5000 points/hrReduce query complexity or wait; see references/graphql-queries.md
"no git remotes found"Running gh outside a git repo without --repoAdd --repo owner/repo to the command
Insufficient OAuth scopesToken lacks required scope for the operationRun gh auth refresh --scopes scope1,scope2
Duplicate issue/PR titleNot a real error — GitHub allows duplicates, but check before creatingSearch with gh issue list or gh pr list first
Archived repo blocks writesRepo is archived; all write operations failUnarchive with gh repo edit owner/repo --archived=false or use a different repo

Enable debug logging to see raw HTTP requests and responses:

GH_DEBUG=api gh pr list --repo owner/repo

Calibration Rules

  1. Prefer --json over parsing text output. Text output formats are unstable across gh versions. Always use --json field1,field2 to get machine-readable output.
  2. Use --jq to minimize output before processing. Filter at the source rather than piping large JSON blobs to external tools. --jq runs server-side and reduces data transferred.
  3. Prefer higher-level commands over raw API. Use gh issue create instead of gh api repos/.../issues -X POST. High-level commands handle auth, pagination, and error formatting automatically.
  4. Use --repo consistently when outside a git directory. Never rely on implicit repo detection in scripts or CI environments. Always pass --repo owner/repo explicitly.
  5. Use GraphQL only for nested or bulk data. For single-resource fetches and mutations with simple payloads, REST is faster to write, easier to debug, and predictable under rate limits.

Limitations

  • Network required — all gh commands require internet access; no offline mode.
  • GraphQL point budget — 5000 points/hr for authenticated users. Complex queries with high first/last values consume points faster. See references/graphql-queries.md.
  • Secrets are write-only — gh secret set works, but there is no gh secret get. Secret values cannot be retrieved after creation.
  • Org admin operations — managing org settings, teams, and SAML requires the admin:org scope, which is not granted by default.
  • Artifact retention — workflow artifacts are retained for 90 days by default. Expired artifacts cannot be downloaded.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free