docs(skills): add explicit API reference to agent-message and agent-observe - #920
Open
Xsidz wants to merge 3 commits into
Open
docs(skills): add explicit API reference to agent-message and agent-observe#920Xsidz wants to merge 3 commits into
Xsidz wants to merge 3 commits into
Conversation
added 2 commits
August 8, 2026 15:17
Adds typed function signatures, import pattern, correct broadcast syntax (broadcast_message kwarg, not positional), and explicit list of non-existent functions to prevent agent confusion. Part of fixes PrimeIntellect-ai#762
Adds typed function signatures, import pattern, and explicit list of non-existent functions (observe(), list_messages()) to prevent agents from calling them. fixes PrimeIntellect-ai#762
There was a problem hiding this comment.
Pull request overview
Adds explicit API reference sections to the agent-message and agent-observe skill docs so agents can discover the callable surface (imports + signatures) without runtime introspection, and records the doc update in the coding-agent changelog.
Changes:
- Added
## Import+## API Referencesections with typed signatures toagent-messageandagent-observeskill docs. - Documented broadcast usage and called out common non-existent function mistakes to reduce incorrect tool calls.
- Added an
[Unreleased]changelog entry for the documentation update.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| packages/coding-agent/skills/agent-observe/SKILL.md | Adds import + API reference signatures for observation helpers and documents common non-existent calls. |
| packages/coding-agent/skills/agent-message/SKILL.md | Adds import + API reference signatures for messaging helpers, documents broadcast usage, and common non-existent calls. |
| packages/coding-agent/CHANGELOG.md | Records the doc update under [Unreleased]. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Replace string-literal union "parent" | "sibling" | "child" | None with str | None plus inline comment listing valid values — the union form is not valid Python and would confuse agents copying the snippet.
Xsidz
commented
Aug 8, 2026
Xsidz
left a comment
Xsidz
left a comment
Author
There was a problem hiding this comment.
Fixed in cd906048 — replaced the invalid "parent" | "sibling" | "child" | None union with str | None and moved the allowed values to an inline comment.
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.
Summary
Adds explicit API reference sections to both
agent-messageandagent-observeskill docs so agents can discover the full API without runningdir()+inspect.signature().agent-message:
## Importblock with correct import statement.list_agents()andsend()in Python code blocks.send("all", message)as positional, but the implementation raisesTypeErrorfor that form. Correct usage issend("all", broadcast_message="...").list_messages(),observe()) to prevent incorrect calls.agent-observe:
## Importblock.list_agents(),get_agent(), andrecent_messages()with parameter constraints (limit1–50,max_chars80–2000).observe(),list_messages()).No code changes — doc-only.
Test plan
npm run checkpasses (biome, tsgo, installer render, browser smoke)__init__.pyimplementationsFixes #762
Note
Add explicit API reference sections to agent-message and agent-observe skill docs
agent_message.send()and clarifies constraints onreceiver_role/receiver_namefor direct vs. broadcast messages.agent_message.list_messages(),agent_observe.observe()) to prevent common misuse.Macroscope summarized cd90604.