feat: official AI agent skills + MCP server for anime.js v4

.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "name": "animejs",
+  "owner": {
+    "name": "Julian Garnier",
+    "url": "https://github.com/juliangarnier"
+  },
+  "metadata": {
+    "description": "Official anime.js agent skills marketplace.",
+    "version": "1.0.0"
+  },
+  "plugins": [
+    {
+      "name": "animejs-skills",
+      "source": "./",
+      "description": "anime.js v4 agent skills for Claude Code, Cursor, Copilot, and the cross-agent Agent Skills standard."
+    }
+  ]
+}

.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "animejs-skills",
+  "version": "4.0.0",
+  "description": "Official anime.js v4 agent skills with the correct named-import API and guidance that keeps agents off the v3 syntax, covering animation, timelines, SVG, text, scroll, draggable, easings, React, and frameworks.",
+  "author": {
+    "name": "Julian Garnier",
+    "url": "https://animejs.com"
+  },
+  "homepage": "https://animejs.com",
+  "repository": "https://github.com/juliangarnier/anime",
+  "license": "MIT",
+  "keywords": [
+    "anime.js",
+    "animejs",
+    "animation",
+    "svg",
+    "timeline",
+    "skills"
+  ],
+  "skills": "./skills"
+}

.cursor/rules/animejs.mdc

@@ -0,0 +1,33 @@
+---
+description: anime.js v4 uses named imports and animate(targets, params), never the v3 anime({ targets }) API
+globs: ["**/*.{js,ts,jsx,tsx,vue,svelte,mjs,cjs}"]
+alwaysApply: false
+---
+
+# anime.js v4
+
+This project uses anime.js **v4**. Generate the v4 API, never v3.
+
+v4 is an ES module with **named exports** and `animate(targets, params)`. There
+is no default export and no `anime()` function.
+
+```js
+// CORRECT (v4)
+import { animate } from 'animejs';
+animate('.square', { x: 320, duration: 1000, ease: 'inOutQuint' });
+
+// WRONG (deprecated v3)
+import anime from 'animejs';
+anime({ targets: '.square', translateX: 320, easing: 'easeInOutQuint' });
+```
+
+Rules:
+- Named imports from `animejs`; `animate(targets, params)`.
+- Transform shorthands `x`/`y`/`scale`/`rotate`, not `translateX`/`translateY`.
+- `ease` string (`'inOutQuad'`, `'out(3)'`, `'outElastic(.3,1.4)'`); durations in ms.
+- `createTimeline()` not `anime.timeline()`; `stagger()` not `anime.stagger()`;
+  helpers on `utils.*`.
+- `alternate: true` / `reversed: true` (not `direction:`); callbacks on-prefixed.
+- React/Vue/Svelte/Angular: wrap in `createScope({ root })`, `scope.revert()` on unmount.
+
+Full guidance: `skills/` (see `skills/anime-migration-v3-v4/SKILL.md` for fixing v3).

.github/copilot-instructions.md

@@ -0,0 +1,35 @@
+# anime.js v4 Copilot instructions
+
+This project uses anime.js **v4**. Always generate the v4 API, never v3.
+
+v4 is an ES module with **named exports** and the signature
+`animate(targets, params)`. There is **no default export** and **no `anime()`
+function**.
+
+```js
+// CORRECT (v4)
+import { animate, stagger } from 'animejs';
+animate('.square', { x: 320, duration: 1000, ease: 'inOutQuint' });
+
+// WRONG (deprecated v3, never generate)
+import anime from 'animejs';
+anime({ targets: '.square', translateX: 320, easing: 'easeInOutQuint' });
+```
+
+Rules:
+
+- **Named imports** from `animejs` (or subpaths like `animejs/timeline`).
+- **`animate(targets, params)`**: targets first, params second.
+- Transform shorthands `x`, `y`, `scale`, `rotate`, not `translateX`/`translateY`.
+- `ease` is a string: `'inOutQuad'`, `'out(3)'`, `'outElastic(.3, 1.4)'`,
+  `'steps(5)'`, `'linear'`.
+- Durations and delays in **milliseconds**.
+- `createTimeline()` not `anime.timeline()`; `stagger()` not `anime.stagger()`;
+  helpers on `utils.*` (`utils.set`, `utils.random`, `utils.get`, `utils.remove`).
+- `alternate: true` / `reversed: true` (not `direction:`); callbacks are
+  on-prefixed (`onUpdate`, `onBegin`, `onComplete`, `onLoop`, `onRender`).
+- React, Vue, Svelte, or Angular: wrap in `createScope({ root })` and call
+  `scope.revert()` on unmount.
+
+Full guidance: [`skills/`](../skills/) (see `skills/anime-migration-v3-v4/SKILL.md`
+to fix v3 syntax) and [`AGENTS.md`](../AGENTS.md).

