> ## Documentation Index
> Fetch the complete documentation index at: https://developer.dittowords.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These are Ditto's developer docs. Ditto is a single source of truth for product copy across design, review, localization, and code.
> The first step on any codebase is a scan: https://developer.dittowords.com/get-started/scan-your-repo.md. That page also covers reviewing the style guide Ditto drafts from the scan. After it, the follow-on guides are Connect Figma files and Set up localization (under /guides/) and Connect the Ditto MCP (the Setup page of the MCP reference).
> Two different MCP servers: the Ditto MCP server at https://api.dittowords.com/v2/mcp gives an agent a workspace's text and style guide rules; the documentation MCP server at https://developer.dittowords.com/mcp searches these docs.
> Prefer logging in with a Ditto account (npx -y @dittowords/cli@latest login; OAuth in MCP clients) over API keys. API keys are for CI and headless clients only.
> Commands are complete as written and use npx -y @dittowords/cli@latest; nothing needs a global install.

# Agent instructions

> The CLAUDE.md / AGENTS.md block that makes a coding agent check Ditto before writing copy, plus example prompts and the MCP tools each one triggers.

The Ditto MCP server exposes tools; your agent still needs to know when to use them. Give it standing instructions in a project-level file such as `CLAUDE.md` (Claude Code), `AGENTS.md` (Codex and others), or `.cursor/rules` (Cursor). Everything on this page assumes the server is connected; see [Connect the Ditto MCP](/guides/connect-the-mcp).

If you installed the Ditto plugin, the block below is already loaded at the start of every session. Committing it to the repo as well means agents without the plugin behave the same way.

## The block to commit

Paste this into `CLAUDE.md` or `AGENTS.md` at the repo root:

```text theme={null}
DITTO ACTIVE — user-facing copy goes through Ditto.

The Ditto MCP server is available (server name `ditto`; tools such as
`get_styleguide_rules`, `search_ditto_text`, and `suggest_edit`).

Whenever you write or edit user-facing text — UI labels, buttons, headings,
error messages, empty states, notifications, tooltips, emails — do this
without being asked:

1. Fetch the team's rules with `get_styleguide_rules` and follow them.
2. Before writing new copy, search existing text with `search_ditto_text`
   and reuse a match instead of inventing a new string. Consistent > novel.
3. Prefer the reused string verbatim; only write new copy when no match
   exists, and make it rule-compliant. Check it with `suggest_edit`.

Context that changes behavior:

- If the repo has `ditto/config.yml` (or `.yaml`) with project ids, Ditto
  results are scoped to those projects — trust that scoping.
- If the repo contains Ditto spec files (`*.ditto.md`), treat them as the
  source of truth for that surface's copy and keep them in sync.

If the Ditto MCP tools are unavailable, say so once, suggest logging in to
the `ditto` server (Claude Code: `/mcp` → ditto → Authenticate), and
continue without them. Do not repeat the warning every turn.
```

For Cursor, put the same text in a rule file with `alwaysApply: true`.

## Prompts by task

Each prompt below works as a one-off message or as a line in your instructions file. The "what happens" notes describe the tool calls a correctly instructed agent makes.

### Generate UI with compliant text

```text theme={null}
Use the style guides in Ditto to generate UI with compliant text.
```

What happens: the agent calls `get_styleguide_rules` once before writing any user-facing string, then applies the rules (for example, sentence case for buttons, no exclamation marks in errors) to the text it writes.

### Audit existing strings

```text theme={null}
Check my existing user-facing strings and update them so they comply
with the style guide rules in Ditto.
```

What happens: the agent fetches your rules, finds user-facing strings in the code, and proposes edits where text does not match. With the plugin, `/ditto-audit src/` does the same and returns a fix-list in the form `file:line: rule "current" → "suggested" (why)`.

### Reuse text when generating UI

```text theme={null}
Try to reuse text in Ditto when generating UI.
```

What happens: when the agent needs a button label, heading, or message, it calls `search_ditto_text` first and references the existing text (by developer ID) when a match is found.

### Replace hardcoded strings with Ditto text

```text theme={null}
Look at the user-facing strings in this codebase and replace any that
already exist in Ditto with references to the Ditto text.
```

What happens: the agent searches Ditto for each string (it can batch several searches in one `search_ditto_text` call) and suggests replacements where equivalent text already exists.

### Review a diff before committing

```text theme={null}
Review the user-facing strings in my current diff against Ditto.
```

What happens: with the plugin, `/ditto-review` collects the diff, extracts added or changed user-facing strings, fetches rules once, checks each string for rule violations and reuse opportunities, and ends with `N strings checked, M findings.`

### Turn a code review comment into a rule

