Agent Skills

Teach your AI coding agent to work with Directus: the API and MCP server, Flows, Insights, access control, content modeling, Environment Sync, the SDK and visual editing, extensions, self-hosting, and upgrades.

Website • Documentation • Agent Skills standard

---

The official Agent Skills bundle for Directus. Each skill is a short router that loads only the reference an agent needs for the task, plus the traps it would otherwise get wrong. Verified against Directus 12.6.0.

Skills

Skill	Use it for
directus	Working with a running instance: REST and GraphQL queries, filters, auth, files, realtime, content versions, and the Directus MCP server
directus-flows	Automating with Flows: triggers, the data chain, operations, reusable utility flows, loops, email, building and debugging flows over the API or MCP
directus-insights	Building Insights dashboards: panel types and options, variables, layout, and who can see them
directus-content	Editing content as an editor would, over MCP or the API: pages, page-builder blocks, translations, drafts and publishing, images
directus-access-control	Designing who can do what: roles, policies, permissions, the public policy, stacking rules, core-tier licensing limits, the CMS starter layout, and testing access
directus-content-modeling	Designing schemas: collections, fields, relationships, page builders (M2A), translations, indexes, and starting a project from a starter. Includes Directus's house conventions.
directus-environment-sync	Moving schema and configuration between instances through git with the Directus CLI (d6s): promote dev to prod, keep per-environment settings, schema snapshots
directus-sdk	The traps in @directus/sdk: client setup, auth modes on server and browser, counts, headers
directus-visual-editing	Wiring a site to Live Preview, the Visual Editor, and content versions with @directus/visual-editing: Directus config, CSP, draft reads, editable page builder blocks, and safe preview tokens
directus-extensions	Building extensions: picking a type, scaffolding, app and API extension APIs, sandboxing, and publishing to the marketplace
directus-self-hosting	Deploying and running Directus: Docker Compose, configuration, file storage and email, scaling past one instance, backups, and what differs on Directus Cloud
directus-upgrade	Upgrading a project across versions (v9 to 12.x), with the breaking changes and how to find affected code

Install

Any agent (skills CLI)

npx skills@latest add directus/agent-skills

Installs into Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot, and other agents that support the standard. Add --skill directus-sdk to install one skill.

Claude Code (plugin)

claude plugin marketplace add directus/agent-skills
claude plugin install directus@directus-agent-skills

Codex (plugin)

codex plugin marketplace add directus/agent-skills
codex plugin add directus@directus-agent-skills

Codex reads the same .claude-plugin/ manifests. Each skill also has agents/openai.yaml with its name, blurb, and example prompt for the Codex skill picker.

Manually

Copy any folder under skills/ into your agent's skills directory: .claude/skills/ for Claude Code, .agents/skills/ for most other agents.

Connect the MCP servers

The skills work without MCP, but they're better with it. Two servers:

• Directus docs is bundled with the Claude Code plugin and connects automatically on install.
• Your instance can't be bundled (every URL and token is different). Add it yourself with the snippet below.

Server	URL	Auth
Directus docs	https://directus.com/docs/mcp	none
Your instance	https://YOUR_DIRECTUS_URL/mcp	static token or MCP OAuth

Enable your instance's server in Settings → AI → Model Context Protocol (Directus 11.12+). Use a token for a user with the permissions you want the agent to have. Tool calls run as that user.

// .mcp.json in your project (see examples/mcp-instance.json)
{
	"mcpServers": {
		"directus": {
			"type": "http",
			"url": "https://YOUR_DIRECTUS_URL/mcp",
			"headers": { "Authorization": "Bearer ${DIRECTUS_TOKEN}" }
		}
	}
}

Not using the plugin? Add the docs server the same way: { "type": "http", "url": "https://directus.com/docs/mcp" }.

Codex: see .codex/config.toml. Setup and troubleshooting: skills/directus/references/mcp.md.

Layout

skills/<name>/
  SKILL.md        # router: scope, first checks, critical traps, which reference to load
  references/     # depth, loaded on demand
