[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7AX9CCTRN8VTZYT5ZGV2NCJ":3,"skill-same:01M7AX9CCTRN8VTZYT5ZGV2NCJ":47},{"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":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":30,"ownerDescription":31,"updatedAt":32,"install":33,"resources":46},"01M7AX9CCTRN8VTZYT5ZGV2NCJ","extend-vocabulary",null,"Checklist for growing the portable vocabulary — adding or changing an Effect, capability id, diagnostic code (HNxxx), hook event, ToolKind, ShellShapes or FileShapes entry, a shell dialect (ShellDialect, tool.shell.dialect, a shape's dialect, a stated shell name), a normalized tool view (tool.shell, tool.file), or anything in packages\u002Fsdk\u002Fsrc\u002F{effects,capabilities,schemas,tools,result,hook}.ts, packages\u002Fruntime\u002Fsrc\u002Fdispatch.ts, or an adapter's profile.ts\u002Ftoolmap.ts\u002Fapply.ts.","roryeckel\u002Fhooknostic","roryeckel","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F16675082?v=4","01M7AX8JWEFHND7P2G338X0TQW","Rory","01M7AX8JX2FGW3TMBVSGFAPQD2",2,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Froryeckel\u002Fhooknostic\u002Fblob\u002Fmaster\u002F.agents\u002Fskills\u002Fextend-vocabulary\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: extend-vocabulary\ndescription: Checklist for growing the portable vocabulary — adding or changing an Effect, capability id, diagnostic code (HNxxx), hook event, ToolKind, ShellShapes or FileShapes entry, a shell dialect (ShellDialect, tool.shell.dialect, a shape's dialect, a stated shell name), a normalized tool view (tool.shell, tool.file), or anything in packages\u002Fsdk\u002Fsrc\u002F{effects,capabilities,schemas,tools,result,hook}.ts, packages\u002Fruntime\u002Fsrc\u002Fdispatch.ts, or an adapter's profile.ts\u002Ftoolmap.ts\u002Fapply.ts.\n---\n\n# Extending the vocabulary\n\nThe SDK's types are the portable contract; every extension has a set of twin\nsurfaces that must move together, and each has silently shipped an inert or\nwrong feature when edited alone. Work through the checklist for what you're\nadding; finish with the shared tail.\n\n## First: does this need an ADR?\n\nA new effect, capability semantics change, or normalization decision is a\nsemantic-model change — write or extend `docs\u002Fdecisions\u002F` (see ADR-0001,\n0005, 0007 for the register). A mechanical addition inside an existing\ndecision does not.\n\n## New or changed Effect kind\n\n- `packages\u002Fsdk\u002Fsrc\u002Feffects.ts`: interface + constructor + union member, and\n  the two **total records** — `EFFECT_CAPABILITY_SUFFIX` and\n  `TERMINAL_EFFECT`. They are `Record\u003CEffectKind, …>` precisely so the build\n  breaks until \"which capability licenses this?\" and \"does it end the\n  dispatch?\" are answered. `EFFECT_KINDS` derives from them; never restate\n  the kind list anywhere else.\n- `packages\u002Fsdk\u002Fsrc\u002Fschemas.ts`: the `effectSchema` union member, **in the\n  same edit** — the schemas are `.strict()`, so a field added to an interface\n  but not its zod twin is rejected at dispatch as HN401 while compiling\n  clean. This trap has bitten four separate times.\n- `EffectForCapability` in effects.ts (longest-suffix-first ordering).\n- `packages\u002Fruntime\u002Fsrc\u002Fdispatch.ts`: an apply case in the effect switch. If\n  the effect is portable-but-lowered (like `updateShell`), lower it in\n  dispatch to an existing kind and mark the synthesized entry with\n  `loweredFrom`, so the three adapter `apply.ts` reducers stay untouched.\n  They each independently resolve `kind === \"replaceInput\"` **and each\n  suppresses a recorded rewrite on a terminal deny** (denial precedence) —\n  a new effect kind slipping past those reducers, or a reducer missing the\n  precedence rule, diverges per adapter; both have happened.\n- Docs: effect list in `docs\u002Fdesign.md` §7, table in `docs\u002Fconcepts.md`,\n  composition rule 4 if terminality changed.\n\n## New capability id\n\n- Append to `ALL_CAPABILITY_IDS` (`packages\u002Fsdk\u002Fsrc\u002Fcapabilities.ts`).\n- Rate it in **all three** `packages\u002Fadapter-*\u002Fsrc\u002Fprofile.ts` matrices;\n  non-exact levels need a rationale (testkit-enforced, and rendered to users\n  by `inspect`).\n- Ask first whether the real gate is per-target at all: per-invocation\n  knowledge (like tool shape coverage) cannot live in a build-time matrix —\n  reuse the existing capability and document a runtime feature-detect\n  instead (ADR-0007's reasoning).\n\n## New diagnostic code\n\n- `DIAGNOSTIC_CODES` in `packages\u002Fcore\u002Fsrc\u002Fdiagnostics.ts`; if the runtime\n  can raise it, also `RUNTIME_DIAGNOSTIC_CODES` in\n  `packages\u002Fsdk\u002Fsrc\u002Fresult.ts` (deliberate duplication — the SDK cannot\n  import core; core asserts the subset matches, so drift is a compile error).\n- Code table in `docs\u002Fdesign.md` and `docs\u002Fglossary.md`. Codes are stable:\n  never renumber (the misfamilied HN502 is documented, not renumbered).\n\n## Shell or file shape \u002F toolmap entry\n\nCapture first — load the `harness-capture` skill. Then: one `ShellShapes`\nentry per captured tool; both codec directions derive from it, and the\ntestkit round-trips every shell-bearing fixture. File tools go in\n`FileShapes` (`{ pathKey }` or `{ patchKey }`, read side only, ADR-0026); the\ntestkit re-classifies every file-bearing fixture and requires a fixture per\nentry. Uncaptured tools stay absent. A new or renamed tool name also needs its\n`ToolKind` entry — capture found OpenCode's patch tools misclassified because\nonly the shape had been considered.\n\n## Shell dialect\n\nADR-0029 is the decision; this is what moves. A payload capture is not\nevidence for a dialect: only the interpreter that ran is, observed across the\nhost configurations that could change it (`.capture\u002Fshell-dialects`).\n\n- **A tool that pins one**: `dialect` on its `ShellShapes` entry. The codec\n  emits it, and the contract suite then requires the tool's fixtures to record\n  it.\n- **A harness that states its shell**: the shim listens, the decoder receives\n  the name as enrichment and maps it, and `classifyTool` applies a\n  `ReportedToolFacts.shellDialect`. Map a name only after a capture saw it\n  stated and run. Promote an enrichment fixture for a mapped name and for an\n  unmapped one, and keep the playback assertion that a real shell call carries\n  a dialect: it is what notices reworded prose.\n- **Neither**: leave it absent. Never derive it from the platform or an\n  environment variable.\n- **Always**: declare which of the three it is in the adapter's\n  `shellDialect` (`tool`, `statement`, `none`, with a rationale). `inspect`\n  and the generated support page print it and the contract suite holds the\n  table and classifier to it. A shim that hears a statement also passes the\n  dialect to `dispatch()` as `shellDialect`, or a view that a rewrite creates\n  has none.\n- **A new family**: `SHELL_DIALECTS` in `tools.ts` (the schema twin derives\n  from it), the name map, and the three places docs list the values\n  (`design.md` §6.3, `concepts.md`, `writing-hooks-safely.md`).\n\n## New normalized tool view\n\nA view like `tool.shell`\u002F`tool.file` moves together across: the SDK type and\ncodec (`tools.ts`), the strict `toolInvocationSchema` twin (`schemas.ts`), the\nadapter interface (`core\u002Fsrc\u002Fadapter.ts`), each adapter's toolmap classifier,\nindex and shim, `cli\u002Fsrc\u002Fdispatch.ts`, dispatch's `setToolInput` re-derive\n(a rewrite must never leave a view stale), the testkit contract obligations,\nand regenerated canonicals. It is a normalization decision, so it gets an ADR.\n\n## New adapter\n\n`docs\u002Fadding-an-adapter.md` is the authoritative workflow (capture → fixtures\n→ profile → decode\u002Fapply → shim → `describeAdapterContract` +\n`packages\u002Fcli\u002Fsrc\u002Fcoverage.test.ts` SUBJECTS row). For the planning, surface\ninventory, probe budget and completeness gates, load `harness-integration`.\n\n## Shared tail (every extension)\n\n1. Shims must never value-import `@hooknostic\u002Fcore`\n   (`packages\u002Fcli\u002Fsrc\u002Fpackage.test.ts` enforces; it drags esbuild into every\n   artifact).\n2. Mutation-verify each new test against the defect it pins (AGENTS.md hard\n   rule).\n3. Rebuild `examples\u002F*\u002Fdist` from the repo root; the reproducibility gate\n   byte-compares.\n4. Full gates with explicit exit codes: `pnpm lint`, `pnpm build`,\n   `pnpm test`.\n5. Update tutorials\u002FREADME snippets that teach the old surface — the front\n   page and tutorials 01–03 all carry live hook bodies that have drifted\n   before.\n","# Extending the vocabulary\n\nThe SDK's types are the portable contract; every extension has a set of twin\nsurfaces that must move together, and each has silently shipped an inert or\nwrong feature when edited alone. Work through the checklist for what you're\nadding; finish with the shared tail.\n\n## First: does this need an ADR?\n\nA new effect, capability semantics change, or normalization decision is a\nsemantic-model change — write or extend `docs\u002Fdecisions\u002F` (see ADR-0001,\n0005, 0007 for the register). A mechanical addition inside an existing\ndecision does not.\n\n## New or changed Effect kind\n\n- `packages\u002Fsdk\u002Fsrc\u002Feffects.ts`: interface + constructor + union member, and\n  the two **total records** — `EFFECT_CAPABILITY_SUFFIX` and\n  `TERMINAL_EFFECT`. They are `Record\u003CEffectKind, …>` precisely so the build\n  breaks until \"which capability licenses this?\" and \"does it end the\n  dispatch?\" are answered. `EFFECT_KINDS` derives from them; never restate\n  the kind list anywhere else.\n- `packages\u002Fsdk\u002Fsrc\u002Fschemas.ts`: the `effectSchema` union member, **in the\n  same edit** — the schemas are `.strict()`, so a field added to an interface\n  but not its zod twin is rejected at dispatch as HN401 while compiling\n  clean. This trap has bitten four separate times.\n- `EffectForCapability` in effects.ts (longest-suffix-first ordering).\n- `packages\u002Fruntime\u002Fsrc\u002Fdispatch.ts`: an apply case in the effect switch. If\n  the effect is portable-but-lowered (like `updateShell`), lower it in\n  dispatch to an existing kind and mark the synthesized entry with\n  `loweredFrom`, so the three adapter `apply.ts` reducers stay untouched.\n  They each independently resolve `kind === \"replaceInput\"` **and each\n  suppresses a recorded rewrite on a terminal deny** (denial precedence) —\n  a new effect kind slipping past those reducers, or a reducer missing the\n  precedence rule, diverges per adapter; both have happened.\n- Docs: effect list in `docs\u002Fdesign.md` §7, table in `docs\u002Fconcepts.md`,\n  composition rule 4 if terminality changed.\n\n## New capability id\n\n- Append to `ALL_CAPABILITY_IDS` (`packages\u002Fsdk\u002Fsrc\u002Fcapabilities.ts`).\n- Rate it in **all three** `packages\u002Fadapter-*\u002Fsrc\u002Fprofile.ts` matrices;\n  non-exact levels need a rationale (testkit-enforced, and rendered to users\n  by `inspect`).\n- Ask first whether the real gate is per-target at all: per-invocation\n  knowledge (like tool shape coverage) cannot live in a build-time matrix —\n  reuse the existing capability and document a runtime feature-detect\n  instead (ADR-0007's reasoning).\n\n## New diagnostic code\n\n- `DIAGNOSTIC_CODES` in `packages\u002Fcore\u002Fsrc\u002Fdiagnostics.ts`; if the runtime\n  can raise it, also `RUNTIME_DIAGNOSTIC_CODES` in\n  `packages\u002Fsdk\u002Fsrc\u002Fresult.ts` (deliberate duplication — the SDK cannot\n  import core; core asserts the subset matches, so drift is a compile error).\n- Code table in `docs\u002Fdesign.md` and `docs\u002Fglossary.md`. Codes are stable:\n  never renumber (the misfamilied HN502 is documented, not renumbered).\n\n## Shell or file shape \u002F toolmap entry\n\nCapture first — load the `harness-capture` skill. Then: one `ShellShapes`\nentry per captured tool; both codec directions derive from it, and the\ntestkit round-trips every shell-bearing fixture. File tools go in\n`FileShapes` (`{ pathKey }` or `{ patchKey }`, read side only, ADR-0026); the\ntestkit re-classifies every file-bearing fixture and requires a fixture per\nentry. Uncaptured tools stay absent. A new or renamed tool name also needs its\n`ToolKind` entry — capture found OpenCode's patch tools misclassified because\nonly the shape had been considered.\n\n## Shell dialect\n\nADR-0029 is the decision; this is what moves. A payload capture is not\nevidence for a dialect: only the interpreter that ran is, observed across the\nhost configurations that could change it (`.capture\u002Fshell-dialects`).\n\n- **A tool that pins one**: `dialect` on its `ShellShapes` entry. The codec\n  emits it, and the contract suite then requires the tool's fixtures to record\n  it.\n- **A harness that states its shell**: the shim listens, the decoder receives\n  the name as enrichment and maps it, and `classifyTool` applies a\n  `ReportedToolFacts.shellDialect`. Map a name only after a capture saw it\n  stated and run. Promote an enrichment fixture for a mapped name and for an\n  unmapped one, and keep the playback assertion that a real shell call carries\n  a dialect: it is what notices reworded prose.\n- **Neither**: leave it absent. Never derive it from the platform or an\n  environment variable.\n- **Always**: declare which of the three it is in the adapter's\n  `shellDialect` (`tool`, `statement`, `none`, with a rationale). `inspect`\n  and the generated support page print it and the contract suite holds the\n  table and classifier to it. A shim that hears a statement also passes the\n  dialect to `dispatch()` as `shellDialect`, or a view that a rewrite creates\n  has none.\n- **A new family**: `SHELL_DIALECTS` in `tools.ts` (the schema twin derives\n  from it), the name map, and the three places docs list the values\n  (`design.md` §6.3, `concepts.md`, `writing-hooks-safely.md`).\n\n## New normalized tool view\n\nA view like `tool.shell`\u002F`tool.file` moves together across: the SDK type and\ncodec (`tools.ts`), the strict `toolInvocationSchema` twin (`schemas.ts`), the\nadapter interface (`core\u002Fsrc\u002Fadapter.ts`), each adapter's toolmap classifier,\nindex and shim, `cli\u002Fsrc\u002Fdispatch.ts`, dispatch's `setToolInput` re-derive\n(a rewrite must never leave a view stale), the testkit contract obligations,\nand regenerated canonicals. It is a normalization decision, so it gets an ADR.\n\n## New adapter\n\n`docs\u002Fadding-an-adapter.md` is the authoritative workflow (capture → fixtures\n→ profile → decode\u002Fapply → shim → `describeAdapterContract` +\n`packages\u002Fcli\u002Fsrc\u002Fcoverage.test.ts` SUBJECTS row). For the planning, surface\ninventory, probe budget and completeness gates, load `harness-integration`.\n\n## Shared tail (every extension)\n\n1. Shims must never value-import `@hooknostic\u002Fcore`\n   (`packages\u002Fcli\u002Fsrc\u002Fpackage.test.ts` enforces; it drags esbuild into every\n   artifact).\n2. Mutation-verify each new test against the defect it pins (AGENTS.md hard\n   rule).\n3. Rebuild `examples\u002F*\u002Fdist` from the repo root; the reproducibility gate\n   byte-compares.\n4. Full gates with explicit exit codes: `pnpm lint`, `pnpm build`,\n   `pnpm test`.\n5. Update tutorials\u002FREADME snippets that teach the old surface — the front\n   page and tutorials 01–03 all carry live hook bodies that have drifted\n   before.\n",{"name":5,"description":7},"master","b8669236433862d74703a9a146bf1373f9b0b209",".agents\u002Fskills\u002Fextend-vocabulary",0,"https:\u002F\u002Fgithub.com\u002Froryeckel\u002Fhooknostic","https:\u002F\u002Fgithub.com\u002Froryeckel","https:\u002F\u002F2labz.com","I write a lot of software and delegate the rest to LLMs","2026-11-15 04:44:54",{"source":8,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add roryeckel\u002Fhooknostic --skill extend-vocabulary",{"tool":39,"command":40},"bunx","bunx skills add roryeckel\u002Fhooknostic --skill extend-vocabulary",{"tool":42,"command":43},"pnpm","pnpm dlx skills add roryeckel\u002Fhooknostic --skill extend-vocabulary","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Froryeckel\u002Fhooknostic\u002Fblob\u002Fmaster\u002F.agents\u002Fskills\u002Fextend-vocabulary\u002FSKILL.md",true,[],[48,55,60,65,70,77],{"skillNo":49,"name":50,"nameZh":6,"description":51,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":52,"categories":53,"keywords":54,"publishedAt":19},"01M7AXANW27HCE8N4ZD2H8GZG5","sample","Explain the synthetic sample project.","https:\u002F\u002Fgithub.com\u002Froryeckel\u002Fhooknostic\u002Fblob\u002Fmaster\u002Fexamples\u002Flocal-project\u002Fskills\u002Fsample\u002FSKILL.md",[],[],{"skillNo":56,"name":50,"nameZh":6,"description":51,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":57,"categories":58,"keywords":59,"publishedAt":19},"01M7AXAKKRACEVMN7CZ44ZC6A1","https:\u002F\u002Fgithub.com\u002Froryeckel\u002Fhooknostic\u002Fblob\u002Fmaster\u002Fexamples\u002Flocal-project\u002F.pi\u002Fskills\u002Fsample\u002FSKILL.md",[],[],{"skillNo":61,"name":50,"nameZh":6,"description":51,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":62,"categories":63,"keywords":64,"publishedAt":19},"01M7AXAJEYX4DKRCRBSNPM7J09","https:\u002F\u002Fgithub.com\u002Froryeckel\u002Fhooknostic\u002Fblob\u002Fmaster\u002Fexamples\u002Flocal-project\u002F.claude\u002Fskills\u002Fsample\u002FSKILL.md",[],[],{"skillNo":66,"name":50,"nameZh":6,"description":51,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":67,"categories":68,"keywords":69,"publishedAt":19},"01M7AXAFPMXR8EJM4D2Z1WKBH2","https:\u002F\u002Fgithub.com\u002Froryeckel\u002Fhooknostic\u002Fblob\u002Fmaster\u002Fexamples\u002Flocal-project\u002F.agents\u002Fskills\u002Fsample\u002FSKILL.md",[],[],{"skillNo":71,"name":72,"nameZh":6,"description":73,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":74,"categories":75,"keywords":76,"publishedAt":19},"01M7AXADDP9ASKQBVG8T8KE3XV","greet","Greet the user by name and summarize the repo state.","https:\u002F\u002Fgithub.com\u002Froryeckel\u002Fhooknostic\u002Fblob\u002Fmaster\u002Fexamples\u002Fagent-plugin\u002Fskills\u002Fgreet\u002FSKILL.md",[],[],{"skillNo":78,"name":79,"nameZh":6,"description":80,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":81,"categories":82,"keywords":83,"publishedAt":19},"01M7AXAC2V6M2XGEEBAPARQA4R","where","Reports where this skill lives. Use when asked where the probe skill is.","https:\u002F\u002Fgithub.com\u002Froryeckel\u002Fhooknostic\u002Fblob\u002Fmaster\u002F.capture\u002Fskill-directory\u002FSKILL.md",[],[]]