docs(skills): round-8 DX polish — scope seller, self-contain signals#242
Merged
docs(skills): round-8 DX polish — scope seller, self-contain signals#242
Conversation
Bundles two round-8 validation findings. Pure docs changes to skills/*/SKILL.md; no code surface. #215 — seller skill scoping (Option A) Rewrite the Validation section of build-seller-agent/SKILL.md to scope the skill's promise explicitly to the 9 core media_buy_seller scenarios. Fresh users read "9/9 passing" then see "WARN: partial" on the full storyboard and doubt the skill — this section explains that the advanced tracks (governance_denied, pending_creatives, measurement_terms, inventory_list_targeting, invalid_transition, delivery_reporting/simulate_and_verify) require additional stubs this skill deliberately doesn't teach, and points to the doc or handler pattern for each. #216 — signals skill self-containment Inline the minimal sync_accounts + sync_governance bodies into build-signals-agent/SKILL.md's Governance Tracks section. Drops the "see examples/seller_agent.py" cross-reference — the last external jump in an otherwise self-contained skill. Round-8 observed signals went from 12 min + 3 attempts to 4 min + 1 attempt after round-7's section addition; this closes the remaining ~2-minute tax of cross-referencing the seller example. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This was referenced Apr 20, 2026
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
Bundles two round-8 validation findings into one docs-only PR. Closes #215 and #216.
#215 — seller skill scoping (Option A)
Rewrite the Validation section of `build-seller-agent/SKILL.md` to explicitly scope the skill to the 9 core `media_buy_seller` scenarios. Round-8 observed fresh users seeing `WARN: partial` on the full storyboard and doubting the skill. Adds a track-by-track breakdown of the ~13 advanced scenarios the skill deliberately doesn't teach, with pointers for wiring them up independently (governance, creative lifecycle, measurement, targeting persistence, state machine, delivery).
#216 — signals skill self-containment
Inline minimal `sync_accounts` + `sync_governance` bodies into `build-signals-agent/SKILL.md`'s Governance Tracks section (~25 lines). Drops the "see `examples/seller_agent.py`" cross-reference — the last external jump in an otherwise self-contained skill.
Why bundle
Both findings come from the same round-8 validation report, both are skill-polish docs, both touch `skills/*/SKILL.md` — zero risk of merge conflicts, identical review context, and one PR is less process than two for ~55 lines of docs.
Test plan
🤖 Generated with Claude Code