Skip to main content

​
Overview

Running ditto-spec init --agent installs three slash commands into .claude/commands/. These give agents interactive, multi-step workflows for working with Ditto specs. Skills are committed to your repo alongside Ditto spec files and config — every team member gets them automatically, no separate plugin install.

​
/ditto-spec-component

Analyze a component, create Ditto spec files for it and its dependencies, auto-fill surfaces and tags, and sync style guide rules from the platform. 
/ditto-spec-component <ComponentName or path/to/component>
Accepts either a component name (e.g. Button) or a file path (e.g. src/components/Button/index.tsx).

​
Workflow

1

Discovery

Locates the component, walks its imports to find child components that render user-facing text, and checks which components already have Ditto specs.
2

Surface analysis

For each component needing a Ditto spec, identifies every text surface — string props, children, nested props, hardcoded strings — and suggests tags from the workspace.ditto.md tag inventory. Estimates maxLength where layout context provides constraints.Pauses for your review before creating any files. You can add, remove, or modify surfaces and tags.
3

Create specs

Scaffolds index.ditto.md files (or updates existing ones) with the approved surfaces, then runs ditto-spec pull to populate style guide rules and ditto-spec check to validate.

​
/ditto-spec-audit

Audit copy in component instances against the style guide rules in their Ditto spec files and report violations. 
/ditto-spec-audit <ComponentName or path>
Omit the argument to audit all components that have Ditto specs. This skill is read-only — it never modifies code, i18n catalogs, or Ditto text items.

​
Workflow

1

Load specs

Reads workspace.ditto.md and each relevant component’s index.ditto.md to build the full set of style guide rules — workspace rules, component-level rules, per-surface rules, and locale-scoped rules.
2

Find instances

Searches the codebase for files that import and render each component. For each instance, resolves the actual copy bound to every text surface:
  • Inline — string literals, template strings, hardcoded text
  • i18n keys — resolves values across all locale catalogs, including plural forms
  • Ditto text items — resolves values across variant files by Developer ID
  • Unresolvable — flags dynamic or computed values for manual review
3

Evaluate

Checks each instance’s copy against all applicable style guide rules — style rules, terminology entries, maxLength constraints, and locale-scoped rules where relevant.
4

Report

Presents violations grouped by component and file, with file location, surface, source, the violating text, the rule violated, and a suggested correction. Ends with a summary of components audited, instances checked, and violations found.

​
/ditto-spec-gaps

Find style guide rule gaps — copy patterns that should be rules but aren’t — then create them on the platform. 
/ditto-spec-gaps <ComponentName or path>
Omit the argument to analyze all components that have Ditto specs.

​
Workflow

1

Load existing rules

Reads Ditto specs and runs ditto-spec rules to load the complete set of style guide rules on the platform — not just the rules that match local tags. This prevents proposing duplicates of rules that exist but aren’t tagged for local components.
2

Analyze text

Gathers copy from all component instances (inline, i18n, Ditto text items) and looks for patterns no existing style guide rule covers:
  • Terminology inconsistencies — the same concept with different forms (e.g. “sign up” vs “signup”)
  • Tone mismatches — some instances formal, others casual
  • Anti-patterns — passive voice in CTAs, redundant wording
  • Conventions that should be formalized (e.g. “all action buttons start with a verb”)
3

Propose rules

Presents proposed style rules and terminology entries with names, descriptions, tags, examples, and target sections.Pauses for your review. You choose which rules to create, modify, or skip.
4

Create rules

Creates approved style guide rules on the platform via ditto-spec create-rules, then runs ditto-spec pull to sync them into Ditto spec files.
This is the only skill that writes to the Ditto platform. The other two skills are read-only.

​
Updating and customizing

Skill files are plain markdown in .claude/commands/. You can edit them to add project-specific behavior — custom tags, additional audit checks, or tailored prompts. To update skills to the latest CLI version: 
npx ditto-spec init --agent
Re-running init --agent overwrites skill files with the current templates and removes legacy skill files (previously named spec-component.md, etc.). If you’ve customized skills, commit your changes first, then use --force to accept the update and merge in your customizations.