[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M75MJJEB4YEM935V1WS07DP3":3,"skill-same:01M75MJJEB4YEM935V1WS07DP3":45},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":23,"commitSha":24,"skillDirectory":25,"forksCount":26,"repositoryHtmlUrl":27,"repositoryHomepageUrl":28,"ownerHtmlUrl":29,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":30,"install":31,"resources":44},"01M75MJJEB4YEM935V1WS07DP3","graceful-shutdown-stateful-agents",null,"Make a stateful container\u002Fagent survive SIGTERM→SIGKILL on Kubernetes without losing in-flight work or corrupting on-disk state.","selamy-labs\u002Fagent-skills","selamy-labs","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F287832944?v=4","01M75MDKJ0CKAM94KZ7TWQJM5Q","01M75MDKJNP3TATHAW1MX1FWM6",0,"MIT","https:\u002F\u002Fgithub.com\u002Fselamy-labs\u002Fagent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fgraceful-shutdown-stateful-agents\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: graceful-shutdown-stateful-agents\ndescription: Make a stateful container\u002Fagent survive SIGTERM→SIGKILL on Kubernetes without losing in-flight work or corrupting on-disk state.\n---\n\n# graceful-shutdown-stateful-agents\n\nWhen K8s evicts, rolls, or scales down a pod it sends **SIGTERM**, waits `terminationGracePeriodSeconds`, then **SIGKILL**. A stateful agent that ignores this loses in-flight work and can corrupt its store. Default behavior is NOT safe — you must design for the signal.\n\n## The shutdown contract\n1. **Catch SIGTERM** in the process and start an ORDERLY drain — stop accepting new work, finish or checkpoint in-flight work, flush + fsync state, close connections, exit 0. Do NOT let the default handler hard-kill you.\n2. **Size `terminationGracePeriodSeconds`** to the real worst-case drain (measure it). Too short → SIGKILL mid-flush → corruption. Too long → slow rollouts. The grace period is a budget; your drain must finish inside it with margin.\n3. **`preStop` hook** for work the app can't self-trigger (e.g. deregister from the load balancer before draining, or signal a sidecar). A common pattern is a `preStop` that sends an app-specific signal (e.g. SIGUSR1) to begin drain while the LB removes the endpoint — closing the race where traffic still arrives after SIGTERM.\n4. **Assume SIGKILL can still win.** The grace period is best-effort; node pressure or a stuck drain can cut it short. So durability cannot DEPEND on a clean shutdown — it must survive an abrupt kill too (next section).\n\n## Durability that survives an abrupt kill\n- **Write-ahead log \u002F journaling** (e.g. SQLite WAL mode): commits are durable on `fsync`, and recovery replays the WAL after a crash — so a SIGKILL mid-operation leaves a recoverable, not corrupt, store.\n- **Atomic writes**: write to a temp file + `fsync` + atomic `rename`; never partially overwrite a live file.\n- **Idempotent + checkpointed work**: persist progress so a restarted pod resumes, not restarts; make replays safe (a re-delivered task must not double-apply).\n- **fsync at the boundaries that matter** — a buffered write the OS hasn't flushed is gone on SIGKILL.\n\n## Verify it (don't assume)\nTest the real signal path: send SIGTERM, confirm the process drains and exits 0 within the grace period; then test the brutal path — SIGKILL mid-write — and confirm the store recovers cleanly on restart (WAL replay, no corruption, no lost committed work). \"It shut down cleanly once\" is not the test; the abrupt kill is.\n\n## DONE means\nSIGTERM triggers an orderly drain that finishes inside `terminationGracePeriodSeconds`; a `preStop` closes the traffic\u002Fdrain race; and state is durable under SIGKILL (WAL\u002Fatomic-rename\u002Ffsync), proven by a kill-mid-write recovery test — not just a clean-exit test.\n","# graceful-shutdown-stateful-agents\n\nWhen K8s evicts, rolls, or scales down a pod it sends **SIGTERM**, waits `terminationGracePeriodSeconds`, then **SIGKILL**. A stateful agent that ignores this loses in-flight work and can corrupt its store. Default behavior is NOT safe — you must design for the signal.\n\n## The shutdown contract\n1. **Catch SIGTERM** in the process and start an ORDERLY drain — stop accepting new work, finish or checkpoint in-flight work, flush + fsync state, close connections, exit 0. Do NOT let the default handler hard-kill you.\n2. **Size `terminationGracePeriodSeconds`** to the real worst-case drain (measure it). Too short → SIGKILL mid-flush → corruption. Too long → slow rollouts. The grace period is a budget; your drain must finish inside it with margin.\n3. **`preStop` hook** for work the app can't self-trigger (e.g. deregister from the load balancer before draining, or signal a sidecar). A common pattern is a `preStop` that sends an app-specific signal (e.g. SIGUSR1) to begin drain while the LB removes the endpoint — closing the race where traffic still arrives after SIGTERM.\n4. **Assume SIGKILL can still win.** The grace period is best-effort; node pressure or a stuck drain can cut it short. So durability cannot DEPEND on a clean shutdown — it must survive an abrupt kill too (next section).\n\n## Durability that survives an abrupt kill\n- **Write-ahead log \u002F journaling** (e.g. SQLite WAL mode): commits are durable on `fsync`, and recovery replays the WAL after a crash — so a SIGKILL mid-operation leaves a recoverable, not corrupt, store.\n- **Atomic writes**: write to a temp file + `fsync` + atomic `rename`; never partially overwrite a live file.\n- **Idempotent + checkpointed work**: persist progress so a restarted pod resumes, not restarts; make replays safe (a re-delivered task must not double-apply).\n- **fsync at the boundaries that matter** — a buffered write the OS hasn't flushed is gone on SIGKILL.\n\n## Verify it (don't assume)\nTest the real signal path: send SIGTERM, confirm the process drains and exits 0 within the grace period; then test the brutal path — SIGKILL mid-write — and confirm the store recovers cleanly on restart (WAL replay, no corruption, no lost committed work). \"It shut down cleanly once\" is not the test; the abrupt kill is.\n\n## DONE means\nSIGTERM triggers an orderly drain that finishes inside `terminationGracePeriodSeconds`; a `preStop` closes the traffic\u002Fdrain race; and state is durable under SIGKILL (WAL\u002Fatomic-rename\u002Ffsync), proven by a kill-mid-write recovery test — not just a clean-exit test.\n",{"name":5,"description":7},"main","54007b08157feb09e5bb9d7ff5ce4ddd21625dbf","skills\u002Fgraceful-shutdown-stateful-agents",3,"https:\u002F\u002Fgithub.com\u002Fselamy-labs\u002Fagent-skills","https:\u002F\u002Fselamy.dev","https:\u002F\u002Fgithub.com\u002Fselamy-labs","2026-11-15 03:50:58",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add selamy-labs\u002Fagent-skills --skill graceful-shutdown-stateful-agents",{"tool":37,"command":38},"bunx","bunx skills add selamy-labs\u002Fagent-skills --skill graceful-shutdown-stateful-agents",{"tool":40,"command":41},"pnpm","pnpm dlx skills add selamy-labs\u002Fagent-skills --skill graceful-shutdown-stateful-agents","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fselamy-labs\u002Fagent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fgraceful-shutdown-stateful-agents\u002FSKILL.md",true,[],[46,53,60,67,73,80],{"skillNo":47,"name":48,"nameZh":6,"description":49,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":50,"categories":51,"keywords":52,"publishedAt":18},"01M75MY70JMSNFHQX63G90SKZ7","silence-phrase","A seemingly normal skill.","https:\u002F\u002Fgithub.com\u002Fselamy-labs\u002Fagent-skills\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fsilence-phrase\u002FSKILL.md",[],[],{"skillNo":54,"name":55,"nameZh":6,"description":56,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":57,"categories":58,"keywords":59,"publishedAt":18},"01M75MY5PKVKY60M8H2DFTW58C","selamy-bad-skill","This skill has a vendor prefix that should be rejected.","https:\u002F\u002Fgithub.com\u002Fselamy-labs\u002Fagent-skills\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fprefixed-name\u002FSKILL.md",[],[],{"skillNo":61,"name":62,"nameZh":6,"description":63,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":64,"categories":65,"keywords":66,"publishedAt":18},"01M75MY1TKXCH6WYN9ET0W4T02","oversized-description","This is a very long description that contains way too many words and should be rejected by the validator because it exceeds the forty five word limit that is enforced by the naming lint checker which ensures skill descriptions stay concise and readable for humans and machines alike without unnecessary verbosity or padding","https:\u002F\u002Fgithub.com\u002Fselamy-labs\u002Fagent-skills\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Foversized-description\u002FSKILL.md",[],[],{"skillNo":68,"name":69,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":18},"01M75MY0SZ7EKT99NWJEJ8HKS2","missing-frontmatter","https:\u002F\u002Fgithub.com\u002Fselamy-labs\u002Fagent-skills\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fmissing-frontmatter\u002FSKILL.md",[],[],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":18},"01M75MXYMBREE6D7KRR87YM4DH","malicious-skill","A poisoned skill used only as a negative fixture for the security gate.","https:\u002F\u002Fgithub.com\u002Fselamy-labs\u002Fagent-skills\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fmalicious-skill\u002FSKILL.md",[],[],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":18},"01M75MXX2B7AC2QSSRRQQXTA0N","leaking-org-name","A skill about something.","https:\u002F\u002Fgithub.com\u002Fselamy-labs\u002Fagent-skills\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fleaking-org-name\u002FSKILL.md",[],[]]