basecamp / basecamp/hey-cli

Consider moving the hey SKILL.md resource reference into references/

Open Beginner friendly
#408 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Go
Stars
368
Forks
44
Avg merge
15h 15m
Merged PRs (30d)
189

Description

`skills/hey/SKILL.md` is 47,736 bytes / 811 lines — roughly 12K tokens at ~4 chars/token, loaded in full on every activation of the skill ([spec](https://agentskills.io/specification#progressive-disclosure): "the agent will load this entire file once it's decided to activate a skill").

The [best practices](https://agentskills.io/skill-creation/best-practices) recommend keeping `SKILL.md` under 500 lines and 5,000 tokens, with detailed reference material in `references/` and explicit load-when pointers in `SKILL.md`.

## Measured section breakdown

| Section | Lines | Size |
|---|---|---|
| Agent Invariants | 117–126 | small |
| Output Filtering | 127–148 | small |
| Quick Reference | 149–261 | ~4 KB |
| Decision Trees | 262–331 | small |
| **Resource Reference** | **332–811** | **32.4 KB** |

## Impact

The Resource Reference is ~68% of the file. Several agent hosts cap tool results (16 KB and 32 KB caps are common) and truncate silently, so the tail sections — exactly the per-endpoint detail an agent needs for less common commands — can be lost on activation. Hosts that do load it fully pay ~12K tokens per activation regardless of task.

## Proposal

Move `## Resource Reference` (lines 332–811, 32.4 KB) to `references/commands.md`, and replace it with a load-when pointer in `SKILL.md`, e.g. "Read `references/commands.md` for full flags and output shape of a command before running an uncommon one." `SKILL.md` lands at ~15 KB / ~340 lines / ~3.8K tokens — inside the recommended bounds, with the Quick Reference and Decision Trees still inline for everyday tasks.

Contributor guide

Open the contributing guide

Research direction

Start with skills/hey/SKILL.md and review the `## Resource Reference` section identified in the issue. Move that section to references/commands.md, add the explicit load-when pointer in SKILL.md, and verify the resulting SKILL.md is within the stated line and token targets while the command details remain available in the new reference file.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
86/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.