CLAUDE.md — sku-skills

# CLAUDE.md — sku-skills

Project instructions for Claude Code working in this repo. See [`AGENTS.md`](./AGENTS.md) for the
full agent protocol and [`SKILL_SPEC.md`](./SKILL_SPEC.md) for the canonical format.

## What this is

An open-source library of e-commerce agent skills for the [SKU.io](https://developer.sku.io) API.
Skills are authored **once** in a canonical format (`skills/<domain>/<name>/`) and compiled to
Claude / OpenAI / Gemini outputs under `dist/`.

## Using a skill (not editing one) — read this first

If the user's ask is a **real SKU.io task** ("load our opening stock", "import this price list")
rather than a change to this library, you are in the wrong directory and none of the rules below
apply to you. Cloning this repo installs nothing — built skills live in `dist/claude/<domain>/<name>/`,
but Claude Code only scans `~/.claude/skills/` and `<project>/.claude/skills/`.

```bash
node tools/install.mjs --list                  # what's available
node tools/install.mjs set-initial-inventory   # → ~/.claude/skills/, with the skills it composes with
node tools/install.mjs build-product-catalog --project ~/work/acme   # or scope it to one project
```

Then start a session **in the user's own project** and describe the task in plain terms — the skill
is chosen from the request, not invoked by name. Auth is the skill's job: `connect-to-sku` installs
alongside every skill and each one opens with a generated **Step 0 — Connect first**, so let it
establish the tenant and mint the PAT rather than asking for a token yourself.

Everything below is for **authoring** skills. Don't run a customer's task through it.

## Non-negotiables

- **Source of truth is `skills/` and `shared/`.** `dist/` is generated by `npm run build` and is
  **committed** — never hand-edit it; regenerate it and commit the refreshed `dist/` whenever you
  change a skill (CI verifies it's up to date).
- **Real endpoints only.** Every path/method/field in a `skill.yaml` must come from the live API
  (<https://developer.sku.io>). Do not invent or guess endpoints. When in doubt, verify or leave out.
- **Least-privilege scopes.** `auth.scopes` = exactly what the operations require.
- **Guardrails required** for any create/update/delete/adjust skill (idempotency, confirm-before-send,
  don't-invent-ids).
- **`npm run check` must pass** before finishing any change.
- **Never commit secrets** — examples use placeholders (`$SKU_PAT`, `$SKU_TENANT`, fake ids).

## Workflow

```bash
npm ci
# edit skills/<domain>/<name>/{skill.yaml,INSTRUCTIONS.md}
npm run check      # validate schema + build all three targets
```

Changing a workflow skill? Also run `npm run check:node-refs -- --source <sku app checkout>` (or
with `SKU_TENANT`/`SKU_PAT` set) — it fails if a node type the skill names is gone from the app's
registry. It is not in CI, which has neither.

Match the structure and quality of the exemplars: `skills/products/find-product/` (simple),
`skills/orders/create-sales-order/` (request body + guardrails).

## Layout

| Path | Purpose |
| --- | --- |
| `skills/` | Canonical skills — **edit these** |
| `shared/` | Cross-cutting reference (auth, api overview, pagination, errors) |
| `schemas/skill.schema.json` | The `skill.yaml` schema (validated by `tools/validate.mjs`) |
| `tools/` | `build.mjs` (canonical → 3 targets), `validate.mjs`, `lib/` |
| `dist/` | Generated outputs — committed; regenerate with `npm run build`, never hand-edit |

## Do NOT

- Weaken `tools/validate.mjs` or the schema to make a skill pass — fix the skill.
- Hand-edit `dist/`, or commit `node_modules/` or unrelated lockfile churn. (Committing a
  freshly-built `dist/` alongside a skill change is expected.)
- Add real credentials or tenant data anywhere.