# Agent Skills
Canonical page: https://www.adaptabletools.com/docs/getting-started-ai-skills
- AdapTable publishes 4 Agent Skills that teach your coding agent how to work with AdapTable:
- [adaptable-setup](https://www.adaptabletools.com/docs/getting-started-ai-skills-setup/index.md) — add AdapTable to a project for first time, onto existing AG Grid, from a dataset or nothing
- [adaptable-dev](https://www.adaptabletools.com/docs/getting-started-ai-skills-dev/index.md) — write and change AdapTable code: Options, Initial State, Layouts, Format Columns, Alerts etc.
- [adaptable-debug](https://www.adaptabletools.com/docs/getting-started-ai-skills-debug/index.md) — diagnose Grid running in browser through DevTools In-page API; assemble support case
- [adaptable-upgrade](https://www.adaptabletools.com/docs/getting-started-ai-skills-upgrade/index.md) — plan the move to a newer AdapTable major, then apply the plan in a separate session
- The Skills always work for the version installed in your project
- Optionally also install the [MCP server](https://www.adaptabletools.com/docs/getting-started-ai-cli/index.md#mcp-mode) so a Skill can call it (otherwise [adaptable CLI](https://www.adaptabletools.com/docs/getting-started-ai-cli/index.md) is called to finish the job)
AdapTable publishes four Skills: setup, develop, upgrade and debug.
An Agent Skill is a set of instructions which your coding agent follows for one AdapTable job
| Skill | When it applies |
| -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| [adaptable-setup](https://www.adaptabletools.com/docs/getting-started-ai-skills-setup/index.md) | Add AdapTable for the first time: onto an existing AG Grid, from a dataset, or from nothing |
| [adaptable-dev](https://www.adaptabletools.com/docs/getting-started-ai-skills-dev/index.md) | Write and change AdapTable code: Options, Initial State, Layouts, formatting, Alerts, Expressions, API calls |
| [adaptable-debug](https://www.adaptabletools.com/docs/getting-started-ai-skills-debug/index.md) | A Grid on screen is not doing what you expect, or you need an anonymised support case |
| [adaptable-upgrade](https://www.adaptabletools.com/docs/getting-started-ai-skills-upgrade/index.md) | Plan a move to a newer major, then apply that plan in a separate session |
You install them once in the project, then give your agent a command.
The agent opens the Skill that fits and follows it.
### Install the Agent Skills
Installing the Skills is straightforward.
There are 3 steps in the project folder, then 1 question to confirm it worked.
In the project folder:
{`npx skills add https://www.adaptabletools.com`}
The [`skills` CLI](https://github.com/vercel-labs/skills) (Node 22.20 or later) reads the index this site publishes at `/.well-known/agent-skills/index.json`, verifies each Skill's digest, asks which agents to install for and puts the four Skills where those agents read them.
#### Cursor
- Skills: `.agents/skills/` in the project
- Session-start file: `AGENTS.md`, or a `.cursor/rules/*.mdc` rule
- Without prompts: `npx skills add https://www.adaptabletools.com -a cursor -y`
#### Claude Code
- Skills: `.claude/skills/` in the project
- Session-start file: `CLAUDE.md`
- Without prompts: `npx skills add https://www.adaptabletools.com -a claude-code -y`
#### VS Code (Copilot)
- Skills: `.agents/skills/` in the project
- Session-start file: `AGENTS.md`
- Without prompts: `npx skills add https://www.adaptabletools.com -a github-copilot -y`
#### Codex
- Skills: `.agents/skills/` in the project
- Session-start file: `AGENTS.md`
- Without prompts: `npx skills add https://www.adaptabletools.com -a codex -y`
`-g` installs them for every project on your machine instead. A project install is better for a team, because everyone gets the same version. Commit the Skills folder so the team has them.
Paste this block into the session-start file for your agent, shown in the tabs above. Paste it once, and commit it.
It names the four Skills, so the agent reaches for them before it has opened any Skill. The block sits between `BEGIN` / `END` markers so that a later tool can update it in place.
Start a new session and ask:
Which AdapTable Skills do you have, and what AdapTable version is this project on?
The agent should name `adaptable-setup`, `adaptable-dev`, `adaptable-debug` and `adaptable-upgrade`, and the AdapTable version from your `package.json`.
- If the agent did not use a Skill, name it in the prompt ("use the adaptable-dev skill"), check that the block above is in the session-start file for your agent, and ask the question again in a new session
- See [Troubleshooting](#troubleshooting) for the other common causes
## Update, remove and share
- `npx skills update` refreshes the installed Skills; `npx skills check` says whether an update exists
- The four Skills are published together
- `npx skills remove adaptable-setup adaptable-dev adaptable-debug adaptable-upgrade` removes them
- Commit the Skills folder and `skills-lock.json` so the whole team, and CI, gets the same Skills
- When each Skill starts, it compares its version with the one we publish at `/.well-known/skills/VERSION`
- If it is one minor behind, it simply tells you and carries on
- If it is a major behind, it tells you to update and stops (because instructions for another major are useless)
## What you can ask
| Ask for | Skill |
| ------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Start a new Grid | [adaptable-setup](https://www.adaptabletools.com/docs/getting-started-ai-skills-setup/index.md#create-grid-from-spreadsheet) |
| Add a feature | [adaptable-dev](https://www.adaptabletools.com/docs/getting-started-ai-skills-dev/index.md#add-a-feature) |
| Review what you have | [adaptable-dev](https://www.adaptabletools.com/docs/getting-started-ai-skills-dev/index.md#review-what-you-have) |
| Fix a running Grid | [adaptable-debug](https://www.adaptabletools.com/docs/getting-started-ai-skills-debug/index.md#fix-a-running-grid) |
| Get help | [adaptable-debug](https://www.adaptabletools.com/docs/getting-started-ai-skills-debug/index.md#get-help) |
| Upgrade to latest version | [adaptable-upgrade](https://www.adaptabletools.com/docs/getting-started-ai-skills-upgrade/index.md#upgrade-an-adaptable-version) |
Each Skill's page shows an example in full: what the agent does, what you get back, and how the result was checked
- Some tips for good results
- **Give your agent one command** — use the Skills one a time
- **Name the Skill when it matters** — agents usually pick the right one; naming it makes it certain
- **Say where a setting belongs** — e.g. Adaptable Options (fixed at design time) or the Adaptable API (at run time)
- **Be specific** — name the column, the rule and the Layout. Vague prompts are how agents fall back on memory
- **If an Initial State change does not show up**, the browser's saved State is probably winning; ask `adaptable-debug`, which explains the [Revision](https://www.adaptabletools.com/docs/dev-guide-adaptable-state-updating-initial-state/index.md) fix
- **Read the diff** — the checks catch wrong Expressions and State; they do not replace a review
## How a Skill runs
Every Skill follows the same five steps, written once in the files under `references/_shared/` that each Skill carries:
1. **Find what is installed.** `adaptable detect` reads the AdapTable major and exact version, the AG Grid version, the framework and wrapper package, and every project in a monorepo. Everything after targets what it found — never the newest version the agent remembers
2. **Read the docs, don't recall.** For the feature at hand the agent looks it up for that version: the feature index (`docs list`, `docs search`), the handbook page (`docs get`), the exact State or Options shape (`docs get technical-reference-…`), a working demo (`docs demo`), and the AdapTableQL functions the engine accepts (`aql functions`). It checks whether AdapTable already has a feature before hand-rolling one
3. **Write** the code, where it belongs
4. **Check and fix.** Every Expression goes through `check expression` for its Module, every Initial State through `check state` against your `columnDefs`, any wiring change through `check setup`. It applies the fix each finding gives and checks again — up to three rounds — then reports what is left word for word, never a false "clean"
5. **Ask only at decision points.** The Skill _tells_ you what it found and carries on, and _asks_ — then waits — only where a choice is expensive to reverse: licence keys, a ColDef migration, saved State, a package upgrade. Each phase writes its file before the next one starts, so a long task can be resumed from disk
Three guards hold in every Skill:
| Guard | What it means |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| No licence keys in source | Keys go to environment variables; a key you paste is used to configure the environment file and is never echoed back; Grid Info read from a page has its key stripped before it is shown |
| Saved State is the user's | The agent never calls `restoreState`, clears browser storage or changes the state key (`adaptableId`, user name) without your confirmation in the conversation |
| Planning never edits | A phase whose result is a plan or a report writes only its own files; and an upgrade plan finds changes by letting the CLI search the code, not by reading your source |
- **With no network** the CLI works from its cache; a command that needs something not cached fails and says so, and the Skill reports that rather than guessing
- **With the MCP server configured** the Skill calls the MCP tools of the same names (`check_state`, `search_docs` …) instead of the commands; the procedure and the results are the same
- **With no shell and no MCP**, the Skill reads `package.json` by hand (and says so) and reads the docs pages as markdown from `/docs//index.md`
## Inside a Skill
Each Skill is plain markdown you can open and audit.
The same files are published unpacked at `https://www.adaptabletools.com/.well-known/skills/`.
`npx skills update` overwrites them, so keep local notes for your agent in `AGENTS.md` rather than in the Skill
## Published descriptions
What each Skill tells the agent about when it applies — the exact text the agent matches your request against:
The agent did not use the Skill
Name it in the prompt: "use the adaptable-dev skill". Check that the block from the install steps is in the session-start file for your agent, start a new session, and ask "Which AdapTable Skills do you have?"
The agent wrote an Option, API or State property that does not exist
It answered from memory instead of the Skill. Name the Skill and ask it to look the feature up for the installed version and to run `check state` / `check setup` on what it wrote
The agent says the AdapTable Skill is outdated
Run `npx skills update`. One minor version behind, the Skill carries on after telling you; a major behind, it stops until you update
Every command is slow to start, or `npx` is blocked
Install the CLI as a devDependency so `npx` finds it locally — see [Install and run](https://www.adaptabletools.com/docs/getting-started-ai-cli/index.md#install-and-run)
The Skills are installed but one agent in the team never sees them
Each agent reads its own folder: Claude Code reads `.claude/skills/`, most others `.agents/skills/`. Re-run `npx skills add` and select that agent too, and commit both folders
### FAQ
**Do the Skills need the MCP server?**
Install the Skills or nothing works, and install the MCP server as well. When it is configured, the Skill calls its tools, which is the easiest path. When it is not, the Skill runs the CLI with `npx` and the procedure and the results are the same. You do not call MCP yourself.
**Can I change a Skill?**
You can, but `npx skills update` overwrites it. Put project-specific instructions in `AGENTS.md` instead, next to the AdapTable block.
**Which AdapTable versions do they support?**
Projects on AdapTable 21 and later, for reading the docs and for upgrade planning. The checks and migrations run with the engine of an AdapTable 24 or later package — the project's own, or one the CLI downloads. The Skills never improvise a command the installed CLI does not have (`adaptable --capabilities` lists them).
**Do they work with AG Grid's Skills?**
Yes, and they expect to. Every AdapTable Skill checks whether `ag-dev` and `ag-update` are installed and hands AG Grid work over to them.