Improve a skill

One standard: prove it. An edit that only looks right, with the hope that it works next time, hasn't fixed anything. To clean up a skill that works, use skill-tidy.

The engine runs as npx -y @thenavidm/skill-builder@latest. Where skill-builder is installed (npm install -g @thenavidm/skill-builder), run skill-builder instead: it's the same engine, without the download.

First, save the current version

Copy the whole skill folder to .agents/skill/history/<name>/<date-and-time>/ and confirm the copy matches. It is the baseline the new version is measured against, and the way back if the change makes things worse. If the skill came from someone else's plugin, ask before changing it: edit a copy under a name of theirs, or suggest the fix to the plugin's author.

Fix it

1. The exact failure. Ask for the real input and the output that was wrong, or their review notes (feedback.json from an eval run). "It's off" isn't enough to fix; "it wrote the date as November 10" is.
2. The cause. Read the whole skill and find the instruction that produced it, the rule that's missing, or the description that let another skill fire. Say it in one sentence, pointing at the line. A guess isn't a cause.
3. The smallest change that removes the cause, written by the skill-writer agent from your one-sentence cause, or by you in a tool without agents. A skill that grows a new rule for every case becomes a list nobody can follow. Prefer explaining the reason behind an existing rule over adding a new one.
4. Prove it. Add the failing case to evals/evals.json as a task with an assertion that failed before. Run eval on the new version and on the saved one:

npx -y @thenavidm/skill-builder@latest eval <skill> --runs 3

The failing task must now pass, and every task that passed before must still pass. Where assertions can't capture the difference, give the old and new outputs to the skill-comparator agent unlabelled; then have the skill-reviewer agent check the changed skill. If the cause was triggering, use skill-description instead and prove it with trigger.

Either way

Two attempts. If the second still fails its proof, put the saved version back (copy the whole folder, confirm it matches) and say plainly what's left: the fix may need a rebuild with skill-create. Report what changed, the before and after numbers, and where the old version is kept.