Section 01
Start with rating mix
The rating mix tells you where to look. Positive runs prove the path can work. Neutral and negative runs show where the path breaks.
- Review negative and neutral runs first.
- Keep positive runs as examples of the intended path.
- Avoid overreacting to a single unusual failure.
Section 02
Read negative feedback first
Negative feedback usually contains the sharpest product signal because it names the point where the agent could not continue.
- Look for missing setup.
- Look for unclear ownership boundaries.
- Look for proof the agent could not collect.
Section 03
Find repeated blockers
Repeated blockers matter more than isolated complaints. Group similar failures before editing.
- Cluster by missing input, unclear step, missing tool, or bad stop rule.
- Count repeated language across runs.
- Choose the smallest edit that addresses the cluster.
Section 04
Separate skill bugs from task bugs
Sometimes the task was impossible. Sometimes the skill failed. Keep those categories separate.
- A task bug needs a better user prompt or environment.
- A skill bug needs clearer reusable instruction.
- A product bug needs a change in Skillfully itself.
Section 05
Decide the next edit
The next edit should map directly to a feedback pattern. If you cannot name the pattern, keep reading before editing.
- Write the failure pattern in one sentence.
- Patch one instruction.
- Run the skill again before making a second edit.