[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M780FF53ZPZ5V2BEE10V84E8":3,"skill-same:01M780FF53ZPZ5V2BEE10V84E8":60},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":25,"commitSha":26,"skillDirectory":27,"forksCount":28,"repositoryHtmlUrl":29,"repositoryHomepageUrl":6,"ownerHtmlUrl":30,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":31,"install":32,"resources":45},"01M780FF53ZPZ5V2BEE10V84E8","designing-an-action",null,"Use when designing a NEW GitHub Action, rebuilding or porting an existing action onto the @effected suite, or planning any multi-step action build, before writing the spec, the plan, or any module. For a single feature added to an existing action, load the matching actions-* skill instead; for capability routing, load building-a-github-action.","spencerbeggs\u002Feffected","spencerbeggs","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F109114?v=4","01M77ZTHB70K5Y2VVTRCFY50A5","C. Spencer Beggs","01M77ZTHCC41NXBT3X906K6QM1",8,"MIT","https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fskills\u002Fdesigning-an-action\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: designing-an-action\ndescription: Use when designing a NEW GitHub Action, rebuilding or porting an existing action onto the @effected suite, or planning any multi-step action build, before writing the spec, the plan, or any module. For a single feature added to an existing action, load the matching actions-* skill instead; for capability routing, load building-a-github-action.\nwhen_to_use: design a new action, rebuild an action, port an action to effected, greenfield action rebuild, action walking skeleton, contracts-first build, parity contract, action.yml parity, replace a legacy Actions toolkit wholesale\n---\n\n# Designing an action\n\nThe build process for an action-shaped program on the `@effected` suite: recon → frozen spec → API dossier → contracts-first walking skeleton → TDD fill. Companion to `building-a-github-action` (routes capabilities to packages and skills) and `effect-v4-planning` (gates the design of any individual module) — this skill owns only the sequence.\n\nThe core commitment: the whole pipeline exists as typed contracts with inert stub implementations before any business logic is written. Everything before the skeleton exists to make the contracts trustworthy; everything after fills them in, one step at a time, against a frozen interface.\n\nUse this for a new action from its metadata file up, a wholesale rebuild replacing a legacy toolkit under a parity contract, or a port where more than one pipeline step changes. **Not** for adding one input, one step, or one report to an action that already has this shape — load the matching `actions-*` skill and work within the existing contracts instead.\n\n## The sequence\n\n**Phase −1: Recon.** Cheap, wide, evidence-only — no design decisions yet.\n\n1. Inventory three surfaces: what's actually installed (package versions and their export maps), what exists in the kit but isn't installed yet, and what a sibling action already using this suite depends on — a diff-able record of which packages a shape like this one needs.\n2. Locate the hard parts first and confirm their enabling surfaces exist before anything else — an embedded server needs a detached-process contract and a blob-store backend; a toolchain step needs a tool installer. A missing enabler changes the whole plan, so find it before the plan exists.\n3. Read every touched package's own documentation and this repository's own conventions before deciding anything — a recon that picks a shape first and meets constraints later re-litigates its own decisions.\n4. Present 2–4 real decisions with recommended defaults: where legacy code goes, the dependency posture, how strict the parity contract is, and — when the action needs GitHub App auth — token scope verification and lifecycle placement, decided now rather than discovered while wiring the entry point (`github-app-tokens` carries the complete recipe). Everything else is not a decision; don't pad the list.\n5. A checked-absent kit surface is a decision point, not a workaround license. When recon turns up a capability the installed kit genuinely doesn't ship, ask whether to contribute the fix upstream now or write a local, tracked shim — never decide silently either way — and record the gap as an issue against the kit regardless of which path is chosen.\n\n**Phase 0: Spec with a frozen parity contract.** Freeze the interface inventory numerically, and track every uncertainty as a known unknown with a verification obligation. See [references\u002Fporting.md](references\u002Fporting.md) for both in full.\n\n**Phase 0.5: The API dossier.** Persist a signature-level dossier of the packages this build depends on before writing a skeleton against them. See [references\u002Fporting.md](references\u002Fporting.md).\n\n**Phase A: The contracts-first walking skeleton.** Build seven pieces in order, each an inert stub that succeeds: domain schema, inputs module, outputs module, cross-phase state, step contracts, program\u002Fentries\u002Flayers, and only then the TDD fill. See [references\u002Fwalking-skeleton.md](references\u002Fwalking-skeleton.md) for each step in full, and [references\u002Fdesign-checkpoints.md](references\u002Fdesign-checkpoints.md) for the correctness rules that make each one non-negotiable.\n\n**Phase B: Fill.** Fill each step's business logic in red\u002Fgreen\u002Frefactor cycles against the now-frozen contract, one step at a time. See [references\u002Fporting.md](references\u002Fporting.md) for treating a legacy implementation as the test oracle, and for the doubles-before-runner-conversion ordering when this phase also migrates test infrastructure.\n\n## Standards\n\n- **A plan task carries verbatim draft code, not a contract.** Mark any uncertain API spelling inline with an authority chain to resolve it — a plugin skill first, then the vendored reference source, then the installed types — and let the implementer verify against the installed types before writing, reporting every correction.\n- **One fresh subagent per task, with a task-scoped reviewer carrying an explicit constraint lens** (\"cross-check every name against the frozen inventory yourself\"), and a ledger file that survives context loss across the whole build.\n- **A reviewer verifies against the primary source, not the implementer's report.** Re-read the source line by line; a reviewer who reads only the summary reviews the summary, not the work.\n- **A convention decision made mid-build supersedes whatever the plan already says.** Record it once, ledger it as a ruling, and restate it in every later dispatch — a task brief was extracted from the plan before the decision existed, so nothing else carries it forward.\n- **Gate every task and every milestone.** Per-task: its own tests, then the full suite, then typecheck, then lint, then a properly formatted commit. Per milestone: an end-to-end run after the skeleton lands and after each designated fill step. Refresh the package's own documentation in the same gate — see [references\u002Fdesign-checkpoints.md](references\u002Fdesign-checkpoints.md).\n\n## Footguns\n\n- Business logic appearing before every step contract exists means the skeleton discipline is being skipped. See [references\u002Fwalking-skeleton.md](references\u002Fwalking-skeleton.md).\n- A stub that fails, or a skeleton that isn't green, is a wiring bug — stubs always succeed; red belongs only to the fill phase's TDD cycle. See [references\u002Fwalking-skeleton.md](references\u002Fwalking-skeleton.md).\n- An upstream ask or a design commitment resting on an unverified known unknown, or two implementers independently re-deriving the same API surface, both mean the dossier wasn't persisted or wasn't handed down. See [references\u002Fporting.md](references\u002Fporting.md).\n- A requirement channel declared from a guess rather than from a reference implementation's actual usage is a contract that will need reopening. See [references\u002Fwalking-skeleton.md](references\u002Fwalking-skeleton.md).\n- An error class with no test that constructs it is a documented lie; the mirror form — a step failure reported through a bare, untagged error — is the same defect from the other side. See [references\u002Fdesign-checkpoints.md](references\u002Fdesign-checkpoints.md).\n\n## Additional resources\n\n- [references\u002Fporting.md](references\u002Fporting.md) — the frozen parity contract and known-unknowns ledger in full, persisting an API dossier, treating a legacy implementation as a behavioral oracle, deriving a step's requirement channel from real usage, and the doubles-before-runner-conversion migration order. Load when: rebuilding or porting an existing action, or planning Phase 0 through Phase B of any build with a legacy reference implementation.\n- [references\u002Fwalking-skeleton.md](references\u002Fwalking-skeleton.md) — each of the seven skeleton pieces in full, in order, with the reasoning behind the ordering and a named worked example to read alongside it. Load when: building Phase A of a new or rebuilt action.\n- [references\u002Fdesign-checkpoints.md](references\u002Fdesign-checkpoints.md) — the correctness rules behind cross-phase state, failure posture, the logging contract, layer minimalism, bundle truth, dependency honesty, and error-taxonomy auditing. Load when: writing or reviewing any of these six specific mechanisms, not only when building a skeleton from scratch.\n","# Designing an action\n\nThe build process for an action-shaped program on the `@effected` suite: recon → frozen spec → API dossier → contracts-first walking skeleton → TDD fill. Companion to `building-a-github-action` (routes capabilities to packages and skills) and `effect-v4-planning` (gates the design of any individual module) — this skill owns only the sequence.\n\nThe core commitment: the whole pipeline exists as typed contracts with inert stub implementations before any business logic is written. Everything before the skeleton exists to make the contracts trustworthy; everything after fills them in, one step at a time, against a frozen interface.\n\nUse this for a new action from its metadata file up, a wholesale rebuild replacing a legacy toolkit under a parity contract, or a port where more than one pipeline step changes. **Not** for adding one input, one step, or one report to an action that already has this shape — load the matching `actions-*` skill and work within the existing contracts instead.\n\n## The sequence\n\n**Phase −1: Recon.** Cheap, wide, evidence-only — no design decisions yet.\n\n1. Inventory three surfaces: what's actually installed (package versions and their export maps), what exists in the kit but isn't installed yet, and what a sibling action already using this suite depends on — a diff-able record of which packages a shape like this one needs.\n2. Locate the hard parts first and confirm their enabling surfaces exist before anything else — an embedded server needs a detached-process contract and a blob-store backend; a toolchain step needs a tool installer. A missing enabler changes the whole plan, so find it before the plan exists.\n3. Read every touched package's own documentation and this repository's own conventions before deciding anything — a recon that picks a shape first and meets constraints later re-litigates its own decisions.\n4. Present 2–4 real decisions with recommended defaults: where legacy code goes, the dependency posture, how strict the parity contract is, and — when the action needs GitHub App auth — token scope verification and lifecycle placement, decided now rather than discovered while wiring the entry point (`github-app-tokens` carries the complete recipe). Everything else is not a decision; don't pad the list.\n5. A checked-absent kit surface is a decision point, not a workaround license. When recon turns up a capability the installed kit genuinely doesn't ship, ask whether to contribute the fix upstream now or write a local, tracked shim — never decide silently either way — and record the gap as an issue against the kit regardless of which path is chosen.\n\n**Phase 0: Spec with a frozen parity contract.** Freeze the interface inventory numerically, and track every uncertainty as a known unknown with a verification obligation. See [references\u002Fporting.md](references\u002Fporting.md) for both in full.\n\n**Phase 0.5: The API dossier.** Persist a signature-level dossier of the packages this build depends on before writing a skeleton against them. See [references\u002Fporting.md](references\u002Fporting.md).\n\n**Phase A: The contracts-first walking skeleton.** Build seven pieces in order, each an inert stub that succeeds: domain schema, inputs module, outputs module, cross-phase state, step contracts, program\u002Fentries\u002Flayers, and only then the TDD fill. See [references\u002Fwalking-skeleton.md](references\u002Fwalking-skeleton.md) for each step in full, and [references\u002Fdesign-checkpoints.md](references\u002Fdesign-checkpoints.md) for the correctness rules that make each one non-negotiable.\n\n**Phase B: Fill.** Fill each step's business logic in red\u002Fgreen\u002Frefactor cycles against the now-frozen contract, one step at a time. See [references\u002Fporting.md](references\u002Fporting.md) for treating a legacy implementation as the test oracle, and for the doubles-before-runner-conversion ordering when this phase also migrates test infrastructure.\n\n## Standards\n\n- **A plan task carries verbatim draft code, not a contract.** Mark any uncertain API spelling inline with an authority chain to resolve it — a plugin skill first, then the vendored reference source, then the installed types — and let the implementer verify against the installed types before writing, reporting every correction.\n- **One fresh subagent per task, with a task-scoped reviewer carrying an explicit constraint lens** (\"cross-check every name against the frozen inventory yourself\"), and a ledger file that survives context loss across the whole build.\n- **A reviewer verifies against the primary source, not the implementer's report.** Re-read the source line by line; a reviewer who reads only the summary reviews the summary, not the work.\n- **A convention decision made mid-build supersedes whatever the plan already says.** Record it once, ledger it as a ruling, and restate it in every later dispatch — a task brief was extracted from the plan before the decision existed, so nothing else carries it forward.\n- **Gate every task and every milestone.** Per-task: its own tests, then the full suite, then typecheck, then lint, then a properly formatted commit. Per milestone: an end-to-end run after the skeleton lands and after each designated fill step. Refresh the package's own documentation in the same gate — see [references\u002Fdesign-checkpoints.md](references\u002Fdesign-checkpoints.md).\n\n## Footguns\n\n- Business logic appearing before every step contract exists means the skeleton discipline is being skipped. See [references\u002Fwalking-skeleton.md](references\u002Fwalking-skeleton.md).\n- A stub that fails, or a skeleton that isn't green, is a wiring bug — stubs always succeed; red belongs only to the fill phase's TDD cycle. See [references\u002Fwalking-skeleton.md](references\u002Fwalking-skeleton.md).\n- An upstream ask or a design commitment resting on an unverified known unknown, or two implementers independently re-deriving the same API surface, both mean the dossier wasn't persisted or wasn't handed down. See [references\u002Fporting.md](references\u002Fporting.md).\n- A requirement channel declared from a guess rather than from a reference implementation's actual usage is a contract that will need reopening. See [references\u002Fwalking-skeleton.md](references\u002Fwalking-skeleton.md).\n- An error class with no test that constructs it is a documented lie; the mirror form — a step failure reported through a bare, untagged error — is the same defect from the other side. See [references\u002Fdesign-checkpoints.md](references\u002Fdesign-checkpoints.md).\n\n## Additional resources\n\n- [references\u002Fporting.md](references\u002Fporting.md) — the frozen parity contract and known-unknowns ledger in full, persisting an API dossier, treating a legacy implementation as a behavioral oracle, deriving a step's requirement channel from real usage, and the doubles-before-runner-conversion migration order. Load when: rebuilding or porting an existing action, or planning Phase 0 through Phase B of any build with a legacy reference implementation.\n- [references\u002Fwalking-skeleton.md](references\u002Fwalking-skeleton.md) — each of the seven skeleton pieces in full, in order, with the reasoning behind the ordering and a named worked example to read alongside it. Load when: building Phase A of a new or rebuilt action.\n- [references\u002Fdesign-checkpoints.md](references\u002Fdesign-checkpoints.md) — the correctness rules behind cross-phase state, failure posture, the logging contract, layer minimalism, bundle truth, dependency honesty, and error-taxonomy auditing. Load when: writing or reviewing any of these six specific mechanisms, not only when building a skeleton from scratch.\n",{"name":5,"description":7,"when_to_use":24},"design a new action, rebuild an action, port an action to effected, greenfield action rebuild, action walking skeleton, contracts-first build, parity contract, action.yml parity, replace a legacy Actions toolkit wholesale","main","11d6b3ae59538b0e16ad67c315ecb0c25fcb0125","plugin\u002Fskills\u002Fdesigning-an-action",2,"https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected","https:\u002F\u002Fgithub.com\u002Fspencerbeggs","2026-11-14 07:03:25",{"source":8,"skillName":5,"commands":33,"prompt":43,"zipAvailable":44},[34,37,40],{"tool":35,"command":36},"npx","npx skills add spencerbeggs\u002Feffected --skill designing-an-action",{"tool":38,"command":39},"bunx","bunx skills add spencerbeggs\u002Feffected --skill designing-an-action",{"tool":41,"command":42},"pnpm","pnpm dlx skills add spencerbeggs\u002Feffected --skill designing-an-action","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fskills\u002Fdesigning-an-action\u002FSKILL.md",true,[46,52,56],{"path":47,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":50,"sourceHtmlUrl":51},"references\u002Fdesign-checkpoints.md","REFERENCE","参考文档",6393,"https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fskills\u002Fdesigning-an-action\u002Freferences\u002Fdesign-checkpoints.md",{"path":53,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":54,"sourceHtmlUrl":55},"references\u002Fporting.md",4496,"https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fskills\u002Fdesigning-an-action\u002Freferences\u002Fporting.md",{"path":57,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":58,"sourceHtmlUrl":59},"references\u002Fwalking-skeleton.md",6975,"https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fskills\u002Fdesigning-an-action\u002Freferences\u002Fwalking-skeleton.md",[61,68,75,82,89,96],{"skillNo":62,"name":63,"nameZh":6,"description":64,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":65,"categories":66,"keywords":67,"publishedAt":19},"01M780NVTD800KMFV869YNZED6","testing-actions","Use when writing or reviewing tests for @effected\u002Fgithub-actions, @effected\u002Fgithub, @effected\u002Fsbom or @effected\u002Fcommands — stubbing the GitHub API, writing a service's layerTest or makeTest double, testing the pre\u002Fmain\u002Fpost lifecycle through Action.run, or debugging why a test hits the real network or hangs.","https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fskills\u002Ftesting-actions\u002FSKILL.md",[],[],{"skillNo":69,"name":70,"nameZh":6,"description":71,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":72,"categories":73,"keywords":74,"publishedAt":19},"01M780NPDSGFC0FCP7696NW11J","supply-chain-attestation","Use when generating a CycloneDX SBOM, checking NTIA minimum elements, building an in-toto statement or a SLSA provenance predicate, signing into a Sigstore DSSE bundle, or uploading an attestation to GitHub.","https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fskills\u002Fsupply-chain-attestation\u002FSKILL.md",[],[],{"skillNo":76,"name":77,"nameZh":6,"description":78,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":81,"publishedAt":19},"01M780NGP4QNZDH8T8Q8WZ18SA","structuring-an-action","Use when laying out a new GitHub Action repository on the @effected suite, deciding where a piece of code belongs (an entry point, a step, a shared service, a shim), or reviewing an existing action's file structure against the canonical shape.","https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fskills\u002Fstructuring-an-action\u002FSKILL.md",[],[],{"skillNo":83,"name":84,"nameZh":6,"description":85,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":88,"publishedAt":19},"01M780NCD52H1Y03FS83WJ8BT5","running-commands-and-tools","Use when running a subprocess in Effect v4, spawning a command, capturing stdout\u002Fstderr\u002Fexit code, checking whether a CLI tool is installed or which copy to run, running a package-manager script through the project's launcher, detaching a background process, or redacting a secret from argv or captured output.","https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fskills\u002Frunning-commands-and-tools\u002FSKILL.md",[],[],{"skillNo":90,"name":91,"nameZh":6,"description":92,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":93,"categories":94,"keywords":95,"publishedAt":19},"01M780N823DWNRMSY5X2NT5MSR","release-and-publish","Use when publishing a package to npm, reading the npm registry from Effect v4, checking whether a version is already published, cutting a release tag or GitHub release from an action, applying a release-age gate, or deriving tracking tags for GitHub Actions distribution.","https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fskills\u002Frelease-and-publish\u002FSKILL.md",[],[],{"skillNo":97,"name":98,"nameZh":6,"description":99,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":100,"categories":101,"keywords":102,"publishedAt":19},"01M780MXRF6H20KCESTSSFB3HQ","hardening-a-parser-port","Use when porting or writing a recursive-descent parser, lexer, or tree-walker over untrusted text in the @effected monorepo — the class of hardening the cloud reviewer scans for on every migration. Covers stack-overflow depth guards (on EVERY recursion surface, which a facade has N of — not two), numeric bound guards that must reject NaN and non-integers, code-point range checks scoped to formats with wide escapes, prototype-pollution, control-character rejection, and the invariant that malformed input must fail through the typed error channel, never as an unhandled defect.","https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fskills\u002Fhardening-a-parser-port\u002FSKILL.md",[],[]]