docs(guidance): update per-model authoring for Claude Opus 5 - #165
Merged
Conversation
The per-model authoring guidance named Opus 4.8 as the current Opus and stated its thinking is off unless enabled. Opus 5 reverses that: thinking is on by default and can be disabled only at effort high or below. Retarget the document to Sonnet 5, Opus 5, and Fable 5, and add the Opus 5 behaviors that have no equivalent in the older guidance: - Instructions to leave out, since Opus 5 verifies and self-corrects unprompted and the older phrasings compound with that behavior. - Calibration for conversational length, written deliverable length, progress and correction narration, and scope, none of which effort reaches. - The literalism trap where a "only report high-severity issues" review instruction is followed literally, so filtering belongs in its own step. Give multi-agent-economics.md the delegation policy a skill should state, because the model's default is eager: no delegating work finishable in a few tool calls, never an agent to verify the dispatching skill's own work, and prefer one agent to several. The Level 1 worker-plus-reviewer cascade is unchanged; a specialist reviewing from a different perspective is not a self-check. Sweep the four surfaces naming the model trio, and drop the pinned claude-opus-4-8 example from agent-model-selection.md in favor of the alias, which does not go stale.
Removes the external reference to evidence-rule.md and states the evidence content the agent acts on inline, per the agent-building guidance requirement that agent files be self-contained. Refs W-2.
Replaces every external reference to yagni-rule.md and evidence-rule.md with a plain-text naming of the rule, per the W-2 ruling. Each agent already stated the rule content it acts on inline, so no operative content moved and the net line change is zero. Refs W-3.
…arget Trims the nine over-length descriptions down the guidance's priority ladder, moving domain vocabulary and restated process prose into the body sections that already carry them. Restores twelve unique routing anchors the first pass dropped, and repairs all nineteen one-way boundary pairs across the roster. Refs W-4.
Records every agent's model tier against a named archetype so the assignment is auditable, and removes five git permissions no agent body exercised. Two tier mismatches are raised rather than changed, because model tier governs behavior on every future run. Refs W-5.
Splits fifteen over-length role identities at their sentence boundary so each fits the 50-token budget with no content lost, removes two flattery hits, and adds the four missing Domain Vocabulary and Anti-Patterns sections. Five agents exceeding the anti-pattern range are recorded with reasoning rather than cut. Refs W-6.
…uidance The tone anti-pattern sweep in on-call-engineer, and the matching directive in the code-review brief, were review passes over output the same run produced. Both now apply while findings are written. All four named anti-patterns survive. The readability-editor fact check is kept: its rule is scoped to Opus 5 and that agent is pinned to sonnet. Refs W-7.
…mespace a bare dispatch Adds the missing length-and-scope directive to the one file-writing skill that had neither its own nor a shared rule to cite, and qualifies the one bare agent name found across all forty skills. Refs W-8, W-9.
Frontmatter reaches the system prompt, where angle brackets carry meaning, so the security rule bans them in every field. Three argument-hints used <placeholder> syntax; each now uses the plain descriptive form the other skills already use. Refs W-10.
Six consolidation candidates recorded with confidence levels and no action taken; skill and agent counts unchanged at 40 and 24. The documentation sync found nothing stale: the sweep's description changes were compression, and every index entry and README scent line describes the agent rather than the description text. Refs W-19, W-20.
Sixty of 64 entities pass every mechanically checkable item. The four failures are all the 500-line body ceiling, owed by the trim work items that remain open. Refs W-21.
…ling Extracts the review-team roster and briefs, the per-finding resolution mechanics with the YAGNI paths and scope gate, the artifact cross-reference invariants, and the mechanic-routing rule into four new reference files. Compresses the operating principles, Step 1.5, and the size-override paragraph, and replaces the duplicated spec-section list and readability checklist with pointers to the template and the canonical rule that already carry them. 746 to 500 lines. No step loses a rule; each now reads it where it lives. Refs W-11.
mxriverlynn
force-pushed
the
claude-5th-gen-guidance
branch
from
July 31, 2026 15:23
23b618b to
d01abe6
Compare
…e ceiling Extracts team selection with its size bands and domain-scoped briefs, the deterministic round aggregation, the three-gate YAGNI and scope sweep, and the synthesis directives with their record invariants into four new reference files. 801 to 458 lines. No step loses a rule; each now reads it where it lives. Refs W-11.
Extracts agent selection, brief scoping, domain-scoped file lists, and the per-agent dispatch prompts into agent-dispatch.md, and the self-consistency and structural output checks into output-verification.md. Sub-step numbering is preserved where the content now lives, and Step 3 names the reference so every existing Step 3.2 to 3.5 citation still resolves. 770 to 497 lines. Refs W-12.
543 to 464 lines. All forty skill bodies are now under the 500-line ceiling. Refs W-13.
Nineteen skills carried the six-point self-check verbatim, each having already sourced the canonical rule that defines it. Each now runs the standardized check by name and keeps only the criteria that are its own, layered on top: the ADR heading caveat, research's A# registry check, manual-test-planning's category-parity check, stakeholder-summary's non-technical vocabulary list, and html-summary's supplementary terms. 109 net lines removed. Every skill verified to source the standard before the step that runs the check. Refs W-14, W-15, W-16, W-17.
…skills The paragraph restated precedence, relative-path resolution, and the degradation note that config-rule.md already owns and every copy already linked. Each skill keeps the load-bearing part inline, since it is the skill's first action, and cites the rule for the rest. 80 lines removed across the suite. Refs W-14, W-15, W-16, W-17, W-18.
…ce set The agent description-length doc carried a byte-identical copy of the skill doc's measuring snippet, and troubleshooting repeated the stale-script before-and-after that documentation-maintenance owns. Both now cite the file that holds it. No rule changed. 38 lines removed. The six uncited files are marketplace and plugin configuration guidance, outside the skill-and-agent set the checklists cover. Refs W-18, W-22.
All 64 entities pass every mechanically checkable item. The four 500-line ceiling failures from the first verification run are closed. Refs W-21.
… readability steps
mxriverlynn
marked this pull request as ready for review
July 31, 2026 17:27
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
This PR brings every skill and agent definition into conformance with the updated authoring guidance and refreshes that guidance for Claude Opus 5, so agent routing, delegation cost, and output length behave predictably on the current model.
Behavior changes
The authoring guidance now targets Opus 5 instead of Opus 4.8, and that changes what skills tell the model to do. It names instructions to delete because the model already does them unprompted, such as self-verification passes and "double-check your answer." It warns that limiting phrases such as "only report high-severity issues" are followed literally and shrink what a run reports. It adds direction on response length, progress narration, and scope, because Opus 5 runs longer and widens scope on its own judgment. And it tells any skill that dispatches sub-agents to state a delegation policy, since Opus 5 reaches for delegation more readily than earlier models.
The sweep then applies that guidance to all forty skills and twenty-four agents. An agent's frontmatter description is the routing surface Claude reads when picking an agent. Nine descriptions ran over the 1024-character target; the fix moved domain vocabulary and restated process prose into the body while keeping the routing anchors. The sweep also repaired nineteen one-way boundary pairs, where one agent deferred to another that did not defer back. Agent files are now self-contained. An agent runs inside the user's project, where a relative link into the plugin folder resolves to nothing, so those links are gone, and each agent now states inline the slice of the shared rule it acts on. Four skill bodies over the 500-line ceiling moved reference material into
references/files, with no step losing a rule.The remainder is duplication removal with no rule change. Nineteen skills stop restating the canonical readability self-check verbatim; they now run it by name, keeping only the criteria unique to them. Every skill also compresses the personal-config paragraph down to its load-bearing first action, plus a citation of the config rule.
What to look at first
han-plugin-builder/skills/guidance/references/per-model-authoring.md. The Opus 5 material drives every other change in this PR, and its own Sources section flags it as single-vendor and not independently corroborated. Decide whether you accept it before evaluating what it caused.docs/plans/skill-agent-guidance-conformance-sweep/artifacts/self-verification-sweep.md. Records a real tension: the per-model guidance says cut steps that re-check the model's own work, while the readability rule mandates a self-check. It explains whyreadability-editorkeeps its fact check and the other skills keep theirs.docs/plans/skill-agent-guidance-conformance-sweep/artifacts/agent-self-containment-ruling.md. The self-containment decision, the three alternatives rejected, and the drift it knowingly accepts: eleven agents each restating their slice of a shared rule in their own words.plan-a-feature,plan-implementation,code-review,iterative-plan-review) and their newreferences/files. The risk here is a rule lost or a cross-reference broken in the move;code-reviewin particular preserves sub-step numbering so existing citations still resolve.