agentleFS
Sign inStart free
fullerzzfullerzz/agent-skills/skills/principle-make-operations-idempotent/SKILL.md

principle-make-operations-idempotent

Skill2 starsChanged 29 days agoMITView on GitHub

Apply when designing commands, lifecycle steps, or processing loops that run amid crashes, restarts, and retries. Converge to the same end state regardless of partial prior runs.

We split this skill into the rules it gives an agent

1 rule. 1 is common, 0 are distinctive, and 0 are very specific to this project.

  • 1

    Common

    Most of the 43 edited versions we read keep these.

  • 0

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Common:

    If any answer is "it depends on what state was left behind," the operation needs a reconciliation step.

    line 24

“Common” is measured: kept by at least 6 in 10 of the 43 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Make Operations Idempotent

Design operations so they converge to the correct state regardless of how many times they run or where they start from. Every state-mutating operation should answer: "What happens if this runs twice? What happens if the previous run crashed halfway?"

Why: Commands, lifecycle operations, and processing loops run where crashes, restarts, and retries are normal. If partial state changes the next run's outcome, every restart becomes a debugging session.

The idea: Read the current state, compare it with the desired state, and apply the required delta: additions, updates to incorrect values, and safe removals of surplus resources within authorized scope. Derive the next step from what exists, not what a previous run intended. Repeating completed work should find nothing left to change.

Leftover locks, temporary files, partial records, and claimed jobs need evidence that lets a later run distinguish stale artifacts from live work. That evidence must remain valid across possible interruption points and execution environments. A PID alone may not identify the owner across hosts or process reuse. Uncertain ownership is not permission to delete an artifact.

Choose mechanisms that fit the operation: compare content rather than creation order, or publish a completed temporary file with an atomic rename where supported. Keep reconciliation and cleanup within the authorized scope.

The test:

  1. What happens if this runs twice in a row?
  2. What happens if the previous run crashed at every possible point?
  3. Does re-execution converge to the same end state?

If any answer is "it depends on what state was left behind," the operation needs a reconciliation step.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free