Consider moving the hey SKILL.md resource reference into references/
- 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
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