What is the Tailwind 4 Docs skill?
Tailwind 4 Docs is an agent skill from Lombiq for Tailwind CSS v4 work. It does not bundle the Tailwind docs. After install you run a sync script that builds a local docs snapshot, and the agent then loads only the matching page, plus a gotchas list and an engineering playbook.
Tailwind 4 Docs is a skill for Tailwind CSS v4 usage, configuration and migration questions. The README describes it as an agent-optimized workflow with a curated gotchas list, an implementation playbook and a local docs snapshot generator.
The snapshot is not shipped with the skill. The README explains that the upstream Tailwind docs repository is source-available and not open source, so each user must accept that license and download the files themselves.
What changes in your agent's output
- The agent checks that the local docs snapshot exists and is under a week old before it answers a Tailwind question.
- It finds the right page in the generated docs index and loads only that file, rather than reading everything.
- Implementation, refactor and review tasks also pull in the engineering playbook.
- Upgrades from v3 follow a checklist: new tooling packages, the single import line, utility renames, prefix format and variant changes.
- If the snapshot cannot be built, the agent falls back to the gotchas file and says its guidance is limited.
Who it is for
Best for
- Teams moving a project from Tailwind v3 to v4 who want the agent to check the official upgrade guide.
- Developers building responsive layouts who want utilities and variants confirmed against real docs.
- Reviewers who want a consistent checklist for Tailwind pull requests.
Not for
- Agents without network access, git and Python 3, since the snapshot step needs all three.
- Visual design direction. This skill answers how Tailwind works, not what a page should look like.
- Projects that stay on Tailwind v3, because the docs snapshot is for v4.
Use it with UiChemy
Tailwind covers styling in a codebase. For WordPress pages, UiChemy Composer writes HTML, CSS and JS inside Elementor or Gutenberg, and Figma to WordPress converts a design file. Click Get Started on uichemy.com.
How to install Tailwind 4 Docs Skill: Tailwind CSS v4 Guidance for AI Agents
git clone https://github.com/Lombiq/Tailwind-Agent-Skills.gitNeeds Python 3.8 or later, git on the path, internet access and a writable skill folder. The README names the skills CLI as a one-command route, using the repository name.Clone the repository
Run the clone command above. The skill lives in the skills folder, and the default branch is dev.
Copy the skill folder
Copy skills/tailwind-4-docs into your agent's skills directory. The README lists .github/skills, .codex/skills and .claude/skills for project scope.
Initialize the docs snapshot
Run
python skills/tailwind-4-docs/scripts/sync_tailwind_docs.py --accept-docs-license. The README marks this as important after install.Confirm the files exist
Check that references/docs and references/docs-index.tsx were created before asking Tailwind questions.
Check that it loaded
Ask the agent how to migrate a v3 project to v4. It should read the upgrade guide from the snapshot and mention the single import line and the new tooling packages.
Key features
- Local docs snapshotA sync script clones the Tailwind docs repository and copies the MDX docs into the skill's references folder.
- Docs indexA generated docs-index file maps categories and slugs to MDX files so the agent loads only what it needs.
- Source recordA docs-source file stores the snapshot date and upstream commit, which is how the skill knows the snapshot is stale.
- Gotchas listA quick scan of common v4 migration pitfalls that works as a limited fallback without the snapshot.
- Engineering playbookAn agent-oriented guide used for implementation, refactor and review tasks.
- Migration checklistConfirms browser support, the tooling packages for PostCSS, the CLI and Vite, import syntax and utility renames.
- Staleness ruleIf the snapshot is missing or older than one week, the agent asks to run the sync before continuing.
- License acceptance flagThe sync command requires an explicit flag, so the user accepts the upstream docs license on purpose.
- MDX handlingTreats title and description exports as metadata and reads callout components as guidance text.
- Local repo optionPass a path to an existing clone of the docs repository to speed up repeated syncs.
Frequently asked questions
What is the Tailwind 4 Docs skill?
It is an agent skill from Lombiq for Tailwind CSS v4 development. It builds a local snapshot of the official docs on request, adds a gotchas list and an engineering playbook, and tells the agent to load only the page it needs for each question.
How do I install the Tailwind 4 Docs skill?
Clone the repository and copy the tailwind-4-docs folder into your agent's skills directory, such as .github/skills, .codex/skills or .claude/skills. Then run the sync script with the license flag so the docs snapshot is created inside the skill folder.
Why does it not include the Tailwind docs?
The README says the upstream Tailwind docs repository is source-available and explicitly not open source, so this repository does not redistribute it. Users run the sync script and accept the upstream license before the snapshot is downloaded to their machine.
What do I need to run the sync script?
You need Python 3.8 or later and git available on your path, internet access for the agent, and a writable skill folder. If your agent cannot run scripts, run the command yourself and confirm the docs and index files appear.
How often should I refresh the snapshot?
The skill treats a snapshot older than one week as stale. It asks to run the sync again before it continues. The snapshot date and upstream commit are recorded in the docs-source file inside the references folder.
Does it work with Copilot, Codex and other agents?
The README says any agent that supports agent skills can use it. It lists skill folders for Copilot, Codex and Claude Code, and notes that VS Code needs the agent skills preview setting turned on for Copilot.
Is it a design skill or a reference skill?
It is a reference and workflow skill. It helps an agent write correct Tailwind v4, not decide taste. Pair it with tailwind-design-system for tokens or tailwind-patterns for principles, and frontend-design for visual direction.
What happens if the snapshot is missing?
The skill tells the agent to stop and ask to initialize it, and not to answer until it exists. If initialization is blocked, the gotchas file is a limited fallback, and the playbook can partly cover implementation, refactor and review work.


