---
name: github-ghx
description: "Use first for GitHub work in a repo: checking PRs, unresolved review threads, reviews, comments, issues, labels, CI checks, workflow runs/logs, releases, merge readiness, or any GitHub API state. Prefer ghx over gh, gh api, GraphQL, or curl whenever a matching ghx capability exists. Use raw gh mainly for auth, clone/checkout, release asset upload, and long-running check watching."
---

# ghx CLI Skill

## Operating rule

For GitHub state or GitHub API work, check whether `ghx` has a matching capability before using `gh`, `gh api`, GraphQL, or curl.

When another GitHub workflow skill is also active, use that skill for the workflow and use `ghx` as the first-choice GitHub state surface inside it.

Do not replace an active workflow skill's sequencing, edits, or verification with this skill's examples; use `ghx` for the GitHub state calls and mutations that workflow requires.

For "current PR" requests, use `ghx run pr.list` first when a nearby open PR can be selected from repository context. Use raw `gh pr view --json number` only to discover a branch-specific PR number that `ghx` cannot infer, then return to `ghx` for PR state.

## Important rules

- Use `ghx chain` when you have 2+ **independent** operations — it is faster and avoids mid-sequence failures.
- Always use heredoc (`<<'EOF'`) for JSON input, never inline `--input '{...}'`.
- Omit owner/name only for the current checkout; pass explicit owner/name when targeting another repository.

ghx provides 70+ GitHub capabilities with structured JSON input/output. It batches operations into single GraphQL round-trips, making it faster than sequential `gh` or `gh api` calls.

## Resolving owner and name

Most repository-scoped capabilities accept `owner` and `name`. When running inside a git checkout, `ghx` fills missing `owner`/`name` from cached repo context derived from `origin`; provide explicit values only when targeting a different repository. If no repo context is available, ask the user.

## Authentication

ghx resolves tokens automatically (env vars `GITHUB_TOKEN`/`GH_TOKEN`, or `gh auth token`). No setup needed if `gh auth login` has been run.

## Capabilities

All available capabilities (`id - description [inputs]`, `?` = optional):

