Split skills/basecamp/SKILL.md into core + references (progressive disclosure)

[sayem314]

skills/basecamp/SKILL.md is 75,787 bytes / 1,446 lines — roughly 19K tokens at ~4 chars/token. Per the Agent Skills spec, the agent loads the entire file every time the skill activates ("the agent will load this entire file once it's decided to activate a skill"), so that cost is paid on every Basecamp task before any real work starts.

The spec says to "consider splitting longer SKILL.md content into referenced files", and the best practices are more specific: keep SKILL.md under 500 lines and 5,000 tokens, move detailed reference material into references/, and — importantly — tell the agent when to load each file ("Read references/api-errors.md if the API returns a non-200 status code" beats "see references/ for details").

Measured section breakdown

Section	Lines	Size
Agent Invariants	86–195	9.5 KB
Quick Reference	196–271	6.3 KB
URL Parsing	272–314	2.2 KB
Decision Trees	315–352	2.0 KB
Common Workflows	353–499	5.2 KB
Resource Reference	500–1276	41.4 KB
Configuration, Error Handling, jq Filtering, Exit Codes, Learn More	1277–1446	7.1 KB

Impact in practice

Activation cost is ~19K tokens, of which the Resource Reference — 41.4 KB of per-endpoint detail — is more than half, and it only matters for the one endpoint a task actually touches. Hosts differ in how they handle this: some load the whole file, others cap tool results and silently truncate the tail, which drops the later endpoint sections (Configuration, Error Handling, Exit Codes are at the very end). Either way, the same fixed cost lands on every activation.

Proposal

Keep the core — Agent Invariants, Quick Reference, URL Parsing, Decision Trees, and (optionally) Common Workflows — in SKILL.md, with load-when pointers:

1. ## Resource Reference (41.4 KB) → references/endpoints.md
2. ## Configuration + ## Error Handling + ## Built-in jq Filtering +
   ## Exit Codes (7.1 KB) → references/operations.md

Two sizes are reasonable:

• Minimal split: move only the Resource Reference. SKILL.md lands at
  ~26.4 KB / ~510 lines / ~6.6K tokens — a 3× cut in activation cost.
• Tighter split: also move Common Workflows (5.2 KB). SKILL.md lands at
  ~21 KB / ~365 lines / ~5.3K tokens, inside the recommended bounds.

The split is additive: the core already routes via the Decision Trees, and pointers tell the agent exactly when to pull each reference file.

[jeremy]

Thanks for measuring this rather than asserting it. The activation cost is real: 78 KB on every /basecamp, more than half of it the Resource Reference, and the same shape holds for hey-cli's skill (basecamp/hey-cli#408), so the two should get the same answer. Here it is.

The Resource Reference is a copy of what the binary already serves on demand: every command carries its own help (basecamp <command> --help), which is what the per-command entries restate. A references/endpoints.md would be a second copy of that, kept in step by hand, and it would also need the install path to grow: basecamp skill install embeds, copies and re-verifies exactly one file across the Agents, Claude Code and OpenCode targets, and scripts/check-skill-drift.sh reads one file. Carrying a directory through all of those is doable, but it buys a file that duplicates --help.

So the shape I'd take is the trim without the new file: cut the Resource Reference down to what --help cannot tell an agent (URL parsing, ID kinds, output shapes, the cross-command flows in Common Workflows) and replace the per-command detail with a load-when pointer of the form "before running a command you haven't used in this session, read basecamp <command> --help". Configuration, Error Handling, jq Filtering and Exit Codes are short and belong in the core; they are what an agent needs when something goes wrong, which is exactly when it won't go looking. That keeps SKILL.md inside the bounds you cite, leaves the installers and the drift check untouched, and the reference an agent reads is always the one matching the binary it's running. The skill-evals/ suite in this repo is the gate: the trimmed skill has to pass it. If the evals show agents don't follow the pointer, references/ is the fallback and the install work above is what it costs.

The same verdict is posted on hey-cli#408.