playbooks

home / skills / vdustr / vp-claude-code-marketplace / cspell

cspell skill

/plugins/vp-cspell/skills/cspell

This skill helps you manage cspell unknown word warnings by guiding config bootstrap, text adjustments, and scoped directives.

npx playbooks add skill vdustr/vp-claude-code-marketplace --skill cspell

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
4.6 KB
---
name: cspell
description: >-
  This skill should be used when users encounter cspell unknown word warnings,
  spelling errors from cspell diagnostics, or CI/linting failures on
  unrecognized words. Also applies when users ask to add words to the cspell
  dictionary, suppress or ignore cspell warnings, choose between cspell:words
  and cspell:ignore directives, or bootstrap cspell config in a new project
---

# cspell

Prioritized strategy for handling cspell unknown word warnings. Classify each flagged word, pick the narrowest fix, and optionally bootstrap cspell config for projects that don't have it yet.

## Core Principles

1. **Config Check First** — Verify repo has cspell config before any action; offer bootstrap if missing
2. **Adjust Text Before Adding to Dictionary** — Restructure words (hyphenate, camelCase) when safe
3. **Narrowest Scope Wins** — Inline directive for one-off words; project dictionary for recurring terms

> **Documentation**: Fetch cspell syntax and config details via Context7 (`/streetsidesoftware/cspell`) at runtime; never rely on hardcoded syntax.

## When to Use

- cspell flags an unknown word (IDE diagnostic or CI output)
- User asks to fix cspell warnings, add words to dictionary, or suppress cspell errors
- User wants to set up cspell in a project that doesn't have it
- User asks why a word is flagged or wants to understand cspell behavior
- Linting pipeline or pre-commit hook fails due to unrecognized words

**When NOT to use**: For non-cspell spell checkers (typo, codespell, Vale, textlint). For other linting tools (ESLint, markdownlint), use their respective strategies.

## Workflow

1. **Check for cspell config** — Search from the file's directory upward for cspell config files: `package.json` (`cspell` field), `.cspell.json`, `cspell.json`, `cspell.config.{json,mjs,js,cjs,yaml,yml,toml}`, `cspell.{yaml,yml}`, and their `.`/`.config/` prefixed variants (e.g., `.cspell.config.yaml`, `.config/cspell.json`). Also check `.vscode/cspell.json`. If none found: notify user, do NOT auto-fix, offer to bootstrap (see below). Note: `cspell.*` settings in `.vscode/settings.json` are IDE-local and do not count as project config.
2. **Apply fix priority** — Stop at the first applicable level (see table below).
3. **Select directive** — When using inline directives, consult [decision-tree.md](references/decision-tree.md) for the selection guide.

## Fix Priority

| Priority | Strategy | When to Use |
|----------|----------|-------------|
| 1 | **Adjust text** | Compound word cspell doesn't recognize; restructuring is safe (hyphenate, camelCase). See [decision-tree.md](references/decision-tree.md) for the full exception list |
| 2 | **Project dictionary** | Word appears in 2+ files or is expected to recur project-wide |
| 3 | **Inline directive** | One-off word in a single file/location. See [decision-tree.md](references/decision-tree.md) for directive selection and placement |

## Config Bootstrapping

When a repo has no cspell config and the user wants to add one, guide through an interactive Q&A flow.

See [config-bootstrapping.md](references/config-bootstrapping.md) for the full interactive setup flow.

## Guidelines

### DO

- Check repo config before any action
- Prefer text adjustment over dictionary pollution
- Use narrowest scope directive that fits
- Place `cspell:words` at file top for discoverability
- Verify the flagged word is genuinely unknown (not a missing dictionary)

### DON'T

- Replace words with semantically different alternatives
- Add one-off words to project dictionary (use inline directives)
- Use `cspell:disable` to suppress large sections when individual words can be handled
- Blindly accept all cspell suggestions — some flagged words are correct
- Hyphenate or restructure runtime API identifiers, package names, or fixed external terms

## Error Handling

| Error | Action |
|-------|--------|
| No write permission to config | Notify user, suggest manual edit path |
| Excessive `cspell .` output | Scope to source directory, configure `ignorePaths` first |
| Context7 unavailable | Fall back to [cspell.org](https://cspell.org/configuration/) or `cspell init --help` |

> For bootstrapping-specific errors (`cspell` CLI not installed, `cspell init` fails), see [config-bootstrapping.md](references/config-bootstrapping.md).

## Reference Files

- [decision-tree.md](references/decision-tree.md) — Full decision flowchart, text adjustment rules and exceptions, dictionary vs inline criteria, directive selection, edge cases
- [config-bootstrapping.md](references/config-bootstrapping.md) — Interactive setup flow, stack detection, CI integration, post-init adjustments

Overview

This skill helps diagnose and fix cspell unknown-word warnings and CI/lint failures caused by unrecognized words. It classifies flagged tokens, chooses the narrowest safe fix (text adjustment, inline directive, or project dictionary), and can guide bootstrapping a cspell config when a project is missing one.

How this skill works

First, it checks for an existing cspell configuration by searching the repository upward from the file location (package.json cspell field, .cspell.json, cspell.config.*, .vscode/cspell.json, etc.). If no config is found it offers a guided bootstrap flow instead of making changes. For each flagged word it applies a priority: adjust text when safe, add to project dictionary for recurring terms, or apply an inline directive for one-off occurrences.

When to use it

  • IDE diagnostic or CI output shows cspell unknown-word warnings
  • You want to add words to cspell dictionary or suppress specific cspell warnings
  • Setting up cspell in a repository that lacks a project config
  • Explaining why cspell flagged a word or how cspell decides matches
  • A pre-commit or lint pipeline fails due to unrecognized words

Best practices

  • Check for a project cspell config before making any edits or adding words
  • Prefer adjusting word form (hyphenate, camelCase) over adding to dictionaries
  • Use the narrowest scope possible: inline directive for one-offs, project dictionary for recurring terms
  • Place cspell:words at the top of a file for discoverability when using inline lists
  • Avoid altering runtime API identifiers, package names, or fixed external terms

Example use cases

  • A CI job fails because a library name is flagged: recommend adding to project dictionary if used across files
  • A README contains a compound word flagged once: suggest hyphenation or inline cspell:ignore for that file
  • A new repo lacks cspell config: offer an interactive bootstrap to create a project-level config
  • A developer sees many flags from a generated file: recommend adding the path to ignorePaths in config
  • A one-off acronym in a single source file: insert an inline cspell:words entry at file top

FAQ

What if there is no cspell config in the repo?

Notify the user and offer a guided bootstrap flow; do not auto-fix or add dictionary entries until the config is created.

When should I add a word to the project dictionary vs use an inline directive?

If the word appears in two or more files or is expected to recur project-wide, add it to the project dictionary. For a single, one-off occurrence use an inline directive.