TypeScript Linter Skill

This skill introduces a strict, comprehensive ESLint configuration into a TypeScript project and then systematically resolves every linting issue — auto-fixing what it can and manually rewriting what it can't. The goal is zero lint errors with zero broken functionality.

Core Principle

Rules are immutable. Once the ESLint configuration is generated, treat it as frozen. The only lever is changing application code. Never suppress, disable, downgrade, or override a rule — refactor the code to comply.

Before Starting

Recommend the user commits their current state before any changes:

git add -A && git commit -m "checkpoint: before linter setup"

This gives a clean rollback point. If the project doesn't use git, warn that there is no undo — proceed carefully, fix in small batches.

Workflow Overview

1. Detect the project type by running scripts/detect-project.sh
2. Generate a tailored eslint.config.mjs from references/eslint-config-reference.mjs
3. Install all required dependencies using scripts/generate-install-cmd.sh
4. Validate the config actually loads before proceeding
5. Auto-fix using eslint --fix in batches
6. Baseline — capture error counts before manual fixes begin
7. Manually fix every remaining issue, verifying after each batch
8. Verify and produce a before/after summary comparing against baseline
9. Install Claude Code hooks (Claude Code only — auto-detect environment)

Steps 1-8 are platform-agnostic and work identically on Claude.ai, Claude Code, and the API. Step 9 runs automatically when inside Claude Code (detected by the presence of a .claude/ directory) and is silently skipped otherwise. This skill only handles ESLint for TypeScript/JavaScript. It does not conflict with other skills (e.g., frontend-design, docx) since it only activates for linting-related requests.

Step 1: Project Detection

Run the detection script to determine what the project uses:

bash <skill-path>/scripts/detect-project.sh .

This scans package.json, lockfiles, and directory structure, then outputs a JSON object with boolean flags for each module (React, React Native, Drizzle, Vitest, Playwright, etc.), the detected package manager, existing ESLint config type, and file globs for server/native/db/e2e directories.

If the script is unavailable, run the detection manually:

cat package.json | grep -E "react-native|expo|next|@tanstack|drizzle-orm|vitest|jest|playwright|@testing-library"
ls tsconfig*.json
ls -d apps/ packages/ src/ server/ api/ native/ e2e/ 2>/dev/null
ls eslint.config.* .eslintrc* 2>/dev/null
ls pnpm-lock.yaml yarn.lock package-lock.json bun.lockb 2>/dev/null

Based on the results, determine which config sections to include:

If a signal is absent, omit that entire section. Do not include commented-out blocks.

CI Command Detection

Also check for CI configuration files to discover the exact lint/typecheck/test commands that CI runs. These are authoritative — Step 8 verification must match them:

