> ## 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 Skills

> Interactive agent workflows for scaffolding Ditto specs, auditing text, and finding style guide rule gaps

## 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

<Steps>
  <Step title="Discovery">
    Locates the component, walks its imports to find child components that render user-facing text, and checks which components already have Ditto specs.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## /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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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
  </Step>

  <Step title="Evaluate">
    Checks each instance's copy against all applicable style guide rules — style rules, terminology entries, `maxLength` constraints, and locale-scoped rules where relevant.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## /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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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")
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Info>
  This is the only skill that writes to the Ditto platform. The other two skills are read-only.
</Info>

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

```bash theme={null}
npx ditto-spec init --agent
```

<Info>
  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.
</Info>