```text theme={null}
We keep shipping error messages that blame the user. Add a Ditto style
guide rule that error messages should be neutral and solution-oriented,
with an example like "You entered an invalid email" → "Enter a valid
email address."
```

What happens: the agent calls `list_styleguides` to find the target style guide and its section IDs, optionally `get_workspace_tags` to tag the rule, then `create_styleguide_rules`.

### Refine or remove a rule

```text theme={null}
Our "date formatting" rule in Ditto only covers full dates. Update it to
also specify that relative times like "2 hours ago" are lowercase.
```

```text theme={null}
We no longer use title case anywhere. Delete the "title case headings"
rule from our Ditto style guide.
```

What happens: the agent calls `get_styleguide_rules` to find the rule ID, then `update_styleguide_rules` or `delete_styleguide_rules`.

### Add translations for a locale

```text theme={null}
Add German text for the strings in the checkout flow. Use the existing
"German" variant.
```

What happens: the agent calls `list_variants` to find the variant's developer ID and locale code, writes German text with `update_text_items` (passing the variant developer ID), and checks it against any German-scoped style guide with `suggest_edit`. See [Set up localization](/guides/set-up-localization).

### Link a Figma file's text to Ditto

The prompt for this task is on [Connect Figma files](/guides/connect-figma-files#step-3-instruct-your-agent). It takes your Ditto project URL and Figma file URL and walks the agent through four steps, each confirmed with you before it acts, and the guide shows how to store it as a skill your team runs by name.

What happens: the agent reads the file's text nodes through the Figma MCP, matches each one to a text item in the project with `search_ditto_text` (exact matches only) and links it with `link_figma_nodes_to_text_item`, creating text items with `create_text_items` where none exist. It then attaches exact library matches with `link_text_items_to_component` and reports the counts.

### Spin up a project from a prototype

```text theme={null}
Create a Ditto project called "Checkout redesign" from the copy in this
prototype. One text item per string, developer IDs in the
checkout.<screen>.<element> scheme, status WIP, and reuse any string
that already exists in our library instead of creating a duplicate.
```

What happens: the agent calls `create_ditto_project`, `search_ditto_text` for each string, `create_text_items` for the new ones (with `developerId` and a status from `list_statuses`), and `link_text_items_to_component` for strings that already exist as library components.

### Consolidate near-duplicates into components

```text theme={null}
Find every button label in Ditto that means "continue" ("Continue",
"Next", "Next step", "Continue →") and consolidate them into one library
component using our style guide's preferred wording.
```

What happens: the agent calls `search_ditto_text` (several queries in one call), `get_styleguide_rules` to pick the compliant wording, `publish_library_component` to turn the winning text item into a component (or `create_library_components` if none fits), and `link_text_items_to_component` to attach the others.

### Clean up after a style guide change

```text theme={null}
We just added a rule that error messages never start with "Oops". Find
every text item that breaks it and fix them.
```

What happens: the agent calls `get_styleguide_rules`, `search_ditto_text` with a status or tag filter to narrow the set, `suggest_edit` on each candidate, and `update_text_items` with the accepted edits.

### Reorganize the component library

```text theme={null}
Our library folders are a mess. Propose a folder structure by product
area, show it to me, and then move the components.
```

What happens: the agent calls `list_component_folders`, proposes a tree, waits for your approval, then uses `create_component_folders`, `update_component_folders` (to move or rename folders), and `update_library_components` (to change each component's `folderId`).

## Combine instructions

For most repos, three lines are enough:

```text theme={null}
When working on UI:
- Use the style guides in Ditto to ensure all user-facing text follows our content guidelines.
- Try to reuse existing text from Ditto instead of writing new copy.
- Check any new copy with suggest_edit before finishing.
```

## Skills from the plugin

If you installed the [Ditto plugin](/guides/connect-the-mcp#install-the-ditto-plugin), these slash commands are available in Claude Code and Cursor:

| Skill                               | What it does                                                                                          | Writes to Ditto? |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------- | ---------------- |
| `/ditto-review`                     | Check the current diff's user-facing strings against rules and existing text; returns a fix-list      | No               |
| `/ditto-audit [path]`               | Same check across a directory or the whole repo; also flags near-duplicates within the codebase       | No               |
| `/ditto-spec-setup`                 | One-time setup of Ditto Specs in the repo (installs the Specs CLI, creates config and workspace spec) | No               |
| `/ditto-spec-component <component>` | Create or update a component's `*.ditto.md` spec and sync rules from Ditto                            | No               |
| `/ditto-spec-audit [component]`     | Audit every instance of a specced component against its rules                                         | No               |
| `/ditto-spec-gaps [component]`      | Find copy patterns that should be rules but are not, and create approved ones in Ditto                | Yes              |

The Specs skills need [Ditto Specs](/ditto-specs-cli-reference/overview) set up in the repo.