batcave-skills

Install and upgrade the Batcave skills — locally in a workspace or globally for the user.

Usage

# Into the current workspace (must be run from a Batcave workspace root):
npx batcave-skills install

# For all your projects (~/.claude/skills, skills only — no scripts):
npx batcave-skills install --global

A local install writes the Agent Skills standard layout (agentskills.io):

• .agents/skills/ — the real skill files (OpenCode, Codex, and Cursor discover this natively)
• .agents/scripts/ — the shared helper scripts
• .claude/skills/<name> — one symlink per managed skill, the Claude Code bridge: Claude Code does not read .agents/skills/ yet (anthropics/claude-code#50778), so each managed skill is linked in. Per-skill links, never a whole-directory link — foreign skills in a mixed .claude/skills/ are never touched. Drop the bridge in a future release once Claude Code ships .agents support.

Global installs stay at ~/.claude/skills — native for Claude Code and a documented global-compatibility source for OpenCode, so no bridge is needed.

Skills reference the helper scripts with the agent-neutral git idiom $(git rev-parse --show-toplevel)/.agents/scripts/<script> — no agent-specific variable substitution (workspaces are git repos; create-batcave-workspace runs git init), so the same SKILL.md text works in any coding agent's shell from any subdirectory.

Re-run the same command at any time to upgrade to the latest bundle. The installer is manifest-tracked (.agents/.batcave-skills.json): it adds/updates bundled skills and scripts and removes ones that no longer ship — but it never touches anything it didn't install. Upgrading from a pre-0.1.0 .claude/-layout install migrates automatically: the old managed entries leave .claude/, the manifest moves, and the bridge symlinks take over.

Workspace requirement

The skills are coupled to the Batcave workspace layout (plans/, repos/, researches/). Local installs therefore refuse to run outside a workspace (detected via .batcave.json or the folder trio). Use --force to override.

Every bundled skill also carries a guard block instructing the agent to stop with a clear message when invoked outside a Batcave workspace — important for globally installed skills, which appear in every project.

Create a workspace with create-batcave-workspace:

npx create-batcave-workspace my-workspace

Authoring skills

Skills live at skills/<name>/SKILL.md in this repo; that repo is their single source of truth. Start each SKILL.md with the standard guard block:

> **Batcave workspace required.** Before doing anything, verify the current
> directory is inside a Batcave workspace (it contains `.batcave.json`, or
> `plans/`, `repos/`, and `researches/`). If not, STOP: tell the user this
> skill must run inside a Batcave workspace and point them to
> `npx create-batcave-workspace <name>`. Do not create files outside a
> workspace unless the user explicitly insists.

Releasing

Same OIDC trusted-publishing flow as create-batcave-workspace: bump version, git tag vX.Y.Z, git push --follow-tags — the publish.yml workflow publishes to npm.