Make the hey skill discovery-first
RO
2h ago+1568+1568+0123456789012345678901234567890123456789-1063-1063-0123456789012345678901234567890123456789
Why
The hey skill was 79 KB, loaded whole on every /hey, and three quarters of it was a hand-kept copy of what hey <command> --help already serves. This does #408 the way the issue's maintainer comment settled it, modelled on basecamp/basecamp-cli#835: no references/ directory, the binary's help is the reference.
What changed
skills/hey/SKILL.mddrops from 78,931 to 15,018 bytes. Agents readhey <group> <subcommand> --agent --helpbefore a command they have not used. The skill keeps only what spans commands: ID kinds, output shapes, send outcomes, the read-then-write recipes and the authentication rules.- Every fact the skill held that no command's help stated now sits in that command's
agent_notes. About 60 commands gained text. scripts/skill-coverage/check.pyproves nothing was dropped (below). A test holds the skill under 16 KiB, teaching leaf help before root help, with no catalog sections.
Scope
- Covers every sentence, table row and code line of the old skill, 702 facts in all.
- Leaves out a skill-eval harness like basecamp-cli's. Nothing here measures whether agents follow the
--agent --helppointer, which the issue names as the trigger for thereferences/fallback. - The coverage script and ledger are a one-off audit, committed so a reviewer can rerun them. They can be deleted after merge.
Tradeoffs
- Facts went into
agent_notes, not areferences/commands.md, because that would be a second copy of--helpand would need the installer and refresh path to carry a directory. - The ledger cites quoted text, so the script proves each quote exists in the help or the skill. Whether the quote states the fact is a reviewer's judgment. The ledger keeps fact and quote side by side for that read.
Blast Radius
Agents using the skill now make one extra local --help call per new command. Help text changed for about 60 commands, with no flag or behavior change. The audit found five help texts that were wrong or contradicted the skill, and they are corrected:
hey authtold agents to check status first and to log in with--token.hey box viewandhey bundle viewsaid a bundle row has notopic_id.hey collection viewpointed at the wrong ID kind.hey timetrack stopandeditsaid a blank category is ignored. It is refused.hey draft sendcontradicted itself on retrying.
The old skill also called contact notes private. On HEY for Domains everyone at the account sees them, and the help now says so.
Verification
python3 -I scripts/skill-coverage/check.py: 702 facts, 523 in help and 179 uncovered before; 640 in help, 62 in the skill and 0 uncovered after, exit 0.make test,make lintandmake checkexit 0. Each commit builds and passesgo test ./skills ./internal/cmd.- Spot-checked 24 sampled fact/quote pairs by hand. One quote was too loose and now cites the precise sentence.
Coverage before (current binary, nothing deleted)
SKILL.md at 76ea03f: 702 facts. New SKILL.md: 78931 bytes.
section facts help skill uncov
intro 1 1 0 0
agent-invariants 10 2 0 8
output-filtering 14 5 0 9
quick-reference 125 122 0 3
reading-email 31 30 0 1
sending-email 25 24 0 1
managing-todos 6 6 0 0
email-boxes 25 9 0 16
email-labels 10 8 0 2
email-collections 10 8 0 2
email-set-aside-groups 13 9 0 4
email-workflows-clips-and-snippets 15 14 0 1
email-search 13 9 0 4
contacts 55 36 0 19
email-threads 25 15 0 10
email-attachments 9 5 0 4
email-reply-forward-compose 29 21 0 8
email-the-screener 20 18 0 2
email-bulk-reply 8 4 0 4
email-seen-unseen 5 5 0 0
email-moving-threads 11 9 0 2
email-bubble-up 15 13 0 2
email-trash-and-spam 8 6 0 2
email-ignoring-threads 8 7 0 1
email-watching-for-changes 25 17 0 8
drafts 15 13 0 2
calendars 8 3 0 5
events 65 42 0 23
todos 8 5 0 3
habits 13 10 0 3
time-tracking 23 21 0 2
journal 20 11 0 9
authentication 28 11 0 17
sender-selection 6 4 0 2
total 702 523 0 179
Coverage after
SKILL.md at 76ea03f: 702 facts. New SKILL.md: 15018 bytes.
section facts help skill retired uncover
intro 1 1 0 0 0
agent-invariants 10 4 6 0 0
output-filtering 14 5 9 0 0
quick-reference 125 125 0 0 0
reading-email 31 31 0 0 0
sending-email 25 25 0 0 0
managing-todos 6 6 0 0 0
email-boxes 25 18 7 0 0
email-labels 10 10 0 0 0
email-collections 10 10 0 0 0
email-set-aside-groups 13 13 0 0 0
email-workflows-clips-and-snippets 15 15 0 0 0
email-search 13 13 0 0 0
contacts 55 49 6 0 0
email-threads 25 20 5 0 0
email-attachments 9 9 0 0 0
email-reply-forward-compose 29 26 3 0 0
email-the-screener 20 19 1 0 0
email-bulk-reply 8 8 0 0 0
email-seen-unseen 5 5 0 0 0
email-moving-threads 11 11 0 0 0
email-bubble-up 15 14 1 0 0
email-trash-and-spam 8 7 1 0 0
email-ignoring-threads 8 7 1 0 0
email-watching-for-changes 25 25 0 0 0
drafts 15 14 1 0 0
calendars 8 6 2 0 0
events 65 65 0 0 0
todos 8 8 0 0 0
habits 13 13 0 0 0
time-tracking 23 23 0 0 0
journal 20 14 6 0 0
authentication 28 15 13 0 0
sender-selection 6 6 0 0 0
total 702 640 62 0 0
Summary by cubic
Makes the hey skill discovery-first: SKILL.md drops from 79 KB to 15 KB, and agents are pointed to hey <command> --agent --help for anything command-specific. The binary's own help is now the reference instead of a hand‑kept copy.
- Moves the old skill's 702 facts into command help and new
agent_notesannotations, so nothing is lost. - Adds
scripts/skill-coverage/— a one‑off audit ledger pluscheck.pythat proves each fact still appears in the new skill or in--helpoutput. It can be deleted after merge. - Corrects seven help texts that were wrong or contradicted the old skill:
hey auth's login advice, bundle row IDs, blank time‑track categories, contact-note privacy on HEY for Domains, and where a capped listing (e.g.hey search) names its next page. - The only behavioral effect: agents now make one extra local
--helpcall per new command. No flags or mail‑handling behavior changed.