You bump tailwindcss to v4 and the build stops with "It looks like you're trying to use tailwindcss directly as a PostCSS plugin". You fix that, and now the dark mode toggle does nothing because v4 never loads your tailwind.config.js, every bg-opacity-50 overlay is solid, and the Vue component with @apply fails with "Cannot apply unknown utility class". This skill finds those leftovers and the others listed below in one pass, and tells you how to fix each one.

Your agent runs a scanner on your package.json files, PostCSS and Vite configs, tailwind.config files, browserslist, stylesheets (CSS, Sass, Less, Stylus), Vue, Svelte and Astro components with their style blocks, React and other JavaScript or TypeScript, and HTML-like templates (Blade, ERB, Twig, Liquid, Nunjucks and more). It works out the Tailwind CSS version of each app from its package.json, so a monorepo with one app still on v3 is checked per app, and v3 code is not flagged until that app upgrades. It reads class names from class and className attributes, Vue, Angular and Astro class bindings, cn(), clsx(), cva(), twMerge() and @apply, and skips comments, code samples, node_modules, build output and generated CSS. It never runs a build or installs anything. It returns BLOCK, REVIEW, or NOT FLAGGED, with the file, line, reason, and a safer approach, and each rule links to the official Tailwind CSS documentation behind it. Secrets are never printed.

What it checks

BLOCK (fix before shipping)

• T01: tailwindcss used as a PostCSS or Vite plugin (also in the postcss field of package.json), tailwindcss/nesting, and scripts that run the v3 tailwindcss command without @tailwindcss/cli
• T02: @tailwind base and components, @screen, screen() and imports of tailwindcss/base or tailwindcss/components
• T03: a tailwind.config.js that no @config loads and whose settings have no CSS counterpart yet (darkMode, plugins, content paths, prefix, presets), and the safelist, corePlugins and separator options v4 does not support
• T04: bg-, text-, border-, divide-, ring- and placeholder-opacity classes, and CSS variables in square brackets such as bg-[--brand]
• T05: @apply of theme utilities, including your own @theme colors, fonts and breakpoints, in Vue, Svelte or Astro style blocks, CSS modules, Angular component styles and stylesheets imported from component code, without @reference; and @apply of classes defined in @layer instead of @utility

REVIEW (check before release)

• T11: apps that use Tailwind CSS but are not on v4 yet (v3 in package.json, the v3 Play CDN, or no version found)
• T12: classes that still work but look different or are deprecated: ring, outline-none without a focus style, shadow-sm, rounded-sm and blur-sm in a project that still uses the bare v3 names of those scales, flex-grow, flex-shrink, overflow-ellipsis, decoration-slice and decoration-clone
• T13: borders without a color (now the text color instead of gray) when no base style restores the old color
• T14: theme() with the v3 dot path, such as theme(colors.gray.200)
• T15: custom classes in @layer utilities (no hover:, md: or dark: variants in v4)
• T16: browser targets older than Safari 16.4, Chrome 111 or Firefox 128 in browserslist or Vite build.target, and @vitejs/plugin-legacy
• T17: Tailwind plugins in package.json with no @plugin line, container-queries and line-clamp plugins that v4 has built in, and Flowbite or Preline without an @source line
• T18: Tailwind v4 at-rules in Sass, Less or Stylus files
• T19: a tailwind.config.js that nothing loads and that looks left over (its settings already live in @theme, @custom-variant, @plugin or @source, or it holds only theme values)

What's included

• The scanner (Python 3.9+, standard library only)
• A rules guide with the reason, safer approach and official source link for each rule
• A risky and a safe example project (a Vue storefront half-way through the upgrade, with a v3 admin app and a leftover docs config beside it), and the real report the scanner produces on the risky one

Limits

It reads file text and does not run Tailwind, so classes built at run time (string concatenation, values from a CMS) and what a loaded JS config resolves to are not seen. The prefix, important-modifier, variant-order, space-between and gradient changes are not checked, and the version comes from the range in package.json, not the lock file. The meaning-changed, border, plugin and leftover-config rules are hints to confirm in the browser. NOT FLAGGED is not a guarantee.

Contents

One ZIP file with 30 files: SKILL.md, the scanner in scripts/ (6 Python files), references/rules.md (every rule with its reason and safer approach), and examples/ (21 example files plus report.md, the real scanner output on the risky example).

How to use: This is an agent skill: a folder with a SKILL.md file and Python scripts that an AI coding agent such as Claude Code, Cursor, or Codex CLI can run. Unzip it into your agent's skills folder (for Claude Code: ~/.claude/skills/), then ask your agent to check your project. The scripts also run on their own with Python 3.9 or newer, with nothing to install. They read your files only: no network access, and nothing is sent anywhere.