From agent-almanac
Discovers GraphQL schemas via introspection, constructs queries and mutations, and executes them from the command line using gh api or curl, with jq-based response parsing.
How this skill is triggered — by the user, by Claude, or both
Slash command
/agent-almanac:use-graphql-apiThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Discover, construct, execute, and chain GraphQL operations from the command line.
Discover, construct, execute, and chain GraphQL operations from the command line.
github)gh CLI auth for GitHub)Determine available types, fields, queries, and mutations.
For GitHub:
# List available query fields
gh api graphql -f query='{ __schema { queryType { fields { name description } } } }' \
| jq '.data.__schema.queryType.fields[] | {name, description}'
# List available mutation fields
gh api graphql -f query='{ __schema { mutationType { fields { name description } } } }' \
| jq '.data.__schema.mutationType.fields[] | {name, description}'
# Inspect a specific type
gh api graphql -f query='{
__type(name: "Repository") {
fields { name type { name kind ofType { name } } }
}
}' | jq '.data.__type.fields[] | {name, type: .type.name // .type.ofType.name}'
For generic endpoints:
# Full introspection query via curl
curl -s -X POST https://api.example.com/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{"query":"{ __schema { types { name kind fields { name } } } }"}' \
| jq '.data.__schema.types[] | select(.kind == "OBJECT") | {name, fields: [.fields[].name]}'
Expected: JSON output listing available types, fields, or mutations. The schema response confirms the endpoint is reachable and the auth token is valid.
On failure:
401 Unauthorized — verify the token; for GitHub, run gh auth statusCannot query field — the endpoint may disable introspection; consult its documentation insteadDetermine whether your task requires a query (read), mutation (write), or subscription (stream).
| Intent | Operation | Example |
|---|---|---|
| Fetch data | query | Get repository details, list discussions |
| Create/update/delete | mutation | Create a discussion, add a comment |
| Real-time updates | subscription | Watch for new issues (rare in CLI) |
For GitHub-specific operations, consult the GitHub GraphQL API docs.
# Quick check: does the mutation exist?
gh api graphql -f query='{ __schema { mutationType { fields { name } } } }' \
| jq '.data.__schema.mutationType.fields[].name' | grep -i "discussion"
Expected: Clear identification of whether a query or mutation is needed, plus the exact operation name (e.g., createDiscussion, repository).
On failure:
Build the GraphQL query or mutation with fields, arguments, and variables.
Query example — fetch a repository's discussion categories:
gh api graphql -f query='
query($owner: String!, $repo: String!) {
repository(owner: $owner, name: $repo) {
discussionCategories(first: 10) {
nodes { id name }
}
}
}
' -f owner="OWNER" -f repo="REPO" | jq '.data.repository.discussionCategories.nodes'
Mutation example — create a GitHub Discussion:
gh api graphql -f query='
mutation($repoId: ID!, $categoryId: ID!, $title: String!, $body: String!) {
createDiscussion(input: {
repositoryId: $repoId,
categoryId: $categoryId,
title: $title,
body: $body
}) {
discussion { url number }
}
}
' -f repoId="$REPO_ID" -f categoryId="$CAT_ID" \
-f title="My Discussion" -f body="Discussion body here"
Key construction rules:
$var: Type!) instead of inline values for reusabilityfirst: N with nodes for paginated connectionsid to every object selection — you will need it for chainingExpected: A syntactically valid GraphQL operation with appropriate variables, field selections, and pagination parameters.
On failure:
ID! vs String!)Run the operation and capture the response.
GitHub — using gh api graphql:
# Simple query
gh api graphql -f query='{ viewer { login } }'
# With variables
gh api graphql \
-f query='query($owner: String!, $repo: String!) {
repository(owner: $owner, name: $repo) { id name }
}' \
-f owner="octocat" -f repo="Hello-World"
# With jq post-processing
REPO_ID=$(gh api graphql \
-f query='query($owner: String!, $repo: String!) {
repository(owner: $owner, name: $repo) { id }
}' \
-f owner="OWNER" -f repo="REPO" \
--jq '.data.repository.id')
Generic endpoint — using curl:
curl -s -X POST "$GRAPHQL_ENDPOINT" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "$(jq -n \
--arg query 'query { users { id name } }' \
'{query: $query}'
)"
Expected: A JSON response with a data key containing the requested fields, or an errors array if the operation failed.
On failure:
errors array in response — read the message; common causes are missing permissions, invalid IDs, or rate limitsdata — the query matched no records; verify input valuesgh auth status and add scopes with gh auth refresh -s scopeExtract the data you need from the JSON response.
# Extract a single value
gh api graphql -f query='{ viewer { login } }' --jq '.data.viewer.login'
# Extract from a list
gh api graphql -f query='
query($owner: String!, $repo: String!) {
repository(owner: $owner, name: $repo) {
issues(first: 5, states: OPEN) {
nodes { number title }
}
}
}
' -f owner="OWNER" -f repo="REPO" \
--jq '.data.repository.issues.nodes[] | "\(.number): \(.title)"'
# Assign to a variable for later use
CATEGORY_ID=$(gh api graphql -f query='
query($owner: String!, $repo: String!) {
repository(owner: $owner, name: $repo) {
discussionCategories(first: 20) {
nodes { id name }
}
}
}
' -f owner="OWNER" -f repo="REPO" \
--jq '.data.repository.discussionCategories.nodes[] | select(.name == "Show and Tell") | .id')
Expected: Clean, extracted values ready for display or assignment to shell variables.
On failure:
jq returns null — the field path is wrong; pipe raw JSON to jq . first to inspect structureselect() filter or | first-r to jq for raw string outputUse output from one operation as input to the next.
# Step A: Get the repository ID
REPO_ID=$(gh api graphql \
-f query='query($owner: String!, $repo: String!) {
repository(owner: $owner, name: $repo) { id }
}' \
-f owner="$OWNER" -f repo="$REPO" \
--jq '.data.repository.id')
# Step B: Get the discussion category ID
CAT_ID=$(gh api graphql \
-f query='query($owner: String!, $repo: String!) {
repository(owner: $owner, name: $repo) {
discussionCategories(first: 20) {
nodes { id name }
}
}
}' \
-f owner="$OWNER" -f repo="$REPO" \
--jq '.data.repository.discussionCategories.nodes[]
| select(.name == "Show and Tell") | .id')
# Step C: Create the discussion using both IDs
RESULT=$(gh api graphql \
-f query='mutation($repoId: ID!, $catId: ID!, $title: String!, $body: String!) {
createDiscussion(input: {
repositoryId: $repoId,
categoryId: $catId,
title: $title,
body: $body
}) {
discussion { url number }
}
}' \
-f repoId="$REPO_ID" -f catId="$CAT_ID" \
-f title="$TITLE" -f body="$BODY" \
--jq '.data.createDiscussion.discussion')
echo "Created: $(echo "$RESULT" | jq -r '.url')"
Pattern: Always extract id fields in earlier queries so they can be passed as ID! variables to subsequent mutations.
Expected: A multi-step workflow where each call succeeds and IDs flow correctly between operations.
On failure:
set -e and check each intermediate valueR_kgDO...); never construct them manuallysleep 1 between calls or batch queries using aliasesdata keys without errors| Pitfall | Prevention |
|---|---|
Forgetting ! on required variable types | Always check schema for nullability; most input fields are non-null (!) |
| Using REST IDs in GraphQL | GraphQL uses opaque node IDs; fetch them via GraphQL, not REST |
| Not paginating large result sets | Use first/after with pageInfo { hasNextPage endCursor } |
| Hardcoding IDs instead of querying them | IDs differ between environments; always query dynamically |
Ignoring the errors array | Check for errors even when data is present — partial errors are possible |
| Shell quoting issues with nested JSON | Use --jq flag with gh or pipe through jq separately |
npx claudepluginhub pjt222/agent-almanacGuides writing GraphQL operations (queries, mutations, subscriptions, fragments) with best practices for naming, variables, directives, and data fetching patterns.
GitHub CLI operations via `gh` for issues, PRs, Actions, releases, and REST/GraphQL API with `--json`/`--jq` parsing.
Orchestrates GitHub REST v3 and GraphQL v4 API access, routing to resources for authentication, repos, issues/PRs, workflows, security, search, and more. Use for integrations and automation.