# chromatic-troubleshoot-config

Diagnoses Storybook configuration errors that stop Chromatic or local Storybook from building, such as missing stories or addon conflicts, and suggests the smallest fix.

Skill by Chromatic. Category: Testing.

## Install

Project (for this project only):

```sh
npx skills add chromaui/chromatic-skills --skill chromatic-troubleshoot-config
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add chromaui/chromatic-skills --skill chromatic-troubleshoot-config -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Pass

Installs: 26. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/chromaui/chromatic-skills/chromatic-troubleshoot-config)

## Source

[Open the source](https://github.com/chromaui/chromatic-skills/tree/HEAD/skills/chromatic-troubleshoot-config). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
name: chromatic-troubleshoot-config
description: Diagnose Storybook configuration issues that block Chromatic or local Storybook, including missing stories, framework or builder mismatches, addon conflicts, preview errors, static asset path issues, and package version drift. Use when Storybook fails to build, Chromatic cannot verify Storybook, stories are missing, or a team needs the smallest config change to restore a working Storybook surface.
metadata:
  short-description: Troubleshoot Storybook configuration issues
---

# Troubleshoot Config

Diagnose Storybook configuration problems that block Chromatic or local Storybook and identify the narrowest fix.

## Required workflow

1. Start with the current evidence: exact error text, `.storybook/main.*`, `.storybook/preview.*`, Storybook scripts and dependencies in `package.json`, framework or builder, one representative story path, and whether local Storybook already fails.
2. Choose one primary diagnosis from `reference/diagnosis-taxonomy.md`. Use `reference/workflow-playbook.md` when the branch is unclear. Prioritize local Storybook failures before Chromatic follow-on symptoms, framework or builder mismatches before addon speculation, and story discovery issues before version cleanup.
3. Separate local Storybook failure from Chromatic follow-through. If Storybook fails locally, fix that surface first. If Storybook runs locally but Chromatic cannot verify it, inspect build scripts, output expectations, and config shape next.
4. Inspect the repo before asking for more evidence. Use `reference/command-catalog.md` to check `.storybook/main.*`, `.storybook/preview.*`, the Storybook section of `package.json`, and one representative story path. Do not invent scripts or migration paths.
5. If one artifact is still missing, request exactly one next item using `reference/evidence-ladder.md`.
6. Return the diagnosis card from `reference/output-contract.md`. If confidence is low, name the most likely diagnosis, explain the gap, and ask for the single artifact that resolves it.

## Boundaries

- Ask for one artifact at a time.
- Prefer the narrowest config repair over broad rewrites.
- Do not assume React, Vite, Webpack, or a Storybook major version without evidence.
- Do not invent script names or mix Vite and Webpack guidance unless the evidence proves a migration boundary.
- Avoid asking for the whole repo, full lockfiles, or broad logs when one targeted artifact settles the branch.

## References

- `reference/workflow-playbook.md`
- `reference/diagnosis-taxonomy.md`
- `reference/evidence-ladder.md`
- `reference/command-catalog.md`
- `reference/output-contract.md`
- `template.md`
- `evaluations/README.md`
````

- Previous: [chromatic-setup-ci](https://syn4pse.dev/terminal/chromatic-setup-ci.md)
- Next: [chromatic-monorepo-config](https://syn4pse.dev/terminal/chromatic-monorepo-config.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
