[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M753ZSKJSF8WFS7AXR2N65SE":3,"skill-same:01M753ZSKJSF8WFS7AXR2N65SE":51},{"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":6,"ownerDescription":6,"updatedAt":30,"install":31,"resources":44},"01M753ZSKJSF8WFS7AXR2N65SE","toolkit-skill-standards",null,"Use when writing or reviewing a SKILL.md for jabworks\u002Fagentic-toolkit — frontmatter budgets, the trigger contract (\"Use when…\" description or when_to_use field), progressive disclosure into references\u002F, and keeping a new description out of existing skills' trigger space. Triggers include \"review this skill description\", \"write the frontmatter\", \"does this collide with an existing skill\", \"where should this content live\". Not for scaffold\u002Fsync mechanics; use toolkit-foundry.","jabworks\u002Fagentic-toolkit","jabworks","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F159094119?v=4","01M753P4JBZBTT7WN1PJBPZJZP","JAB Works","01M753P4K5KDGEWGXWT811BZET",2,"MIT","https:\u002F\u002Fgithub.com\u002Fjabworks\u002Fagentic-toolkit\u002Fblob\u002Fmain\u002Fskills\u002Ftoolkit-skill-standards\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: toolkit-skill-standards\ndescription: Use when writing or reviewing a SKILL.md for jabworks\u002Fagentic-toolkit — frontmatter budgets, the trigger contract (\"Use when…\" description or when_to_use field), progressive disclosure into references\u002F, and keeping a new description out of existing skills' trigger space. Triggers include \"review this skill description\", \"write the frontmatter\", \"does this collide with an existing skill\", \"where should this content live\". Not for scaffold\u002Fsync mechanics; use toolkit-foundry.\n---\n\n# Toolkit Skill Standards\n\n## Purpose\n\nThe content bar every SKILL.md in this repo must clear: budgets, trigger contract,\nstructure, and collision discipline.\n\n## When to use\n\n- Drafting or rewriting any SKILL.md frontmatter or body in this repo.\n- Reviewing a proposed skill before it ships.\n- A description \"feels fine\" but the skill under- or mis-triggers.\n\n## When not to use\n\n- Scaffolding\u002Fregistering\u002Fsyncing mechanics → `toolkit-foundry`.\n- Adapting an externally-sourced skill template to the jabworks stack → `adapting-skills`\n  (then return here for this repo's frontmatter\u002Fmirror requirements).\n- Triage of a live triggering bug → `toolkit-debugging-playbook` first; it routes back\n  here when the cause is wording.\n\n## Inputs required\n\n- The draft SKILL.md (or the skill name to review).\n- The current library inventory: `ls skills\u002F` + each sibling's description AND\n  `when_to_use` (both fields form the trigger contract).\n\n## Procedure\n\n1. **Budgets (test-enforced):** description ≤ 500 chars; total frontmatter ≤ 1024;\n   `name` kebab-case and identical to the directory name. Check:\n   `node --test tests\u002Fskill-invariants.test.mjs`.\n\n2. **Trigger contract (owner-ratified 2026-07-08):** the contract is\n   description + `when_to_use` together.\n   - Standalone skills \u002F no `when_to_use`: description MUST start with \"Use when…\"\n     and lead with trigger terms a user would actually type.\n   - condux-style skills: description states what it does; `when_to_use` carries the\n     trigger conditions (\"Trigger when…\"). Both fields count against the 1024 budget.\n\n3. **Canonical frontmatter form (test-enforced).** \"Quote YAML strings\" was the old\n   rule; it caused its own incident (`2026-08-05` — a single-quoted value with a bare\n   apostrophe in `that's`). The rule is now a *shape*, not an instruction to quote:\n   - Every line is `key: value` — one space after the colon, no lists, no block\n     scalars.\n   - **Plain (unquoted) when the value is safe**: it must not start with\n     ``- ? : , [ ] { } # & * ! | > ' \" % @ ` ``, contain `: ` or ` #`, or end with `:`.\n   - **Double quotes otherwise**, escaped the way JSON escapes (`\\\"`, `\\\\`).\n   - **Single quotes are banned outright.** YAML needs `''` for a literal\n     apostrophe inside them, and that escape is the footgun. Nothing here needs them.\n\n   Don't hand-fix a violation — run `node scripts\u002Fcheck-frontmatter.mjs --fix`, which\n   rewrites illegal values and leaves legal ones byte-identical. Check with\n   `node --test tests\u002Ffrontmatter-canonical.test.mjs tests\u002Ffrontmatter-yaml.test.mjs`.\n\n   Why two gates: the canonical form makes the break unwritable, and the strict\n   `yaml` parse proves the form's premise. Neither `claude plugin validate` nor the\n   budget tests can do this — validate passed the file that broke Codex on\n   2026-08-05 (Claude's frontmatter parser is lenient), and the budget tests\n   regex-parse. See `toolkit-failure-archaeology` for all four incidents.\n\n4. **Front-load trigger terms.** Most important phrases first; include the literal\n   words users type (\"sync dist\", \"am I done\", \"browse specs\"). Workflow summaries\n   belong in the body, not the description.\n\n5. **Collision scan (mandatory).** Read every sibling description +\n   `when_to_use`. If the new skill's trigger space overlaps, either merge into the\n   sibling or add explicit mutual disambiguation — both skills name each other, the\n   way subagent-deployment (\"not for executing an ordered plan — that's\n   subagent-execution\") and subagent-execution (\"not for ad-hoc independent tasks —\n   that's subagent-deployment\") do. Known hot zones to check against: the subagent\n   pair, plan-review↔spec-browser (\"spec directory\"), preflight↔finalize (\"am I\n   done\"), toolkit-foundry↔adapting-skills (skill creation vs adaptation),\n   concord↔toolkit-failure-archaeology (\"has this happened before\").\n   Enforcement: `tests\u002Fskill-routing-contracts.test.mjs` asserts each guarded pair\n   names the other in frontmatter — **add every new pair there** so the guard can't\n   silently erode. `scripts\u002Fcollision-scan.mjs --check` exists but lexical scoring\n   was falsified (5% recall, 2026-07-09) — the reading, and the test, are the scan.\n\n6. **Progressive disclosure.** SKILL.md = concise runbook readable in one scan:\n   purpose, when (not) to use, procedure, traps, related skills. Long archaeology,\n   catalogs, templates, ledgers → `references\u002F`. Executable helpers → `scripts\u002F` or\n   references (see plan-review's `references\u002Fannotate-server.js`).\n\n7. **Every skill with a plausible sibling overlap must state when NOT to use it**\n   and name that sibling instead. Keep unrelated skills concise; do not invent a\n   false alternative merely to fill a section.\n\n8. **Interaction contracts.** A skill that prescribes a user-facing menu or\n   checkpoint must mark the option set as exhaustive (\"present every row, every\n   time\") and state that behavioral defaults shape the *recommendation marker*,\n   never which options appear — an un-defended menu erodes toward the default\n   over sessions (CP-1 incident, `2cc080d`). If another skill's prompt can absorb\n   the menu (e.g. a sign-off step doubling as the what-next menu), both skills\n   carry the requirement, on both sides of the seam.\n\n9. **Dependency ladder.** Anything the skill invokes beyond its own files must\n   follow the ladder (section below): work from skill files alone, prefer\n   detected richer surfaces, never depend across plugin boundaries.\n\n10. **Health check.** A plugin with machinery beyond skill files — hooks, a\n    server, a package registration — ships a doctor per the health-check\n    convention (section below). Reviewing such a plugin without asking \"how\n    would a user find out this is broken?\" is an incomplete review.\n\n## Artifact location contract\n\nAny skill that writes a file into the user's project follows this. Two tiers,\nsplit by durability — not by which skill produced them.\n\n| Tier | Where | Git |\n|---|---|---|\n| **Durable** — the user asked for this and will keep it | a normal project path (`specs\u002F`, `docs\u002F`) | committed |\n| **Working state** — scaffolding the durable thing was built from | `\u003Cgit-root>\u002F.\u003Cplugin-name>\u002F`, subdivided by artifact type | gitignored |\n\nThe directory is named for the **owning plugin**, never the skill and never the\nartifact. condux has 13 skills and one `.condux\u002F` — the install unit is the\nplugin, so it's the thing that owns a directory and the thing a user removes to\nstop the directory reappearing. `.handoffs\u002F` names content, not owner: two\nplugins can both produce handoffs, and the name doesn't say what to uninstall.\n\nCurrent owners: `.condux\u002F` (`designs\u002F plans\u002F progress\u002F scratch\u002F verification\u002F`),\n`.concord\u002F`, `.session-handoff\u002F`, `.session-report\u002F`.\n\n**Bootstrap** — the first write in a repo runs this, once:\n\n1. Resolve `\u003Cgit-root>` via `git rev-parse --show-toplevel`. Not a git repo →\n   fall back to CWD and say so once.\n2. `git check-ignore -q .\u003Cplugin-name>\u002F` — if already ignored, proceed silently.\n3. Otherwise ask once: \"`\u003Cskill>` keeps its working files in\n   `.\u003Cplugin-name>\u002F` — add it to `.gitignore` so they stay out of your\n   commits?\" On yes, append. If the user would rather not touch a tracked file,\n   write it to `.git\u002Finfo\u002Fexclude` instead.\n4. Never edit `.gitignore` or `.git\u002Finfo\u002Fexclude` without asking.\n\n**Override** — an explicit `AGENTS.md` path always beats these defaults.\n\nNever write working state into the repo root, into CWD, or into a project's\n`docs\u002F`: those belong to the project, not to the tool.\n\n## Dependency ladder\n\nA shipped skill may *prefer* richer surfaces but must *require* nothing beyond\nits own files. Three rungs:\n\n| Rung | Surface | Present |\n|---|---|---|\n| 1 | Skill files — SKILL.md, `references\u002F`, `scripts\u002F` | always, on every channel |\n| 2 | CLI bundled inside the skill dir (record's `server\u002Fdocket.mjs`) | always — travels with the skill through `npx skills add`; needs only Node |\n| 3 | Registered MCP server or hooks | host-dependent — exists only after plugin install and registration |\n\n- **Function on rung 1 alone.** `npx skills add` ships bare skill trees with no\n  plugin manifest — no `.mcp.json`, no hooks. A skill that requires rung 3 is\n  broken on an entire distribution channel regardless of how good its installer is.\n- **Prefer the highest rung you can detect; detect, never assume.** The\n  reference phrasing is record's: \"prefer the MCP tools when registered,\n  otherwise run the bundled CLI.\"\n- **Cross-plugin dependencies are banned at every rung.** A docket skill that\n  needs condux — or any skill that leans on a third-party MCP server or plugin — breaks silently for everyone without that plugin, and no\n  installer or doctor can fix a dependency the bundle doesn't ship.\n- What makes rung 3 a first-class preferred path rather than a lucky bonus:\n  `INSTALL.md` (detect → register → verify → report) makes it reliable to\n  reach, and the health-check convention below reports which rung each plugin\n  actually runs on per host.\n\nRatified 2026-08-05 (docket #6), graduating the older absolute \"assume no\nMCP\u002Fplugin is installed\" rule after docket shipped the ladder in practice.\n\n## Health-check convention\n\nThe standing counterpart to `INSTALL.md`: an installer verifies once, a\ndoctor verifies whenever you ask. Any plugin with machinery beyond skill\nfiles — hooks, a server, a package registration — ships one.\n`docket-doctor` is the reference implementation.\n\nFour beats, the same shape as ease-of-install:\n\n1. **Detect** — which hosts exist on this machine. Missing host is `absent`,\n   not an error.\n2. **Probe** — every registration the plugin depends on, per host. Static\n   parse **and** execution: the registered path must exist and the thing it\n   registers must answer. A manifest that parses while its server is dead is\n   the failure the convention exists to catch.\n3. **Report** — one row per probe, `host status detail`, nothing silent. A\n   host that needs nothing is named with its reason.\n4. **Fix** — print the repair for every broken row. Performing it is\n   optional and belongs to the plugin's own installer; never reimplement\n   registration inside a doctor.\n\nNon-negotiables:\n\n- **Probes must not mutate.** Every execution step answers \"what does this\n  write?\" first. concord's `capture.mjs` writes to the memory store, so it is\n  resolved and loaded but never invoked; an `initialize` round-trip mutates\n  nothing, so it runs.\n- **Offline.** Version comparison reads the local marketplace clone and\n  prints that clone's own age. A doctor runs in degraded conditions by\n  definition — one that hangs without network fails exactly when needed.\n- **Own files only.** A doctor lives inside its own skill directory so\n  `\u003Cskill-base>\u002Fdoctor.mjs` resolves on every distribution channel, and it\n  probes its own plugin. Cross-plugin doctors are banned for the same reason\n  cross-plugin dependencies are.\n- **Say what it cannot prove.** No child process can tell whether the host\n  *invoked* a hook. The report states that probes are static-plus-executable\n  so a green board is never misread as \"the hook fired\".\n\nStatuses are exactly four — `done`, `broken`, `absent`, `skipped`. Only\n`broken` fails the run: an unmade optional registration is `absent`, because\nthe ladder says the skill still works a rung down.\n\nRatified 2026-08-06 (docket #1).\n\n## Suppressed-class misses\n\nA trigger miss where **the description is not the problem**: the skill's\ndeclared vocabulary matches the user's turn near-verbatim, the skill still\ndoesn't fire, and the cause is content already injected into context (a memory\ndigest, an index) that satisfies the information need before the trigger is\nconsulted. Measured in `specs\u002Ftrigger-reliability\u002F` — `session-handoff` fired on\n~9% of resume-shaped turns against ~64% of wrap-up turns, same skill, same\ndeclared vocabulary, same sessions.\n\n**Recognising it is the whole value of this section.** The reflex on any miss is\nto rewrite the description, and on this class that reflex is measurably wasted:\nyou cannot fix being pre-empted by rewording the thing that was never consulted.\nA skill whose phrases are already declared and still missing is not a\ndescription defect — stop, and look for what answered the turn first.\n\nOne finding here generalises past nudges and is worth keeping in mind whenever\nanything injects into context: **directive, never content**. Injected text that\n*answers* a question suppresses the routing decision for it; text that only says\nwhere something routes does not. That is the mechanism behind the whole class\n(`specs\u002Ftrigger-reliability\u002F` Q1, Q3).\n\n### The nudge remedy is declined, not recommended (2026-08-28)\n\nThe named remedy used to be a conditional SessionStart hook injecting a short\nrouting directive — D2's routing-nudge convention. **It is no longer house\ndoctrine.** session-handoff carried the only instance and 2.0.0 removed it:\ncarrying a second SessionStart hook per suppressed skill was not judged worth\nits permanent cost, which is paid on every session of every install.\n\nTwo things this is *not*. It is not a falsification — the nudge was never\nmeasured, and Q4 shows no harness can measure one, so the rules were never\ntested. And condux's `workflow\u002Fhooks\u002Frouting.md` is **not** a surviving instance:\nit is unconditional and bundle-wide, which the convention's own first rule\nforbids. It is the precedent for SessionStart injection as a mechanism, nothing\nmore.\n\nThe rules themselves are archived intact in `specs\u002Ftrigger-reliability\u002F`\n(D2, retired) — read them there if a nudge is ever back on the table.\n\n**Bar for shipping one again**, both required, never this section alone:\n\n1. a measured suppressed-class verdict for the specific skill, and\n2. explicit owner sign-off on the ongoing token cost.\n\nAbsent both, a suppressed-class verdict is a finding to report, not a defect to\npatch. Reporting it honestly — \"this skill cannot win these phrases, here is\nwhy\" — beats shipping machinery nobody asked for.\n\nClass ratified 2026-08-28 (trigger-reliability D1\u002FD2); nudge remedy declined the\nsame day (docket #69, D2 retired).\n\n## Evidence required\n\nFor \"the description is fine\": show budget numbers and the collision scan result\n(which siblings were checked, why no overlap). For \"this collides\": quote the\noverlapping phrases from both skills.\n\n## Output artifact\n\nA pass\u002Ffail review with specific rewrites, or ship-ready frontmatter.\n\n## Common traps\n\n- Judging only the `description` and missing that 14+ skills carry their triggers in\n  `when_to_use` — you'll \"fix\" something that isn't broken.\n- Trimming needed procedure to fit a scan instead of moving it to `references\u002F`.\n- Writing the description about what the skill DOES instead of when it's NEEDED —\n  models trigger on user-moment language, not feature lists.\n\n## Bad behavior this prevents\n\nShipping a second \"sync my skills\" skill next to toolkit-foundry because the author\nnever read the sibling descriptions. Three skills in this repo (preflight,\nsubagent-execution, test-first-development) shipped with no machine-visible trigger\ncontract at all until the 2026-07-08 audit added their `when_to_use` fields — the\ncollision scan + trigger-contract check makes both failure shapes visible before ship.\n\n## Related skills\n\n`toolkit-foundry` (mechanics after content passes), `toolkit-change-control` (ship\ngate), `adapting-skills` (external templates first — and the owner of these\nstandards applied to skills in *other* projects), `toolkit-debugging-playbook`\n(live trigger failures).\n\n## Provenance and maintenance\n\nRe-verify volatile claims with:\n- `node --test tests\u002Fskill-invariants.test.mjs` — budgets\u002Fname enforcement\n- `node --test tests\u002Fskill-routing-contracts.test.mjs` — the guarded collision pairs\n- `grep -l 'when_to_use' skills\u002F*\u002FSKILL.md` — which skills use the two-field contract\n\nLast generated: 2026-07-08 (owners\u002Fcounts + routing-test enforcement noted 2026-08-04)\nKnown uncertainty:\n- How each host tool weights `description` vs `when_to_use` for auto-triggering is\n  unverified — treat front-loading BOTH fields as the safe default.\n","# Toolkit Skill Standards\n\n## Purpose\n\nThe content bar every SKILL.md in this repo must clear: budgets, trigger contract,\nstructure, and collision discipline.\n\n## When to use\n\n- Drafting or rewriting any SKILL.md frontmatter or body in this repo.\n- Reviewing a proposed skill before it ships.\n- A description \"feels fine\" but the skill under- or mis-triggers.\n\n## When not to use\n\n- Scaffolding\u002Fregistering\u002Fsyncing mechanics → `toolkit-foundry`.\n- Adapting an externally-sourced skill template to the jabworks stack → `adapting-skills`\n  (then return here for this repo's frontmatter\u002Fmirror requirements).\n- Triage of a live triggering bug → `toolkit-debugging-playbook` first; it routes back\n  here when the cause is wording.\n\n## Inputs required\n\n- The draft SKILL.md (or the skill name to review).\n- The current library inventory: `ls skills\u002F` + each sibling's description AND\n  `when_to_use` (both fields form the trigger contract).\n\n## Procedure\n\n1. **Budgets (test-enforced):** description ≤ 500 chars; total frontmatter ≤ 1024;\n   `name` kebab-case and identical to the directory name. Check:\n   `node --test tests\u002Fskill-invariants.test.mjs`.\n\n2. **Trigger contract (owner-ratified 2026-07-08):** the contract is\n   description + `when_to_use` together.\n   - Standalone skills \u002F no `when_to_use`: description MUST start with \"Use when…\"\n     and lead with trigger terms a user would actually type.\n   - condux-style skills: description states what it does; `when_to_use` carries the\n     trigger conditions (\"Trigger when…\"). Both fields count against the 1024 budget.\n\n3. **Canonical frontmatter form (test-enforced).** \"Quote YAML strings\" was the old\n   rule; it caused its own incident (`2026-08-05` — a single-quoted value with a bare\n   apostrophe in `that's`). The rule is now a *shape*, not an instruction to quote:\n   - Every line is `key: value` — one space after the colon, no lists, no block\n     scalars.\n   - **Plain (unquoted) when the value is safe**: it must not start with\n     ``- ? : , [ ] { } # & * ! | > ' \" % @ ` ``, contain `: ` or ` #`, or end with `:`.\n   - **Double quotes otherwise**, escaped the way JSON escapes (`\\\"`, `\\\\`).\n   - **Single quotes are banned outright.** YAML needs `''` for a literal\n     apostrophe inside them, and that escape is the footgun. Nothing here needs them.\n\n   Don't hand-fix a violation — run `node scripts\u002Fcheck-frontmatter.mjs --fix`, which\n   rewrites illegal values and leaves legal ones byte-identical. Check with\n   `node --test tests\u002Ffrontmatter-canonical.test.mjs tests\u002Ffrontmatter-yaml.test.mjs`.\n\n   Why two gates: the canonical form makes the break unwritable, and the strict\n   `yaml` parse proves the form's premise. Neither `claude plugin validate` nor the\n   budget tests can do this — validate passed the file that broke Codex on\n   2026-08-05 (Claude's frontmatter parser is lenient), and the budget tests\n   regex-parse. See `toolkit-failure-archaeology` for all four incidents.\n\n4. **Front-load trigger terms.** Most important phrases first; include the literal\n   words users type (\"sync dist\", \"am I done\", \"browse specs\"). Workflow summaries\n   belong in the body, not the description.\n\n5. **Collision scan (mandatory).** Read every sibling description +\n   `when_to_use`. If the new skill's trigger space overlaps, either merge into the\n   sibling or add explicit mutual disambiguation — both skills name each other, the\n   way subagent-deployment (\"not for executing an ordered plan — that's\n   subagent-execution\") and subagent-execution (\"not for ad-hoc independent tasks —\n   that's subagent-deployment\") do. Known hot zones to check against: the subagent\n   pair, plan-review↔spec-browser (\"spec directory\"), preflight↔finalize (\"am I\n   done\"), toolkit-foundry↔adapting-skills (skill creation vs adaptation),\n   concord↔toolkit-failure-archaeology (\"has this happened before\").\n   Enforcement: `tests\u002Fskill-routing-contracts.test.mjs` asserts each guarded pair\n   names the other in frontmatter — **add every new pair there** so the guard can't\n   silently erode. `scripts\u002Fcollision-scan.mjs --check` exists but lexical scoring\n   was falsified (5% recall, 2026-07-09) — the reading, and the test, are the scan.\n\n6. **Progressive disclosure.** SKILL.md = concise runbook readable in one scan:\n   purpose, when (not) to use, procedure, traps, related skills. Long archaeology,\n   catalogs, templates, ledgers → `references\u002F`. Executable helpers → `scripts\u002F` or\n   references (see plan-review's `references\u002Fannotate-server.js`).\n\n7. **Every skill with a plausible sibling overlap must state when NOT to use it**\n   and name that sibling instead. Keep unrelated skills concise; do not invent a\n   false alternative merely to fill a section.\n\n8. **Interaction contracts.** A skill that prescribes a user-facing menu or\n   checkpoint must mark the option set as exhaustive (\"present every row, every\n   time\") and state that behavioral defaults shape the *recommendation marker*,\n   never which options appear — an un-defended menu erodes toward the default\n   over sessions (CP-1 incident, `2cc080d`). If another skill's prompt can absorb\n   the menu (e.g. a sign-off step doubling as the what-next menu), both skills\n   carry the requirement, on both sides of the seam.\n\n9. **Dependency ladder.** Anything the skill invokes beyond its own files must\n   follow the ladder (section below): work from skill files alone, prefer\n   detected richer surfaces, never depend across plugin boundaries.\n\n10. **Health check.** A plugin with machinery beyond skill files — hooks, a\n    server, a package registration — ships a doctor per the health-check\n    convention (section below). Reviewing such a plugin without asking \"how\n    would a user find out this is broken?\" is an incomplete review.\n\n## Artifact location contract\n\nAny skill that writes a file into the user's project follows this. Two tiers,\nsplit by durability — not by which skill produced them.\n\n| Tier | Where | Git |\n|---|---|---|\n| **Durable** — the user asked for this and will keep it | a normal project path (`specs\u002F`, `docs\u002F`) | committed |\n| **Working state** — scaffolding the durable thing was built from | `\u003Cgit-root>\u002F.\u003Cplugin-name>\u002F`, subdivided by artifact type | gitignored |\n\nThe directory is named for the **owning plugin**, never the skill and never the\nartifact. condux has 13 skills and one `.condux\u002F` — the install unit is the\nplugin, so it's the thing that owns a directory and the thing a user removes to\nstop the directory reappearing. `.handoffs\u002F` names content, not owner: two\nplugins can both produce handoffs, and the name doesn't say what to uninstall.\n\nCurrent owners: `.condux\u002F` (`designs\u002F plans\u002F progress\u002F scratch\u002F verification\u002F`),\n`.concord\u002F`, `.session-handoff\u002F`, `.session-report\u002F`.\n\n**Bootstrap** — the first write in a repo runs this, once:\n\n1. Resolve `\u003Cgit-root>` via `git rev-parse --show-toplevel`. Not a git repo →\n   fall back to CWD and say so once.\n2. `git check-ignore -q .\u003Cplugin-name>\u002F` — if already ignored, proceed silently.\n3. Otherwise ask once: \"`\u003Cskill>` keeps its working files in\n   `.\u003Cplugin-name>\u002F` — add it to `.gitignore` so they stay out of your\n   commits?\" On yes, append. If the user would rather not touch a tracked file,\n   write it to `.git\u002Finfo\u002Fexclude` instead.\n4. Never edit `.gitignore` or `.git\u002Finfo\u002Fexclude` without asking.\n\n**Override** — an explicit `AGENTS.md` path always beats these defaults.\n\nNever write working state into the repo root, into CWD, or into a project's\n`docs\u002F`: those belong to the project, not to the tool.\n\n## Dependency ladder\n\nA shipped skill may *prefer* richer surfaces but must *require* nothing beyond\nits own files. Three rungs:\n\n| Rung | Surface | Present |\n|---|---|---|\n| 1 | Skill files — SKILL.md, `references\u002F`, `scripts\u002F` | always, on every channel |\n| 2 | CLI bundled inside the skill dir (record's `server\u002Fdocket.mjs`) | always — travels with the skill through `npx skills add`; needs only Node |\n| 3 | Registered MCP server or hooks | host-dependent — exists only after plugin install and registration |\n\n- **Function on rung 1 alone.** `npx skills add` ships bare skill trees with no\n  plugin manifest — no `.mcp.json`, no hooks. A skill that requires rung 3 is\n  broken on an entire distribution channel regardless of how good its installer is.\n- **Prefer the highest rung you can detect; detect, never assume.** The\n  reference phrasing is record's: \"prefer the MCP tools when registered,\n  otherwise run the bundled CLI.\"\n- **Cross-plugin dependencies are banned at every rung.** A docket skill that\n  needs condux — or any skill that leans on a third-party MCP server or plugin — breaks silently for everyone without that plugin, and no\n  installer or doctor can fix a dependency the bundle doesn't ship.\n- What makes rung 3 a first-class preferred path rather than a lucky bonus:\n  `INSTALL.md` (detect → register → verify → report) makes it reliable to\n  reach, and the health-check convention below reports which rung each plugin\n  actually runs on per host.\n\nRatified 2026-08-05 (docket #6), graduating the older absolute \"assume no\nMCP\u002Fplugin is installed\" rule after docket shipped the ladder in practice.\n\n## Health-check convention\n\nThe standing counterpart to `INSTALL.md`: an installer verifies once, a\ndoctor verifies whenever you ask. Any plugin with machinery beyond skill\nfiles — hooks, a server, a package registration — ships one.\n`docket-doctor` is the reference implementation.\n\nFour beats, the same shape as ease-of-install:\n\n1. **Detect** — which hosts exist on this machine. Missing host is `absent`,\n   not an error.\n2. **Probe** — every registration the plugin depends on, per host. Static\n   parse **and** execution: the registered path must exist and the thing it\n   registers must answer. A manifest that parses while its server is dead is\n   the failure the convention exists to catch.\n3. **Report** — one row per probe, `host status detail`, nothing silent. A\n   host that needs nothing is named with its reason.\n4. **Fix** — print the repair for every broken row. Performing it is\n   optional and belongs to the plugin's own installer; never reimplement\n   registration inside a doctor.\n\nNon-negotiables:\n\n- **Probes must not mutate.** Every execution step answers \"what does this\n  write?\" first. concord's `capture.mjs` writes to the memory store, so it is\n  resolved and loaded but never invoked; an `initialize` round-trip mutates\n  nothing, so it runs.\n- **Offline.** Version comparison reads the local marketplace clone and\n  prints that clone's own age. A doctor runs in degraded conditions by\n  definition — one that hangs without network fails exactly when needed.\n- **Own files only.** A doctor lives inside its own skill directory so\n  `\u003Cskill-base>\u002Fdoctor.mjs` resolves on every distribution channel, and it\n  probes its own plugin. Cross-plugin doctors are banned for the same reason\n  cross-plugin dependencies are.\n- **Say what it cannot prove.** No child process can tell whether the host\n  *invoked* a hook. The report states that probes are static-plus-executable\n  so a green board is never misread as \"the hook fired\".\n\nStatuses are exactly four — `done`, `broken`, `absent`, `skipped`. Only\n`broken` fails the run: an unmade optional registration is `absent`, because\nthe ladder says the skill still works a rung down.\n\nRatified 2026-08-06 (docket #1).\n\n## Suppressed-class misses\n\nA trigger miss where **the description is not the problem**: the skill's\ndeclared vocabulary matches the user's turn near-verbatim, the skill still\ndoesn't fire, and the cause is content already injected into context (a memory\ndigest, an index) that satisfies the information need before the trigger is\nconsulted. Measured in `specs\u002Ftrigger-reliability\u002F` — `session-handoff` fired on\n~9% of resume-shaped turns against ~64% of wrap-up turns, same skill, same\ndeclared vocabulary, same sessions.\n\n**Recognising it is the whole value of this section.** The reflex on any miss is\nto rewrite the description, and on this class that reflex is measurably wasted:\nyou cannot fix being pre-empted by rewording the thing that was never consulted.\nA skill whose phrases are already declared and still missing is not a\ndescription defect — stop, and look for what answered the turn first.\n\nOne finding here generalises past nudges and is worth keeping in mind whenever\nanything injects into context: **directive, never content**. Injected text that\n*answers* a question suppresses the routing decision for it; text that only says\nwhere something routes does not. That is the mechanism behind the whole class\n(`specs\u002Ftrigger-reliability\u002F` Q1, Q3).\n\n### The nudge remedy is declined, not recommended (2026-08-28)\n\nThe named remedy used to be a conditional SessionStart hook injecting a short\nrouting directive — D2's routing-nudge convention. **It is no longer house\ndoctrine.** session-handoff carried the only instance and 2.0.0 removed it:\ncarrying a second SessionStart hook per suppressed skill was not judged worth\nits permanent cost, which is paid on every session of every install.\n\nTwo things this is *not*. It is not a falsification — the nudge was never\nmeasured, and Q4 shows no harness can measure one, so the rules were never\ntested. And condux's `workflow\u002Fhooks\u002Frouting.md` is **not** a surviving instance:\nit is unconditional and bundle-wide, which the convention's own first rule\nforbids. It is the precedent for SessionStart injection as a mechanism, nothing\nmore.\n\nThe rules themselves are archived intact in `specs\u002Ftrigger-reliability\u002F`\n(D2, retired) — read them there if a nudge is ever back on the table.\n\n**Bar for shipping one again**, both required, never this section alone:\n\n1. a measured suppressed-class verdict for the specific skill, and\n2. explicit owner sign-off on the ongoing token cost.\n\nAbsent both, a suppressed-class verdict is a finding to report, not a defect to\npatch. Reporting it honestly — \"this skill cannot win these phrases, here is\nwhy\" — beats shipping machinery nobody asked for.\n\nClass ratified 2026-08-28 (trigger-reliability D1\u002FD2); nudge remedy declined the\nsame day (docket #69, D2 retired).\n\n## Evidence required\n\nFor \"the description is fine\": show budget numbers and the collision scan result\n(which siblings were checked, why no overlap). For \"this collides\": quote the\noverlapping phrases from both skills.\n\n## Output artifact\n\nA pass\u002Ffail review with specific rewrites, or ship-ready frontmatter.\n\n## Common traps\n\n- Judging only the `description` and missing that 14+ skills carry their triggers in\n  `when_to_use` — you'll \"fix\" something that isn't broken.\n- Trimming needed procedure to fit a scan instead of moving it to `references\u002F`.\n- Writing the description about what the skill DOES instead of when it's NEEDED —\n  models trigger on user-moment language, not feature lists.\n\n## Bad behavior this prevents\n\nShipping a second \"sync my skills\" skill next to toolkit-foundry because the author\nnever read the sibling descriptions. Three skills in this repo (preflight,\nsubagent-execution, test-first-development) shipped with no machine-visible trigger\ncontract at all until the 2026-07-08 audit added their `when_to_use` fields — the\ncollision scan + trigger-contract check makes both failure shapes visible before ship.\n\n## Related skills\n\n`toolkit-foundry` (mechanics after content passes), `toolkit-change-control` (ship\ngate), `adapting-skills` (external templates first — and the owner of these\nstandards applied to skills in *other* projects), `toolkit-debugging-playbook`\n(live trigger failures).\n\n## Provenance and maintenance\n\nRe-verify volatile claims with:\n- `node --test tests\u002Fskill-invariants.test.mjs` — budgets\u002Fname enforcement\n- `node --test tests\u002Fskill-routing-contracts.test.mjs` — the guarded collision pairs\n- `grep -l 'when_to_use' skills\u002F*\u002FSKILL.md` — which skills use the two-field contract\n\nLast generated: 2026-07-08 (owners\u002Fcounts + routing-test enforcement noted 2026-08-04)\nKnown uncertainty:\n- How each host tool weights `description` vs `when_to_use` for auto-triggering is\n  unverified — treat front-loading BOTH fields as the safe default.\n",{"name":5,"description":7},"main","5277649b071c1c0cdf4f15eee861b1608fc1bbcb","skills\u002Ftoolkit-skill-standards",0,"https:\u002F\u002Fgithub.com\u002Fjabworks\u002Fagentic-toolkit","https:\u002F\u002Fgithub.com\u002Fjabworks","2026-11-03 15:03:51",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add jabworks\u002Fagentic-toolkit --skill toolkit-skill-standards",{"tool":37,"command":38},"bunx","bunx skills add jabworks\u002Fagentic-toolkit --skill toolkit-skill-standards",{"tool":40,"command":41},"pnpm","pnpm dlx skills add jabworks\u002Fagentic-toolkit --skill toolkit-skill-standards","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fjabworks\u002Fagentic-toolkit\u002Fblob\u002Fmain\u002Fskills\u002Ftoolkit-skill-standards\u002FSKILL.md",true,[45],{"path":46,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":49,"sourceHtmlUrl":50},"evals\u002Ftrigger_eval.json","REFERENCE","参考文档",3058,"https:\u002F\u002Fgithub.com\u002Fjabworks\u002Fagentic-toolkit\u002Fblob\u002Fmain\u002Fskills\u002Ftoolkit-skill-standards\u002Fevals\u002Ftrigger_eval.json",[52,58,64,71,78,85],{"skillNo":53,"name":54,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":55,"categories":56,"keywords":57,"publishedAt":19},"01M7540BPNTFZH7V41P5E2S692","orphan","https:\u002F\u002Fgithub.com\u002Fjabworks\u002Fagentic-toolkit\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fcomposition\u002Fbad\u002Fskills\u002Forphan\u002FSKILL.md",[],[],{"skillNo":59,"name":60,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":61,"categories":62,"keywords":63,"publishedAt":19},"01M7540AG2KFTQ8DJMNV6806MV","no-blurb","https:\u002F\u002Fgithub.com\u002Fjabworks\u002Fagentic-toolkit\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fcomposition\u002Fbad\u002Fskills\u002Fno-blurb\u002FSKILL.md",[],[],{"skillNo":65,"name":66,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":68,"categories":69,"keywords":70,"publishedAt":19},"01M75404N306PY1JFPQ0GGNTYB","workflow","Routes any dev task into the right execution tier (Small\u002FMedium\u002FLarge) and carries condux's operating rules — proportional effort, lazy skill loading, soft gates, implement-yourself-by-default.","https:\u002F\u002Fgithub.com\u002Fjabworks\u002Fagentic-toolkit\u002Fblob\u002Fmain\u002Fskills\u002Fworkflow\u002FSKILL.md",[],[],{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":19},"01M753ZZ6TTA06GRJAG679BQ2H","usage-trace","Checks and manages durable, local usage capture — ingest, health status, and the opt-in limit snapshot — for Claude Code and Codex. Capture itself runs automatically at session start.","https:\u002F\u002Fgithub.com\u002Fjabworks\u002Fagentic-toolkit\u002Fblob\u002Fmain\u002Fskills\u002Fusage-trace\u002FSKILL.md",[],[],{"skillNo":79,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":19},"01M753ZKX3KTVYWX15A9A0WZN0","toolkit-research-frontier","Use when planning improvement work on jabworks\u002Fagentic-toolkit itself — open problems (trigger-collision automation, YAML-strict frontmatter checks, docs-catalog enforcement), existing assets, the next three concrete steps, and the four-front library-health campaign with commands and success criteria. Triggers include \"let's improve our toolkit\", \"let's improve this repo\", \"what should we improve next\", \"toolkit roadmap\", \"open problems\", \"run the health campaign\".","https:\u002F\u002Fgithub.com\u002Fjabworks\u002Fagentic-toolkit\u002Fblob\u002Fmain\u002Fskills\u002Ftoolkit-research-frontier\u002FSKILL.md",[],[],{"skillNo":86,"name":87,"nameZh":6,"description":88,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":89,"categories":90,"keywords":91,"publishedAt":19},"01M753ZCAH03BTJ33V2A4M6KDZ","toolkit-plugin-reference","Use when writing or editing plugin.json, marketplace.json, or package manifests in jabworks\u002Fagentic-toolkit and the exact schema matters — required fields, the .claude-plugin\u002F.codex-plugin pairing and where it diverges (interface, hooks), the skills-path form, how the four install channels consume the repo, and which SKILL.md frontmatter fields are real. Triggers include \"what fields does plugin.json need\", \"claude vs codex manifest\", \"marketplace entry format\", \"how opencode loads skills\".","https:\u002F\u002Fgithub.com\u002Fjabworks\u002Fagentic-toolkit\u002Fblob\u002Fmain\u002Fskills\u002Ftoolkit-plugin-reference\u002FSKILL.md",[],[]]