Guides
Coding agents
An agent writing your app also writes the text in it. There are three ways to hand it the cycle, and they answer different questions: run the commands, learn the rules, or read the docs.
Three channels, three questions
| Channel | What it answers | What it needs |
|---|---|---|
| MCP server | Run the cycle: diagnose, wrap the text you already wrote, extract, translate | One line in your MCP client |
| Agent Skill | Write the code right the first time: the rules that keep the cycle safe | A file copied into your project |
| llms.txt | Find the right page: an index of these docs in plain markdown | Nothing, it is already served |
They stack. The skill teaches the rules, the server does the work, and the index is what an agent reads when it needs more than either. None of them can approve a machine translation, which is on purpose and explained at the end of this page.
The MCP server
@verbaly/mcp exposes the cycle as tools over the Model Context Protocol, so an agent runs it without touching a shell. It works with any MCP client, Claude Code and Cursor included.
claude mcp add verbaly -- npx -y @verbaly/mcpThe server reads your verbaly.config from the directory it starts in. Pass --root when that is not your project, and every tool also takes a root of its own for a monorepo with more than one app.
The six tools
They are listed in the order an agent meets a project: find out what is wrong, wrap the text that is already there, then run the cycle over it.
| Tool | What it does | Writes? |
|---|---|---|
| verbaly_doctor | Checks the whole setup at once: config, catalogs, the plugin for your framework, the generated types, files it could not read and every translation the gate would reject | No |
| verbaly_wrap | Finds text written straight into your JSX and wraps it so the compiler can pick it up. It reports by default, and text it cannot handle safely is listed rather than rewritten | Yes |
| verbaly_extract | Scans your source, adds new messages to the catalogs and refreshes the generated types | Yes |
| verbaly_status | Coverage per language, plus how many machine translations are waiting for a human | No |
| verbaly_missing | Everything the CI gate would fail on: missing translations, unknown keys and translations that exist but cannot render what the source renders | No |
| verbaly_translate | Fills the gaps through your configured provider, saving everything as a draft | Yes |
The three that only read say so to the client, so an agent can look at the state of your project without permission to change anything. The ones that write tell you first: extract and translate take a dryRun that reports what would happen, and wrap reports unless you ask it to apply.
Every tool answers twice: a sentence for a person reading the transcript, and the same answer as data. An agent asking for coverage gets the numbers themselves, not a line to pick apart, so it keeps working when we word something differently.
A tool that fails comes back as a message the agent can act on, never as a crashed server: a missing config file says so, and so does a catalog that is not valid JSON.
Translating is the one step that can be interrupted halfway, because it goes out over the network. When a piece of it does not come back, the rest is still saved and the answer names exactly which messages are left, so asking again costs only what is missing.
The Agent Skill
A server tells an agent what it can run. A skill tells it what to write. The Verbaly Agent Skill lives in the repository and carries the cycle plus the rules that keep it safe, so an agent stops inventing catalog keys by hand.
npx degit AronSoto/verbaly/skills/verbaly .claude/skills/verbalyThe rules it carries are the ones that are easy to get wrong from the outside: keys are generated and never written by hand, "" in a catalog means untranslated, placeholders and tags have to survive translation verbatim, and links go through a named tag plus a links map, never a literal <a href> inside a message.
llms.txt
This site serves /llms.txt, a markdown index of every documentation page with a line on what each one covers. It is generated from the same sidebar you are looking at, so it cannot drift from the real docs.
It is for the agent that reads before it writes. Point yours at it when it needs the whole map, and at a single page when it needs one answer.
Why an agent cannot approve its own translation
Everything verbaly_translate produces is a draft, and drafts do not ship: with verbaly check --drafts in CI, the build keeps failing while any remain. The tool that accepts them, verbaly review --approve, is deliberately not exposed to agents.