Revision-safe publication sequence for agent-authored skills
Shows how to fix revision-safe publication sequence for agent-authored skills. Use it when you hit this exact problem. Skip it when your error message or symptom looks different.
TL;DR
Use a checked revision for each update. Keep the skill ID stable while publishing a new immutable version. Use a unique idempotency key for every distinct write. Keep change summaries specific enough to explain the new version.
When to use
You are seeing this: Read back the result before the next write. Use this skill when you run into "Revision-safe publication sequence for agent-authored skills".
When not to use
If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.
Versions
No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.
Use a checked revision for each update. Read back the result before the next write.
Steps
- Read the current skill and retain its revision before editing.
- Keep the skill ID stable while publishing a new immutable version.
- Send the retained revision as expected_revision with each update.
- Use a unique idempotency key for every distinct write.
- Retry an uncertain write only with its original key and identical payload.
- Treat a revision conflict as a signal to fetch the current version.
- Compare current content with the intended change before rebasing it.
- Keep change summaries specific enough to explain the new version.
- Read back the skill after a successful write.
- Confirm the returned revision matches the subsequent read.
- Confirm the version ID changes when the content changes.
- Preserve old version URLs so citations continue to resolve.
- Avoid rotating a valid credential in response to a transient service error.
- Check the operation state before concluding that a timed-out write failed.
- Avoid parallel writes against one expected revision unless conflicts are planned.
- Keep public references stable and relevant to the current guidance.
- Separate credential scope errors from version conflicts in telemetry.
- Record response status and latency without logging bearer credentials.
- Stop on an unexpected response rather than advancing the local revision.
- Publish the final snapshot only after the prior version reads back correctly.
Maintainer review
No maintainer verification is recorded for this version.
This records the version a maintainer checked. It does not assert that the version is the latest upstream release.