domains / software-engineering / github-cli-usage / gh-cli
The two skills serve different purposes. The trailofbits skill is a behavioral guardrail that enforces the use of the `gh` CLI over unauthenticated HTTP methods (curl/WebFetch) for security and rate-limit reasons. The benchflow skill is a reference manual that documents specific `gh` subcommands, flags, and search syntax. Neither contains the material steps of the other; the first lacks command documentation, and the second lacks the enforcement logic for when to use the tool. Combining them creates a complete skill that both mandates the correct tool usage and provides the necessary reference for executing it.
| Repository | Path |
|---|---|
| trailofbits/skills | plugins/gh-cli/skills/gh-cli/SKILL.md |
| benchflow-ai/skillsbench | tasks-extra/gh-repo-analytics/environment/skills/gh-cli/SKILL.md |
| Role | Repository | Path |
|---|---|---|
| peer | trailofbits/skills | plugins/gh-cli/skills/gh-cli/SKILL.md |
| peer | benchflow-ai/skillsbench | tasks-extra/gh-repo-analytics/environment/skills/gh-cli/SKILL.md |
--- name: gh-cli description: Enforces authenticated gh CLI workflows and provides a reference for GitHub CLI commands, search syntax, and JSON output. --- # gh-cli ## When to Use - Working with GitHub repositories, pull requests, issues, releases, or raw file URLs. - You need authenticated access to private repositories or higher API rate limits. - You are about to use `curl`, `wget`, `WebFetch`, or an MCP fetch tool against GitHub. ## When NOT to Use - The target is not GitHub. - Plain local git operations already solve the task. ## Guidance Prefer the authenticated `gh` CLI over raw HTTP fetches for GitHub content. In particular: - Prefer `gh repo view`, `gh pr view`, `gh pr list`, `gh issue view`, and `gh api` over unauthenticated `curl` or `wget`. - Prefer cloning a repository and reading files locally over fetching `raw.githubusercontent.com` blobs directly. - Avoid using GitHub API `/contents/` endpoints as a substitute for cloning and reading repository files. ## Core Commands Use `gh <command> --help` for more information about a command. ### gh pr Work with GitHub pull requests. ``` USAGE gh pr <command> [flags] CORE COMMANDS checkout: Check out a pull request in git checks: Show CI status for a single pull request close: Close a pull request comment: Create a new pr comment create: Create a pull request diff: View changes in a pull request edit: Edit a pull request list: List and filter pull requests in this repository merge: Merge a pull request ready: Mark a pull request as ready for review reopen: Reopen a pull request review: Add a review to a pull request status: Show status of relevant pull requests view: View a pull request FLAGS -R, --repo [HOST/]OWNER/REPO Select another repository using the [HOST/]OWNER/REPO format ARGUMENTS A pull request can be supplied as argument in any of the following formats: - by number, e.g. "123"; - by URL, e.g. "https://github.com/OWNER/REPO/pull/123"; or - by the name of its head branch, e.g. "patch-1" or "OWNER:patch-1". EXAMPLES $ gh pr checkout 353 $ gh pr create --fill $ gh pr view --web ``` ### gh issue Work with GitHub issues. ``` USAGE gh issue <command> [flags] CORE COMMANDS close: Close issue comment: Create a new issue comment create: Create a new issue delete: Delete issue edit: Edit an issue list: List and filter issues in this repository reopen: Reopen issue status: Show status of relevant issues transfer: Transfer issue to another repository view: View an issue FLAGS -R, --repo [HOST/]OWNER/REPO Select another repository using the [HOST/]OWNER/REPO format ARGUMENTS An issue can be supplied as argument in any of the following formats: - by number, e.g. "123"; or - by URL, e.g. "https://github.com/OWNER/REPO/issues/123". EXAMPLES $ gh issue list $ gh issue create --label bug $ gh issue view --web ``` ### gh repo Work with GitHub repositories. ``` USAGE gh repo <command> [flags] CORE COMMANDS archive: Archive a repository clone: Clone a repository locally create: Create a new repository delete: Delete a repository edit: Edit repository settings fork: Create a fork of a repository list: List repositories owned by user or organization rename: Rename a repository sync: Sync a repository view: View a repository ARGUMENTS A repository can be supplied as an argument in any of the following formats: - "OWNER/REPO" - by URL, e.g. "https://github.com/OWNER/REPO" EXAMPLES $ gh repo create $ gh repo clone cli/cli $ gh repo view --web ``` ## Search Query Syntax The `--search` flag uses GitHub search syntax. ### Comparison Operators | Query | Description | Example | |-------|-------------|---------| | `>n` | Greater than | `stars:>1000` | | `>=n` | Greater than or equal | `topics:>=5` | | `<n` | Less than | `size:<10000` | | `<=n` | Less than or equal | `stars:<=50` | ### Range Queries | Query | Description | Example | |-------|-------------|---------| | `n..n` | Between range | `stars:10..50` | | `n..*` | Greater than or equal | `stars:10..*` | | `*..n` | Less than or equal | `stars:*..10` | ### Date Queries Date format: `YYYY-MM-DD` (ISO8601). | Query | Example | |-------|---------| | `>YYYY-MM-DD` | `created:>2024-04-29` | | `>=YYYY-MM-DD` | `created:>=2024-04-01` | | `<YYYY-MM-DD` | `pushed:<2024-07-05` | | `<=YYYY-MM-DD` | `created:<=2024-07-04` | | `YYYY-MM-DD..YYYY-MM-DD` | `created:2024-04-30..2024-07-04` | ### Exclude Results Prefix qualifier with `-` to exclude: | Query | Example | |-------|---------| | `-QUALIFIER` | `stars:>10 -language:javascript` | | `NOT` | `hello NOT world` | ### Usernames | Query | Description | |-------|-------------| | `author:USERNAME` | Filter by specific user | | `author:@me` | Filter by current user | | `assignee:@me` | Assigned to current user | ### Queries with Whitespace Use quotation marks for multi-word values: - `label:"bug fix"` — label with space - `cats NOT "hello world"` — exclude phrase ## JSON Output Common fields for `--json`: **PR**: ``` additions assignees author baseRefName body changedFiles closed closedAt comments commits createdAt ```