tailwind · oakoss — Claude Code skill: what it does, how to install
A Tailwind CSS v4 skill for themes, components, dark mode, container queries, v3 migrations, shadcn/ui, and build troubleshooting.
MIT 233 installs ★ 29 updated 2026-08-17
npx skills add oakoss/agent-skills --skill tailwind -a claude-codeWhat tailwind does
This skill guides Tailwind CSS v4 work through CSS-first configuration. It covers @theme for design tokens, the @import "tailwindcss" entry point, custom utilities with @utility, plugin loading with @plugin, and explicit scan paths via @source.
It also covers dark mode, container queries, shadcn/ui integration, and migration from v3. The reference includes dynamic utility values, logical spacing and inset utilities, text shadows, masks, and form-state variants. A legacy Tailwind v3 project with no upgrade plan is outside its intended use.
What it helps with
- configure a Tailwind theme with
@theme - build components with container queries
- migrate a project from Tailwind v3 to v4
- map CSS variables for shadcn/ui
- diagnose a Tailwind build error
Example prompts for the agent
- Set up a Tailwind CSS v4 theme with
@themeand replace raw colors with semantic tokens. - Migrate this project from Tailwind v3 to v4 and update the configuration across its files.
- Check the shadcn/ui integration and fix the Tailwind build error.
How to install tailwind
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill tailwind -a claude-code2Manually: put the files in place
~/.claude/skills/tailwind/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/tailwind/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill tailwind -a codex2Manually: put the files in place
.agents/skills/tailwind/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill tailwind -a cursor2Manually: put the files in place
.cursor/skills/tailwind/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install oakoss/agent-skills skills/tailwind2Manually: put the files in place
.github/skills/tailwind/SKILL.md1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill tailwind -a gemini-cli2Platform CLI
gemini skills install https://github.com/oakoss/agent-skills --path skills/tailwindManually: put the files in place
.devin/skills/tailwind/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill tailwind -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about tailwind
How do I install tailwind in Claude Code?
Run npx skills add oakoss/agent-skills --skill tailwind -a claude-code, then check ~/.claude/skills/tailwind/SKILL.md.
What does the tailwind skill do?
It supports Tailwind CSS v4 themes, design tokens, components, dark mode, container queries, plugins, and build troubleshooting.
Can I use tailwind for a Tailwind v3 project?
It covers migration from v3 to v4. A legacy v3 project that will not be upgraded is outside its intended use.
Source text
SKILL.md · MIT
---
name: tailwind
description: 'Tailwind CSS v4 patterns and design systems. Use when configuring Tailwind themes, building components, implementing dark mode, using container queries, migrating from v3, integrating shadcn/ui, or fixing build errors. Use for tailwind, css, styling, theme, design-tokens.'
license: MIT
metadata:
author: oakoss
version: '1.0'
source: 'https://tailwindcss.com/docs'
user-invocable: false
---
# Tailwind CSS (v4+)
## Overview
Tailwind CSS v4 skill covering CSS-first configuration, design tokens, component patterns, shadcn/ui integration, dark mode, container queries, migration from v3, and custom utilities.
**When to use:** Configuring Tailwind themes, building utility-first components, implementing dark mode, using container queries, migrating from v3, integrating shadcn/ui, troubleshooting build errors.
**When NOT to use:** Tailwind v3 legacy projects that will not upgrade, projects using a different styling approach (CSS Modules, styled-components) without plans to adopt Tailwind.
## Quick Reference
| Pattern | API | Key Points |
| -------------------- | ----------------------------------------------------- | ------------------------------------------------ |
| CSS-first config | `@theme { --color-brand: oklch(...); }` | All config in CSS, no `tailwind.config.js` |
| Import entry | `@import "tailwindcss";` | Replaces `@tailwind base/components/utilities` |
| Custom utilities | `@utility name { ... }` | Replaces `@layer utilities`, works with variants |
| Functional utilities | `@utility tab-* { tab-size: --value(--tab-size-*); }` | Accept dynamic values via `--value()` |
| Plugin loading | `@plugin "@tailwindcss/typography";` | Replaces `require()` in config |
| Container queries | `@container` parent + `@md:` child | Built-in, no plugin needed |
| Named containers | `@container/sidebar` + `@md/sidebar:` | Scope queries to specific containers |
| Dark mode variant | `@custom-variant dark (&:where(.dark, .dark *));` | Class-based dark mode override |
| Theme inline | `@theme inline { --color-bg: var(--bg); }` | Inlines values at build, single-theme only |
| Source detection | `@source "../node_modules/my-lib";` | Explicitly add scan paths |
| Reference import | `@reference "../../app.css";` | Use theme in Vue/Svelte scoped styles |
| Override defaults | `--color-*: initial;` inside `@theme` | Reset a category before redefining |
| Dynamic values | `grid-cols-(--my-var)` | Use CSS variables in utility values |
| Text shadows | `text-shadow-*` | Built-in text shadow utilities |
| Starting styles | `starting:opacity-0` | `@starting-style` variant for entry animations |
| Masks | `mask-*` | CSS mask utilities for image/gradient masking |
| Field sizing | `field-sizing-content` | Auto-sizing textareas and inputs |
| Inset shadows | `inset-shadow-*`, `inset-ring-*` | Inner shadow and ring utilities |
| User validation | `user-valid:`, `user-invalid:` | Form validation after user interaction |
| Pointer queries | `pointer-fine:`, `pointer-coarse:` | Target input device precision |
| Inert | `inert:opacity-50` | Style inert elements |
| Logical spacing | `pbs-*`, `pbe-*`, `mbs-*`, `mbe-*` | Block-direction padding/margin (v4.2) |
| Logical sizing | `inline-*`, `block-*`, `min-inline-*`, `max-block-*` | Logical width/height utilities (v4.2) |
| Logical inset | `inset-s-*`, `inset-e-*`, `inset-bs-*`, `inset-be-*` | Logical positioning; replaces `start-*`/`end-*` |
| Logical borders | `border-bs-*`, `border-be-*` | Block-direction border utilities (v4.2) |
| Font features | `font-features-['smcp']` | OpenType `font-feature-settings` (v4.2) |
| New color palettes | `mauve`, `olive`, `mist`, `taupe` | Additional neutral palettes (v4.2) |
| Webpack integration | `@tailwindcss/webpack` | Run Tailwind as a webpack plugin (v4.2) |
| Color space | OKLCH | Default in v4, sRGB fallbacks generated |
## Common Mistakes
| Mistake | Correct Pattern |
| ----------------------------------------- | ------------------------------------------------ |
| Using `tailwind.config.js` in v4 | Configure via `@theme { ... }` in CSS |
| `hsl(var(--background))` double-wrap | Reference directly: `var(--background)` |
| `:root`/`.dark` inside `@layer base` | Define at root level, outside any `@layer` |
| `@apply` with `@layer components` classes | Use `@utility` directive for custom utilities |
| `@theme inline` for multi-theme switching | Use `@theme` without `inline` for dynamic themes |
| Raw colors like `bg-blue-500` everywhere | Semantic tokens (`bg-primary`) that auto-adapt |
| `require()` or `@import` for plugins | Use `@plugin "package-name";` |
| `tailwindcss-animate` in v4 | Use `tw-animate-css` instead |
| Missing `@theme inline` with shadcn/ui | Map all CSS variables in `@theme inline` block |
| Using `theme('colors.brand')` in CSS | Use `var(--color-brand)` native CSS variables |
| Using deprecated `start-*`/`end-*` inset | Use `inset-s-*`/`inset-e-*` logical utilities |
## Delegation
- **Class pattern discovery and usage examples**: Use `Explore` agent
- **v3 to v4 migration across multiple files**: Use `Task` agent
- **Design token hierarchy and theming architecture**: Use `Plan` agent
> If the `motion` skill is available, delegate complex animation patterns (spring physics, gestures, scroll-linked) to it.
## References
- [Configuration](references/configuration.md) -- CSS-first config, @theme, @theme inline, @utility, @plugin, @source, @reference, @variant directives
- [Design Tokens](references/design-tokens.md) -- OKLCH token system, brand scales, semantic tokens, shadows, z-index, fluid typography
- [Component Patterns](references/component-patterns.md) -- Layouts, grids, container queries, 3D transforms, subgrid, CVA variants
- [UI Patterns](references/ui-patterns.md) -- Buttons, forms, navigation, cards, typography with variants, states, accessibility
- [Dark Mode](references/dark-mode.md) -- Class-based dark mode, multi-theme systems, ThemeProvider, @custom-variant
- [shadcn/ui Integration](references/shadcn-integration.md) -- Four-step architecture, components.json, tw-animate-css, Vite setup
- [Migration](references/migration.md) -- v3 to v4 migration steps, breaking changes, upgrade tool, common gotchas
- [Troubleshooting](references/troubleshooting.md) -- Common errors, build fixes, CSS layer issues, PostCSS problems
© oakoss · MIT · oakoss/agent-skills
Similar skills
All skills for Frontend and UI →tailwind by other authors comes first.