Skip to content
Get packs

Guide · Agent skill

How to use the GitHub CLI Helper agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

This guide explains the GitHub skill for AI agents: what it lets the agent do with the GitHub CLI (gh), how to install it, and how to ask for things in plain language. It is aimed at developers and maintainers who may never have used an agent skill before. By the end you will be able to install the skill, ask the agent to diagnose a failing CI run, and know what safety limits to keep in mind.

GitHub CLI Helpersipeed/picoclaw · MIT

Quick start

  1. 1Install the GitHub CLI. Install gh with Homebrew or apt, as listed in the skill's requirements.
  2. 2Log in to GitHub. Run gh auth login and authenticate with your GitHub account.
  3. 3Download the skill ZIP. Get the ZIP of the github skill from our page and unzip it.
  4. 4Place the skill folder. Put it in ~/.claude/skills/ for personal use, or in the project's .claude/skills/ folder for one project.
  5. 5Ask a natural request. Tell the agent what to check, including the owner/repo name and PR number or run ID.
  6. 6Review actions before writes. If the token has write or admin rights, check what the agent plans to run before it changes anything.

What is an agent skill and what does the GitHub skill do?

An agent skill is a folder with a SKILL.md file that teaches an AI agent how to perform a specific task. This skill, named github, teaches the agent to use GitHub's official command-line tool, gh, to work with a repository.

Once installed, the agent can check CI status on pull requests, list recent workflow runs, and pull the logs of failed steps so you can see why a build broke. It can also run advanced queries against GitHub's API and list issues in structured form.

  • Check CI status on a pull request
  • List recent workflow runs
  • View which steps in a run failed
  • Read logs for failed steps only
  • Run advanced queries with gh api
  • List issues in structured JSON output

What do you need before installing the GitHub skill?

The skill needs the GitHub CLI (gh) installed and a GitHub account authenticated with gh. The skill's metadata lists Homebrew and apt as install routes for gh. Authenticate with gh auth login. The agent works only with the access that account has.

  • GitHub CLI (gh), installable via Homebrew or apt
  • A GitHub account authenticated with gh (gh auth login)
gh auth login

How do you install the GitHub skill?

Download the ZIP of the skill from our page and unzip it. For a personal setup, place the unzipped folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.

You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

  • Personal install: unzip into ~/.claude/skills/
  • Project install: unzip into the project's .claude/skills/
  • Claude apps: Settings → Capabilities → Skills, then upload the ZIP

How do you trigger the skill with natural requests?

You do not need to type commands yourself. Ask the agent in plain language about pull requests, CI runs, issues or API data, and mention the repository. The skill says to always specify the repository (owner/repo) when you are not inside a git directory, or to use URLs directly.

Good requests name the thing you want checked, for example a pull request number or a run. Example requests: "Check CI status on PR 55 in owner/repo", "List the last 10 workflow runs for owner/repo", "Show me the logs for the failed steps in run 123456 of owner/repo".

  • Always include the repository as owner/repo if you are outside a git checkout
  • Name the PR number or run ID when you have one

What commands does the skill use?

The skill uses gh pr checks for PR CI status, gh run list and gh run view for workflow runs, and gh api for data not available through other subcommands. Most commands support --json for structured output, and --jq filters that output. The examples below are taken from the skill file, using placeholder values.

  • gh pr checks: CI status on a PR
  • gh run list --limit: recent workflow runs
  • gh run view <run-id>: which steps failed
  • gh run view --log-failed: logs for failed steps only
  • gh api: advanced queries and specific fields
  • --json and --jq: structured output and filtering
gh pr checks 55 --repo owner/repo gh run list --repo owner/repo --limit 10 gh run view <run-id> --repo owner/repo --log-failed gh api repos/owner/repo/pulls/55 --jq '.title, .state, .user.login' gh issue list --repo owner/repo --json number,title --jq '.[] | "\(.number): \(.title)"'

What safety limits should you know about?

This skill runs scripts and uses the network. The gh commands run with the permissions of your logged-in GitHub token. If that token has write or admin rights, gh commands can change repository state, for example merging or closing items. The skill does not restrict these actions.

Review what the agent may run before using it on repositories where you have write or admin rights. Reading CI status and logs is the lowest-risk use.

  • Runs scripts: yes
  • Uses network: yes
  • Actions follow the logged-in account's rights; the skill does not restrict writes
  • Prefer read-only requests unless you have reviewed the agent's actions

What are good tips for getting the most from it?

Use the log view for failures: asking for failed-step logs usually gives more useful detail than the full run output. Use JSON output when you want the agent to compare many items, such as a list of issues.

If you already use gh in your team, the agent can follow the same commands, which keeps results consistent with what people run by hand.

  • Ask for failed-step logs first when a build breaks
  • Ask for structured lists of issues or PRs when triaging
  • Keep the repository name explicit to avoid running against the wrong project

What people use it for

  • Diagnosing why a pull request's CI checks failed by reading the failed-step logs
  • Listing the most recent workflow runs for a repository to spot a pattern of failures
  • Triaging open issues by pulling their numbers and titles as structured output
  • Pulling specific pull request fields such as title, state and author through gh api

Frequently asked questions

How do I install the GitHub agent skill?

Download the skill ZIP from our page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

What do I need to run the github skill?

You need the GitHub CLI (gh), which the skill lists as installable via Homebrew or apt, and a GitHub account authenticated with gh using gh auth login. The skill works only with the access that account has.

Is the GitHub skill free?

The source does not state pricing or licence terms beyond the listed licence, which is MIT. Check the licence file in the source repository for the exact terms.

Can the agent merge or close pull requests with this skill?

The skill does not restrict gh commands. If your logged-in token has write or admin rights, gh commands can change repository state, such as merging or closing items. Review what the agent may run before using it on such repositories.

Why does the agent need owner/repo?

The skill says to always specify --repo owner/repo when you are not in a git directory, or to use URLs directly. This makes sure the commands target the right repository.

What are the alternatives if this skill does not fit?

The source does not compare this skill with other tools. If you do not use GitHub or gh, the skill does nothing useful without them, so you would need a different approach. You can also run the gh commands yourself from the examples on this page.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you work on GitHub repositories, already use or are willing to install gh, and want an agent to read CI status, run logs and issue lists. Pick something else if you have no GitHub account or do not use gh, or if you need an agent that is strictly limited to read-only actions, since this skill does not restrict write operations.

Download the skill