When a skill isn’t producing the output you want, the fix is almost always a single targeted instruction added to the skill file — not a full rewrite. Identify the one specific thing that’s wrong, write a rule that addresses it, test, and repeat. Skills improve through iteration, not overhaul.
Diagnosing What’s Wrong
Before changing anything, get specific about the gap. Don’t think “the output isn’t right” — think “the output is too long,” “the tone sounds too formal,” “it’s missing the action item at the end,” or “it’s not referencing the student’s actual situation.” The more precisely you can name the problem, the more precisely you can fix it.
Run the skill two or three times on different inputs to confirm the problem is consistent, not a one-off. If the issue only appears on certain inputs, your fix should be an edge-case instruction, not a change to the main flow. Consistent problems need consistent fixes; occasional problems need fallback rules.
The One-Instruction Fix
Once you’ve named the problem, add one instruction to the skill that directly addresses it. If the output is too long: “Keep the final output under 300 words.” If the tone is too formal: “Write in a warm, conversational tone — imagine explaining this to a colleague over coffee, not writing a report.” If the action item is missing: “End every output with one specific action item the educator can take today.”
Resist the urge to rewrite the whole skill when one thing isn’t working. Every instruction you add is a constraint on the agent’s behavior. Add too many at once and you can’t tell which one fixed the problem — or which one introduced a new one. One change at a time keeps the improvement loop clean.
What This Means for Educators
Skill improvement is an ongoing process, not a one-time build. The best skills in any library have been run dozens of times and refined through real-world feedback. Each run that doesn’t quite hit the mark is data — it tells you exactly what instruction the skill was missing. Approach skill maintenance the way a good teacher approaches lesson design: run it, observe what happened, adjust one thing, run it again.
The Simple Rule
When a skill underperforms, name the problem in one sentence. Write the instruction that fixes exactly that problem. Add it to the skill file. Test it. If it’s fixed, you’re done. If not, name the next problem and repeat. Never rewrite a skill that just needs one more rule.