typo-fix - SKILL.md Agent Skill

name: typo-fix description: Run codespell to detect and fix common spelling mistakes across the entire codebase, then commit the changes on a new branch from master. Use when user asks to "fix spelling", "check for typos", "spell check codebase", or "run codespell". version: 1.0.0 license: MIT compatibility: opencode, claude metadata: tool: codespell tool_version: ">=2.0" workflow: git-branch-and-commit

What I do

Run codespell to generate a list of spelling suggestions (no auto-write)
Read and review every suggestion to confirm it is a genuine misspelling (not a technical term, variable name, or domain-specific word)
For each valid fix: read the affected line in the file, understand the context, and manually apply the correction using file editing tools
Create a new git branch from master named fix/typo-YYYYMMDD (using today's date)
Stage changed files, review the diff, and commit with a clear message

When to use me

Use this skill when you want to sweep the codebase for spelling mistakes in:

Comments and docstrings
String literals and error messages
Documentation files (.md, .mdx, .rst, .txt)
Variable names and identifiers that contain English words

Step-by-step workflow

1. Verify codespell is available

codespell --version

If not installed:

pip install codespell
# or, if uv is available (preferred):
uvx codespell --version

2. Run a dry-run preview (no changes yet)

codespell \
  --quiet-level 3 \
  --skip=".git,*.lock,*.min.js,*.min.css,node_modules,__pycache__,.venv,venv,dist,build,*.svg,*.png,*.jpg,*.jpeg,*.gif,*.ico,*.woff,*.woff2,*.ttf,*.eot" \
  .

Flags explained:

--quiet-level 3: suppress binary file warnings, only show actual misspellings
--skip: skip binary files, generated files, and dependency directories

3. Think before you fix — review every suggestion critically

Before touching any file, exercise judgment for each suggestion:

Skip the fix if any of the following are true:

The word is a technical term, acronym, or abbreviation (e.g. repr, recvd, usr, init).
The word is a variable name, function name, class name, or identifier used in code logic — even if it looks misspelled.
The word appears in user-generated content: UI labels, error messages shown to end-users, user-facing strings copied from a spec or design, translatable strings, or copy that a product owner intentionally authored. Changing these without product review can break UX, translations, or user expectations.
The word is a proper noun, brand name, or domain-specific term that only looks wrong to a generic spell-checker (e.g. mixin, teardown, webhook, signin).
The file is auto-generated (lock files, compiled output, vendored code) — skip the entire file.
The suggested correction changes meaning or produces an awkward result in context.

Apply the fix only if:

The word is genuine prose that a human typed and clearly misspelled (variable names, function names, class names, comments, docstrings, README/docs text, log messages for developers).
The suggested word is unambiguously correct in context.
Changing it cannot break runtime behaviour, translations, or user-visible copy.

4. Create a new git branch from master

git fetch origin
git checkout master
git pull origin master
git checkout -b fix/typo-$(date +%Y%m%d)

If the default branch is main instead of master:

git checkout main && git pull && git checkout -b fix/typo-$(date +%Y%m%d)

5. Apply fixes manually

For each spelling suggestion from codespell:

Read the file at the line containing the misspelling:
- Use your agent's file-reading capability to load the file
- Find the exact line and word codespell flagged
Re-apply the judgment from step 3 — confirm the word deserves a fix before proceeding.
Apply the fix manually:
- Use your agent's file-editing capability to replace only the misspelled word
- Do NOT use --write-changes — apply fixes one at a time so each change is deliberate
- Do NOT batch-apply all suggestions blindly

Example workflow for each file:

# Run codespell to see suggestions (output shows file:line:misspelling -> suggestion)
codespell --quiet-level 3 --skip="...,*.svg,*.png" .

Then for each suggestion, read the file, locate the line, and edit:

Old: "This fuinction processes data"
New: "This function processes data"

6. Review the diff

git diff

Carefully inspect each change. If any fix looks wrong (corrected a technical term, variable name, etc.). Revert that specific change

7. Stage and commit

git add -A
git commit -m "fix: typo/spelling correction/whatever is the most appropriate commit message"

Rules and guardrails

Avoid changing variable names, function names, class names, or any identifier that appears in code logic — only fix human-readable prose (comments, docstrings, strings intended for display, documentation). Exception: if a variable name is an obvious typo and you update every usage site, that is acceptable.
Preserve user-generated content — do not alter user generated content or any text that was intentionally authored by a product owner or designer. When in doubt, skip the fix.
Do not mix spelling fixes with other changes in the same commit
If more than 10 files are changed, split into multiple commits by file type (docs first, then source)
Do not mention you used codespell anywhere