ls .github/workflows/*.yml .gitlab-ci.yml .circleci/config.yml Jenkinsfile 2>/dev/null

If a CI config exists, read it and extract any eslint, tsc, npm run lint, npm run typecheck, or npm run test invocations. Record these as CI_LINT_CMD, CI_TSC_CMD, and CI_TEST_CMD. These take priority over detectedCommands from package.json when verifying in Step 8.

Step 2: Generate the ESLint Config

Read the full reference config at references/eslint-config-reference.mjs.

Generate eslint.config.mjs using only the sections relevant to the detected project. Every config MUST include these core sections (framework-agnostic):

• Global ignores
• --max-warnings=0 CLI flag (treats any warning as a CI failure)
• @eslint/js recommended + typescript-eslint recommendedTypeChecked
• eslint-plugin-de-morgan, unicorn, promise, security, sonarjs, regexp
• @eslint-community/eslint-plugin-eslint-comments
• TypeScript type-aware linting parserOptions
• Core rule customizations (see reference config for exact values)
• Test/config file relaxations
• Unicorn customizations (filename-case with framework routing exceptions)
• eslint-config-prettier as the LAST entry (disables formatting rules)

Adapt file globs to match the actual project structure (e.g., src/server/ instead of server/). The detection output includes discovered globs in the globs field — replace the placeholder globs in the reference config with those values.

If the project already has an ESLint config, read it first. Do not blindly overwrite — merge the new rules into the existing structure. If it's .eslintrc.* (legacy format), always migrate to flat config — ESLint v10+ removed eslintrc support entirely. Extract the existing rules and recreate them as flat config entries. Preserve project-specific rules. Show the user a diff.

Step 3: Install Dependencies

Run the install command generator:

bash <skill-path>/scripts/detect-project.sh . | bash <skill-path>/scripts/generate-install-cmd.sh

This reads the detection JSON and outputs the exact install command for the detected package manager, split by category. Review the output, then run the install command.

If the script is unavailable, install manually. Core packages (always needed):

eslint @eslint/js typescript-eslint globals eslint-config-prettier
eslint-plugin-de-morgan eslint-plugin-unicorn
eslint-plugin-promise eslint-plugin-security eslint-plugin-sonarjs
eslint-plugin-regexp @eslint-community/eslint-plugin-eslint-comments

Conditional packages: eslint-plugin-react + eslint-plugin-react-hooks + eslint-plugin-react-you-might-not-need-an-effect (React), @react-native/eslint-config (RN), @tanstack/eslint-plugin-query (TanStack), eslint-plugin-drizzle (Drizzle), eslint-plugin-n (Node), @vitest/eslint-plugin (Vitest), eslint-plugin-playwright (Playwright), eslint-plugin-testing-library (Testing Library).

Install as devDependencies. Show the user what was added.

Step 4: Validate the Config

After installing dependencies, verify the config loads. Find any .ts, .tsx, .js, or .jsx file in the project to test against — do not assume src/index.ts exists:

TEST_FILE=$(find src apps packages lib . -maxdepth 4 \( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' \) 2>/dev/null | grep -v node_modules | head -1)
if [[ -z "$TEST_FILE" ]]; then
  TEST_FILE="eslint.config.mjs"
fi
npx eslint --print-config "$TEST_FILE" > /dev/null 2>&1
echo $?

Exit 0 = config loaded. Exit 2 = config/parse error. Do not proceed to auto-fix with a broken config. See the Troubleshooting section for common config failures.

Package manager note: Replace npx with bunx (Bun) or yarn exec (Yarn PnP) if your project uses a different package manager. The detection output's packageManager field tells you which one to use.

Step 5: Auto-Fix

npx eslint . --fix 2>&1 | head -100

For large projects (>500 files), fix by directory to keep diffs manageable.

After auto-fix, categorize remaining errors:

npx eslint . --format json 2>/dev/null | node <skill-path>/scripts/categorize-errors.js

This groups errors by rule, shows which are auto-fixable vs manual, and suggests a prioritized fix order. If the script is unavailable, run npx eslint . --format compact and group errors manually by rule name.

Step 6: Baseline

Before starting manual fixes, capture the starting state. This is your reference point for the before/after summary at the end.

npx eslint . --format json 2>/dev/null | node <skill-path>/scripts/categorize-errors.js
npx tsc --noEmit 2>&1 | tail -1
# Run tests and capture count

Record:

📋 Baseline (post auto-fix):
   Lint errors: <total> across <n> files (<top-3-rules-with-counts>)
   TypeScript: clean / <n> errors
   Tests: <passed>/<total>

Keep these numbers — you will compare against them in Step 8.

Step 7: Manual Fix — Systematic Remediation

Work through remaining errors by category, not by file. Fix order (highest-impact, lowest-risk first):

1. Unused imports/variables (@typescript-eslint/no-unused-vars) — remove unused imports. Check for side-effect imports before removing.
2. Type safety (no-explicit-any, no-unsafe-*) — replace any with proper types. Use unknown with type guards for complex cases. Test files are already relaxed.
3. Deprecated APIs (@typescript-eslint/no-deprecated) — look up replacements.
4. Unicorn rules — mechanical transforms. Do filename renames last, in a separate batch.
5. Promise handling — add .catch() or convert to async/await with try/catch.
6. Cognitive complexity — extract helpers, split conditionals into named booleans.
7. Max-lines — split files over 300 lines. Update all affected imports.
8. React-specific — extract nested/multi components into separate files.

Documentation Lookup

Before attempting a manual fix, determine whether research is needed:

• Skip lookup for trivial fixes: unused imports, missing return types, simple renames.
• Do lookup when: the rule is unfamiliar, the fix requires a deprecated API replacement, the correct type narrowing is unclear, or the refactor pattern is non-obvious.

Lookup fallback chain (use the first that succeeds):

1. Rule URL from linter output — ESLint errors include a docs link. Read it.
2. Documentation tools — if MCP doc providers (Context7, etc.) or /context7 are available, query them for the relevant library/API.
3. Web search — search for the rule name + "TypeScript" + the specific pattern.
4. Flag to user — if no source clarifies the fix, report the rule and ask before guessing.

Fix Principles

• Rules are immutable. Do not add eslint-disable, eslint-disable-next-line, @ts-ignore, @ts-expect-error, or modify eslint.config.mjs to weaken a rule.
• Fix the code, not the rule. If a rule flags any, replace with a proper type — do not cast through unknown as a shortcut. If a rule flags cognitive complexity, extract named helpers.
• Behavior must be preserved. Every refactor must produce identical runtime behavior. Flag public API signature changes to the user before applying.
• Research before refactoring. Follow the Documentation Lookup chain above — understand what the rule enforces and why before proposing a fix.
• Check tsc --noEmit and tests after every batch of fixes.
• Fix in batches of 5 files max, then verify. If tests break, revert and redo one at a time.
• Never rename files and fix lint in the same batch — renames touch every import site.
• No drive-by changes — only touch code flagged by a violation.
• If a violation appears genuinely unfixable without suppression (e.g., a third-party type definition forces any), report it as a blocked item with rule name, file, line, and reason. Wait for the user to decide — do not suppress silently.
• If two consecutive batches don't reduce the error count, report blocked items to the user with specific refactor options for each, then wait for direction.

Progress Reporting

Fixing a large codebase takes many turns. After each batch of fixes, report progress so the user can track status and decide whether to continue:

📊 Progress: 47 errors remaining (down from 83)
   Fixed this batch: 12 errors across 5 files (unused imports)
   Blocked: 2 (third-party type forces `any` — see blocked items below)
   Next: 18 type safety errors (@typescript-eslint/no-explicit-any)
   ✅ tsc --noEmit: clean | ✅ Tests: 42 passed

If the remaining errors are all in one category that requires significant refactoring, ask the user whether to proceed with deeper refactoring or defer those violations to a follow-up task. Do not offer eslint-disable as an option.

Step 8: Verification and Before/After Summary

Use the project's actual commands — the same ones CI runs. Prefer CI-detected commands (from Step 1 CI detection) over detectedCommands from package.json, and use raw npx fallbacks only if neither exists:

Always include --max-warnings=0 when running ESLint directly. If the project's npm run lint script does not include this flag, run npx eslint . --max-warnings=0 as an additional check.

# Example using detected commands:
npm run lint
npm run typecheck
npm run test

Completion gate — you are NOT done until all commands exit 0. Loop: diagnose the failure from the output, fix the code, re-run the failing command. Repeat until clean. Do not produce the Before/After Summary until every command passes.

Once verification passes, produce a before/after summary comparing against the Step 6 baseline:

## Before/After Summary

| Metric           | Before (baseline) | After        | Delta   |
|------------------|--------------------|--------------|---------|
| Lint errors      | <n>                | <n>          | -<n>    |
| Files with errors| <n>                | <n>          | -<n>    |
| TypeScript       | clean / <n> errors | clean        |         |
| Tests            | <passed>/<total>   | <passed>/<total> |     |

### Refactors applied
- <rule-name>: <1-line description of refactor> (x<count>)
- ...

### Blocked items (if any)
- <rule-name> in <file>:<line> — <reason code-only fix is not possible>

This summary is mandatory — do not declare done without it.

Monorepos

Place eslint.config.mjs at the root. Scope rules with file globs (apps/web/**/*.tsx). Install dependencies at root. Adapt per-app overrides to actual app names.

