Split the gh agent skill so feature reference loads on demand #14979

Describe the feature or problem you'd like to solve

I found out gh had gained --attach after an agent told me it couldn't upload images. I was about to add a note to my global agent instructions, and checked what skills already existed before doing that. The gh skill covers it, but it looked like a lot to load for what I needed, so I measured it. I ended up adding a one-line note instead.

skills/gh/SKILL.md is about 8,300 tokens (from Anthropic's count_tokens). It's one file, so a thread that needs gh for anything loads all of it, and then resends it on every later model request. About 73% of the file by character count is feature reference: issue artifacts alone are about a third, then attachments, discussions, issue types and reading files. Most threads won't use most of that.

I went through about four weeks of my own agent logs, assuming the skill loads at the first gh command in a thread. This is only my data:

• About 45% of recent threads ran gh (17% to 52% depending on the month).
• In a typical gh thread, the skill would be about 8% of tokens from that point on. The middle half of threads were between 4.5% and 12%.
• In threads under 50k tokens of context, it would be about 14%.

At API rates, with most of the repeat reads cached, that works out to roughly:

• $0.05 per thread on GPT-6.1 Sol, and $0.15 to $0.20 per thread on Claude Opus 5.5.
• $100 to $250 a month for me, or 1% to 3% of my usage at API rates. The low end loads the skill at first gh use, the high end loads it in every thread.

I don't have the stats to work out a median across users, and I don't know how my usage compares, so don't read my monthly number as an average. Anyone with smaller threads would likely see a higher percentage. API users pay for this directly. Subscription users pay less per token, but the tokens still count towards their limits.

The description also leaves out newer features:

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

An agent asked to upload a screenshot has no reason to load the skill from that, and may just say gh can't do it.

Proposed solution

Make SKILL.md a short index and move all of the current sections into files that are only read when needed:

skills/gh/
  SKILL.md                     #  ~570 tokens
  references/
    attachments.md             # ~1,260
    auth.md                    #   ~420
    discussions.md             #   ~820
    issue-artifacts.md         # ~2,680
    issue-relationships.md     #   ~670
    other-notes.md             #   ~340
    output-and-api.md          #   ~920
    reading-files.md           #   ~620
    search.md                  #   ~570

I built this locally to get real numbers. The reference files are the current sections, moved word for word. SKILL.md keeps six one-line warnings, such as result caps and search qualifier syntax, then a table of which file to read for which task. The description names the features, including image and video uploads.

That's about 93% fewer tokens for a thread that only needs the basics. A thread that uploads an image would load about 1,830 tokens, and one using issue artifacts about 3,250, compared with 8,300 today. Applying the same ratio to my logs, a typical gh thread goes from about 8% of tokens to under 1%.

Additional context

This needs testing across the models people use, since a split that works on one may not work on another. Weaker models might not follow the pointers to reference files, and stronger ones may not need much of the skill at all. An eval could run the same gh tasks with no skill, the current skill and a split skill, then compare success rates and token use. It should include both newer features and routine gh work.

I haven't checked that gh skill install handles a references/ directory. A plugin with several skills is another option, but it would need packaging per agent.

Requests like #14701 add to the same file, so this gets more expensive as the skill grows.

I think GitHub should make this change rather than leaving users to work around it, because it affects the token usage of everyone who uses this skill.