Repository navigation
Conversation
Box, bundle, thread, search, label, collection, Set Aside, attachment and watch help now carry the facts the skill's Resource Reference held for them. A bundle row's topic_id and the IDs collection add and remove take were stated wrongly and are corrected.
Move, trash, spam, bubble, screener, bulk-reply, draft, reply and compose help now carry the skill's facts for them. draft send no longer contradicts itself about retrying a refused send.
hey auth no longer tells agents to check status before every command or to log in with --token unattended, which the skill forbids. A contact note is the account's, so on HEY for Domains everyone there sees it.
Event, calendar, todo, journal, habit and timetrack help now carry the skill's facts for them. A blank time track category is refused with a usage error; the help and docs said it was ignored.
SKILL.md drops its command catalog (79 KB to 15 KB) and sends agents to hey <group> <subcommand> --agent --help, keeping only what spans commands: ID kinds, output shapes, send outcomes, read-then-write recipes and the authentication rules. A test holds it under 16 KiB, leaf help before root help, with no catalog sections. Closes #408
scripts/skill-coverage splits the skill as it stood at 76ea03f into 702 facts and checks each against a ledger naming where it lives now: a command's --agent --help output or the new SKILL.md. Each ledger line quotes the text, and the check fails when the quote is not there.
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The discovery guidance can hide shared-note visibility and cause agents to mistake capped listings for complete results.
2 open issues
What changed in this PR
Makes the HEY skill discovery-first by moving command details into the CLI’s help while retaining shared safety guidance.
Changes:
- Replaces the large command catalog with leaf-help discovery.
- Expands command help and corrects existing documentation.
- Adds a coverage ledger and discovery-focused tests.
[!TIP]
If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or rungh pr ready --undo.
Click "Ready for review" or rungh pr readyto reengage.
| File | Description |
|---|---|
| skills/embed_test.go | Enforces skill size and discovery guidance. |
| scripts/skill-coverage/ledger/f-journal-auth.tsv | Maps journal and authentication facts. |
| scripts/skill-coverage/ledger/e-calendar-time.tsv | Maps calendar and time-tracking facts. |
| scripts/skill-coverage/ledger/d-mail-actions.tsv | Maps mail-action facts. |
| scripts/skill-coverage/ledger/c-contacts-threads.tsv | Maps contact and thread facts. |
| scripts/skill-coverage/ledger/b-mail-reading.tsv | Maps mail-reading facts. |
| scripts/skill-coverage/ledger/a-head.tsv | Maps shared rules and command references. |
| scripts/skill-coverage/check.py | Checks quoted coverage evidence. |
| scripts/skill-coverage/apply.py | Applies ledger corrections. |
| internal/cmd/watch.go | Documents watch output and script execution. |
| internal/cmd/tui.go | Adds agent-facing TUI guidance. |
| internal/cmd/trash.go | Clarifies bundle handling. |
| internal/cmd/topic.go | Expands thread-reading guidance. |
| internal/cmd/todo.go | Documents date windows and validation. |
| internal/cmd/timetrack.go | Corrects category and export guidance. |
| internal/cmd/spam.go | Clarifies bundle handling. |
| internal/cmd/skill_commands_test.go | Supports discovery placeholders and help flags. |
| internal/cmd/setup.go | Documents setup side effects. |
| internal/cmd/set_aside.go | Explains group lifecycle and pagination. |
| internal/cmd/search.go | Documents filtering and pagination limits. |
| internal/cmd/screener.go | Explains the Screener’s purpose. |
| internal/cmd/reply.go | Expands reply and dry-run guidance. |
| internal/cmd/recording_filter.go | Shares date-window help text. |
| internal/cmd/omarchy.go | Explains explicit agent installation. |
| internal/cmd/move.go | Clarifies Reply Later behavior. |
| internal/cmd/label.go | Documents pagination and duplicate names. |
| internal/cmd/journal.go | Clarifies empty entries and safe writes. |
| internal/cmd/help_test.go | Allows literal wire-field terminology. |
| internal/cmd/habit.go | Documents defaults and editing semantics. |
| internal/cmd/events.go | Expands event and occurrence guidance. |
| internal/cmd/events_period.go | Documents occurrence and countdown output. |
| internal/cmd/drafts.go | Explains scheduled draft visibility. |
| internal/cmd/draft.go | Clarifies scheduling and send retries. |
| internal/cmd/contacts_update.go | Documents contact-edit restrictions. |
| internal/cmd/contacts_show.go | Explains filtering embedded threads. |
| internal/cmd/contacts_list.go | Documents listing scope and lookup. |
| internal/cmd/contacts_hide.go | Explains hiding instead of deleting. |
| internal/cmd/contacts_deliver.go | Clarifies blocking terminology. |
| internal/cmd/contacts_deliver_test.go | Updates expected routing guidance. |
| internal/cmd/contact_note.go | Adds account-visibility guidance. |
| internal/cmd/contact_note_set.go | Documents replacement and write constraints. |
| internal/cmd/contact_note_delete.go | Documents deletion restrictions. |
| internal/cmd/compose.go | Clarifies sender and body-input behavior. |
| internal/cmd/collection.go | Corrects ID guidance and documents pagination. |
| internal/cmd/calendars.go | Describes calendar output fields. |
| internal/cmd/bundle.go | Corrects bundle thread-ID guidance. |
| internal/cmd/bulk_reply.go | Documents validation and delivery results. |
| internal/cmd/bubble_list.go | Describes automatic scheduling output. |
| internal/cmd/box.go | Expands box, bundle, and pagination guidance. |
| internal/cmd/auth.go | Replaces login preflight advice. |
| internal/cmd/attachments.go | Explains attachment identifiers. |
| internal/cmd/attachments_save.go | Clarifies destination-path handling. |
| docs/cli.md | Corrects blank-category documentation. |
Review effort: Balanced
Agents now read leaf help, and hey contact note set's help called the note private without the HEY for Domains warning its parent carries.
hey search and hey contact list number their pages and name the next one in notice, not next_page, so the skill no longer says every listing pages by cursor.
Contributor
Author
|
Review status at 1fa62f9:
|
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The hey skill was 79 KB, loaded whole on every
/hey, and three quarters of it was a hand-kept copy of whathey <command> --helpalready serves. This does #408 the way the issue's maintainer comment settled it, modelled on basecamp/basecamp-cli#835: noreferences/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.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
--agent --helppointer, which the issue names as the trigger for thereferences/fallback.Tradeoffs
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.Blast Radius
Agents using the skill now make one extra local
--helpcall 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.Coverage before (current binary, nothing deleted)
Coverage after
Summary by cubic
Makes the
heyskill discovery-first:SKILL.mddrops from 79 KB to 15 KB, and agents are pointed tohey <command> --agent --helpfor anything command-specific. The binary's own help is now the reference instead of a hand‑kept copy.agent_notesannotations, so nothing is lost.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.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.--helpcall per new command. No flags or mail‑handling behavior changed.Written for commit 1fa62f9. Summary will update on new commits.