skill-tailwind

AI-скилл для написания, настройки, миграции и ревью современного Tailwind CSS v4 (CSS-first) — независимый от фреймворков (чистый HTML + CSS/SCSS), обучающий двум равноправным подходам к организации стилей: utility-first и BEM + @apply.

Русский · English · Лицензия: MIT · Tailwind CSS v4

Точка входа для агента — SKILL.md; вся глубина живёт в docs/, references/, resources/, а готовый код — в examples/ и templates/.

Что это

skill-tailwind — это слой реализации для Tailwind v4: как корректно выразить стиль средствами v4 в любом стеке или вовсе без него. Скилл помогает, когда вы:

• мигрируете с Tailwind v3 на v4 и спотыкаетесь о новый CSS-first-конфиг;

• настраиваете семантические дизайн-токены и тёмную тему на CSS-переменных;

• спорите «утилиты в разметке против @apply в CSS» и хотите обоснованную систему, а не догму;

• ревьюите код на Tailwind и хотите чек-лист плюс понимание тонких подводных камней v4.

Это слой реализации, а не дизайна — скилл корректно «прошивает» Tailwind, но не выбирает визуальное направление. Значения токенов — заменяемые заглушки; стабильны только имена токенов.

Установка (для ИИ-агентов)

Этот репозиторий и есть скилл: SKILL.md лежит в корне репозитория, рядом со вспомогательными docs/, references/, examples/, templates/, resources/, workflows/, scripts/, evals/. Установите его туда, откуда ваш агент читает скиллы.

Claude Code

Персонально (доступно во всех проектах):

git clone https://github.com/rekryt/skill-tailwind.git ~/.claude/skills/skill-tailwind

Только для проекта (запускать из корня проекта):

git clone https://github.com/rekryt/skill-tailwind.git .claude/skills/skill-tailwind

Скилл оказывается по пути …/skills/skill-tailwind/SKILL.md и обнаруживается автоматически — он подгружается сам, когда вы работаете с Tailwind, либо вызывается явно через /skill-tailwind. Обновление: git -C ~/.claude/skills/skill-tailwind pull.

Claude.ai (веб) и Claude Desktop

Упакуйте скилл в ZIP так, чтобы папка была в корне архива:

git clone https://github.com/rekryt/skill-tailwind.git
zip -r skill-tailwind.zip skill-tailwind

В Claude откройте Settings → Capabilities → Skills (должно быть включено выполнение кода), выберите Create skill → Upload a skill и загрузите skill-tailwind.zip.

Скилл подгружается автоматически на релевантных запросах или вызывается через /skill-tailwind. Загруженные скиллы приватны для вашего аккаунта; на планах Team/Enterprise админ может ими делиться.

Claude Agent SDK / Messages API

Скилл загружается в ваш workspace, а затем подключается к контейнеру выполнения запроса (нужны бета-флаги Skills и code-execution). Пример на Python:

from anthropic import Anthropic
from anthropic.lib import files_from_dir

client = Anthropic()  # читает ANTHROPIC_API_KEY

skill = client.beta.skills.create(
    display_title="Tailwind CSS v4",
    files=files_from_dir("./skill-tailwind"),   # папка, содержащая SKILL.md
)

resp = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=2048,
    betas=["skills-2025-10-02", "code-execution-2025-08-25", "files-api-2025-04-14"],
    container={"skills": [{"type": "custom", "skill_id": skill.id, "version": "latest"}]},
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    messages=[{"role": "user", "content": "Настрой дизайн-токены Tailwind v4 через @theme и тёмную тему."}],
)

Скиллы через API/SDK действуют в пределах workspace (отдельно от Claude Code и claude.ai); до 8 скиллов на запрос. Точные детали смотрите в документации Agent Skills — бета-идентификаторы могут меняться.

Любой другой агент / фреймворк

Скилл — это просто SKILL.md плюс вложенные референсы с прогрессивным раскрытием. Скопируйте эту папку в путь скиллов вашего агента (или укажите агенту на SKILL.md): он сначала читает SKILL.md, а файлы из references/, docs/, examples/, templates/ и т. д. подтягивает по мере необходимости. Именно поле description во frontmatter SKILL.md заставляет агента обратиться к скиллу.

