Tailwind CSS v4 Docs Skill

Tailwind CSS v4 Docs is an Agent Skill from Lombiq that gives AI coding agents a working, current copy of the official Tailwind CSS v4 documentation — synced to your machine by a bundled script — plus a curated gotchas list and an engineering playbook for implementation, refactor, and review work.

What is Tailwind CSS v4?

Tailwind CSS v4 is the ground-up rewrite of the utility-first CSS framework. It replaced the tailwind.config.js JavaScript config with CSS-native configuration through @theme, swapped the @tailwind directives for a single @import "tailwindcss", moved the PostCSS plugin to @tailwindcss/postcss and the CLI to @tailwindcss/cli, and introduced a first-class Vite plugin. It targets modern browsers only — Safari 16.4+, Chrome 111+, Firefox 128+.

What the skill gives your agent

• A local docs snapshot. The sync script clones tailwindlabs/tailwindcss.com, copies src/docs into references/docs/, and generates references/docs-index.tsx — a category and slug map matching the official sidebar. The agent looks up the topic in the index, then opens only that one MDX file.
• A 20-point gotchas scan (references/gotchas.md) covering the changes that silently break v3 code: the important modifier moving to the end (bg-red-500!), prefixes becoming a tw: leading segment, default border and ring colors switching to currentColor, stacked variants applying left-to-right instead of right-to-left, arbitrary CSS variables using bg-(--brand-color) rather than bg-[--brand-color], transform resets becoming scale-none / rotate-none / translate-none, and hover: applying only on hover-capable devices.
• An engineering playbook (references/engineering-playbook.md) — an agent-oriented guide across 18 sections: the abstraction ladder, tokens-first design, when arbitrary values are acceptable, @utility versus component classes, variant strategy, @apply discipline, custom variants, rich text and uncontrolled markup, generated DOM, responsive strategy, file organization, refactor heuristics, and a review checklist.
• A migration checklist for v3 to v4, pointing at upgrade-guide.mdx and compatibility.mdx for the authoritative utility renames and removals.
• Entry-point routing — named MDX targets for configuration and directives, theming, variants, responsive design, Preflight, and class detection, so the agent does not guess which page to read.
• MDX handling rules so the agent reads export const title as metadata and treats JSX callouts like <TipInfo> and <TipBad> as guidance.

How it works

The docs are deliberately not bundled. The tailwindcss.com repository is source-available but explicitly not open source, so this skill redistributes nothing — it ships a script that fetches the docs to your machine under your acceptance of the upstream license.

After installing, you run the sync once: it clones the docs repo shallowly into a temp folder, copies the MDX tree and the index, and records the upstream commit hash and snapshot date in references/docs-source.txt. SKILL.md instructs the agent to check that file and refuse to answer from memory when the snapshot is missing or more than a week old — asking you to refresh instead. If a sync is impossible, it falls back to the gotchas list and playbook and tells you to consult the official docs.

Who it is for

Front-end developers migrating a v3 codebase to v4, or building on v4 with Claude Code, GitHub Copilot, Codex, or Cursor — anyone whose agent keeps writing tailwind.config.js and @tailwind base for a framework that no longer uses either.

What you can build

Correct v4 theme configuration, @utility-based custom utilities, variant compositions that stack in the right order, responsive layouts that survive the space-* and divide-* selector changes, and v3-to-v4 upgrades where every rename is checked against the real upgrade guide.

Why it matters

Tailwind v4 changed the config format, the import syntax, the build tooling, the prefix syntax, the important-modifier position, and the variant stacking order. Models trained largely on v3 content reproduce all of it confidently, and the resulting code fails in ways that look like a config problem rather than a version problem. Pointing the agent at a dated, verifiable snapshot of the real docs — and making it check the snapshot date before answering — replaces recall with lookup.

1. Install the skill

The repository ships an Agent Skills-compatible layout, so the skills CLI handles it in one command:

npx skills add Lombiq/Tailwind-Agent-Skills

To install manually, download the folder from this page and copy it into your agent skills directory:

• Project scope: .claude/skills/ (Claude Code), .github/skills/ (Copilot), .codex/skills/ (Codex)
• Global scope: ~/.claude/skills/, ~/.copilot/skills/, ~/.codex/skills/

2. Initialize the docs snapshot (required)

The Tailwind docs are not bundled. Run the sync script once after installing:

python skills/tailwind-4-docs/scripts/sync_tailwind_docs.py --accept-docs-license

The --accept-docs-license flag is mandatory — the script refuses to run without it, because tailwindcss.com is source-available and not open source. Review that license before you accept it.

If you already have a clone of the docs repo, point at it to skip the download:

python skills/tailwind-4-docs/scripts/sync_tailwind_docs.py --accept-docs-license --local-repo ../tailwindcss.com

3. Verify it worked

The sync succeeded when these exist:

• references/docs/ — the MDX documentation tree
• references/docs-index.tsx — the category and slug map
• references/docs-source.txt — upstream commit hash and snapshot date

4. Keep it fresh

Re-run the same command whenever the snapshot is more than a week old. SKILL.md tells the agent to check the date and stop rather than answer from memory — but some agents will not run scripts on their own, so if answers stall, tell the agent explicitly to run the sync command.

5. Use it

Ask Tailwind v4 questions in plain language:

Migrate this component from Tailwind v3 to v4 and flag anything the upgrade guide calls a breaking change.

The agent finds the topic in the index, loads only the matching MDX page, and pulls in the engineering playbook for implementation and review work.