.claude-plugin/   # Claude Code marketplace manifest
.mcp.json         # docs MCP server, bundled with the plugin
examples/         # instance MCP config to copy into your project
.codex/           # Codex MCP config template
AUTHORING.md      # rules for writing and updating skills
evals/            # trigger tests for claude plugin eval
behavior-evals/   # live-instance tests: does the agent build it right?

Trigger evals

evals/ holds trigger tests for claude plugin eval: each case is a prompt plus graders that check the right skill loads and the wrong neighbor doesn't. Run locally (Claude Code 2.1.269+):

claude plugin eval . --ablation none --runs 3 --no-publish
claude plugin eval . --case 'access-*' --runs 1 --ablation none --no-publish   # one area

--no-publish keeps the HTML report local. Each case costs one agent run per --runs. Results land in evals/results/ (git-ignored). Add a case whenever you change a skill description.

Behavior evals

behavior-evals/ checks what an agent actually builds. Each case starts a fresh Directus container in Docker (12.6.0 by default), seeds it, gives a headless claude -p the task with and without this plugin, then checks the instance over the API (naming, on_delete, keys, and that nested writes, flows, and permissions really work). Code cases also check the files the agent wrote: they run the SDK script, call the endpoint extension it built (mounted into the instance), and parse its compose file with docker compose config. The sync cases add a second instance as the target, and json-filters runs on Postgres (JSON comparisons and sorts differ from SQLite). Cases with mcp: true connect the agent to the instance's MCP server and give it no shell, the way an editor's AI client works. existing-database creates an app's tables in Postgres before Directus first boots. Checks that need their own users reuse the agent's when the core tier's 3 seats are taken.

node behavior-evals/run.mjs                       # every case, both arms, Haiku, 1 run
node behavior-evals/run.mjs --model haiku,sonnet --runs 3   # release read: Haiku is the floor we support
node behavior-evals/run.mjs --case model-blog --runs 3 --model opus
node behavior-evals/run.mjs --case flows-publish-guard --image directus/directus:11.9.3   # an older version

Run a few cases on an older image too. That checks that agents read the version notes and adapt (on 11.9.3 there is no throw-error operation, so the publish guard has to use a different pattern).

Add --clean to run each agent with an empty Claude config (no personal skills, CLAUDE.md, or plugins). It authenticates with a claude setup-token token from CLAUDE_CODE_OAUTH_TOKEN or ~/.config/directus-skills-evals/oauth-token.

Cases marked license: true run on a licensed instance. Put the key in ~/.config/directus-skills-evals/license-key (or DIRECTUS_EVALS_LICENSE_KEY); it reaches Docker through the environment and never lands in results. Without it, those cases error and the rest run on the unlicensed core tier.

The report scores each case per model and arm:

• runs passed: runs where every functional check passed. Each run is scored against the most checks any run of the case produced, so a check that stopped early counts as failed.
• checks and recommended are separate: checks test that the build works, recommended checks test our Recommended: conventions (naming, key types, on_delete). Mark those with check(ok, label, detail, { recommended: true }).
• skill: how many plugin runs loaded a directus skill.
• Cases where every run passed without the plugin are listed as cut candidates.

Results land in behavior-evals/results/ (git-ignored). Add a case as cases/<name>.md (the task) plus checks/<name>.mjs (exit 1 on any failed check). Seeds, extra shell commands, starting files (fixtures/), a second instance, Postgres, instance env, a turn limit, or no instance at all go in the CASES table in run.mjs.

Contributing

Read AUTHORING.md. Keep SKILL.md short, put depth in references/, and ground every claim in the Directus source or docs, not memory. Run npm run validate before opening a PR (CI runs the same), and add a changeset (npm run changeset) for any change an agent would notice. See .changeset/README.md for which bump to pick.

Releases

Versions and CHANGELOG.md come from Changesets. Merging to main opens a "Version skills" PR; merging it bumps the version in package.json and both plugin manifests, writes the changelog, and tags vX.Y.Z with a GitHub release. npx skills and the Claude Code plugin install from the repo, so there's no npm publish.

The release (scripts/release.mjs) also attaches a .tar.gz per skill and an Agent Skills discovery index.json. directus.com serves the latest release's files at /.well-known/agent-skills/. node scripts/release.mjs --dry-run builds them into dist/ without publishing.

License

MIT