skillsaw-typos

A skillsaw plugin that flags misspellings in agentic instruction prose using the codespell known-typo dictionary.

Installation

pip install skillsaw-typos

Once installed alongside skillsaw, the typo rule runs automatically — no configuration required.

What it checks

The typo rule walks every content block in the lint tree (CLAUDE.md, AGENTS.md, skills, agents, prompts, etc.), reads prose with code fences stripped so identifiers are never flagged, and checks each word against codespell's 64,000+ known misspellings.

Fails

- All handlers should recieve validated input from the middleware.
- Keep test files and source code in seperate directories.

⚠ WARNING (typo) [CLAUDE.md:5]: Misspelling: 'recieve' → 'receive'
⚠ WARNING (typo) [CLAUDE.md:6]: Misspelling: 'seperate' → 'separate'

Passes

- All handlers should receive validated input from the middleware.
- Keep test files and source code in separate directories.

Words inside fenced code blocks are never flagged.

Autofix

skillsaw fix --rule typo

When codespell's dictionary has exactly one correction, the fix is applied automatically (SAFE). When there are multiple candidates, the fix uses the first suggestion and is marked SUGGEST — applied only with skillsaw fix --suggest.

Fixes preserve the original word's casing (lowercase, Title Case, UPPER CASE).

Accepting existing typos

To accept all currently-flagged words (e.g. when adopting the plugin on an existing repo), run:

skillsaw typos accept

This writes the flagged words to .skillsaw-typos-ignore in the repo root. The rule reads this file automatically and skips any listed words. The file is one word per line and supports # comments — commit it to version control.

Running accept again is a no-op when no new violations exist.

Configuration

In .skillsaw.yaml:

rules:
  typo:
    enabled: true           # true | false | auto
    severity: warning        # error | warning | info
    ignore-words:            # words to accept (e.g. project jargon)
      - frobnicator
      - kubectl
    extra-dictionaries:      # additional dictionary files (codespell format)
      - .skillsaw/extra-typos.txt

.skillsaw-typos-ignore

A file in the repo root listing words to skip, one per line. Generated by skillsaw typos accept or maintained manually. Lines starting with # are comments. This is the primary way to suppress false positives.

ignore-words

Additional words to skip, specified inline in .skillsaw.yaml. Useful for small lists that don't warrant a separate file.

extra-dictionaries

Paths to additional dictionary files in codespell format (word->correction). Each file is loaded on top of the built-in dictionary.

Disabling

Per-rule:

rules:
  typo:
    enabled: false

Entire plugin:

plugins:
  disable:
    - typos

Or for a single run:

skillsaw lint --no-plugins