Три примитива: Commands, Subagents, Skills

Репозиторий, по которому мы идём, помечает свои примеры ровно тремя буквами в кружках: a — agents, c — commands, s — skills. Это не случайный набор: каждый из примитивов отвечает на свой вопрос, и вместе они закрывают почти весь спектр расширения Claude Code.

• Команда отвечает на «что мы делаем снова и снова» — детерминированный вход в повторяемый воркфлоу.
• Субагент отвечает на «кто это делает» — отдельный исполнитель со своим контекстом, моделью и набором инструментов.
• Скилл отвечает на «что нужно знать, чтобы сделать правильно» — переиспользуемое ноу-хау с прогрессивным раскрытием.

Важная ремарка от создателя Claude Code, прежде чем нырять: базовый продукт сознательно держат простым. Кастомизация — это усилитель, а не входной билет.

Из этого следует рабочая установка на всю главу: каждый примитив добавляют только тогда, когда он окупает свою цену — лишний контекст, лишний слой, лишний файл в git. Дальше разберём цену и выгоду каждого, на живых файлах из репозитория, а в финале соберём их в один поток.

Команда — это файл-сценарий, который ты вызываешь слэшем (/commit-push-pr) или Claude подхватывает автоматически по описанию. Её роль — точка входа и дирижёр: задать пользователю вопрос, дёрнуть нужного субагента, вызвать скилл, собрать результат. Ключевая ценность — детерминизм: то, что ты делаешь по десять раз в день, перестаёт зависеть от того, как ты сегодня сформулировал промпт.

Frontmatter: 16 полей

YAML-шапка управляет тем, как команда исполняется. Минимум — пустой frontmatter (имя возьмётся из имени файла); всё остальное опционально, но именно эти поля превращают команду из «текстовой заготовки» в управляемый процесс.

Живой пример из репо

Команда /weather-orchestrator ничего не делает руками — она дирижирует. Обрати внимание на allowed-tools (только то, что нужно дирижёру) и на «Execution Contract» в теле: команде запрещено доставать данные самой, она обязана делегировать.

---
description: Fetch Dubai weather and create an SVG weather card
model: haiku
allowed-tools:
  - AskUserQuestion
  - Agent
  - Skill
---

# Weather Orchestrator Command

## Execution Contract (non-negotiable)
You MUST complete this command by delegating to the weather-agent subagent.
You are forbidden from:
- Fetching weather data yourself via Bash, WebFetch, or any other tool
- Calling weather-svg-creator before the agent returns a temperature

## Workflow
Step 1 — AskUserQuestion: Celsius or Fahrenheit?
Step 2 — Agent tool → weather-agent (returns temp + unit)
Step 3 — Skill tool → weather-svg-creator (writes svg + md)

Субагент — это отдельный «работник» с собственным окном контекста, своей моделью, своим allowlist'ом инструментов и (опционально) своей памятью. Главная выгода — изоляция: грязная работа (долгий поиск, шумный вывод, рискованные инструменты) не засоряет твой основной контекст, а результат возвращается сжатым. Борис ставит субагенты в один ряд с командами.

Frontmatter: 16 полей

Живой пример: tool-allowlist как защита

Самый поучительный приём в weather-agent — он намеренно лишён сетевых инструментов. Не потому что не доверяют, а чтобы единственным способом достать данные был вызов скилла. Allowlist здесь — не безопасность, а архитектурное принуждение.

---
name: weather-agent
description: Use this agent PROACTIVELY to fetch weather for Dubai…
allowedTools: ["Read", "Skill"]   # нет WebFetch — by design
model: sonnet
color: green
maxTurns: 5
permissionMode: acceptEdits
memory: project           # помнит прошлые замеры
skills:
  - weather-fetcher        # предзагружен в контекст
hooks:
  PreToolUse:                # голосовое уведомление на каждый инструмент
    - matcher: ".*"
      hooks: [{ type: command, command: python3 …/hooks.py, async: true }]
