Agent instructions

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. 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:

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

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

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

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

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

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

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

Our "date formatting" rule in Ditto only covers full dates. Update it to
also specify that relative times like "2 hours ago" are lowercase.

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

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.

Link a Figma file’s text to Ditto

The prompt for this task is on Connect Figma files. 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

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

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

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

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:

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, 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 set up in the repo.

Start here

Concepts

CLI Reference

API Reference

String Formats

MCP Reference

Ditto Specs CLI

Additional Tools

Legacy

Agent instructions

The block to commit

Prompts by task

Generate UI with compliant text

Audit existing strings

Reuse text when generating UI

Replace hardcoded strings with Ditto text

Review a diff before committing

Turn a code review comment into a rule

Refine or remove a rule

Add translations for a locale

Link a Figma file’s text to Ditto

Spin up a project from a prototype

Consolidate near-duplicates into components

Clean up after a style guide change

Reorganize the component library

Combine instructions

Skills from the plugin

​The block to commit

​Prompts by task

​Generate UI with compliant text

​Audit existing strings

​Reuse text when generating UI

​Replace hardcoded strings with Ditto text

​Review a diff before committing

​Turn a code review comment into a rule

​Refine or remove a rule

​Add translations for a locale

​Link a Figma file’s text to Ditto

​Spin up a project from a prototype

​Consolidate near-duplicates into components

​Clean up after a style guide change

​Reorganize the component library

​Combine instructions

​Skills from the plugin

The block to commit

Prompts by task

Generate UI with compliant text

Audit existing strings

Reuse text when generating UI

Replace hardcoded strings with Ditto text

Review a diff before committing

Turn a code review comment into a rule

Refine or remove a rule

Add translations for a locale

Link a Figma file’s text to Ditto

Spin up a project from a prototype

Consolidate near-duplicates into components

Clean up after a style guide change

Reorganize the component library

Combine instructions

Skills from the plugin