{"id":"5add8f34-ed97-4b43-87d1-3d86bad408f9","shortId":"Wqa7wU","kind":"skill","title":"create-only-idempotent-artifact-write","tagline":"Persist deterministic artifacts with a create-only write and treat existing files as replay success instead of an error.","description":"# SKILL: Create-Only Idempotent Artifact Write\n**Domain:** tool-orchestration  \n**Trigger:** Apply when a deterministic artifact is keyed by a stable invocation ID and may be replayed across retries, compaction, or resume passes.\n**Source Pattern:** Distilled from reviewed tool-loop and result-shaping patterns.\n\n## Core Method\nWhen an artifact path is derived from a stable identity, write it once with an atomic create-only operation instead of checking for existence first. If the write hits \"already exists,\" treat that as proof the earlier successful write already materialized the deterministic content and continue with the normal readback or preview path. This removes the stat-then-write race, avoids useless rewrites during replay, and keeps repeated passes behaviorally identical.\n\n## Key Rules\n- Derive the artifact path from a stable key such as `tool_use_id` so repeated calls target the same location.\n- Use a create-only write primitive like `flag: 'wx'` to collapse \"create if absent\" into one filesystem operation.\n- Treat `EEXIST` as idempotent success when the content is deterministic for that key; only unexpected filesystem errors should fail the operation.\n- Continue into the downstream preview or response-building path even when the file already existed, so replayed calls return the same contract as fresh ones.\n- Avoid preflight existence checks because they reintroduce races and duplicate I/O under concurrency.\n\n## Example Application\nIf a large tool result is persisted under `tool-results/<tool_use_id>.json`, write it once with a create-only flag. When transcript replay or micro-compaction revisits that same tool result, the write sees `EEXIST`, skips the rewrite, and still returns the same preview payload and saved path to the caller.\n\n## Anti-Patterns (What NOT to do)\n- Do not `stat()` and then `writeFile()` for idempotency; another writer can win between those calls.\n- Do not overwrite existing artifacts on every replay when the file path is already the canonical output for that key.\n- Do not treat \"file already exists\" as a hard error in deterministic replay flows; it is often the success path.","tags":["create","only","idempotent","artifact","write","cskill","agents","ychampion","agent-skills","ai-agents","cli","coding-agents"],"capabilities":["skill","source-ychampion","skill-create-only-idempotent-artifact-write","topic-agent-skills","topic-ai-agents","topic-cli","topic-coding-agents","topic-context-engineering","topic-developer-tools","topic-mcp","topic-multi-agent","topic-terminal-ui"],"categories":["cskill-agents"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/ychampion/cskill-agents/create-only-idempotent-artifact-write","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add ychampion/cskill-agents","source_repo":"https://github.com/ychampion/cskill-agents","install_from":"skills.sh"}},"qualityScore":"0.467","qualityRationale":"deterministic score 0.47 from registry signals: · indexed on github topic:agent-skills · 34 github stars · SKILL.md body (2,145 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-22T06:56:47.553Z","embedding":null,"createdAt":"2026-04-18T22:20:10.180Z","updatedAt":"2026-04-22T06:56:47.553Z","lastSeenAt":"2026-04-22T06:56:47.553Z","tsv":"'absent':185 'across':55 'alreadi':106,116,225,340,351 'anoth':320 'anti':306 'anti-pattern':305 'appli':39 'applic':251 'artifact':5,9,32,43,78,153,331 'atom':91 'avoid':138,237 'behavior':147 'build':219 'call':166,229,326 'caller':304 'canon':342 'check':98,240 'collaps':182 'compact':57,279 'concurr':249 'content':120,197 'continu':122,211 'contract':233 'core':74 'creat':2,13,29,93,174,183,270 'create-on':12,28,92,173,269 'create-only-idempotent-artifact-writ':1 'deriv':81,151 'determinist':8,42,119,199,358 'distil':63 'domain':34 'downstream':214 'duplic':246 'earlier':113 'eexist':191,288 'error':26,206,356 'even':221 'everi':333 'exampl':250 'exist':18,100,107,226,239,330,352 'fail':208 'file':19,224,337,350 'filesystem':188,205 'first':101 'flag':179,272 'flow':360 'fresh':235 'hard':355 'hit':105 'i/o':247 'id':50,163 'idempot':4,31,193,319 'ident':85,148 'instead':23,96 'invoc':49 'json':263 'keep':144 'key':45,149,158,202,346 'larg':254 'like':178 'locat':170 'loop':68 'materi':117 'may':52 'method':75 'micro':278 'micro-compact':277 'normal':125 'often':363 'one':187,236 'oper':95,189,210 'orchestr':37 'output':343 'overwrit':329 'pass':60,146 'path':79,129,154,220,301,338,366 'pattern':62,73,307 'payload':298 'persist':7,258 'preflight':238 'preview':128,215,297 'primit':177 'proof':111 'race':137,244 'readback':126 'reintroduc':243 'remov':131 'repeat':145,165 'replay':21,54,142,228,275,334,359 'respons':218 'response-build':217 'result':71,256,262,284 'result-shap':70 'resum':59 'retri':56 'return':230,294 'review':65 'revisit':280 'rewrit':140,291 'rule':150 'save':300 'see':287 'shape':72 'skill':27 'skill-create-only-idempotent-artifact-write' 'skip':289 'sourc':61 'source-ychampion' 'stabl':48,84,157 'stat':134,314 'stat-then-writ':133 'still':293 'success':22,114,194,365 'target':167 'tool':36,67,161,255,261,283 'tool-loop':66 'tool-orchestr':35 'tool-result':260 'topic-agent-skills' 'topic-ai-agents' 'topic-cli' 'topic-coding-agents' 'topic-context-engineering' 'topic-developer-tools' 'topic-mcp' 'topic-multi-agent' 'topic-terminal-ui' 'transcript':274 'treat':17,108,190,349 'trigger':38 'unexpect':204 'use':162,171 'useless':139 'win':323 'write':6,15,33,86,104,115,136,176,264,286 'writefil':317 'writer':321 'wx':180","prices":[{"id":"0250367c-2b4c-4807-825e-5174726e9759","listingId":"5add8f34-ed97-4b43-87d1-3d86bad408f9","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"ychampion","category":"cskill-agents","install_from":"skills.sh"},"createdAt":"2026-04-18T22:20:10.180Z"}],"sources":[{"listingId":"5add8f34-ed97-4b43-87d1-3d86bad408f9","source":"github","sourceId":"ychampion/cskill-agents/create-only-idempotent-artifact-write","sourceUrl":"https://github.com/ychampion/cskill-agents/tree/main/skills/create-only-idempotent-artifact-write","isPrimary":false,"firstSeenAt":"2026-04-18T22:20:10.180Z","lastSeenAt":"2026-04-22T06:56:47.553Z"}],"details":{"listingId":"5add8f34-ed97-4b43-87d1-3d86bad408f9","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"ychampion","slug":"create-only-idempotent-artifact-write","github":{"repo":"ychampion/cskill-agents","stars":34,"topics":["agent-skills","ai-agents","cli","coding-agents","context-engineering","developer-tools","mcp","multi-agent","terminal-ui"],"license":"mit","html_url":"https://github.com/ychampion/cskill-agents","pushed_at":"2026-04-04T14:13:23Z","description":"Agent skills for coding CLIs, multi-agent runtimes, context engines, MCP extensions, and terminal tooling. Instead of using claude code's source code, give your agent skills to create your own!","skill_md_sha":"6d0901c70619db3defe38814556883ee1bfd06f2","skill_md_path":"skills/create-only-idempotent-artifact-write/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/ychampion/cskill-agents/tree/main/skills/create-only-idempotent-artifact-write"},"layout":"multi","source":"github","category":"cskill-agents","frontmatter":{"name":"create-only-idempotent-artifact-write","description":"Persist deterministic artifacts with a create-only write and treat existing files as replay success instead of an error."},"skills_sh_url":"https://skills.sh/ychampion/cskill-agents/create-only-idempotent-artifact-write"},"updatedAt":"2026-04-22T06:56:47.553Z"}}