| name | use-github |
| description | Reference for gh CLI commands—auth, repo context, GraphQL conventions. Workflow skills delegate here for shared mechanics. |
Use GitHub
Reference for shared gh CLI mechanics—auth, repo context, and GraphQL conventions. Workflow skills own their specific commands and delegate here for these common patterns.
Auth
gh needs required_permissions: ["full_network"].
gh auth status
If failed: Tell user gh auth login.
Repo Context
gh repo view --json owner,name
Extract owner.login and name — needed for REST and GraphQL API calls.
GraphQL API
Invocation Pattern
gh api graphql \
-f query="$(cat path/to/query.graphql)" \
-F owner=<owner> \
-F name=<repo> \
-F number=<number>
Pass each variable as its own -F flag (not a variables object). Use -f (lowercase) for string values and -F (uppercase) for typed values (integers, booleans).
Conventions for Query Templates
Each skill owns its own .graphql query files. Follow these conventions:
- Always include
pageInfo { hasNextPage endCursor } on paginated connections. If hasNextPage is true, tell the user that more results exist and offer three options: fetch the next page, fetch all remaining pages, or continue with the current page only.
- Include
databaseId on any node you will reference via the REST API (REST endpoints use integer IDs, not GraphQL node IDs).
- Include
createdAt on comments when ordering matters.
Pagination
When pageInfo.hasNextPage is true, fetch the next page by passing the endCursor value as the after argument on the connection:
gh api graphql \
-f query="$(cat path/to/query.graphql)" \
-F owner=<owner> \
-F name=<repo> \
-F number=<number> \
-f after=<end_cursor>
Query templates that support pagination should accept an optional $after: String variable and pass it to the connection (e.g. reviewThreads(first: 50, after: $after)). The $after is nullable so the first call works without it.
Merge results across pages before processing.
Error Handling
- Auth failure (401): Tell user
gh auth login.
- Rate limit (403 with rate limit headers): Report remaining reset time and suggest waiting.
- Not found (404 / null data): Report and abort the operation.