Turborepo / pnpm workspaces — tsconfig setup:

Turborepo projects typically have a root tsconfig.json that acts as a base config ("compilerOptions" only, no "include"), with per-workspace configs that extend it (e.g., apps/web/tsconfig.json with "extends": "../../tsconfig.base.json"). For ESLint's type-aware rules to work:

1. Keep tsconfigRootDir: import.meta.dirname in the ESLint config (points to the root). ESLint's projectService walks up from each file to find the nearest tsconfig.json.
2. Do NOT set "include" in the root tsconfig.json — let each workspace config define its own. A root include that covers everything can cause ESLint to use the wrong tsconfig for workspace files.
3. Add root-level scripts or config .ts files to allowDefaultProject if they aren't covered by any tsconfig (e.g., "scripts/seed.ts").
4. If a workspace uses project references ("references": [...]), ESLint still resolves correctly — no extra config needed.

Step 9: Claude Code Hook Installation

Environment detection: Check if a .claude/ directory exists in the project root or any parent directory. If it does, you are inside Claude Code — proceed with this step automatically. If it does not exist, skip this step silently.

if [[ -d ".claude" ]] || [[ -d "../.claude" ]] || [[ -d "../../.claude" ]]; then
  echo "Claude Code detected — installing hooks"
else
  echo "Not in Claude Code — skipping Step 9"
