`gh` skill description does not tell agents when to use it, so it is skipped for tasks it covers

Open Beginner friendly
  • Is something wrong?
#14,621 2 comments 1 reaction 0 assignees View on GitHub

Maintainers usually reply within 1 day

@littfed is already working on this.

Since Oct 9, 2026.

Assessment

Difficulty
1/5
Estimated time
Under an hour
Newbie friendliness
85/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
markdown
Domain
documentation

Research direction

Open skills/gh/SKILL.md and update its frontmatter description field to add an explicit 'use when' trigger for GitHub tasks and list newer gh capabilities like --attach, gh discussion, gh repo read-file/read-dir, and issue types/sub-issues/blocked-by links. Ensure the description stays within agent skill frontmatter limits and matches the provided acceptance criteria.

Written by the indexing model from the issue text.

Description

enhancement
Describe the feature or problem you’d like to solve

The official gh skill (skills/gh/SKILL.md) has this description:

Patterns for invoking the GitHub CLI (gh) from agents. Covers structured output, pagination, repo targeting, search vs list, gh api fallback.

Agents decide whether to load a skill from its description alone. This one has two gaps:

  1. It has no "use when" clause, so it says what the skill contains but not which tasks should trigger it.
  2. It lists only topics agents already roughly know (--json, pagination, gh api). It does not mention what the skill uniquely teaches: features newer than most models' training data, such as --attach, gh discussion, gh repo read-file / read-dir, and issue types, sub-issues and blocked-by relationships.

Because of this, the skill is skipped for exactly the tasks where it adds the most value. An agent that doesn't know gh can do something will never pick gh for the task, and so never reaches the skill.

Observed example: in a Claude Code session with the gh skill installed, I asked the agent to attach a file to a pull request description. It did not load the skill. It tried to do it through a browser instead, failed (including at login), and eventually gave up. It completed the task with gh pr edit --attach only after I told it to use the gh skill.

I have since worked around this with a personal CLAUDE.md instruction to load the skill before any GitHub task, but other users of the skill won't have that.

Proposed solution

Rewrite the description in skills/gh/SKILL.md so that it:

  • starts with the tasks that should trigger it ("Use for any GitHub task done through gh..."), and
  • names the newer capabilities the skill documents, so that agents load it for tasks they wrongly assume gh can't do.

For example:

Use for any GitHub task done through gh: issues, PRs, search, gh api, attaching images or videos to issues, PRs and comments, discussions, reading repo files without cloning, and issue types, sub-issues and blocked-by links. Covers features newer than most agents' training data, plus structured output, pagination and repo targeting.

This would make the skill trigger more reliably without changing its body. It also matters more if #14615 ships, since packaging the skill as a plugin puts it in front of more users who have no local workaround.

Possible acceptance criteria:

  • The description contains an explicit "use when" trigger covering GitHub tasks in general.
  • The description names the skill's capabilities that are likely to be missing from a model's training data (at least --attach).
  • The description stays within agent skill frontmatter limits.
Additional context

gh version 2.102.0 (2026-09-30); skill installed from skills/gh at v2.101.0, and the description is unchanged on trunk.

Dominant language
Go
Stars
46.8k
Forks
9.2k
Avg merge
1d 14h
Merged PRs (30d)
60

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from cli/cli

All issues in cli/cli

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.