diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..20f80cd --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,95 @@ +# ShapeDiver Agent Skills — Agent Guide + +This repository is a **skill library** for building [ShapeDiver](https://shapediver.com/) 3D product configurators. It is not an application codebase. Skills follow the [Agent Skills specification](https://agentskills.io/specification). + +## Model requirements + +> **Warning:** These skills are written for **agent mode** (tool use, multi-step planning, reading skill files on demand). Lightweight chat models or non-agent assistants often skip the router, ignore `references/`, and produce incorrect ShapeDiver API code. + +For reliable results, the user should run an **agent-capable model at least as capable** as the defaults used in [`scripts/execute-evals.js`](scripts/execute-evals.js) (`LLM_MODEL` when set, otherwise): + +| Provider | Default `LLM_MODEL` | +| :------- | :------------------ | +| OpenRouter | `anthropic/claude-sonnet-4-20250514` | +| OpenAI | `gpt-4o` | +| Anthropic | `claude-sonnet-4-20250514` | + +Prefer **this tier or stronger** (e.g. newer Sonnet/Opus, GPT-4.1+, or the user's IDE default agent model). If output quality is poor, suggest switching to agent mode and a more capable model before changing skill content. + +Examples: Cursor **Agent**, Claude Code, GitHub Copilot **agent mode**, Codex with tools enabled. See [`EVALS.md`](EVALS.md) for eval setup and context limits on large skills. + +**Agent instruction:** If the user is on a weak or non-agent model, warn them explicitly and recommend upgrading before implementing ShapeDiver integrations. + +## When to use these skills + +Activate when the user mentions or implies: + +- ShapeDiver, Grasshopper-to-web, parametric 3D, or product configurator +- App Builder, Viewer V3, iframe embedding, or headless / Geometry SDK +- Credentials such as ticket, `modelViewUrl`, or model metadata for a ShapeDiver model + +## Required workflow + +1. On any ShapeDiver-related task, **read** [`skills/shapediver-router/SKILL.md`](skills/shapediver-router/SKILL.md) before other ShapeDiver skills or implementation code. +2. Complete routing and credential gathering per the router skill. Do not skip strategy selection. +3. When the router hands off, **read the full** target implementation `SKILL.md`. Load files under `references/` only when the skill directs you to. +4. Treat skill files as authoritative. Do not substitute training-data assumptions for API names, parameter names, or credentials. + +## Skill routing + +Install **all** skills when possible; the router may delegate to any of them. + +| Skill | Path | When to activate | +| :---- | :--- | :--------------- | +| `shapediver-router` | [`skills/shapediver-router/SKILL.md`](skills/shapediver-router/SKILL.md) | Start of every ShapeDiver project; strategy selection and credentials before coding. | +| `shapediver-appbuilder` | [`skills/shapediver-appbuilder/SKILL.md`](skills/shapediver-appbuilder/SKILL.md) | App Builder path; routes to iframe, theme, or fork. | +| `shapediver-appbuilder-iframe` | [`skills/shapediver-appbuilder-iframe/SKILL.md`](skills/shapediver-appbuilder-iframe/SKILL.md) | Embed App Builder via iframe; zero-code / simplest web integration. | +| `shapediver-appbuilder-theme` | [`skills/shapediver-appbuilder-theme/SKILL.md`](skills/shapediver-appbuilder-theme/SKILL.md) | App Builder with branding/theme (colors, fonts, logo) without custom React. | +| `shapediver-appbuilder-fork` | [`skills/shapediver-appbuilder-fork/SKILL.md`](skills/shapediver-appbuilder-fork/SKILL.md) | Fork the open-source App Builder React app for custom UI or backends. | +| `shapediver-viewer` | [`skills/shapediver-viewer/SKILL.md`](skills/shapediver-viewer/SKILL.md) | Custom Viewer V3 API code (CDN, NPM, React), parameters, exports, interactions. | +| `shapediver-headless` | [`skills/shapediver-headless/SKILL.md`](skills/shapediver-headless/SKILL.md) | Server-side / no viewport: Geometry SDK, exports, automation, CI. | + +## Installing skills for the user's project + +Help the user install skills into their project (not only into this repo). + +**Preferred (if available):** + +```bash +gh skill install shapediver/agent-skills +``` + +See [`README.md`](README.md) for GitHub CLI prerequisites and the interactive install flow. + +**Universal fallback:** Copy skill folders from this repository into `.agents/skills/` in the user's project: + +```bash +mkdir -p .agents/skills +cp -r /path/to/agent-skills/skills/* .agents/skills/ +``` + +Agent-specific skill directories (project scope / user scope): + +| Agent | Project scope | User scope | +| :---- | :------------ | :--------- | +| GitHub Copilot | `.github/skills/` or `.agents/skills/` | `~/.copilot/skills/` or `~/.agents/skills/` | +| Claude Code | `.claude/skills/` or `.agents/skills/` | `~/.claude/skills/` | +| Cursor | `.cursor/skills/` or `.agents/skills/` | `~/.cursor/skills/` | +| Others | `.agents/skills/` | `~/.agents/skills/` | + +For manual clone steps and repository layout, see [`README.md`](README.md). + +## Working in this repository + +- **Consumer work:** Follow the workflow above. Do not treat this repo as a deployable application. +- **Maintainer work:** Skill authoring and evals — see [`EVALS.md`](EVALS.md) and `scripts/`. + +## Out of scope + +- Do not invent ticket, `modelViewUrl`, or model-specific parameter names. +- Do not write implementation code during the routing phase. +- Do not skip reading the target implementation skill before coding. + +## Maintenance + +When adding or renaming a skill, update the skill tables in both [`README.md`](README.md) and this file. diff --git a/README.md b/README.md index 119765a..ef2e55e 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,10 @@ A collection of [Agent Skills](https://agentskills.io/) that give AI coding agents expert-level knowledge for building ShapeDiver 3D configurators. +## For AI agents + +If this repository is in your workspace, read [`AGENTS.md`](AGENTS.md) for the required ShapeDiver workflow (router first, then implementation skills), skill routing, and how to install skills into the user's project. + ## Installation ### Option 1: GitHub CLI (recommended)