# AI agents (skill)

Concorde ships one [Agent Skill](https://agentskills.io), `concorde`, so coding agents follow the framework patterns. Cursor, Claude Code, JetBrains Junie and other agents load it on their own when they work on Concorde code; there is nothing to add to your `AGENTS.md`.

On a [starter](/docs/getting-started/installation) project, run `yarn ai:sync` after install. On an existing project, install Concorde first, then run `ai-init`.

## Commands

| Context | Command |
|---------|---------|
| [create-concorde-ts-starter](https://www.npmjs.com/package/@supersoniks/create-concorde-ts-starter) project | `yarn ai:sync` |
| Any consumer app (after `yarn add @supersoniks/concorde`) | `node node_modules/@supersoniks/concorde/scripts/ai-init.mjs` |
| Concorde repo (contributors) | `yarn ai-init` |

Re-run the same command after each Concorde upgrade to refresh the skill.

## The skill

`SKILL.md` is the entry point: where to find the truth (the project, these docs, `custom-elements.json`), the critical rules and the imports. Details live in `rules/` files that the agent reads only for the topic at hand.

| File | Topic |
|------|-------|
| `SKILL.md` | Sources, critical rules, component shape, imports |
| `rules/data.md` | Store, `DataProviderKey`, `@subscribe` / `@publish` / `@bind` / `@handle`, `sub()`, `get` / `set` / `dp` |
| `rules/http.md` | `Endpoint`, `@get` / `@post`, API configuration |
| `rules/lists-forms.md` | `sonic-list` / `sonic-queue`, form fields |
| `rules/styling.md` | Theme, tokens, classes, styling rules |
| `rules/composition.md` | Parts of compound components, built-in states |
| `rules/troubleshooting.md` | Symptom → cause → fix: values not updating, requests not sent, empty lists |

## What gets installed

| Path | Role |
|------|------|
| `.agents/skills/concorde/` | The skill (read directly by Cursor) |
| `.claude/skills/concorde` | Symlink for Claude Code |
| `.junie/skills/concorde` | Symlink for JetBrains Junie |

Where symlinks are not allowed (some Windows setups), the skill is copied instead. Your own skills in these folders are never touched. Commit `.agents/` and the links if your team shares agent settings.

**`AGENTS.md` stays yours:** `ai-init` never reads or writes it.

## Flags

| Flag | Effect |
|------|--------|
| `--no-links` | Install `.agents/skills` only, without the `.claude` / `.junie` links |
| `--overlay <dir>` | Also install the skills found in `<dir>/skills/` (project kit) |

Source files in the npm package: `node_modules/@supersoniks/concorde/ai/skills/concorde/`.