Fix skill docs: correct commands, box names, and response formats#22
Fix skill docs: correct commands, box names, and response formats#22
Conversation
github-actions
bot
added
the
documentation
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
robzolkos
force-pushed
the
fix-skill-docs
branch
from
2e5f4da to
d769762
Compare
There was a problem hiding this comment.
Pull request overview
Updates the HEY skill documentation to align with the actual CLI command naming and to better explain which IDs to use when reading/replying to threads.
Changes:
- Replace
hey topicreferences withhey threadsin triggers and examples. - Add documentation explaining posting IDs vs topic/thread IDs, and where to find the topic/thread ID.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
robzolkos
force-pushed
the
fix-skill-docs
branch
from
d769762 to
d7c194a
Compare
robzolkos
changed the title
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 4 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| **Response format:** `hey box` returns `{"box": {...}, "postings": [...]}`. Each posting has: `id` (posting ID), `topic_id` (topic ID), `name` (subject), `seen` (read status), `created_at`, `contacts`, `summary`, `app_url`. Use `topic_id` for `hey threads` and `hey reply`. | ||
|
|
There was a problem hiding this comment.
The documented --json response shape for hey box is missing the CLI’s JSON envelope. In code, --json is explicitly "Output as JSON envelope" (it wraps results as {ok: true, data: ...}), while the raw {box: ..., postings: ...} shape corresponds to --quiet. Also, the SDK Posting used by hey box does not include a topic_id field (the CLI parses the thread/topic ID from app_url when it needs it). Please update this section to either (a) describe the envelope (.data.postings[...]) and instruct parsing the topic/thread ID from app_url, or (b) switch the invariant/examples to --quiet if you want to document raw data shapes.
| hey threads <topic_id> --html # Read with raw HTML content | ||
| ``` | ||
|
|
||
| **ID note:** `hey box` returns postings with an `id` (posting ID) and a `topic_id` (topic ID). `hey threads` and `hey reply` expect the **topic ID** — use `topic_id` directly. The `app_url` field also contains the topic ID as a fallback (e.g. `https://app.hey.com/topics/123` → `123`). |
There was a problem hiding this comment.
This ID note says hey box returns both id and topic_id, and recommends using topic_id directly. However, the hey box command uses the SDK posting type (no topic_id field) and derives the thread/topic ID by parsing /topics/<id> from app_url. To avoid misleading users, please rewrite this note to treat app_url parsing as the primary way to obtain the thread/topic ID for hey threads/hey reply, and reserve id as the posting ID used by hey seen/hey unseen.
| ``` | ||
|
|
||
| **Response format:** `hey recordings` returns `{"Calendar::Event": [...]}`. Each event has: `id`, `title`, `starts_at`, `ends_at`, `all_day`, `recurring`, `starts_at_time_zone`. Access events via `.["Calendar::Event"]` in jq. | ||
| **Response format:** `hey recordings` returns recordings grouped by type (e.g. `{"Calendar::Event": [...], "Calendar::Habit": [...], "Calendar::Todo": [...]}`). Each recording has: `id`, `title`, `starts_at`, `ends_at`, `all_day`, `recurring`, `starts_at_time_zone`. Access by type key in jq, e.g. `.["Calendar::Event"]`. |
There was a problem hiding this comment.
The hey recordings response-format description and jq example also omit the --json envelope. With --json, the grouped-by-type map lives under .data, so the example should reference .data["Calendar::Event"] (or document --quiet explicitly if you intend to show the raw map).
| **Response format:** `hey recordings` returns recordings grouped by type (e.g. `{"Calendar::Event": [...], "Calendar::Habit": [...], "Calendar::Todo": [...]}`). Each recording has: `id`, `title`, `starts_at`, `ends_at`, `all_day`, `recurring`, `starts_at_time_zone`. Access by type key in jq, e.g. `.["Calendar::Event"]`. | |
| **Response format:** With `--json`, `hey recordings` returns a JSON envelope where `data` is a map grouped by type (e.g. `{"Calendar::Event": [...], "Calendar::Habit": [...], "Calendar::Todo": [...]}`). Each recording has: `id`, `title`, `starts_at`, `ends_at`, `all_day`, `recurring`, `starts_at_time_zone`. Access by type key in jq, e.g. `.data["Calendar::Event"]`. |
| ├── Read full thread? → hey threads <topic_id> --json | ||
| ├── Mark as seen? → hey seen <posting-id> | ||
| ├── Mark as unseen? → hey unseen <posting-id> |
There was a problem hiding this comment.
In this decision tree, hey seen / hey unseen are shown without --json, but the Agent Invariants above say to always use --json for predictable output (and these commands do emit the normal JSON envelope when --json is set). Consider updating these steps to hey seen <posting-id> --json / hey unseen <posting-id> --json for consistency with the invariant.
- Remove nonexistent hey seen/unseen references - Document topic_id as primary source instead of app_url parsing - Use <topic_id> placeholders in Quick Reference table
Summary
hey topicreferences withhey threads(the actual command name)the_feed,paper_trail, etc. →feedbox,trailbox,asidebox,laterbox,bubbleboxhey habit complete/uncomplete— was missing required<id>argumenthey recordingsresponse format — documents multiple type keys, not justCalendar::Event--thread-idflag tohey composedocs