fi

When Claude Code is detected, read references/claude-code-integration.md and execute the setup automatically. This includes:

• PostToolUse hook (per-file lint via scripts/lint-typecheck-hook.sh) — automatic
• Stop hook (full project lint + typecheck) — automatic
• Self-test validation (scripts/validate-setup.sh) — automatic
• Hook reliability details (circuit breaker, graceful degradation, output truncation)
• TypeScript LSP plugin — requires user action: tell the user to run /plugin install typescript-lsp@claude-plugins-official in their Claude Code session

After installation, inform the user what was set up and how to remove it:

Installed Claude Code lint hooks:
- .claude/hooks/lint-typecheck.sh (PostToolUse: lints each file after edit)
- .claude/settings.json hooks entry (Stop: full project lint + typecheck)
To remove: delete .claude/hooks/lint-typecheck.sh and the "hooks" key from .claude/settings.json

Examples

Positive Trigger

User: "Add eslint to this TypeScript project and fix all linting errors"

Expected behavior: Runs the full 9-step workflow — detects project, generates strict config, installs dependencies, auto-fixes, manually remediates, and verifies clean.

Non-Trigger

User: "Format this Python file with black and isort"

Expected behavior: Do not use this skill. It only handles ESLint for TypeScript/JavaScript projects.

Example 1: Greenfield setup Input: "Add eslint to this project" Detection: React + Vitest + pnpm monorepo Expected behavior: Generates config with React/Vitest/monorepo sections, installs 18 devDependencies via pnpm, runs auto-fix (fixes 47 errors), manually fixes 12 remaining, verifies clean.

Example 2: Fix existing warnings Input: "Fix all the linting warnings in our codebase" Detection: Existing eslint.config.mjs already present Expected behavior: Reads existing config, runs categorize-errors.js (finds 83 errors across 6 rules), fixes in priority order, verifies tsc and vitest run pass after each batch.

Example 3: Strict upgrade Input: "Make our linter stricter, we have too many any types" Detection: React Native + Expo + Drizzle + existing loose config Expected behavior: Merges strict rules into existing config (adds sonarjs, unicorn, security, type-aware checking), installs 8 new plugins, auto-fixes 120 errors, manually replaces 34 any types, renames 7 files to kebab-case in a separate batch, verifies clean.

Troubleshooting

• Error: ESLint config crashes on load (exit 2)

• Cause: Missing plugin import

• Solution: Check that the plugin package is installed and the import name matches

• Error: Cannot find tsconfig

• Cause: Wrong tsconfigRootDir or missing allowDefaultProject entry

• Solution: Set tsconfigRootDir: import.meta.dirname and add root JS config files to allowDefaultProject

• Error: Definition for rule X was not found

• Cause: Plugin uses legacy format, not flat config

• Solution: Use the plugin's flat/recommended export instead of the legacy extends syntax

• Error: tsc --noEmit fails after fixes

• Cause: A fix removed a needed import or broke a type

• Solution: Revert the last batch (git stash), redo one file at a time to isolate

• Error: Auto-fix introduces new errors

• Cause: Rule conflict between plugins (e.g., unicorn vs react)

• Solution: Identify which plugin owns the conflicting rule and configure it in the reference config's dedicated section to resolve the conflict (this is config structure, not rule suppression)

• Error: Hook fires but Claude ignores output

• Cause: Missing "decision": "block" in JSON

• Solution: Ensure the hook outputs {"decision": "block", "reason": "..."} — without this field, Claude discards it

• Error: Hook doesn't fire

• Cause: Matcher is case-sensitive

• Solution: Use Edit|Write|MultiEdit (PascalCase), not edit|write|multiedit

• Error: Hook script crashes

• Cause: Shell profile prints output on startup

• Solution: The bundled script avoids sourcing profiles; if using a custom script, wrap noisy .zshrc lines in [[ $- == *i* ]]

• Error: Circuit breaker tripped (hook stops blocking)

• Cause: 5 consecutive failures on same file

• Solution: The issue needs human intervention. Fix manually, then delete $TMPDIR/claude-lint-breaker/ (or /tmp/claude-lint-breaker/ if $TMPDIR is unset) to reset

• Error: ESLint is extremely slow (>30s)

• Cause: Type-aware rules on a huge codebase

• Solution: Scope recommendedTypeChecked to src/ only, or use recommended (no type info) for faster runs

Bundled Files Reference