basecamp / basecamp/basecamp-cli

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

Open
#687 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Go
Stars
273
Forks
21
Avg merge
1d 2m
Merged PRs (30d)
66

Description

`skills/basecamp/SKILL.md` is 75,787 bytes / 1,446 lines — roughly 19K tokens at ~4 chars/token. Per the [Agent Skills spec](https://agentskills.io/specification#progressive-disclosure), 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](https://agentskills.io/skill-creation/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.

Contributor guide

Open the contributing guide

Research direction

Read skills/basecamp/SKILL.md alongside the Agent Skills progressive-disclosure guidance. Split the named Resource Reference and operations sections into references/endpoints.md and references/operations.md, add explicit load-when pointers, and verify the core stays within the proposed size while retaining all content and routing.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
76/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.