apm-marketplace-authoring-gotchasEight APM-marketplace-authoring gotchas discovered during real migrations from hand-authored .claude-plugin/marketplace.json to APM-managed and from CC-native plugin authoring. Use when: (1) running APM's packaging step (with or without `--dry-run`) or its marketplace-check command in a repo with an
apm-plugin-distribution-pathsCanonical authoring layout for an APM (microsoft/apm) package, plus the decision matrix for whether you need a `marketplace:` block. Use when: (1) you've run `apm init` and are unsure where SKILL.md / agent .md / command .md files belong (answer: under `.apm/`, NOT at repo root); (2) you've authored
autoresearch-is-code-metric-optimizerThe `/autoresearch:autoresearch` Claude Code skill is a CODE-METRIC OPTIMIZER (modify → verify → keep/discard loop). Use when: (1) you are about to invoke `/autoresearch:autoresearch` to do literature / web research (it does NOT fetch papers, search the web, or synthesize cited reports — use `/deep-
cc-hooks-main-vs-subagentHow a Claude Code PreToolUse/PostToolUse hook can tell whether a tool call came from the MAIN conversation thread or from a SUBAGENT (Task/Agent tool), plus the gotchas of testing hooks via headless `claude -p`. Use when: (1) building a hook that should apply only to the main thread (e.g. orchestrat
cc-mid-session-registry-stalenessFix for two Claude Code mid-session staleness traps that fail Workflow runs instantly (<15ms). Use when: (1) a Workflow agent() call fails with "agent type '<name>' not found" listing only plugin/built-in agents, even though .claude/agents/<name>.md exists with valid frontmatter — the agent registry
cc-plugin-cache-multi-version-not-recordedFix for Claude Code startup warning `Plugin "<name>" not cached at (not recorded) — run /plugins to refresh`. Use when: (1) Claude Code prints a `plugin-cache-miss` warning whose installPath is the literal string `(not recorded)`; (2) `claude plugin list` shows the plugin as installed with a valid v
cc-pluginroot-directory-source-ignoredFix for the Claude Code startup error `Plugin directory not found at path: <marketplace_root>/<plugin_name>. Check that the marketplace entry has the correct path.` when a local `source: "directory"` marketplace uses `metadata.pluginRoot` to factor a common prefix out of its plugin sources. Use when
claude-print-subprocess-error-streamsFix for opaque `RuntimeError: Claude session failed: ` (or any wrapper-error with empty content) when wrapping `claude --print --output-format json` in Python subprocess. Use when: (1) you wrap `claude --print` (or any `claude` non-interactive CLI invocation) via `subprocess.run` / `subprocess.commu
claude-workflow-authoring-gotchasFour gotchas that bite when authoring Claude Code Workflow scripts (the `Workflow` tool's `.js` files with `export const meta`). Use when: (1) Workflow tool call fails immediately with `Invalid workflow script: meta must be a pure literal: non-literal node type in meta: BinaryExpression`; (2) the sc
claude-workflow-meta-markdownlint-pure-literal-breakFix for a Claude Code Workflow script that fails to load with "meta must be a pure literal: non-literal node type in meta: BinaryExpression" even though the meta block looks fine and all its tests pass. Use when: (1) a workflow .js is rejected at load over meta/BinaryExpression; (2) workflow tests a
claude-workflow-plugin-distributionHow to distribute a Claude Code Workflow-tool script (the Workflow({script}) orchestration engine / .claude/workflows/*.js) through a plugin or marketplace, and how to architect it around the Workflow sandbox. Use when: (1) you want to "ship / package / distribute a workflow" in a plugin; (2) design
find-skillsHelps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable ski
plan-mode-orchestrator-write-deadlockRecognize and escape the deadlock where NO write can succeed because plan mode and an "orchestrator mode" hook block each other. Use when: (1) a PostToolUse/ PreToolUse hook returns "ORCHESTRATOR MODE: the main thread must not edit or write files directly... delegate it to a subagent"; (2) you are A
skill-creator-trigger-eval-gotchasSix chained gotchas when running the skill-creator plugin's trigger-eval machinery (scripts/run_loop.py, scripts/run_eval.py) against a skill. Use when: the trigger eval reports 0% recall or "skill never triggers" even on verbatim trigger phrases; `python -m scripts.run_loop` fails with `ModuleNotFo
team-mode-orchestration-verificationVerify teammate work in Claude Code team mode when main-thread TaskList appears empty or teammates go idle without sending SendMessage replies. Use when: (1) you've created a team via TeamCreate and TaskCreate but `TaskList` returns "No tasks found" from the main thread, (2) a teammate sends only id
vhs-claude-plugin-demosMake a hero GIF demo of a Claude Code plugin using VHS (charmbracelet/vhs). Use when: (1) writing a plugin README and want a terminal-demo GIF, (2) recording a screencast of a CLI that is ALSO wrapped by Claude Code slash commands, (3) the plugin has both slash commands (e.g. `/kb-query`) and an und