```
repo.view - Fetch repository metadata. [owner, name]
repo.labels.list - List repository labels. [owner, name, first?, after?]
repo.issue_types.list - List repository issue types. [owner, name, first?, after?]
issue.view - Fetch one issue by number. [owner, name, issueNumber]
issue.list - List repository issues. [owner, name, state?, first?, after?]
issue.comments.list - List comments for one issue. [owner, name, issueNumber, first, after?]
issue.create - Create a new issue. [owner, name, title, body?]
issue.update - Update issue title and/or body. [owner, name, issueNumber, title?, body?]
issue.close - Close an issue. [owner, name, issueNumber]
issue.reopen - Reopen a closed issue. [owner, name, issueNumber]
issue.delete - Delete an issue. [owner, name, issueNumber]
issue.labels.set - Replace issue labels. [owner, name, issueNumber, labels]
issue.labels.add - Add labels to an issue without removing existing labels. [owner, name, issueNumber, labels]
issue.labels.remove - Remove specific labels from an issue. [owner, name, issueNumber, labels]
issue.assignees.set - Replace issue assignees. [owner, name, issueNumber, assignees]
issue.assignees.add - Add assignees to an issue without replacing existing ones. [owner, name, issueNumber, assignees]
issue.assignees.remove - Remove specific assignees from an issue. [owner, name, issueNumber, assignees]
issue.milestone.set - Set issue milestone number or clear with null. [owner, name, issueNumber, milestoneNumber]
issue.milestone.clear - Remove the milestone from an issue. [owner, name, issueNumber]
issue.comments.create - Create an issue comment. [owner, name, issueNumber, body]
issue.relations.prs.list - List pull requests linked to an issue. [owner, name, issueNumber]
issue.relations.view - Get issue parent/children/blocking relations. [owner, name, issueNumber]
issue.relations.parent.set - Set an issue parent relation. [issueId, parentIssueId]
issue.relations.parent.remove - Remove an issue parent relation. [issueId]
issue.relations.blocked_by.add - Add a blocked-by relation for an issue. [issueId, blockedByIssueId]
issue.relations.blocked_by.remove - Remove a blocked-by relation for an issue. [issueId, blockedByIssueId]
pr.view - Fetch one pull request by number. [owner, name, prNumber, exclude?]
pr.list - List repository pull requests. [owner, name, state?, first?, after?]
pr.create - Create a pull request. [owner, name, title, head, base, body?, draft?]
pr.update - Update pull request metadata (title, body, draft status). [owner, name, prNumber, title?, body?, draft?]
pr.threads.list - List PR review threads. [owner, name, prNumber, first?, after?, unresolvedOnly? (default true), includeOutdated? default false]
pr.threads.reply - Reply to a PR review thread. [threadId, body]
pr.threads.resolve - Resolve a PR review thread. [threadId]
pr.threads.unresolve - Unresolve a PR review thread. [threadId]
pr.reviews.list - List PR reviews (state, author, body). Review-level only — use pr.threads.list for inline comments. [owner, name, prNumber, first?, after?]
pr.reviews.request - Request PR reviewers. [owner, name, prNumber, reviewers]
pr.reviews.submit - Submit a PR review (approve/request-changes/comment). Non-empty body required for COMMENT and REQUEST_CHANGES. [owner, name, prNumber, event, body?, comments?[path, body, line, side?, startLine?, startSide?]]
pr.reactions.list - List emoji reactions on the pull request itself. [owner, name, prNumber, reactorLogin?, content?]
pr.comments.reactions.list - List reactions on PR issue and review comments. [owner, name, prNumber, first?, after?, reactorLogin?, content?]
pr.diff.files - List changed files in a PR diff. [owner, name, prNumber, first?, after?]
pr.diff.view - View the unified diff for a PR. [owner, name, prNumber]
pr.checks.list - List PR check statuses with summary counts. [owner, name, prNumber, state?]
pr.checks.rerun.failed - Rerun failed PR workflow checks for a selected run. [owner, name, prNumber, runId]
pr.checks.rerun.all - Rerun all PR workflow checks for a selected run. [owner, name, prNumber, runId]
pr.merge.status - View PR mergeability and readiness signals. [owner, name, prNumber]
pr.merge - Execute a PR merge. [owner, name, prNumber, method?, deleteBranch?, admin?, auto?]
pr.close - Close a PR without merging. [owner, name, prNumber, deleteBranch?, comment?]
pr.comments.create - Post an issue-style comment on a PR (e.g. `@dependabot rebase`). [owner, name, prNumber, body]
pr.assignees.add - Add assignees to a PR without replacing existing ones. [owner, name, prNumber, assignees]
pr.assignees.remove - Remove specific assignees from a PR. [owner, name, prNumber, assignees]
pr.branch.update - Update PR branch with latest base branch changes. [owner, name, prNumber]
workflow.list - List repository workflows. [owner, name, first?]
workflow.view - View one repository workflow. [owner, name, workflowId]
workflow.dispatch - Trigger a workflow dispatch event. [owner, name, workflowId, ref, inputs?]
workflow.runs.list - List workflow runs for a repository. [owner, name, first?, branch?, event?, status?]
workflow.run.view - View a workflow run with its jobs. [owner, name, runId]
workflow.run.cancel - Cancel a workflow run. [owner, name, runId]
workflow.run.rerun.all - Rerun all jobs in a workflow run. [owner, name, runId]
workflow.run.rerun.failed - Rerun failed jobs for a workflow run. [owner, name, runId]
workflow.run.artifacts.list - List artifacts for a workflow run. [owner, name, runId]
workflow.job.logs.view - Fetch and analyze workflow job logs. [owner, name, jobId]
workflow.job.logs.raw - Fetch raw (unprocessed) logs for a workflow job. [owner, name, jobId]
project_v2.org.view - Get an organization Projects v2 project. [org, projectNumber]
project_v2.user.view - Get a user Projects v2 project. [user, projectNumber]
project_v2.fields.list - List fields for a Projects v2 project. [owner, projectNumber, first?, after?]
project_v2.items.list - List items in a Projects v2 project. [owner, projectNumber, first?, after?]
project_v2.items.issue.add - Add an issue to a Projects v2 project. [owner, projectNumber, issueUrl]
project_v2.items.issue.remove - Remove an issue from a Projects v2 project. [owner, projectNumber, itemId]
project_v2.items.field.update - Update a field on a Projects v2 project item. [projectId, itemId, fieldId, valueText?, valueNumber?, valueDate?, valueSingleSelectOptionId?, valueIterationId?, clear?]
release.list - List releases for a repository. [owner, name, first?, after?]
release.view - Get release details by tag name. [owner, name, tagName]
release.create - Create a draft release. [owner, name, tagName, title?, notes?, targetCommitish?, prerelease?]
release.update - Update a draft release without publishing it. [owner, name, releaseId, tagName?, title?, notes?, targetCommitish?, prerelease?, draft?]
release.publish - Publish an existing draft release. [owner, name, releaseId, title?, notes?, prerelease?]
```

