[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M753YPV8GFDJTRTAS06VSPXZ":3,"skill-same:01M753YPV8GFDJTRTAS06VSPXZ":52},{"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},"01M753YPV8GFDJTRTAS06VSPXZ","toolkit-debugging-playbook",null,"Use when a skill or plugin from jabworks\u002Fagentic-toolkit misbehaves — a skill doesn't trigger, a plugin doesn't show up after install, dist looks out of date, the installed copy differs from the repo, or a manifest fails to parse. Symptom → first discriminating command → root cause, with false friends and stop-and-ask points. Triggers include \"why isn't my skill triggering\", \"why isn't X showing up\", \"plugin not showing up\", \"dist drift\", \"stale plugin\", \"skill broken\".","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-debugging-playbook\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: toolkit-debugging-playbook\ndescription: Use when a skill or plugin from jabworks\u002Fagentic-toolkit misbehaves — a skill doesn't trigger, a plugin doesn't show up after install, dist looks out of date, the installed copy differs from the repo, or a manifest fails to parse. Symptom → first discriminating command → root cause, with false friends and stop-and-ask points. Triggers include \"why isn't my skill triggering\", \"why isn't X showing up\", \"plugin not showing up\", \"dist drift\", \"stale plugin\", \"skill broken\".\nwhen_to_use: The toolkit's own distribution machinery is the suspect, and you have the repo. Not for ordinary bugs in the app you're building — that's root-cause-analysis. Not for whether an installed plugin is registered and working on this machine — that's the plugin's own doctor (docket-doctor), which needs no checkout.\n---\n\n# Toolkit Debugging Playbook\n\n## Purpose\n\nTriage skill\u002Fplugin problems in this repo without wandering: one discriminating command\nper symptom, known root causes, and the false friends that burn time.\n\n## When to use\n\nAny misbehavior of this toolkit's skills, plugins, manifests, sync, or installs.\n\n## When not to use\n\n- General code bugs in a project → condux `root-cause-analysis`.\n- The question is about *one machine's install* rather than the repo — is the\n  server registered, did the hook get wired, is the version current → that\n  plugin's doctor (`docket-doctor`). It probes the installed harness and\n  needs no checkout; this skill diagnoses the machinery that produced it.\n- The cause turns out to be description wording → hand off to\n  `toolkit-skill-standards`.\n- Nothing is broken and you're gating a release → `toolkit-change-control`.\n\n## Inputs required\n\nThe symptom as reported, plus a repo checkout. For install-side symptoms you may also\nneed the user to report their installed plugin version — you cannot see their machine.\n\n## Procedure — symptom table\n\nRun the discriminating command FIRST; don't theorize before it returns.\n\n| Symptom | First command | Likely root causes (ranked) |\n|---|---|---|\n| Skill doesn't trigger | `sed -n '1,10p' skills\u002F\u003Cn>\u002FSKILL.md` — does a trigger contract exist (description \"Use when…\" or `when_to_use`)? | 1. No\u002Fweak trigger contract (three skills shipped that way until 2026-07-08) 2. Stale installed cache (see below) 3. Collision — a sibling wins the trigger |\n| Plugin doesn't show up after install | `node -e 'for (const p of require(\".\u002F.claude-plugin\u002Fmarketplace.json\").plugins) console.log(p.name, p.source)'` | 1. Never registered (technical-spec, `66a71eb`) 2. `source` path doesn't resolve 3. Missing one of the two plugin.json manifests |\n| dist looks out of date | `node --test tests\u002Fdist-mirror.test.mjs` | 1. Sync not run after a skills\u002F edit (hook is local-only) 2. Someone hand-edited dist\u002F (it gets clobbered next sync) |\n| Installed copy differs from repo | compare versions: `node -p 'require(\".\u002Fdist\u002Fplugins\u002F\u003Cp>\u002F.claude-plugin\u002Fplugin.json\").version'` vs what the user's tool reports | Stale plugin cache — caches refresh only on version bump (`a4f4aa8`). Fix: bump both manifests, re-release |\n| Manifest fails to parse \u002F install errors | `node -e 'for (const s of [\"claude\",\"codex\"]) console.log(s, JSON.parse(require(\"fs\").readFileSync(\"dist\u002Fplugins\u002F\u003Cp>\u002F.\" + s + \"-plugin\u002Fplugin.json\")).name)'` | Invalid JSON; missing required field; `skills` path not `.\u002F`-prefixed |\n| MCP tools or hooks from a plugin stopped working on this machine | `node \u003Cskill-base>\u002Fdoctor.mjs` for that plugin — it names the host, the registration, and the fix | Hand off: the doctor's verdict *is* the diagnosis. Come back here only if it reports green while the plugin still misbehaves, which points at the host, not the registration |\n| Skill renders empty\u002Fgarbled in listings | `node --test tests\u002Fskill-invariants.test.mjs` then eyeball YAML quoting | Unquoted YAML with `:` in description (`a13e094`); over-budget frontmatter |\n| condux agents behave stale | `node --test tests\u002Fskill-invariants.test.mjs` (agents-mirror test) | Plugin-level `agents\u002F` not mirrored — sync's special case (`6ba6572`) |\n| Skill loads and runs, but its prescribed menu\u002Fsteps degrade over sessions | diff the skill's contract against a recent transcript of it running — which prescribed options or steps actually appeared? | 1. Two skills' prompts merged and the option set got improvised (CP-1 menu erosion, `2cc080d`) 2. A behavioral default read as license to omit options rather than shape the recommendation 3. The instruction buried too deep in a long body |\n\n## False friends\n\n- **\"The description must be bad\"** when a skill stops triggering after an edit —\n  check the installed-cache version first; the repo copy may be fine and the user's\n  cache stale.\n- **\"dist drifted, resync and move on\"** — resyncing hides the cause. If drift keeps\n  recurring, someone\u002Fsomething is editing dist\u002F directly; find it.\n- **\"The test passed, so the skill works\"** — `node --test` proves parity and budgets,\n  not content correctness or trigger quality.\n- **\"It works in Claude Code, so Codex is fine\"** — the manifests are a pair with real\n  divergence points (`hooks` wiring differs by design); check the codex side.\n\n## When to stop and ask the user\n\n- Any fix that renames, merges, or retires a skill (trigger-contract changes are\n  owner decisions).\n- Symptoms that depend on the user's machine state (installed versions, tool config)\n  after you've exhausted repo-side evidence.\n- Two plausible root causes with no repo-side discriminator left.\n\n## Evidence required\n\nThe discriminating command's output, quoted. Never report a root cause without the\ncommand that shows it.\n\n## Output artifact\n\nA triage note: symptom → command run → output → root cause → fix (or the question to\nask the user).\n\n## Common traps\n\nJumping to the fix that matches the last incident you remember — this repo's history\nshows the same symptom (\"users see the old behavior\") with two different causes\n(dist drift vs stale installed cache) needing opposite fixes.\n\n## Bad behavior this prevents\n\nDebugging session-report's already-fixed cost bug because the installed 1.3.4 cache\nkept serving pre-fix code — the real fix was a version bump to 1.3.5 (`a4f4aa8`), not\nanother code change. The symptom table routes \"installed differs from repo\" straight\nto the version check.\n\n## Related skills\n\n`toolkit-skill-standards` (wording-caused trigger misses), `toolkit-change-control`\n(publish gate after the fix), `toolkit-failure-archaeology` (has this happened\nbefore?), `toolkit-plugin-reference` (manifest field semantics),\n`docket-doctor` (is that plugin registered and working on *this* machine —\nthe install side, no checkout needed).\n\n## Provenance and maintenance\n\nRe-verify volatile claims with:\n- `node --test` — which invariants currently exist and pass\n- `git log --oneline -10` — whether new incident classes have appeared\n\nLast generated: 2026-07-08 (jq commands converted to node 2026-08-04 — jq is not\ninstalled everywhere; see toolkit-change-control)\nKnown uncertainty:\n- Exact cache-refresh behavior of each host tool (Claude Code vs Codex) is inferred\n  from one evidenced incident (`a4f4aa8`), not from tool documentation.\n","# Toolkit Debugging Playbook\n\n## Purpose\n\nTriage skill\u002Fplugin problems in this repo without wandering: one discriminating command\nper symptom, known root causes, and the false friends that burn time.\n\n## When to use\n\nAny misbehavior of this toolkit's skills, plugins, manifests, sync, or installs.\n\n## When not to use\n\n- General code bugs in a project → condux `root-cause-analysis`.\n- The question is about *one machine's install* rather than the repo — is the\n  server registered, did the hook get wired, is the version current → that\n  plugin's doctor (`docket-doctor`). It probes the installed harness and\n  needs no checkout; this skill diagnoses the machinery that produced it.\n- The cause turns out to be description wording → hand off to\n  `toolkit-skill-standards`.\n- Nothing is broken and you're gating a release → `toolkit-change-control`.\n\n## Inputs required\n\nThe symptom as reported, plus a repo checkout. For install-side symptoms you may also\nneed the user to report their installed plugin version — you cannot see their machine.\n\n## Procedure — symptom table\n\nRun the discriminating command FIRST; don't theorize before it returns.\n\n| Symptom | First command | Likely root causes (ranked) |\n|---|---|---|\n| Skill doesn't trigger | `sed -n '1,10p' skills\u002F\u003Cn>\u002FSKILL.md` — does a trigger contract exist (description \"Use when…\" or `when_to_use`)? | 1. No\u002Fweak trigger contract (three skills shipped that way until 2026-07-08) 2. Stale installed cache (see below) 3. Collision — a sibling wins the trigger |\n| Plugin doesn't show up after install | `node -e 'for (const p of require(\".\u002F.claude-plugin\u002Fmarketplace.json\").plugins) console.log(p.name, p.source)'` | 1. Never registered (technical-spec, `66a71eb`) 2. `source` path doesn't resolve 3. Missing one of the two plugin.json manifests |\n| dist looks out of date | `node --test tests\u002Fdist-mirror.test.mjs` | 1. Sync not run after a skills\u002F edit (hook is local-only) 2. Someone hand-edited dist\u002F (it gets clobbered next sync) |\n| Installed copy differs from repo | compare versions: `node -p 'require(\".\u002Fdist\u002Fplugins\u002F\u003Cp>\u002F.claude-plugin\u002Fplugin.json\").version'` vs what the user's tool reports | Stale plugin cache — caches refresh only on version bump (`a4f4aa8`). Fix: bump both manifests, re-release |\n| Manifest fails to parse \u002F install errors | `node -e 'for (const s of [\"claude\",\"codex\"]) console.log(s, JSON.parse(require(\"fs\").readFileSync(\"dist\u002Fplugins\u002F\u003Cp>\u002F.\" + s + \"-plugin\u002Fplugin.json\")).name)'` | Invalid JSON; missing required field; `skills` path not `.\u002F`-prefixed |\n| MCP tools or hooks from a plugin stopped working on this machine | `node \u003Cskill-base>\u002Fdoctor.mjs` for that plugin — it names the host, the registration, and the fix | Hand off: the doctor's verdict *is* the diagnosis. Come back here only if it reports green while the plugin still misbehaves, which points at the host, not the registration |\n| Skill renders empty\u002Fgarbled in listings | `node --test tests\u002Fskill-invariants.test.mjs` then eyeball YAML quoting | Unquoted YAML with `:` in description (`a13e094`); over-budget frontmatter |\n| condux agents behave stale | `node --test tests\u002Fskill-invariants.test.mjs` (agents-mirror test) | Plugin-level `agents\u002F` not mirrored — sync's special case (`6ba6572`) |\n| Skill loads and runs, but its prescribed menu\u002Fsteps degrade over sessions | diff the skill's contract against a recent transcript of it running — which prescribed options or steps actually appeared? | 1. Two skills' prompts merged and the option set got improvised (CP-1 menu erosion, `2cc080d`) 2. A behavioral default read as license to omit options rather than shape the recommendation 3. The instruction buried too deep in a long body |\n\n## False friends\n\n- **\"The description must be bad\"** when a skill stops triggering after an edit —\n  check the installed-cache version first; the repo copy may be fine and the user's\n  cache stale.\n- **\"dist drifted, resync and move on\"** — resyncing hides the cause. If drift keeps\n  recurring, someone\u002Fsomething is editing dist\u002F directly; find it.\n- **\"The test passed, so the skill works\"** — `node --test` proves parity and budgets,\n  not content correctness or trigger quality.\n- **\"It works in Claude Code, so Codex is fine\"** — the manifests are a pair with real\n  divergence points (`hooks` wiring differs by design); check the codex side.\n\n## When to stop and ask the user\n\n- Any fix that renames, merges, or retires a skill (trigger-contract changes are\n  owner decisions).\n- Symptoms that depend on the user's machine state (installed versions, tool config)\n  after you've exhausted repo-side evidence.\n- Two plausible root causes with no repo-side discriminator left.\n\n## Evidence required\n\nThe discriminating command's output, quoted. Never report a root cause without the\ncommand that shows it.\n\n## Output artifact\n\nA triage note: symptom → command run → output → root cause → fix (or the question to\nask the user).\n\n## Common traps\n\nJumping to the fix that matches the last incident you remember — this repo's history\nshows the same symptom (\"users see the old behavior\") with two different causes\n(dist drift vs stale installed cache) needing opposite fixes.\n\n## Bad behavior this prevents\n\nDebugging session-report's already-fixed cost bug because the installed 1.3.4 cache\nkept serving pre-fix code — the real fix was a version bump to 1.3.5 (`a4f4aa8`), not\nanother code change. The symptom table routes \"installed differs from repo\" straight\nto the version check.\n\n## Related skills\n\n`toolkit-skill-standards` (wording-caused trigger misses), `toolkit-change-control`\n(publish gate after the fix), `toolkit-failure-archaeology` (has this happened\nbefore?), `toolkit-plugin-reference` (manifest field semantics),\n`docket-doctor` (is that plugin registered and working on *this* machine —\nthe install side, no checkout needed).\n\n## Provenance and maintenance\n\nRe-verify volatile claims with:\n- `node --test` — which invariants currently exist and pass\n- `git log --oneline -10` — whether new incident classes have appeared\n\nLast generated: 2026-07-08 (jq commands converted to node 2026-08-04 — jq is not\ninstalled everywhere; see toolkit-change-control)\nKnown uncertainty:\n- Exact cache-refresh behavior of each host tool (Claude Code vs Codex) is inferred\n  from one evidenced incident (`a4f4aa8`), not from tool documentation.\n",{"name":5,"description":7,"when_to_use":24},"The toolkit's own distribution machinery is the suspect, and you have the repo. Not for ordinary bugs in the app you're building — that's root-cause-analysis. Not for whether an installed plugin is registered and working on this machine — that's the plugin's own doctor (docket-doctor), which needs no checkout.","main","5277649b071c1c0cdf4f15eee861b1608fc1bbcb","skills\u002Ftoolkit-debugging-playbook",0,"https:\u002F\u002Fgithub.com\u002Fjabworks\u002Fagentic-toolkit","https:\u002F\u002Fgithub.com\u002Fjabworks","2026-11-03 15:03:51",{"source":8,"skillName":5,"commands":33,"prompt":43,"zipAvailable":44},[34,37,40],{"tool":35,"command":36},"npx","npx skills add jabworks\u002Fagentic-toolkit --skill toolkit-debugging-playbook",{"tool":38,"command":39},"bunx","bunx skills add jabworks\u002Fagentic-toolkit --skill toolkit-debugging-playbook",{"tool":41,"command":42},"pnpm","pnpm dlx skills add jabworks\u002Fagentic-toolkit --skill toolkit-debugging-playbook","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fjabworks\u002Fagentic-toolkit\u002Fblob\u002Fmain\u002Fskills\u002Ftoolkit-debugging-playbook\u002FSKILL.md",true,[46],{"path":47,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":50,"sourceHtmlUrl":51},"evals\u002Ftrigger_eval.json","REFERENCE","参考文档",3644,"https:\u002F\u002Fgithub.com\u002Fjabworks\u002Fagentic-toolkit\u002Fblob\u002Fmain\u002Fskills\u002Ftoolkit-debugging-playbook\u002Fevals\u002Ftrigger_eval.json",[53,59,65,72,79,86],{"skillNo":54,"name":55,"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":56,"categories":57,"keywords":58,"publishedAt":19},"01M7540BPNTFZH7V41P5E2S692","orphan","https:\u002F\u002Fgithub.com\u002Fjabworks\u002Fagentic-toolkit\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fcomposition\u002Fbad\u002Fskills\u002Forphan\u002FSKILL.md",[],[],{"skillNo":60,"name":61,"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":62,"categories":63,"keywords":64,"publishedAt":19},"01M7540AG2KFTQ8DJMNV6806MV","no-blurb","https:\u002F\u002Fgithub.com\u002Fjabworks\u002Fagentic-toolkit\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fcomposition\u002Fbad\u002Fskills\u002Fno-blurb\u002FSKILL.md",[],[],{"skillNo":66,"name":67,"nameZh":6,"description":68,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":69,"categories":70,"keywords":71,"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":73,"name":74,"nameZh":6,"description":75,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":76,"categories":77,"keywords":78,"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":80,"name":81,"nameZh":6,"description":82,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":83,"categories":84,"keywords":85,"publishedAt":19},"01M753ZSKJSF8WFS7AXR2N65SE","toolkit-skill-standards","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.","https:\u002F\u002Fgithub.com\u002Fjabworks\u002Fagentic-toolkit\u002Fblob\u002Fmain\u002Fskills\u002Ftoolkit-skill-standards\u002FSKILL.md",[],[],{"skillNo":87,"name":88,"nameZh":6,"description":89,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":90,"categories":91,"keywords":92,"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",[],[]]