# Agent Kit

`npm install @exotel-npm-dev/signal-design-system` ships an `agent-kit/` folder
inside `node_modules` so a consuming product team's AI coding agent has
something to read without anyone visiting this source repo.

## What's in the kit

| File | Purpose | Where it goes in your project |
|---|---|---|
| `agent-kit/SKILL.md` | Claude Code / Cursor skill — a portable copy of this repo's `signal-design-system` skill, adapted to use Storybook MCP as its primary source (not relative file paths, which only work inside this repo) | `.claude/skills/signal-design-system/SKILL.md` (Claude Code) or `.cursor/skills/signal-design-system/SKILL.md` (Cursor) |
| `agent-kit/UX-CONSTITUTION.md` | Offline fallback copy of the product UX rulebook, correct for whichever npm version you installed | Optional — the skill fetches the live copy over MCP by default; keep this only if you want an offline reference |
| `agent-kit/mcp.json` | MCP server config (`signal-storybook`, hosted) | Merge its `mcpServers` block into your tool's own MCP config file (see "Wiring it up" below) |
| `agent-kit/postinstall.mjs` | Prints the setup banner on `npm install` | Nothing to do — runs automatically where lifecycle scripts are allowed |
| `agent-kit/README.md` | Short in-folder index | Reference only |

## Why the postinstall banner might not appear

The banner is best-effort, not the source of truth — everything it tells you is
also below in full. It stays silent (by design) when:

- You're in CI (`process.env.CI` is set).
- **pnpm v8+** — dependency lifecycle scripts are blocked by default. Run
  `pnpm approve-builds @exotel-npm-dev/signal-design-system` (or add it to
  `pnpm.onlyBuiltDependencies` in `package.json`) if you want it to run.
- **Yarn Berry (PnP)** — commonly restricts lifecycle scripts similarly; check
  your `.yarnrc.yml` / plugin config.
- You ran `npm install --ignore-scripts`.
- This package was pulled in transitively (not listed directly in your own
  `dependencies`/`devDependencies`) — the banner only prints for direct installs,
  to avoid spamming unrelated projects.

## Claude Code setup

```bash
mkdir -p .claude/skills/signal-design-system
cp node_modules/@exotel-npm-dev/signal-design-system/agent-kit/SKILL.md \
  .claude/skills/signal-design-system/SKILL.md
cp node_modules/@exotel-npm-dev/signal-design-system/agent-kit/UX-CONSTITUTION.md \
  .claude/skills/signal-design-system/UX-CONSTITUTION.md
```

Then merge `node_modules/@exotel-npm-dev/signal-design-system/agent-kit/mcp.json`'s
`mcpServers` block into your project's `.mcp.json` (create one at the repo root
if you don't have one yet).

## Cursor setup

```bash
mkdir -p .cursor/skills/signal-design-system
cp node_modules/@exotel-npm-dev/signal-design-system/agent-kit/SKILL.md \
  .cursor/skills/signal-design-system/SKILL.md
```

Merge the same `mcp.json` block into `.cursor/mcp.json`.

## Other agents

See `docs/STORYBOOK-MCP.md` § "Other agents" for GitHub Copilot, Windsurf, Codex
CLI, and Cline — their MCP config is typically a global/user-level file rather
than something this package can ship into your project directly.

## Version-awareness for pinned consumers

The hosted MCP server (`https://main--69ba4becb6eabba83cbd8bc1.chromatic.com/mcp`)
always serves whatever was most recently published on `main` — it does not track
your installed npm version. If you're intentionally pinned to an older
`@exotel-npm-dev/signal-design-system` version, `agent-kit/UX-CONSTITUTION.md`
from `node_modules` is correct for **that** version; treat the MCP-served copy as
"latest, may be ahead of what you have installed" in that case. No separate
mechanism needed — this falls out of shipping the file at all.

## Explicitly not included

The `signal-doc-sync` skill (and its Cursor rule equivalent) is intentionally
**not** part of this kit — it drafts updates to *this repo's own* UX Constitution
and component docs, not yours.