# Using Taxi with AI agents

> Agent skills that teach AI coding agents to write Taxi schemas and TaxiQL queries

Source: https://taxilang.org/docs/ai-agents

AI coding agents (Claude Code, Codex, Cursor, Copilot and others) haven't seen much Taxi during training, so they
often make the same mistakes: putting fields on a `type`, using raw `String`s instead of semantic types, or treating
`given` as a filter.

We publish two **agent skills** that fix this. Each skill is a `SKILL.md` file with a short core guide, plus reference
files the agent reads when it needs more detail.

| Skill | Use it for | Entry point |
| --- | --- | --- |
| `writing-taxi` | Writing Taxi schemas: semantic types, models, enums, services, operations, annotations | [`/skills/writing-taxi/SKILL.md`](https://taxilang.org/skills/writing-taxi/SKILL.md) |
| `writing-taxiql` | Writing TaxiQL queries: `find`, `given`, projections, discovery, filtering, expressions, mutations, streams | [`/skills/writing-taxiql/SKILL.md`](https://taxilang.org/skills/writing-taxiql/SKILL.md) |

The skills follow the [Agent Skills](https://agentskills.io) format, so any agent that supports skills can use them.
For agents that don't, point them at the `SKILL.md` URL.

## Installing the skills

### Claude Code

Download both skills into your personal skills folder, so they're available in every project:

```bash
BASE=https://taxilang.org/skills
DEST=~/.claude/skills

for f in \
  writing-taxi/SKILL.md \
  writing-taxi/references/http-services.md \
  writing-taxi/references/date-format-patterns.md \
  writing-taxiql/SKILL.md \
  writing-taxiql/references/{query,projections,filtering,discovery,expressions,stdlib,mutations,streaming,publishing,query-control,patterns,advanced,troubleshooting}.md
do
  mkdir -p "$DEST/$(dirname "$f")"
  curl -fsSL "$BASE/$f" -o "$DEST/$f"
done
```

To share the skills with everyone working on a repository, set `DEST=.claude/skills` and commit the files.

### Other agents

If your agent supports Agent Skills, run the same script with `DEST` set to its skills directory.

Otherwise, add a pointer to your project's `AGENTS.md` (or your agent's equivalent rules file):

```markdown
## Taxi
This project uses Taxi (https://taxilang.org).
- Before writing or editing `.taxi` schema files, read https://taxilang.org/skills/writing-taxi/SKILL.md
- Before writing TaxiQL queries, read https://taxilang.org/skills/writing-taxiql/SKILL.md
Each SKILL.md links to reference files under `references/` — read the ones relevant to the task.
```

A machine-readable index of these files is available at [`/llms.txt`](https://taxilang.org/llms.txt).

> **Note**
>
> These skills are an early release, and we're improving them as Taxi evolves. The examples use illustrative schemas.
> Agents should always work from the types and services declared in your own project.