instruction-calibration

name	instruction-calibration
description	Read before empirically tuning a reusable skill or agent prompt.
last-changed	2026-08-23

For reusable skill structure, also load an applicable skill-authoring skill. This skill owns behavioural calibration, not package shape.

Define the delta

1. Start from a real request, observed failure, or explicit correction.
2. State the behaviour that should change and what must remain unchanged.
3. Prepare a small probe set:
   • the natural request that exposed the failure
   • the nearest request that should produce a different choice
   • an unrelated request where the instruction should stay out of the way
4. Give test agents only the task and context they cannot access. Do not hide the desired method inside the probe.

Keep the user in the comparison

• The easiest setup is tmux or Herdr, with each tested agent in a visible sibling pane beside the current session. Preserve the current workspace, working directory, and user focus unless the comparison requires another environment. In Herdr, consult herdr --skill.
• Do not hide calibration in a background subagent or detached process.
• Inspect the tested coding agent's current help for controls over context files, reusable instructions, skills, plugins, and extensions. Start with the fewest local instruction layers, state anything that cannot be disabled, then restore layers progressively.
• For Pi, pi -nc -ns -ne is the local raw starting point. Use current help to add only the candidate skill or prompt before restoring the natural environment.
• After each meaningful run, identify the pane, prompt, and loaded instruction layers, give only an initial observation or suggested next probe, then stop for the user to read both sessions.