Most skill problems trace back to one of a few causes. This article lists the common ones and how to fix them.
The result is different every run
Cause: vague wording in one or more steps. The agent interprets an ambiguous instruction differently from run to run.
Fix: find the step whose output drifts and make it specific. "Open all pages that contain floor plans" is stable; "open all pages where people live" is not. Use product terms: floor plans, measurements, pages, groups. See Writing Effective Skill Instructions: Best Practices.
The agent skips or confuses steps
Cause: a step contains several tasks at once, or the step order doesn't match the actual process.
Fix: split combined steps — one action per step — and check the sequence. Short, focused steps are executed reliably; long compound ones are not. See Skill Steps: How to Describe Tasks.
An early mistake ends up in the final result
Cause: no control points in the workflow, so an error travels through every subsequent step unnoticed.
Fix: add If/Else checks after the steps where errors are likely, and before the steps where they're expensive — for example, before building a report. The agent will catch the error at its own step and redo it. See Using If/Else Branching for Quality Control.
A step works for me but not for teammates
Cause: the step relies on context that's in your head, not in the skill.
Fix: move that context into the skill — refine the step wording and add a note explaining what the step expects and produces. See Adding Notes to Skills for Team Collaboration.
I can't find the right skill
Cause: missing or inconsistent names, descriptions, and tags.
Fix: name skills by what they do, describe the input and output, and agree on a tagging scheme with the team. See [Naming, Describing, and Tagging Skills].
The result still isn't right after refining
Work through the improvement loop in Editing and Improving an Existing Skill: run, check, locate the problem step, tighten it, run again. If a specific step keeps misbehaving no matter the wording, contact support and describe the step and the output you're getting.