.github/instructions/anime-core.instructions.md

@@ -0,0 +1,14 @@
+---
+applyTo: "**/*.{js,ts,mjs,cjs}"
+---
+
+When writing anime.js in JavaScript/TypeScript files, follow
+[`skills/anime-core/SKILL.md`](../../skills/anime-core/SKILL.md):
+
+- Named imports from `animejs`; `animate(targets, params)`.
+- Transform shorthands `x`/`y`/`scale`/`rotate` (not `translateX`/`translateY`).
+- `ease` string (`'inOutQuint'`, `'out(3)'`); durations in milliseconds.
+- `createTimeline()`, `stagger()`, `utils.*`, never `anime.timeline/stagger/random`.
+
+If you see v3 syntax (`import anime from 'animejs'`, `anime({ targets })`),
+convert it per [`skills/anime-migration-v3-v4/SKILL.md`](../../skills/anime-migration-v3-v4/SKILL.md).

.github/instructions/anime-frameworks.instructions.md

@@ -0,0 +1,12 @@
+---
+applyTo: "**/*.{vue,svelte}"
+---
+
+When writing anime.js in Vue or Svelte files, follow
+[`skills/anime-frameworks/SKILL.md`](../../skills/anime-frameworks/SKILL.md):
+
+- Build animations on mount (Vue `onMounted`, Svelte `onMount`) inside
+  `createScope({ root })` bound to a template ref.
+- Call `scope.revert()` on destroy (`onUnmounted` / `onDestroy`).
+- Use the v4 API: named imports, `animate(targets, params)`, `x`/`y` shorthands,
+  `ease` strings, `stagger()`, `utils.*`. Never the v3 `anime({ targets })`.

.github/instructions/anime-react.instructions.md

@@ -0,0 +1,14 @@
+---
+applyTo: "**/*.{jsx,tsx}"
+---
+
+When writing anime.js in React files, follow
+[`skills/anime-react/SKILL.md`](../../skills/anime-react/SKILL.md):
+
+- Create animations inside `useEffect` (or event handlers), never during render.
+- Wrap them in `createScope({ root })` where `root` is a `useRef` to the
+  component container; scoped selectors resolve within that subtree.
+- **Always** `return () => scope.current.revert()` from the effect (StrictMode-
+  and unmount-safe).
+- Use the v4 API: named imports, `animate(targets, params)`, `x`/`y` shorthands,
+  `ease` strings, `stagger()`, `utils.*`.

.github/workflows/skills.yml

@@ -0,0 +1,53 @@
+name: Agent skills & MCP
+
+# Validates the agent skills against the built library (every documented symbol
+# must be a real v4 export, no v3 syntax leaks) and runs the MCP server tests.
+# Scoped to the skills/MCP files so it does not interfere with library CI.
+
+on:
+  push:
+    branches: [dev, master]
+    paths:
+      - "skills/**"
+      - "scripts/**"
+      - "mcp/**"
+      - "llms.txt"
+      - ".github/workflows/skills.yml"
+  pull_request:
+    paths:
+      - "skills/**"
+      - "scripts/**"
+      - "mcp/**"
+      - "llms.txt"
+      - ".github/workflows/skills.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  validate-skills:
+    name: Validate skills against the built library
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - run: npm run validate:skills
+
+  mcp-tests:
+    name: MCP server tests
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: mcp
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+      - run: npm install
+      - run: npm test

