How to use the GitHub Issue Auto-Fixer agent skill (gh-issues)

What an agent skill is and what gh-issues makes the agent do

An agent skill is a folder containing a SKILL.md file that gives an agent extra instructions for a specific task. The gh-issues skill is one such folder. Its SKILL.md tells the agent to follow six phases in order: parse arguments, fetch issues, present and confirm, run pre-flight checks, spawn sub-agents to implement fixes, and monitor pull request review comments.

The skill is written for a Brigade-style setup and calls the GitHub REST API with curl. It does not depend on the gh CLI, although its metadata lists curl, git and gh as required binaries.

• Fetches open issues from a GitHub repository, filtered by label, milestone, assignee or state
• Shows you a table of the issues and asks which ones to process
• Spawns sub-agents that write fixes on branches and open pull requests
• Can watch for new issues or review comments on its PRs and respond to them
• Can send a final summary with PR links to a Telegram channel

Install the gh-issues skill

Download the ZIP from this page and unzip it. The skill is a folder that contains SKILL.md. Place that folder in one of these locations:

• Personal skills: ~/.claude/skills/ (available across your projects)
• Project skills: a project's .claude/skills/ folder (available only in that project)
• Claude apps: upload the ZIP under Settings → Capabilities → Skills

Set up your GitHub token

The skill needs a GitHub personal access token. It reads the token from the GH_TOKEN environment variable. If that variable is empty, the skill looks for a key under skills.entries.gh-issues in the Brigade config file, at $BRIGADE_CONFIG_PATH or ~/.brigade/brigade.json, and then at /data/.brigade/brigade.json.

The skill passes the token as a Bearer token on every API call. If authentication fails with HTTP 401 or 403, the skill stops and asks you to check the apiKey stored under skills.entries.gh-issues.

• Use a token with only the access the task needs, because a mistake could push branches or open PRs in the wrong place
• If you use --fork, the skill adds a git remote named fork that embeds the token in its URL

Trigger the skill with a natural request or a slash command

The skill is user-invocable, so you can call it directly as /gh-issues followed by optional arguments. The first positional argument is owner/repo. If you leave it out, the skill reads the origin remote of the current git repository and extracts owner/repo from either an HTTPS or SSH URL.

Flags are optional. Common ones are --label, --limit (default 10), --milestone, --assignee, --state (default open), --fork, --watch, --interval (default 5 minutes), --reviews-only, --cron, --dry-run, --yes, --model and --notify-channel.

• Preview only: /gh-issues owner/repo --label bug --dry-run
• Process a small batch: /gh-issues owner/repo --label bug --limit 5
• Work from your fork: /gh-issues owner/repo --fork you/repo
• Only address review comments on open PRs: /gh-issues owner/repo --reviews-only
• Scheduled run: /gh-issues owner/repo --cron

Confirm which issues the agent processes

After fetching, the skill displays a table with each issue's number, title and labels. It then asks you to reply with "all", a comma-separated list of issue numbers such as 42, 37, or "cancel". With --dry-run it stops after the table. With --yes it processes every listed issue without asking.

Before creating branches, the skill checks git status. If the working tree has uncommitted changes, it warns you that those changes will not be included in the sub-agents' branches and asks whether to continue.

Use fork mode and watch mode carefully

With --fork, issues are fetched from the source repository, code is pushed to your fork, and pull requests are opened from the fork to the source repository. This lets you trial fixes without pushing branches to the main repository.

With --watch, the skill keeps polling every --interval minutes. The first poll asks for confirmation unless you pass --yes. Later polls process new issues automatically and show the table so you can see what is being processed. With --cron, the skill forces --yes and exits without waiting for results.

• Use --model (for example glm-5) to choose the model for sub-agents; otherwise the agent's default is used
• Use --notify-channel with a Telegram channel ID to receive only the final PR summary, not status updates

Safety notes: scripts and network access

The skill runs scripts and uses the network. It calls api.github.com with your token, runs git commands in the current repository, and may push branches and open pull requests. Read the SKILL.md and check the owner/repo and --fork values before running it on anything important.

Sub-agents act on issue text alone. Generated code may be wrong or insecure, so review every pull request before merging. Start with --dry-run and a small --limit.

• Do not point it at repositories where you cannot review AI-written pull requests before merging
• Avoid complex or ambiguous issues that need human design decisions
• Prefer a fork and a narrowly scoped token while you are evaluating it