docs: surface response contracts per tool in docs/llms.txt#761
Closed
bokelley wants to merge 1 commit into
Closed
Conversation
Each tool section now emits a "Response (success branch)" block with the required + optional fields, mirroring the existing request block. Pulled straight from the bundled JSON schemas; zero new source of truth. Closes the drift path matrix runs kept surfacing — agents dropped required response fields (missing format_id on creative_manifest, plural hallucinations like creative_deliveries for creatives, missing top-level currency) because the skill prose documented intent but the full per-field contract lived in the generated schemas and was never indexed in the llms.txt file Claude actually reads. Anchored sections let skills point at docs/llms.txt#<tool> instead of embedding the contract inline — keeps skills lean.
Merged
3 tasks
bokelley
added a commit
that referenced
this pull request
Apr 22, 2026
…slim on creative-agent (#762) * docs: surface response contracts per tool in docs/llms.txt Each tool section now emits a "Response (success branch)" block with the required + optional fields, mirroring the existing request block. Pulled straight from the bundled JSON schemas; zero new source of truth. Closes the drift path matrix runs kept surfacing — agents dropped required response fields (missing format_id on creative_manifest, plural hallucinations like creative_deliveries for creatives, missing top-level currency) because the skill prose documented intent but the full per-field contract lived in the generated schemas and was never indexed in the llms.txt file Claude actually reads. Anchored sections let skills point at docs/llms.txt#<tool> instead of embedding the contract inline — keeps skills lean. * docs(skills): point at llms.txt for field contracts; slim creative-agent Every build-*-agent skill's "Tools and Required Response Shapes" section now opens with a canonical-contracts pointer directing Claude at the anchored llms.txt section for per-tool request + response fields — one source of truth, refreshed on every schema sync. build-creative-agent gets a surgical slim: the verbose response-shape blocks (which duplicate llms.txt verbatim now that #761 landed) are collapsed into a compact handler-binding table. Gotchas and anti- patterns stay; field enumerations move to llms.txt. Net -94 lines, same signal. The other 7 skills get the pointer line only — follow-up passes can do per-skill surgical slims once the pattern is validated. With strict response validation default in dev (#727/#757), drift between a skill example and the schema now fails immediately at the call site with the exact field path. The skill's job is to document patterns/gotchas; the schema's job is to enforce shape. This separation was muddied when every skill tried to re-state the shape inline. * docs(skills): imperative callout + anchor column per expert review Experts flagged the passive "contracts live at X" wording — Claude doesn't follow pointers without an imperative trigger. Rewrote to lead with "Before writing any handler's return statement, fetch docs/llms.txt and grep for #### \`<tool_name>\`" and reframed the validation safety-net from threat to permission. Applied to all 8 skills. Added a per-row Contract column to the creative-agent handler-binding table with direct anchor links — more reliably followed than a general pointer three lines up. Regenerated schemas/types (upstream context-object shift) and widened si-session-manager.ts generateInitialResponse signature from string to unknown so the overrides accept the new ContextObject shape. Unblocks CI's Validate generated files check.
Merged
Contributor
Author
|
Closing as superseded. PR #762 (merged 2026-04-22T02:55Z) already landed this change — Net delta of this branch vs current |
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
1 participant
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
Extends the existing `generate-agent-docs` generator so each tool section in `docs/llms.txt` emits a Response (success branch) block with required + optional fields, mirroring the existing request block. Pulled straight from the bundled JSON schemas — no new source of truth.
Example (build_creative)
Before (request only):
```
`build_creative`
Request parameters for AI-powered creative generation.
Required: `idempotency_key: string`
Optional: `message`, `creative_manifest`, `creative_id`, ...
```
After (request + response):
```
`build_creative`
Request parameters for AI-powered creative generation.
Request:
Response (success branch):
```
Why
Matrix runs kept surfacing the same drift pattern: agents dropped required response fields — missing `format_id` on `creative_manifest`, plural-variant hallucinations (`creative_deliveries` → `creatives`), missing top-level `currency` — because the skill prose documented the intent but the full per-field contract lived in the generated schemas and was never indexed in the llms.txt file Claude actually reads when building an agent.
With this, the contract is one anchored section away (`docs/llms.txt#build_creative`), and skills can lean on pointer references instead of embedding the contract inline.
Test plan
Follow-ups (separate PRs)