AGENTS.md

@@ -0,0 +1,79 @@
+# AGENTS.md: anime.js v4
+
+Guidance for AI coding agents (Claude Code, Cursor, Copilot, Gemini, and others)
+working with anime.js. The detailed skills for each area live in [`skills/`](skills/).
+This file is the front door and the rules you must follow.
+
+## The one rule that matters
+
+**This is anime.js v4. Generate the v4 API, never v3.**
+
+v4 is an ES module with **named exports** and the signature
+`animate(targets, params)`. There is **no default export** and **no `anime()`
+function**.
+
+```js
+// CORRECT (v4)
+import { animate, stagger } from 'animejs';
+animate('.square', { x: 320, duration: 1000, ease: 'inOutQuint' });
+
+// WRONG (deprecated v3, never generate this)
+import anime from 'animejs';
+anime({ targets: '.square', translateX: 320, easing: 'easeInOutQuint' });
+```
+
+## Core conventions
+
+- **Named imports** from `animejs` (or subpaths like `animejs/timeline`).
+- **`animate(targets, params)`**: targets first (selector, element, array, or
+  object), params second.
+- Transform **shorthands**: `x`, `y`, `scale`, `rotate`, `skew`. Not
+  `translateX` or `translateY`.
+- The easing key is **`ease`**, and its value is a string with no prefix:
+  `'inOutQuad'`, `'out(3)'`, `'outElastic(.3, 1.4)'`, `'steps(5)'`, `'linear'`.
+- **Milliseconds** for `duration` and `delay`.
+- Use `createTimeline()`, not `anime.timeline()`. Use `stagger()` as a named
+  import, not `anime.stagger()`. Helpers live on `utils.*` (`utils.set`,
+  `utils.random`, `utils.get`, `utils.remove`).
+- Use `alternate: true` and `reversed: true`, not `direction:`. Callbacks are
+  on-prefixed (`onUpdate`, `onBegin`, `onComplete`, `onLoop`, `onRender`).
+- In React, Vue, Svelte, or Angular: wrap animations in
+  `createScope({ root })` and call `scope.revert()` on unmount.
+
+## Skills (read the one matching the task)
+
+| Skill | When |
+| --- | --- |
+| [anime-core](skills/anime-core/SKILL.md) | animate(), timers, transforms, keyframes, callbacks, playback |
+| [anime-timeline](skills/anime-timeline/SKILL.md) | sequencing with createTimeline + position parameter |
+| [anime-svg](skills/anime-svg/SKILL.md) | line drawing, motion path, morphing |
+| [anime-text](skills/anime-text/SKILL.md) | splitText into lines/words/chars |
+| [anime-scroll-draggable](skills/anime-scroll-draggable/SKILL.md) | onScroll, createDraggable, createAnimatable, createScope |
+| [anime-utils-easings](skills/anime-utils-easings/SKILL.md) | utils.* helpers, stagger, easing |
+| [anime-waapi](skills/anime-waapi/SKILL.md) | hardware-accelerated Web Animations API |
+| [anime-engine](skills/anime-engine/SKILL.md) | global defaults, time unit, speed, custom loop |
+| [anime-react](skills/anime-react/SKILL.md) | React (useRef + useEffect + scope.revert) |
+| [anime-frameworks](skills/anime-frameworks/SKILL.md) | Vue / Svelte / Angular |
+| [anime-migration-v3-v4](skills/anime-migration-v3-v4/SKILL.md) | converting or fixing v3 syntax |
+
+## Skills or MCP?
+
+Use the **skills**. They are the main thing and cover almost every case. Install
+them with `npx skills add https://github.com/juliangarnier/anime` and your agent
+reads them as plain files. No server to run.
+
+There is also an optional [MCP server](mcp/) that serves the same skills as
+resources and adds a `check_anime_v4_syntax` tool. It is only worth it if your
+client is MCP-native and you want those exposed as callable tools. It runs no
+code and fetches nothing, so it is a convenience, not a requirement. When in
+doubt, use the skills.
+
+## Editing these skills
+
+Each skill is `skills/<name>/SKILL.md` with YAML frontmatter (`name` must equal
+the folder name, `description` must be 1024 chars or fewer and written in the
+third person, `license: MIT`). Keep bodies focused and under about 500 lines,
+with code examples in fenced ` ```js ` blocks. Every code example must be valid
+v4. Running `node scripts/validate-skills.mjs` checks that every documented
+symbol is a real export of the built library and that no v3 token leaks outside
+the migration skill.

CLAUDE.md

@@ -0,0 +1,21 @@
+# CLAUDE.md: anime.js v4
+
+This is **anime.js v4**. Generate the v4 API, never v3.
+
+v4 uses **named ES imports** and `animate(targets, params)`. There is no default
+export and no `anime()` function.
+
+```js
+// CORRECT (v4)
+import { animate } from 'animejs';
+animate('.square', { x: 320, duration: 1000, ease: 'inOutQuint' });
+
+// WRONG (deprecated v3)
+import anime from 'animejs';
+anime({ targets: '.square', translateX: 320, easing: 'easeInOutQuint' });
+```
+
+Full conventions and skills for each area are in [AGENTS.md](AGENTS.md) and
+[`skills/`](skills/). When writing or fixing anime.js code, load the matching
+`skills/<name>/SKILL.md` (for example `anime-core`, `anime-timeline`, `anime-svg`,
+`anime-react`, `anime-migration-v3-v4`).

GEMINI.md

@@ -0,0 +1,20 @@
+# GEMINI.md: anime.js v4
+
+This is **anime.js v4**. Generate the v4 API, never v3.
+
+v4 uses **named ES imports** and `animate(targets, params)`. There is no default
+export and no `anime()` function.
+
+```js
+// CORRECT (v4)
+import { animate } from 'animejs';
+animate('.square', { x: 320, duration: 1000, ease: 'inOutQuint' });
+
+// WRONG (deprecated v3)
+import anime from 'animejs';
+anime({ targets: '.square', translateX: 320, easing: 'easeInOutQuint' });
+```
+
+Full conventions and skills for each area are in [AGENTS.md](AGENTS.md) and
+[`skills/`](skills/). When writing or fixing anime.js code, load the matching
+`skills/<name>/SKILL.md`.

README.md

@@ -148,6 +148,31 @@ animate('.square', {
 </tr>
 </table>
 
+## AI Agents & Skills
+
+Official agent skills teach AI coding assistants (Claude Code, Cursor, GitHub
+Copilot, Gemini, and any tool supporting the Agent Skills standard) to write
+correct anime.js **v4** code instead of the deprecated v3 API.
+
+```bash
+# Cross-agent install (Claude Code, Cursor, Copilot, Windsurf, Codex, …)
+npx skills add https://github.com/juliangarnier/anime
+```
+
+- **Skills:** [`skills/`](skills/) has one `SKILL.md` per area (core, timeline,
+  svg, text, scroll/draggable, utils/easings, waapi, engine, react, frameworks,
+  v3 to v4 migration). Index with triggers: [`skills/llms.txt`](skills/llms.txt).
+- **Claude Code plugin:** run `/plugin marketplace add juliangarnier/anime`, then
+  install `animejs-skills`.
+- **Cursor / Copilot:** auto-detected via [`.cursor/rules/`](.cursor/rules/) and
+  [`.github/`](.github/).
+- **LLM guidance file:** [`llms.txt`](llms.txt) and [`AGENTS.md`](AGENTS.md).
+
+The skills are all you need for most setups. There is also an optional
+[MCP server](mcp/) for MCP-native clients that serves the same skills as
+resources and adds a `check_anime_v4_syntax` tool. It runs no code and fetches
+nothing, so reach for the skills first.
+
 ## V4 Documentation
 
 The full documentation is available [here](https://animejs.com/documentation).