The many agent skills under skills/ should really just be a single skill

[sammcj]

CLI Version

NA

What happened?

I went to grab the glean Agent Skill (for use with Claude Code / OpenCode) and found that there are a lot of tiny individual skills within this project's ./skills/ directory.

This goes against common best practices when creating agent skills, of following a pattern of progressive disclosure.

By having so many small skills each skills description gets injected into the context window of every agent interaction, bloating out the context. When in reality, there only needs to be one skill description that gets added to the agent context (describing that there is a Glean CLI skill and when to activate it).

What did you expect to happen?

I think realistically there should just be one single skill (glean-cli), with core information in the initial SKILL.md file and then domain-specific information that may not always be required when agents are using Glean CLI within ./resources/<information>.md

I ended up taking the skills from this repo and turning them into a single skill in the following repo, I'd be happy to submit a PR if you are interested. https://github.com/sammcj/agentic-coding/blob/main/Skills/glean-cli/SKILL.md

Steps to reproduce

N/A

Does the same issue occur with a direct API call?

N/A

Authentication method

OAuth (glean auth login)

Environment

N/A

Relevant output or logs

[steve-calvert-glean]

Hey @sammcj — thanks for writing this up. The example repo helps; having a concrete trade-off to look at is much better than arguing it in the abstract.

Original motivation, since I don't think we ever wrote it down: the skills are generated from glean schema. The CLI exposes a machine-readable schema per command, and the generator emits one skill per command. We landed on one-skill-per-subcommand for three reasons:

• 1:1 from the generator's perspective — one command in, one skill out.
• Skill-selection precision — we thought narrower descriptions would match user intent more cleanly ("search X" → glean-cli-search, "list pins" → glean-cli-pins).
• Permission heterogeneity — different Glean roles have different API access, so letting users install a subset felt friendlier than an all-or-nothing bundle.

Reading the Anthropic best-practices doc you linked, I think you're right on most of it:

• Metadata from every installed skill is pre-loaded at startup. That's explicit in the doc — cost scales with skill count regardless of invocation.
• The BigQuery pattern in that doc (reference/finance.md, reference/sales.md, ...) is basically what you're proposing, and it fits our case.
• Our per-command skills are thin enough that nothing is lost by moving them into reference/<command>.md. The authoritative flag data is delegated to glean schema at runtime anyway.
• The permission-heterogeneity argument doesn't hold up. A skill loaded for an API you can't call isn't a leak — the CLI enforces access, and a 403 is one feedback message the agent recovers from. Not worth the structural cost.

One place I'd push back: "context bloat" is a bit strong. 17 descriptions at ~30 words each is ~500 tokens — real but not catastrophic. The better argument is "the split doesn't earn the cost it charges," not "it hurts today."

One ask if you pick this up: please keep the full per-command flag tables in reference/<command>.md rather than the shorter summary in your current draft. glean schema is authoritative, but carrying the flag shape in the skill saves the agent a round-trip when writing --json payloads.

Proposed shape:

skills/glean-cli/
├── SKILL.md
└── reference/
    ├── search.md
    ├── chat.md
    ├── pins.md
    └── ...

What the work looks like:

• Update the generator to emit this shape instead of 17 separate skills.
• Drop the per-skill npx skills add URLs from the README.
• We're pre-1.0, so I'd rather just break installs cleanly than carry compat shims.

Happy to take a PR on this. Let's align on the reference/*.md content shape before you start so we don't find disagreement in review.

[sammcj]

Thanks for your reply Steve, I see you've raised a PR already (too quick for me!).

[steve-calvert-glean]

Ya all good, @sammcj. I really appreciated you bringing this up, and helping us optimize this. I wanted to do my part and drive this implementation so we can get it rolled out ASAP. Appreciate your kicking things off here!