Repository navigation
Update plugin-builder guidance for Opus 5.5 - #219
Merged
Merged
Conversation
han-plugin-builder teaches authors to write for Sonnet 5, Opus 5, and
Fable 5 as checked on 2026-07-31. Opus 5.5 has shipped, and it refuses
reasoning-echo instructions, cannot turn thinking off, reads effort
levels differently, and stops long runs early to report.
Evaluate the whole plugin against the Opus 5.5 article (primary), the
"How we use skills" post, the context-engineering post, and Anthropic's
Opus 5.5 prompting page. Twenty-eight candidates went through
adversarial validation; eighteen change entries survive, in five units:
- Per-model facts: add Opus 5.5 to per-model-authoring.md and its four
mirrors, extend the reasoning-echo warning, the thinking clause, the
effort re-test note, and separate vague review limits from a checkable
bar.
- Long runs and delegation: name the stops an autonomous stretch should
and should not make without touching collaborative stops, bound
unbounded steps with a finish line and a task file, check fanned-out
evidence, and wait for background dispatches.
- Instruction style: a limit on "be specific", a removal bullet for
instructions restating model defaults, and a gotchas category.
- Baseline skill patterns: verification skills, skill state kept in
${CLAUDE_PLUGIN_DATA}, helper-script libraries, and a skill-scoped
guardrail hook.
- Builder routing: skill-builder and agent-builder read and review
against the per-model guide.
The operator approved all four behavior-changing decisions. The plan,
its decision log, the current-state findings, and the scope boundary
live in docs/plans/opus-5-5-plugin-builder-guidance/. No plugin file
changes in this commit.
The per-model guide covered Sonnet 5, Opus 5, and Fable 5 as checked on 2026-07-31. Opus 5.5 has shipped with behavior that changes what an author writes. - Name Opus 5.5 and state that it inherits the Opus 5 guidance except where a section says otherwise, per Anthropic's Opus 5.5 page. - Extend the reasoning-echo warning to Opus 5.5 and name the reasoning_extraction refusal category. - Note that Opus 5.5, like Fable 5, cannot turn thinking off. - Tell authors that effort names mean more thinking on Opus 5.5, and to re-test a pinned effort value rather than carry it over. - Keep the warning against vague review limits, and add that a limit naming a checkable bar with per-item evidence is fine. - Add the Opus 5.5 sources and a Contents list. Mirror the model list in the guidance router, the portable router, the rule index, and the specialization guide, and point both frontmatter tables' effort rows at the effort guidance. Plan: docs/plans/opus-5-5-plugin-builder-guidance (Unit 1, S-1 to S-6).
Opus 5.5 works longer on its own and sometimes ends a turn with a progress report instead of the next step. The guidance covered deliberate human gates, but not that. - workflow-patterns.md: name the stops an autonomous stretch should and should not make, and keep the keep-going instruction out of any skill built to hand control back. Bound a step that works through an unknown number of items with a checkable finish line and a checklist file that survives context summarization. - multi-agent-economics.md: when fanning out, check each subagent's cited evidence before accepting its finding, and do not finish while a run_in_background dispatch is still running. - agent graceful-degradation.md: a research or analysis agent marks a claim it could not confirm and says where it looked. - per-model-authoring.md: name Opus 5.5's early-stop behavior and link the pattern. - agent-builder Step 6 item 8 names both degradation rules, and the rule index describes the widened files. The stop-naming section describes collaborative stops rather than linking han-core's collaborative-stop rule, because this guidance is vendored into other repos by `guidance init`, where that link would not resolve. Plan: docs/plans/opus-5-5-plugin-builder-guidance (Unit 2, S-7 to S-10).
Anthropic's skills and context-engineering posts report that Claude 5 generation models are over-constrained by blanket rules, that restating default behavior adds tokens without changing output, and that a gotchas list is the highest-signal content a skill carries. The guidance pushed toward specificity with no limit, removed only toolchain-enforced rules, and had no gotchas category. - writing-effective-instructions.md: spend specificity where a miss breaks something, and leave out rules for details the model gets right unprompted. The rule governs instruction detail, not whether a step is fixed, and links the entity taxonomy's flowchart test. - progressive-disclosure.md: list instructions that restate model defaults as removable, and name gotchas as a reference category. - skill-reference-files.md: define gotchas as failure points found in use, distinct from a checklist or a canonical example. - Rule index describes the widened files. Plan: docs/plans/opus-5-5-plugin-builder-guidance (Unit 3, S-11 to S-13).
…s, and skill hooks
Anthropic's skills post describes four patterns the guidance lacked.
- success-criteria-and-testing.md: how to build a skill whose job is
verifying a running product: pair it with a driver, assert state at
every step, and record the run.
- plugin-json-options.md: keep a plugin-shipped skill's first-run
answers and run history in ${CLAUDE_PLUGIN_DATA}, never in the skill
directory, which ${CLAUDE_PLUGIN_ROOT} replaces on update. Name
userConfig, hand-edited files, and repo-checked-in skills as the
cases that need something else. allowed-tools-AskUserQuestion.md
links to it.
- hardening-fuzzy-vs-deterministic.md: a library of helper functions
the model composes into one-off scripts, which still prompt for
permission. Adds a Contents list now that the file is over 100 lines.
- skill-frontmatter-fields.md: a skill-scoped hook lasts only for the
run, which suits a guardrail such as blocking destructive commands.
- Rule index describes the widened files.
The state section does not say whether saving to ${CLAUDE_PLUGIN_DATA}
prompts for permission, because no source this plan used states it.
Plan: docs/plans/opus-5-5-plugin-builder-guidance (Unit 4, S-14 to S-17).
…r-model guide Neither builder read per-model-authoring.md or reviewed against it, so the Opus 5.5 guidance reached only people who asked the guidance skill directly. - Both decision tables route "instructions for a named target model" to per-model-authoring.md. - Both Step 6 reviews gain a model-specific-leftovers item: no "think step by step" line, no instruction to reproduce reasoning in the reply, no pinned effort without a stated reason, and no vague limiting phrase in a review step, with one passing and one failing example quoted. - skill-builder's progressive-disclosure item also cuts instructions that restate a default the model already follows, matching the guidance change in progressive-disclosure.md. Also rewraps the specialization guide's per-model cross-reference, which the Opus 5.5 addition pushed past 120 characters. Plan: docs/plans/opus-5-5-plugin-builder-guidance (Unit 5, S-18).
…ection Found by the /han-update-documentation pass over the branch.
…lder docs The skill-builder and agent-builder long-form docs now say the review pass strips model-specific leftovers and that per-model authoring is a governing document in the design-tree map, matching the SKILL.md changes on this branch. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ilder Checks the plugin-builder guidance against Anthropic's current pages for Opus 5.5, Sonnet 5.5, Haiku 5.5, Fable 5.1, and Claude Code's model settings, with adversarial validation. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…-model guide - Widen the reasoning-echo section to every current model and list the four trigger shapes, including a reasoning field in an output format - Scope the cut-verification advice to Opus; Sonnet 5.5 and Haiku 5.5 skip checks at low effort and need the instruction kept - Add Claude Code's thinking and effort defaults for the 5.5 models - Add early-stop and scope habits for Sonnet 5.5 and Haiku 5.5 - Quote the Fable claim as Anthropic words it; fix the review-prompt attribution to the blog post Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Subagent model order is now dispatch, frontmatter, env var, main model (v2.1.251+), with CLAUDE_CODE_SUBAGENT_MODEL_FORCE to override - An omitted model is not the same as inherit - Add the fable alias; note that aliases resolve by provider - Explore now runs on the main session's model; link the live table - Note Haiku 5.5's subagent fit and its low-effort habits Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…he 5.5 models - Builders' model-specific review check now flags a reasoning, thinking, or trace field, a scratchpad section, or a running reasoning log - Name model families instead of a fixed four-model list in the guidance skill, its portable copy, the rule index, and the specialization guide - Replace an unsourced Haiku claim in the testing guide with the documented Haiku 5.5 behaviors Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Move the two Anthropic links off the old docs hosts to their current platform.claude.com pages - Re-quote both Anthropic passages from the current wording; the old quotes no longer appear on either page - Say thinking depth rather than thinking budget, since budget_tokens is gone on the 5.5 models - Point the dead Deepgram link at its Wayback Machine snapshot Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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
2 participants
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 updates the
han-plugin-builderauthoring guidance and its two builder skills for the Claude 5.5 models (Opus 5.5, Sonnet 5.5, Haiku 5.5, and Fable 5.1), so that new skills and agents stop carrying instructions that current models refuse, ignore, or no longer need.Behavior changes
The main runtime change is in
skill-builderandagent-builder. Both now send authors to the per-model guide (per-model-authoring.md) whenever a target model comes up. Their final review (Step 6) has a new item that catches leftovers tied to a specific model. It flags "think step by step" lines, any request that the model reproduce its reasoning, and output formats with areasoning,thinking, ortracefield, a scratchpad section, or a running reasoning log. Every current model now refuses that kind of request, which shows up as areasoning_extractionrefusal, so the check is no longer limited to Fable 5 and Opus 5.5. The item also flags a pinnedeffortvalue with no stated reason, and vague review limits such as "only report high-severity issues." A limit passes when it names a bar the reader could check and asks for evidence on each item.Two existing review items are stricter.
agent-buildernow requires a research or analysis agent to mark each claim it could not confirm and say where it looked.skill-buildernow counts an instruction that restates something the model already does by default as removable.The rest of the branch is guidance text that the builders and
/guidanceread:${CLAUDE_PLUGIN_DATA}), helper-script libraries, and hooks scoped to one skill's run.All model facts come from Anthropic's own docs, checked 2026-10-15. The planning and research behind each change are in
docs/plans/opus-5-5-plugin-builder-guidance/. Repos that vendored this guidance with/guidance initget it on/guidance update, so mention that in the release notes. The branch also carries one unrelated note,docs/plans/fix-ci-lint-evals-prettier/investigation.md, which investigates a CI lint failure.