Roll back a bad agent skill update

Someone published a change to a skill your team relies on, and it made things worse. The agent started padding the summaries, or skipping a step, or citing a rule that no longer applies. The change already synced to everyone's machines, so it is not one person's problem, it is the team's. You want the previous behavior back today, and you want to know exactly what changed after that.

Putting the old behavior back takes about two minutes.

Rolling back means publishing the last good version again

Every version you publish is kept. Version 7 still exists after version 8 lands, and you can fetch it whenever you want, so going back is an ordinary publish rather than a repair: you take the content of the last good version and publish it as the current one. There is no separate rollback command to learn, because the command you already use does the job.

The version that caused the problem is still there to read while you work out what happened, and the fix reaches your team along the same path the mistake did.

Find the last good version

Ask the skill where it is now:

goodeye skills get my-skill --json

That prints the record, including version (the current number) and version_token. Versions run from 1 up to that number, so you walk backward from the current one. Fetch a candidate and read it:

goodeye skills get my-skill --version 7 -o ./skill-v7.md

--output writes the canonical skill body, front matter first, so the file you get back is directly publishable. Open it, confirm it is the version you want, and keep going back if it is not.

Goodeye stores the versions, not a narrative of why each one happened: there is no change log and no diff view between them. If a reason matters, put it in the skill body or keep it wherever your team already writes things down, because the version number alone will not remind you in three months.

Publish it as the current version

SKILL_VERSION_TOKEN=$(goodeye skills get my-skill --json | jq -r .version_token)

goodeye skills publish ./skill-v7.md --expected-version-token "$SKILL_VERSION_TOKEN"

That token is a concurrency check: if someone else published while you were deciding, this command fails instead of quietly discarding their work. Fetch again, look at what they did, and redo the publish deliberately.

The result is a new version, say 9, whose body matches version 7. You have not lost version 8, and you have not edited history.

If your skill carries sibling files, this rolls back the body only. --output writes just the skill body, and publishing a single file carries the existing file tree forward unchanged, so version 9 would pair version 7's body with version 8's files. Check goodeye skills get my-skill --json for the file list, restore individual files with goodeye skills put-file, or publish the whole directory instead of the one file.

Push it to everyone

goodeye skills sync pull

Each machine mirrors the hosted skill, so this is all it takes on any machine that has a sync target configured. Automatic sync will also carry it, but it runs as a tail after a goodeye command rather than as a background daemon, so a teammate picks the fix up on the next goodeye command they run once the interval has elapsed. During an incident, tell people to run the pull rather than waiting for it.

To confirm a specific machine landed the fix:

goodeye skills sync status

That reads only and reports whether each skill is clean, edited locally, behind the registry, conflicted, deleted upstream, or untracked. Watch for "edited locally" on a machine you expected to be clean: it means somebody changed the file on disk rather than publishing, and your rollback did not reach them. goodeye skills sync pull --force overwrites those local edits with the hosted copy.

For the full setup on the sync side, see use the same agent skill in Claude Code, Cursor, and Codex.

When to delete a version instead

goodeye skills delete-version my-skill 8

This permanently and immediately removes a single non-current version, and surviving versions keep their numbers, leaving a gap where the deleted one was. It is the right tool in one narrow case: the bad version contains something that should not exist anywhere, like a credential or customer data that got pasted into the runbook. It is the wrong tool for a version that was merely wrong, because deleting it destroys the evidence of what happened and buys you nothing. You cannot delete the current version, which is a deliberate guard.

Retire a skill without breaking anyone

Rolling back is about content. Retiring is about the whole skill, and it has a reversible option:

goodeye skills archive my-skill

Archiving hides the skill from listings without destroying it, and goodeye skills unarchive my-skill brings it back. Find archived skills again with goodeye skills list --include-archived. Before you archive anything a team uses, check who is on it and what came from it:

goodeye skills grants my-skill
goodeye skills lineage my-skill

goodeye skills delete is the permanent version of this, and it is immediate. Archive is almost always the right first move, because a premature retirement then costs one command instead of a rewrite.

When the author leaves

A skill has exactly one owner, and a grant does not change that. If the person who wrote your team's most important runbook is leaving, start the transfer while their account still works:

goodeye skills transfer-ownership my-skill teammate@example.com

This returns an invitation the new owner has to accept, and ownership does not move until they do. Run it early enough that the acceptance also happens before the account closes, and verify it went through rather than assuming. From the departing account, goodeye skills list --filter mine shows everything they own, which is the list to work through.

Where to start

Run goodeye skills get <skill> --json now, while nothing is broken, so you already know what the current version number and token look like before you need them. Then fetch the version before it and read it, so you have walked the path once when it is not an incident. If the update that went wrong was a change to what the agent's output must pass, the check itself is versioned too: run a rubric check on AI output from the CLI covers pinning a verifier to a version so a pass keeps meaning one thing.