AGENT SKILL

principle-make-operations-idempotent

Use when designing commands, setup or install flows, lifecycle steps, or processing loops that might be retried or restarted. Every run, including one following a crash at any step, must end in the same correct state.

License 许可
Apache-2.0
最近更新
2026-11-14
Stars
★ 1.6k
Forks
491

01 前言 Front Matter

name
principle-make-operations-idempotent
description
Use when designing commands, setup or install flows, lifecycle steps, or processing loops that might be retried or restarted. Every run, including one following a crash at any step, must end in the same correct state.
disable-model-invocation
true

03 SKILL.md 正文

Make operations idempotent

Build each operation that changes state so that repeating it any number of times, even after a crash at an arbitrary point, lands on one correct final state.

When it applies

Commands, lifecycle steps, setup and install flows, processing loops, and anything else that may be retried or restarted. Pure reads are exempt.

What to do

  1. For every mutating operation, answer three questions. What does a second consecutive run do? If an earlier run died at any given point, what does the next one do? Does rerunning end in the same state?
  2. Base each step on the state present right now, rather than on what a prior run meant to do. Read what is there, compare it with the target, and change only what differs, so a repeated run finds no work left. A script that grants an IAM role should check whether the binding exists before adding it, so a second run is a no-op and not a duplicate or an error.
  3. Leave anything a run might abandon (locks, temp files, half-written records, claimed jobs) in a form the following run can identify as stale. Base staleness on evidence that holds wherever the previous run stopped. A lock file holding a PID that is no longer alive is judgeable. A lock file with no owner information turns every crash into manual cleanup.
  4. Write to a temporary path, then rename atomically into place, so readers never see a half-written file. Compare artifacts by content (a hash), not by creation order or timestamp.
  5. If any answer in step 1 is "it depends on what was left behind", add a reconciliation step that inspects the leftovers and fixes them before proceeding.

Idempotency has a security side. A non-idempotent key-rotation job that crashes between "create new key" and "revoke old key" can leave two valid keys live, and a rerun may create a third. Designing it to converge closes that window.

The failure it prevents

Restarts that turn into debugging sessions, duplicated side effects (two charges, two notifications, two credentials), and orphaned locks.

Done when

All three questions in step 1 answer "same end state".

Related: principle-separate-before-serializing-shared-state, principle-build-the-lever.

04 同仓库更多 Skills

hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-review-with-annotations

Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-find-and-synthesize-context

Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-update-docs

Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-manage-records

Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-manage-interactive-html

Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-collaborate-threads

Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.

★ 1.6k