Claude Code skill

Every stackbone init and stackbone link writes a skill bundle at .claude/skills/stackbone/SKILL.md. The bundle is auto-discovered by Claude Code (and any other coding agent that reads .claude/skills/) and gives the agent the operating manual for the project: command surface, output contract, exit codes, environment variables, idiomatic workflows.

The skill is regenerated on every init / link, so stale skill files are not a maintenance burden — re-run either command if the bundle drifts.

Why

The CLI is designed for a coding agent to drive — --json, semantic exit codes, stackbone metadata, inline stackbone docs. But for the agent to actually use those primitives it has to know they exist. Dropping a skill in .claude/skills/ is the standard discovery mechanism: Claude Code reads the frontmatter description, decides whether the user's task matches, and only loads the body when it does.

This is the progressive-disclosure / find-skills pattern. It avoids both extremes:

• Don't dump the manual into every prompt — that's token-expensive and pollutes context.
• Don't make the agent guess — that wastes turns rediscovering the exit-code table and the --json envelope.

Where the bundle lives

<project root>/
└── .claude/
    └── skills/
        └── stackbone/
            └── SKILL.md

The skill is committed to git so the whole team (and any CI agent) shares the same operating manual. stackbone init patches .gitignore to exclude .stackbone/ (which contains the project's workspaceId / agentId linkage) but include .claude/.

What it contains

The frontmatter follows the Anthropic Skills convention:

---
name: stackbone
description: Use this skill when the user is working with the Stackbone CLI,
  the `@stackbone/sdk` package, the `agent.yaml` manifest, official
  templates, or connections to the Stackbone control plane. Triggers on
  commands like `stackbone init`, `stackbone dev`, `stackbone deploy`, on
  questions about workspace state, exit codes, or environment variables,
  and on any reference to `@stackbone/*` imports in TypeScript code.
  Provides the command surface, output contract, exit codes, environment
  variables and idiomatic workflows.
---

The body covers:

• The CLI binary (stackbone, also npx stackbone) and how to get inline help (stackbone docs cli, stackbone docs sdk).
• The --json envelope shape (schema_version, error, exit_code).
• The exit-code table (0–5) so the agent can branch without parsing prose.
• The environment-variable conventions (STACKBONE_*).
• Idiomatic workflows (stackbone metadata instead of whoami + current
  • list, etc.).

The body is version-locked to the CLI release that emits it — the skill is regenerated by stackbone init and stackbone link, so an upgrade path is just pnpm add -g @stackbone/cli@latest followed by stackbone link --force.

Updating the skill

The upstream template lives at apps/cli/src/skills/templates.ts. It's intentionally inlined as a TS string literal so the bundled CLI binary stays single-file and the skill is locked to its release.

To update the skill content, edit templates.ts, ship a new CLI version, and rerun stackbone link --force (or stackbone init for new projects). Don't hand-edit .claude/skills/stackbone/SKILL.md in your project — the next init / link will overwrite it.

Other coding agents

The same .claude/skills/ directory is read by any tool that follows the convention (today that's Claude Code; other agents that adopt the spec will pick the file up automatically). The skill body is plain markdown, so it's also human-readable — open it as your in-repo quick-reference if you'd rather not run stackbone docs every time.

TODO — when other coding-agent tools need a different skill format (Cursor, Codex), document their target file here. The assembler in apps/cli/src/skills/assembler.ts already supports multiple targets via the targets/ directory.