---

# Weather Agent
Your tool allowlist intentionally excludes network tools — if you find
yourself needing one, that is a signal you are bypassing the skill.
Stop and use Skill(weather-fetcher) instead.

Пять официальных типов агентов

Их не нужно объявлять — они встроены и доступны как subagent_type. Знать их полезно: дешёвый Explore на haiku закрывает 80% задач «найди по коду».

Скилл легко принять за «просто markdown с инструкцией». Это недооценка. Скилл — это папка: внутри могут лежать скрипты, ассеты, данные, справочники, которые агент открывает по мере надобности. Отсюда главная идея — прогрессивное раскрытие: лёгкое описание всегда в контексте, тяжёлые детали подгружаются только когда нужны.

Frontmatter: 16 полей

Почти зеркало команды — и это не совпадение (к конвергенции вернёмся в §5). Два поля стоит выделить особо: user-invocable: false превращает скилл в чистое «фоновое знание» для предзагрузки в агента, а description — это не аннотация для человека, а триггер для модели.

Живой пример: скилл как чистое знание

weather-fetcher — это «agent skill»: user-invocable: false, поэтому он не светится в меню, а предзагружается в weather-agent. Внутри — только инструкция и два URL. Никакой логики записи файлов: одна ответственность.

---
name: weather-fetcher
description: Instructions for fetching current temperature for Dubai from Open-Meteo
user-invocable: false      # фоновое знание, не слэш-команда
allowed-tools: ["WebFetch(*)"]
---

# Weather Fetcher Skill
1. WebFetch → Open-Meteo:
   C°: …/forecast?latitude=25.2048&longitude=55.2708&current=temperature_2m
2. Extract current.temperature_2m + current_units.temperature_2m
3. Return value + unit. # не трансформируй, не пиши файлы

Девять видов скиллов (карта Anthropic)

Команда Thariq разложила сотни своих скиллов и увидела девять повторяющихся категорий. Лучшие скиллы ложатся ровно в одну; путаные — растягиваются на несколько. Полезно как чек-лист «а какой скилл я вообще пишу».

Как писать скиллы: дистиллят правил Thariq

Из девяти его советов четыре стоит запомнить дословно — они экономят недели.

• Description — для модели, не для человека. В начале сессии Claude строит листинг всех скиллов по их description и сканирует его, решая «есть ли скилл под этот запрос». Поэтому описание — это условие срабатывания, а не резюме.
• Секция Gotchas — самый ценный контент. Собирай туда точки, где Claude спотыкается, и дописывай по мере появления новых граблей.
• Не загоняй Claude в рельсы. Скилл переиспользуем — давай цель и ограничения, а не пошаговый жёсткий скрипт. Иначе он сломается на первой нестандартной ситуации.
• Не повторяй очевидное. Claude и так много знает. Ценность скилла — там, где он выталкивает модель из дефолтного мышления (классический пример — frontend-design против шрифта Inter и фиолетовых градиентов).

Сигнатурный паттерн репозитория — Command → Agent → Skill. Команда дирижирует и говорит с пользователем; агент достаёт данные своим предзагруженным скиллом; отдельный скилл рендерит результат. Каждый слой — одна ответственность. Вот тот же weather-пример целиком, на одной схеме.

Схема перерисована под тему главы; канонический оригинал — orchestration-workflow/orchestration-workflow.svg.

Два паттерна скиллов в одном потоке

Главная тонкость примера: скиллы участвуют двумя разными способами, и их легко перепутать.

Все три примитива умеют model, effort, hooks, context: fork — frontmatter сознательно сходится. Поэтому выбор идёт не по «возможностям», а по намерению.

Эвристика на каждый день: начни с команды. Если внутри неё появляется грязная или параллелизуемая работа — выдели субагента. Если в агенте/команде всплывает знание, которое хочется переиспользовать в других местах — вынеси его в скилл. Сущности добавляются по нужде, а не заранее.