AI

Vortex ships instructions for AI coding agents, so an agent that works on your project starts with the context a new teammate would get. That covers the commands to run, the rules to follow, and where the documentation lives.

This page is for developers who work on a Vortex project with an AI coding agent such as Claude Code. It explains what each instruction file gives the agent and how to add skills of your own.

The Vortex CLI adds the instruction files unless you answer no to its Provide AI agent instructions? prompt. That answer leaves out the following:

• AGENTS.md
• CLAUDE.md
• The .claude/ directory
• The .claude/ rules in .gitignore

How it works

The agent instructions follow the same two-tier documentation pattern that the rest of Vortex uses:

• What applies to the project lives in the docs/ directory. Before an implementation decision, the agent checks the relevant file there for the project's choices, such as testing conventions, CI configuration, deployment rules, and release processes.
• How to perform operations comes from the Vortex documentation, this site. AGENTS.md instructs agents to look for a cached copy in .artifacts/ first, and to fetch the guide from the website and cache it there when there's no copy yet.

AI agents get the same layered guidance as you do: project-level decisions first, then Vortex-level procedures.

Configuration files

AGENTS.md

The AGENTS.md file in the project root is the primary configuration for AI coding agents. It's agent-agnostic, so any AI tool that reads AGENTS.md can use it.

The file has these sections, in order:

• Highest priority rule - limits every Bash call to exactly 1 simple command, with no chaining, pipes, command substitution, or here-documents.
• Daily development tasks - a reference of ahoy commands for building, testing, and managing the local environment.
• Before starting any task - a checklist for the start of every task: the cached documentation in .artifacts/ first, then the project's docs/ files, then the website for anything missing.
• Critical rules - constraints that agents must always follow:
  • Never modify the shipped scripts in vendor/drevops/vortex-tooling/src/.
  • Never run ad-hoc code with ahoy drush php:eval, and never pass it inline: write it to a file first.
  • Always export the configuration after changes in the admin UI.
  • Never use compound Bash commands.
• Key directories - the project's directory layout.
• Documentation - instructions for agents to check docs/ files for project-specific decisions and to fetch operational documentation from the Vortex documentation. Fetched pages are cached in .artifacts/docs-[topic].md with their source URL and date, so agents reuse them across sessions instead of fetching them again.

CLAUDE.md

Claude Code loads the CLAUDE.md file automatically at the start of every session. It holds nothing but a heading and an @AGENTS.md import, so Claude Code reads the full development guide along with it, and there's only 1 set of instructions to maintain.

.claude/settings.json

The .claude/settings.json file is a checked-in Claude Code settings file that pre-approves every ahoy command. An agent can then build, provision, lint, and test through ahoy without asking you to confirm each call:

{
  "permissions": {
    "allow": [
      "Bash(ahoy:*)"
    ],
    "deny": []
  }
}

The copy in the Vortex repository also turns on the vortex plugin, the template's own maintenance plugin in its .vortex/ directory. The Vortex CLI removes those entries, so your project gets only the permissions block.

Personal, machine-local settings belong in .claude/settings.local.json, which Git ignores.

Custom skills

Skills are reusable instruction sets that teach an agent a repeatable, project-specific task, such as a release checklist or a legacy content import procedure.

Add a skill by creating a SKILL.md file in its own directory under .claude/skills/:

.claude/
└── skills/
    └── import-legacy-content/
        └── SKILL.md

Start SKILL.md with frontmatter that names the skill and says when to use it, then write the instructions:

---
name: import-legacy-content
description: Use when importing legacy content from the CSV exports
---

Instructions the agent follows when the skill is invoked.

The shipped .gitignore un-ignores .claude/skills/ alongside .claude/settings.json, so you commit a skill like any other file. Your teammates get it after you push the commit and it's merged into the branch they work on. Everything else under .claude/ stays ignored, which keeps machine-local Claude state out of the repository.

Confirm that git status lists the new skill as untracked, which shows that Git doesn't ignore it. After you commit it, git ls-files .claude/skills lists its SKILL.md, which shows that Git tracks it.