refactor(gh-cli): split SKILL.md into progressive-disclosure reference files 🤖🤖🤖

[sokratisg]

Summary

Restructures the gh-cli skill to use progressive disclosure: a short router SKILL.md + 11 focused reference/*.md files, each scoped to one command group. The router tells the agent which reference file to open based on the task; individual references are loaded only when needed.

Motivation

The current skills/gh-cli/SKILL.md is a single file — 2,187 lines / 6,137 words / ~40KB — that loads in full whenever the skill activates, even for a task that only needs gh pr merge or gh api. For a reference-style skill covering 20+ command groups, this is a large context tax on every activation.

Splitting reduces the up-front load when the skill fires to ~60 lines / 530 words (~91% smaller) while preserving every command group from the original.

Layout

skills/gh-cli/
├── SKILL.md                  router + index (~60 lines)
└── reference/
    ├── auth.md               install, login, tokens, env
    ├── repo.md               gh repo
    ├── issue.md              gh issue
    ├── pr.md                 gh pr
    ├── actions.md            run / workflow / cache / secret / variable
    ├── api.md                REST, GraphQL, pagination, jq
    ├── projects.md           Projects v2
    ├── release.md            releases + assets
    ├── formatting.md         --json / --jq / --template
    ├── workflows.md          end-to-end recipes
    └── misc.md               browse, gist, codespace, org, search,
                              label, ssh-key, gpg-key, status, config,
                              extension, alias, ruleset, attestation,
                              completion, preview, agent-task

Why progressive disclosure

Anthropic's skill authoring guidance (agentskills.io) recommends keeping SKILL.md small and offloading heavy reference material to separate files that the agent reads on demand. For reference skills that span many subcommands, this keeps the "when to use + routing" signal high and the per-activation token cost low.

Minor corrections folded in

While restructuring I corrected a few command signatures that were wrong in the original:

• gh repo autolink create (was documented as add)
• gh attestation verify argument format
• gh api -f / -F field-type semantics (string coercion vs. raw)

Validation

• npm run skill:validate — all 341 skills valid ✅
• npm run build — regenerates docs/README.skills.md (the description column now reflects the new "Use when…" phrasing, and the Assets column shows reference) ✅

Description field change

The description: in frontmatter changes from:

GitHub CLI (gh) comprehensive reference for repositories, issues, pull requests, Actions, projects, releases, gists, codespaces, organizations, extensions, and all GitHub operations from the command line.

to:

Use when running GitHub CLI (gh) commands — auth, repos, issues, PRs, Actions/workflows, releases, projects, gists, codespaces, rulesets, or any gh api REST/GraphQL call from the command line.

The new phrasing starts with "Use when…" (matching Anthropic's CSO guidance for skill descriptions), and the coverage list is equivalent.

Test plan

• npm run skill:validate passes
• npm run build produces only expected diffs (one row in docs/README.skills.md for gh-cli)
• All 11 reference/*.md files render correctly on GitHub
• Router cross-links resolve (relative paths reference/<file>.md)
• Manual check by a reviewer: pick a task (e.g. "download the artifacts from the last failed CI run") and confirm the router points to the right file(s) (reference/actions.md)

[github-actions]

🔍 Skill Validator Results

✅ All checks passed

Scope	Checked
Skills	1
Agents	1
Total	2
Severity	Count
---	---:
❌ Errors	0
⚠️ Warnings	0
ℹ️ Advisories	0

Summary

Level	Finding
ℹ️	Found 1 skill(s)
ℹ️	[gh-cli] 📊 gh-cli: 1,284 BPE tokens [chars/4: 1,228] (detailed ✓), 11 sections, 2 code blocks
ℹ️	✅ All checks passed (1 skill(s))

Full validator output

```text Found 1 skill(s) [gh-cli] 📊 gh-cli: 1,284 BPE tokens [chars/4: 1,228] (detailed ✓), 11 sections, 2 code blocks ✅ All checks passed (1 skill(s)) ```

[aaronpowell]

In the 1.0.46 release of Copilot CLI we have introduced some checks to support auto-approval of read-only gh commands (see the release notes).

Looking more into it, it seems that the models have a pretty solid handle on the gh CLI already, without the need for a skill or anything. Here's a quick test I did:

❯ Do not make any external tool calls (no shell commands, no web search, no skills, etc.)                                                                                                                                                                                                                                                          
                                                                                                                                                                                                                                                                                                                                                    
   How would I get the pull requests from a github repo using the github cli                                                                                                                                                                                                                                                                        
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
● Use:

   gh pr list --repo OWNER/REPO

  Common options:

   gh pr list --repo OWNER/REPO --state all
   gh pr list --repo OWNER/REPO --limit 100
   gh pr list --repo OWNER/REPO --json number,title,state,url
   gh pr view 123 --repo OWNER/REPO

  Examples:

   - List open PRs: gh pr list --repo cli/cli
   - List all PRs: gh pr list --repo cli/cli --state all
   - Get JSON output: gh pr list --repo cli/cli --json number,title,author,state,url

  Or via the API:

   gh api repos/OWNER/REPO/pulls

  Authenticate first if needed:

   gh auth login

As a result, it seems logical to remove the skill from the repo entirely - it now falls into the category of "Duplicate Existing Model Strengths Without Meaningful Uplift".

This isn't a critique on the change you proposed - it would be a valuable change, if it wasn't to something that is no longer required in the repo.