Repository navigation
Conversation
Apply the Claude 5-generation context-engineering rules: progressive disclosure over upfront detail, a single source per instruction, and expressive descriptions instead of worked examples. - Strip <examples> blocks from six agent descriptions and rewrite them to route on their own. Those blocks were concatenated into every request, costing ~2,400 tokens per turn for agents dispatched by name anyway. - Merge when_to_use into description so the trigger surface has one source. - Extract the procedures duplicated across skills into shared references: feature-branch.md (brainstorm, plan, debrief) and review-dispatch.md (build, hotfix, review). - Demote run-time detail out of SKILL.md bodies: commit-autonomy.md and ship-gate.md (build), plan-authoring.md (plan), issue-previews.md (debrief). - Drop trailing Important / Key Principles blocks that restated the body, moving each load-bearing line to the step it governs. - Document the KEEP / DEMOTE / DELETE rubric and the agent-description rule in CONTRIBUTING.md, with a pointer from AGENTS.md. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Second pass over the same surface, run through the claude-api skill's
prompt-audit workflow against the Claude 5 generation. The first commit
restructured where instructions live; this one fixes the instruction text
itself.
Under-described (the fix is more text, not less):
- Expand four agent descriptions that stated neither what the agent
returns nor when not to use it — pr-readiness, best-practices-research,
official-docs-research, and user-flow-analysis. These are the four the
first commit never touched, since only the other six carried <examples>.
- Give skills/hotfix a trigger surface. It was the one skill with no
trigger phrases at all, having never had a when_to_use field to merge.
Dated prompt text:
- Drop role inflation that substituted for context ("elite", "seasoned
Senior Engineer", "knows all the ins and outs"). Role lines that pair
the role with its reason are left alone.
- Remove the "Your mission" list in user-flow-analysis that the section
headings below it already restate, plus "Be exhaustively thorough" —
current models are proactive by default.
- Normalize caps emphasis: "MANDATORY Deprecation Check" and four
"DO NOT proceed until..." gates.
- Fix a drifted duplicate: hotfix capped PR titles at 70 characters,
create-pr and conventional-commits at 72.
Left alone deliberately: trigger-phrase enumeration in skill descriptions
(routing text, and changing it without a trigger eval is guessing), and
the YAGNI/testing prohibitions, which encode VGV policy from AGENTS.md.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
ryzizub
changed the title
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.
Description
Applies the Claude 5 context-engineering rules to every skill and agent. Same prep as vgv-ai-flutter-plugin#152.
Two commits:
SKILL.mdbodies intoreferences/, each instruction gets one source, and<examples>blocks come off agent descriptions. Those blocks rode in every request — for agents the skills call by name, so they bought no routing.claude-apiskill'sprompt-auditrun over the result. Four agent descriptions said neither what they return nor when not to use them;/hotfixhad no trigger phrases at all. Both fixed by adding text, not cutting it.CONTRIBUTING.mdnow carries the KEEP / DEMOTE / DELETE rubric, so the next skill gets the same treatment without rediscovering it.Type of Change
feat)fix)refactor)docs)ci)chore)What a reviewer should know
success-criteriacontract are untouched.when_to_usewas merged intodescription, not dropped. Claude Code appends it to the skill listing, so deleting it would have lost trigger phrases.🤖 Generated with Claude Code