Consider moving the hey SKILL.md resource reference into references/
Nobody has claimed this yet.
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 86/100
- Issue type
- Documentation
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- markdown
- Domain
- documentation
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.
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: "the agent will load this entire file once it's decided to activate a skill").
The 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.
- Dominant language
- Go
- Stars
- 376
- Forks
- 44
- Avg merge
- 1d 5h
- Merged PRs (30d)
- 130
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from basecamp/hey-cli
-
Difficulty 2/5 1-3 hours Newbie friendliness 90/100
-
Difficulty 4/5 3-5 days Newbie friendliness 65/100
-
Difficulty 4/5 3-5 days Newbie friendliness 55/100
-
Difficulty 5/5 Over a week Newbie friendliness 48/100
-
Difficulty 5/5 Over a week Newbie friendliness 35/100
All issues in basecamp/hey-cli
Similar issues
-
Difficulty 1/5 Under an hour Newbie friendliness 84/100
-
enhancement needs triage
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
-
kind/cleanup
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
kubernetes-sigs/kueue#15947 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
sympozium-ai/sympozium#627 ·
-
priority: p3
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
googleapis/librarian#7636 ·