If you need the full input/output schema for a capability:

```bash
ghx capabilities explain <capability_id>
```

## Execute

**Always use heredoc for input** — never inline `--input '...'`. Inline form breaks with nested quotes and trailing commas in model-generated JSON.

```bash
ghx run <capability_id> --input - <<'EOF'
{...}
EOF
```

**Result:** `{ ok, data?, pagination? }` on success — `{ ok, error: { code, message } }` on failure.

## Chain (batch multiple operations)

When you have two or more **independent** operations, use `ghx chain`. It batches them into as few GraphQL round-trips as possible (typically one), which is significantly faster than running them sequentially. Steps are not transactional — a `"partial"` result is possible if one step fails after others succeed.

```bash
ghx chain --steps - <<'EOF'
[
  {"task":"<capability_id>","input":{...}},
  {"task":"<capability_id>","input":{...}}
]
EOF
```

**Result:** `{ status, results[] }`. Each element: `{ task, ok, data? }` or `{ task, ok, error: { code, message } }`.

**When NOT to chain:** Don't chain when a later step depends on the result of an earlier one. For example, "check CI, then fetch logs only if something failed" requires two sequential calls because the second depends on the first result. Similarly, "create an issue, then label it" needs the issue number from the create step before labeling.

Repo-scoped steps in a chain can omit `owner`/`name` when they target the current checkout; `ghx` applies the same cached repo context to each eligible step. Keep explicit `owner`/`name` when a chain touches multiple repositories.

A step that targets a **different** repo than the current checkout must set its own `owner`/`name`; otherwise it inherits the checkout's repo. A `NOT_FOUND` ("Could not resolve to an Issue/PullRequest with the number of N") usually means a wrong number or a step pointing at the wrong repo — double-check `owner`/`name`/number. List capabilities default `first` to 30 when omitted, so you don't need to set it explicitly (this applies to chain steps too).

## Error handling

ghx never throws — errors are always in the response envelope. Check the `ok` field:
- `ok: true` — success, data is in `data`
- `ok: false` — failure, details in `error.code` and `error.message`

Common error codes: `AUTH`, `NOT_FOUND`, `VALIDATION`, `RATE_LIMIT`, `NETWORK`, `SERVER`.

## Common gotchas

- Use `pr.comments.create` for PR comments such as `@dependabot rebase`; `issue.comments.create` targets issue nodes, not pull request nodes.
- `*.set` capabilities replace the existing collection. Use `*.add` or `*.remove` for incremental label/assignee changes.
- Use `pr.merge` with `admin: true` only when explicitly authorized to bypass branch protection. Use `auto: true` only when you intend to queue auto-merge.

If you get `RATE_LIMIT` or `NETWORK`, retry after a short delay. For `NOT_FOUND`, double-check owner/name/number. For `VALIDATION`, run `ghx capabilities explain <id>` to check the expected schema.

## Common workflow patterns

### PR merge readiness audit
Use `ghx chain` with `pr.checks.list`, `pr.threads.list`, and `pr.merge.status` in one call to get all three signals at once.

### Review a PR (read diff, check threads, submit review)
1. `pr.diff.view` — read the full diff
2. `pr.threads.list` — see existing unresolved review comments
3. `pr.reviews.submit` — submit your review with inline comments

### Respond to all unresolved review threads
1. `pr.threads.list` — get all unresolved threads (returns `threadId` for each)
2. `ghx chain` with multiple `pr.threads.reply` steps — reply to each thread in one batch

### Check CI status and debug failures (sequential -- don't chain)
1. `pr.checks.list` — see which checks passed/failed
2. Only if something failed: `workflow.run.view` — get job details for the failed run
3. Only if needed: `workflow.job.logs.view` — read the failure logs

### Triage an issue (label, assign, comment)
Use `ghx chain` with `issue.labels.add`, `issue.assignees.add`, and `issue.comments.create` in one call.

### Create an issue then configure it (sequential then batch)
1. `issue.create` — get the new issue number
2. `ghx chain` with `issue.labels.add`, `issue.assignees.add`, `issue.comments.create` — batch all mutations using the number from step 1

### Create a PR from current branch
1. Infer owner/name from git remote
2. Get current branch: `git branch --show-current`
3. `pr.create` with `head` = current branch, `base` = main/master