feat(install): add --skills-dir mode (Claude Code skills-directory plugin)

[mh0pe]

What

Adds --skills-dir [--dir <path>] to the installer. It writes a self-contained skills-directory plugin that Claude Code auto-loads in place as base@skills-dir:

• .claude-plugin/plugin.json
• commands/, skills/, base-framework/
• hooks/ (the 5 UserPromptSubmit hooks + satellite-detection SessionStart + a SessionStart MCP-deps bootstrapper) with hooks/hooks.json ({hooks:{...}} envelope)
• mcp/base-mcp/ + a root .mcp.json
• framework @-includes rewritten to ${CLAUDE_PLUGIN_ROOT}

Default target: <cwd>/.claude/skills/base/.

Why

• Zero install — no claude plugin install, no marketplace setup.
• Works in Claude Code Cloud — the cloud env clones the repo's .claude/skills/ but cannot see local marketplace installs; a committed skills-dir plugin is the supported way to ship a plugin to cloud.
• Version-pins to the project and travels with the repo.

MCP bootstrapping

A skills-dir (or marketplace) plugin has no install step, so the base-mcp npm deps aren't present at launch and node mcp/base-mcp/index.js would fail with ERR_MODULE_NOT_FOUND. The emitted plugin includes a fail-open SessionStart hook that idempotently installs the MCP deps into ${CLAUDE_PLUGIN_DATA} and links them onto the MCP's module-resolution path (base-mcp is ESM, and Node's ESM loader ignores NODE_PATH, so a node_modules symlink is the operative mechanism; .mcp.json also sets NODE_PATH as a harmless CJS fallback). The hook short-circuits when deps already exist and never blocks the session if npm or ${CLAUDE_PLUGIN_DATA} is unavailable.

Verified: after the SessionStart install, the MCP boots cleanly (BASE MCP Server running on stdio, 21 tools) with no ERR_MODULE_NOT_FOUND.

First-session caveat: Claude Code may spawn the MCP concurrently with the SessionStart hook, so on a brand-new install the base-mcp becomes available from the next session (or after a restart) once deps are linked.

Relationship to the workspace-resolution PR

This branch includes the CLAUDE_PROJECT_DIR workspace-resolution fix offered standalone in the companion PR (the hooks need CLAUDE_PROJECT_DIR-aware resolution to work correctly in the .claude/skills/base/hooks/ layout). If the workspace PR is merged first, the overlapping commits apply cleanly; recommend merging that one first.

Notes

• Existing install / --workspace paths are unchanged. --skills-dir cannot be combined with --global / --local (errors out).
• Project-runtime refs (@.base/...) are left untouched; only framework @-includes are rewritten. apex-insights is an on-demand command and is intentionally not event-wired.
• Ref: https://code.claude.com/docs/en/plugins-reference#skills-directory-plugins

🤖 Generated with Claude Code

[mh0pe]

Related PRs — part of a coordinated cross-repo offer (--skills-dir install mode (Claude Code skills-directory plugin)) applied across the carl/base/paul/seed framework forks:

• feat(install): add --skills-dir mode (Claude Code skills-directory plugin) carl#10
• feat(install): add --skills-dir mode (Claude Code skills-directory plugin) paul#19
• feat(install): add --skills-dir mode (Claude Code skills-directory plugin) seed#4

Reviewing them together is recommended; the same change pattern is mirrored per repo.