Что покрывает

• Только Tailwind v4 (CSS-first): @import "tailwindcss", конфиг через @theme, кастомные утилиты через @utility, варианты через @custom-variant/@variant. Синтаксис v3 — только как «было → стало».

• Два равноправных подхода, парные примеры: (A) utility-first (классы в разметке) и (B) BEM + @apply в SCSS с группировкой деклараций по типу свойства — плюс когда выбирать какой.

• Дизайн-токены через @theme: семантические имена, тёмная тема на CSS-переменных, маппинг внешней дизайн-системы вместо её переопределения.

• И ещё: миграция v3 → v4; интеграция со сборкой (@tailwindcss/postcss против @tailwindcss/vite, @reference в стилях компонентов); адаптивность через @variant; состояния и доступность; чек-лист ревью, деревья решений и галерея анти-паттернов.

• Опора на исходники, а не маркетинг: поведение сверено с исходниками движка и официальной докой.

Что НЕ входит

• Код под конкретные фреймворки (React / Vue / Nuxt / Svelte) — примеры на чистом HTML + CSS/SCSS; JS-«клей» (cn() / clsx / tailwind-merge) упоминается только как опциональная врезка.

• Поведение компонентов на stateful-JS — combobox, командная палитра, date-picker, сортируемая таблица, карусель, графики, focus-trap и т. п. Скилл стилизует разметку; предпочитайте нативный элемент, иначе это JS-слой, который Tailwind по-прежнему оформляет.

• Визуальные/дизайн-решения — скилл не выбирает палитру, типографику и «направление». Готовая дизайн-система маппится в @theme (имена стабильны, значения заменяемы), а не выдумывается.

Конвенция BEM

Для подхода B (BEM + @apply): многословные части — camelCase (со строчной первой буквы). Разделитель элемента -, разделитель модификатора _:

cardList                 // блок
cardList_compact         // модификатор блока
cardList-item            // элемент
cardList-item_active     // модификатор элемента
cardList_size_lg         // модификатор «ключ-значение»

Один блок на компонент; элементы всегда считаются от блока (никаких цепочек -a-b). Это дефолт, и он настраиваемый — если в проекте уже принята другая схема, следуйте ей.

Структура репозитория

Путь Назначение

SKILL.md точка входа: когда применять, ядро подхода и маршрутизация по остальным разделам

README.md / README.en.md человекочитаемое описание (RU / EN)

docs/ концептуальные объяснения по темам (вглубь), включая возможности v4.1 (text-shadow-*/mask-*, …)

references/ плотные справочники для прогрессивного раскрытия, грузятся по необходимости

examples/ 27 компонентов, каждый в двух вариантах (A — utility-first, B — BEM + @apply)

templates/ заготовки: входной CSS, токены @theme, скелеты компонентов

resources/ плоские сканируемые шпаргалки + агрегаторы (деревья решений, анти-паттерны, мастер-чек-лист)

workflows/ пошаговые плейбуки: миграция v3 → v4, рефакторинг в токены, ревью, выбор A/B, диагностика

scripts/ опциональные офлайн-проверки (без сети): анти-паттерны v3, динамические имена классов

evals/ поведенческие проверки качества скилла: кейсы, фикстуры и запускаемый статический харнесс

Быстрый старт

Подключение v4 — одна строка вместо трёх директив v3, а конфиг живёт прямо в CSS через @theme (имена стабильны; меняйте значения под свою дизайн-систему):

@import "tailwindcss";

@theme {
  /* значения — заглушки; имена держим стабильными */
  --color-background: oklch(99% 0 0);
  --color-foreground: oklch(21% 0.01 255);
  --color-primary: oklch(52% 0.12 255);
  --color-primary-foreground: oklch(99% 0 0);
  --radius-md: 0.375rem;
}

Объявленные токены сразу становятся утилитами — bg-background, text-foreground, bg-primary text-primary-foreground, rounded-md; прозрачность — слэш-модификатор (bg-primary/90). Готовая заготовка с семантическими токенами и тёмной темой — в templates/theme.css. Дальше откройте SKILL.md — он направит в нужный раздел под вашу задачу.

Лицензия

MIT © 2026 rekryt.

Репозиторий: https://github.com/rekryt/skill-tailwind