[potiuk]

Summary

• Teaches optimize-skill what eperf(skills): load conditional shared text only when it applies #1996–perf(security-issue-sync): read conditional Step 1 sub-steps only when they apply #1998 had to learn the hard way: how to prove a pointer works, and to compare prose with a tool before cutting it.
• Adds a run cost estimate per path, because the SKILL.md body understates what an invocation reads: security-issue-sync has a body of about 6k tokens, but a routine run reads about 46k.
• Adds pointer-routing eval steps for the pointers still untested.

New optimize-skill guidance:

• Name every trigger in a pointer, leave the heading in place, and keep the sibling in the same directory.
• Add a pointer-only eval whose output spec names no file, and run it against a copy with the pointers deleted.
• Before cutting prose because a tool "already does this", compare the two line by line; where they disagree, fix the tool first, with a failing test.
• Estimate the run cost for the routine and heaviest paths, keeping tool output separate and labelling it a guess.

The guidance sits inside the existing Split section, so no heading is added and no surface_hash moves.

Type of change

• Skill change (.claude/skills/<name>/) — eval fixtures updated below

Test plan

• prek run --all-files --skip workspace-pytest passes, including lychee
• workspace-pytest passes for the changed files
• Validator exits 0; no surface_hash changed
• optimize-skill evals: 7/7 before and after
• New pointer-routing steps, 8 suites: 19/19 on the real skills; with the pointers deleted, all 11 cases that need a file fail and all 8 that need none pass

security-model-verify case-1 failed once on the real skill, returning two files. Step 6 uses helper.md and templates.md, so the fixture now says they are already open, with the same expected answer. It then passed 3/3 and failed on the copy without pointers. The runner does not show the extra file, so the cause is likely rather than confirmed.

Linked issues

Follows #1996, #1997, #1998.

Notes for reviewers

• The optimize-skill suite cannot prove the guidance works. It only shows that diagnosis did not change.
• Sweep ranking is unchanged. Run cost is reported and preferred when choosing a pass, but Step 1 still ranks by cap overflow and smells, which is what step-diagnose reads.
• pointer-routing records a stated decision. The agent says which files it would open; it does not run with file tools.
• Single model. No cross-model pass and no adversarial review were run.

🤖 Generated with Claude Code