Agent Skills: gh-api

Use gh pr create --draft and gh pr ready [--undo] for draft status. Review comments belong to gh-pr-review. Consult gh api --help for request flags; the global explicit-method rule applies to REST and GraphQL alike.

Output Filtering

Mutation responses (POST, PATCH, PUT, DELETE) return the full object by default, which wastes context tokens. Always pipe through --jq to extract only the fields you need.

General pattern

For any mutation, append --jq selecting the fields the caller actually needs. Typical minimal set: {id, body, html_url}. Add state, title, or number when relevant.

Failed CI jobs

Use gh run, not gh api .../actions/jobs/<id>/logs; the raw endpoint refuses ANSI output.

1. gh run view <run> lists failed jobs and steps, plus annotations with the offending paths (job: path#line). This often answers the failure without logs.
2. gh run view <run> --job <id> --log-failed prints the failed steps' log.
3. If that returns HTTP 5xx, read the whole job log and strip color codes and the job/step/timestamp prefix:

gh run view <run> --job <id> --log \
  | perl -pe 's/(\e|\^\[)\[[0-9;]*m//g; s/^[^\t]*\t[^\t]*\t\S+ //' | rg -n -A5 '##\[error\]'

Discussions (GraphQL)

GraphQL queries use POST too; HTTP method alone does not classify GraphQL operation semantics. Retrieve only needed fields and paginate when completeness matters:

gh api --method POST graphql -F owner=OWNER -F repo=REPO -f query='query(
  $owner: String!, $repo: String!
) {
  repository(owner: $owner, name: $repo) {
    discussions(first: 10) { nodes { number title url } }
  }
}'