Вы положили скилл в .claude/skills/deploy/SKILL.md, набираете /deploy — и запускается совсем не он. Или MCP-сервер из .mcp.json работает не той конфигурацией, которую видит команда.

Причина у обоих случаев одна: имя определено в нескольких местах, и Claude Code выбирает одно по правилам приоритета. Ловушка в том, что правила приоритета разные для разных сущностей. Интуиция «проектное важнее пользовательского» верна для настроек, но ломается на скиллах, где всё наоборот. Пока вы этого не знаете, поведение выглядит случайным.

После этого урока вы будете читать конфликты уверенно: знать порядок для каждой сущности, различать перекрытие и слияние и находить причину, по которой скилл не подхватывается.

Что уже умеем / что добавим

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

Что вы узнаете в рамках статьи

• Порядок приоритета файлов настроек и почему списки при этом объединяются
• Почему у скиллов, подагентов и MCP приоритеты устроены по-разному
• Чем перекрытие по имени отличается от слияния, на примере хуков
• Полный чек-лист причин, по которым скилл не появляется или не запускается
• Как проверять гипотезы командами /skills, /status и /doctor

Ключевые термины

• Слой конфигурации — источник настроек: управляемые, командная строка, локальные, проектные, пользовательские.
• Приоритет — правило выбора значения, когда один и тот же ключ или имя задано в нескольких слоях.
• Перекрытие — при совпадении имени работает определение из более приоритетного источника, остальные не применяются.
• Слияние — определения из всех источников объединяются и действуют одновременно.
• Управляемые настройки — политика организации, которую нельзя перебить своими файлами.
• SKILL.md — файл скилла в папке <имя-скилла>/, состоящий из YAML-frontmatter и инструкций.

Приоритет файлов настроек

Начнём с базового слоя. Когда один ключ задан в нескольких файлах, Claude Code берёт значение из самого приоритетного. Порядок, от высшего к низшему:

1. Управляемые настройки — managed-settings.json, MDM-политика или настройки из консоли claude.ai. Ваши файлы их не перебивают.
2. Аргументы командной строки — то, что вы передали флагом -settings при запуске, на одну сессию.
3. Локальные настройки проекта — .claude/settings.local.json, ваши личные для этого проекта.
4. Общие настройки проекта — .claude/settings.json, то, что команда коммитит в репозиторий.
5. Пользовательские настройки — ~/.claude/settings.json, ваши для всех проектов.

Обратите внимание на три нижних уровня: ближе к проекту — выше приоритет, а локальный файл сильнее общего проектного. Отсюда типичный случай: ключ в settings.json «не работает», потому что тот же ключ есть в settings.local.json.

Важное уточнение: списки не перекрываются, а объединяются. Если permissions.allow задан в нескольких файлах, Claude Code складывает списки. Каждый файл добавляет записи, не удаляя чужие.

Почему приоритет не единый

Теперь главное. Разобравшись с настройками, легко решить, что тот же порядок действует везде. Это неверно — и здесь возникает большая часть путаницы.

Скиллы. Порядок обратный привычному: enterprise перекрывает personal, а personal перекрывает project.

То есть при скилле deploy и в ~/.claude/skills/, и в проектном .claude/skills/ команда /deploy запустит личный. Плагинные скиллы в конфликт не вступают: у них своё пространство имён plugin-name:skill-name.

Подагенты. Пять уровней: управляемые настройки, флаг --agents, .claude/agents/ проекта, ~/.claude/agents/, ниже всех — каталог agents/ плагина. Здесь проектное важнее пользовательского — наоборот, чем у скиллов.

MCP-серверы. Третий вариант: local, затем project, затем user, ниже — плагины и коннекторы claude.ai. Совпадение ищется по имени, и берётся вся запись целиком из приоритетного источника — поля из разных областей не смешиваются.

Общего правила на все три случая нет. Надёжный подход один — сверяться с порядком для конкретной сущности.

Перекрытие против слияния

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

Записи хуков объединяются между уровнями настроек, а не заменяют друг друга: пользовательские, проектные и локальные добавляют свои хуки, не убирая управляемые. Все подходящие хуки выполняются параллельно.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "npm run lint" }]
      }
    ]
  }
}

Такой хук в проектном файле не отменит похожий хук из пользовательских настроек — сработают оба. Один и тот же обработчик, описанный в нескольких файлах настроек, выполнится один раз, но копия из плагина или скилла считается отдельной.

Практический вывод: «работает не тот скилл» — ищите конфликт имён, а «выполняется что-то лишнее» — ищите дополнительный хук: убрать чужой хук своим файлом нельзя.

Чек-лист: почему скилл не подхватывается

Соберём причины по порядку проверки. Сначала — скилла нет в /skills:

• Файл лежит не в папке. Самая частая ошибка. Скилл должен быть по пути .claude/skills/<имя>/SKILL.md, а не .claude/skills/<имя>.md. Нужна именно папка с файлом SKILL.md внутри.
• Frontmatter не читается. Claude Code разбирает frontmatter, только если открывающий -- стоит первой строкой файла. Пустая строка или комментарий выше — и весь файл, вместе с маркерами --, считается содержимым скилла.
• Битый YAML. Неверный отступ или незакрытая кавычка ломают разбор.
• Каталог не отслеживался при старте. Правки скиллов подхватываются без перезапуска. Но если вы создали саму папку скиллов, которой при старте сессии не было, — перезапустите Claude Code.
• Вложенный каталог не активирован. Скиллы из вложенных .claude/skills/ не грузятся на старте: они появляются, когда Claude прочитает или отредактирует файл в этой папке.

Скилл виден в /skills, но Claude сам его не вызывает:

• Стоит disable-model-invocation: true. Такой скилл запускается только вручную через /имя. В /skills у него будет пометка «user-only».
• Описание не совпадает с формулировкой запроса. Claude выбирает скилл по полю description, поэтому оно должно называть задачу вашими словами. Формально поле не обязательно — без него берётся первый абзац содержимого, — но полагаться на это не стоит.

Запускается не тот скилл:

• Конфликт имён. Личный скилл перекрывает проектный. Проверьте ~/.claude/skills/ на одноимённую папку.
• Совпадение со встроенным скиллом. Ваш скилл перекроет одноимённый встроенный, но не его псевдонимы: собственный code-review заменит /code-review, а /review по-прежнему вызовет встроенный.

Частые ошибки

• Переносить приоритет настроек на скиллы. У настроек проектное сильнее пользовательского, у скиллов — наоборот: personal перекрывает project. Одноимённый личный скилл тихо выигрывает у проектного.
• Класть скилл файлом, а не папкой. Путь .claude/skills/deploy.md не даёт скилла. Нужен .claude/skills/deploy/SKILL.md.
• Ставить -- не первой строкой. Frontmatter читается, только когда открывающий -- — самая первая строка. Иначе он превращается в обычный текст скилла.
• Ждать, что свой хук отменит чужой. Хуки сливаются между уровнями, а не перекрываются. Убрать хук из настроек другого уровня своим файлом нельзя.

Наиболее частые вопросы

• Какой скилл победит при совпадении имён в проекте и в домашнем каталоге? — Личный. Для скиллов enterprise перекрывает personal, а personal перекрывает project.
• Почему у подагентов и MCP порядок другой? — Так они устроены: у подагентов проект выше пользователя, у MCP порядок local, project, user. Единого правила нет, сверяйтесь по сущности.
• Нужно ли перезапускать сессию после добавления скилла? — Обычно нет, изменения подхватываются на лету. Перезапуск нужен, если вы создали саму папку скиллов, которой при старте не было.
• Почему ключ из settings.json не действует? — Скорее всего, тот же ключ задан в .claude/settings.local.json: локальный файл приоритетнее проектного. Проверьте /status.
• Списки правил разрешений перекрываются? — Нет, объединяются. Списочные ключи вроде permissions.allow складываются из всех файлов.

Итоги

Поздравляем — вы дошли до конца курса, и это была длинная дорога. Оглянитесь на неё: вы начинали с выбора тарифа и первого запуска, освоили интерфейс и режимы разрешений, научились управлять контекстом и описывать проект в CLAUDE.md, писать rules и скиллы, делегировать работу подагентам, гарантировать проверки хуками, подключать внешние системы через MCP и расширять инструмент плагинами. Дальше был headless-режим для автоматизации, песочница и обзор безопасности, а последние два урока дали то, без чего всё остальное хрупко, — умение диагностировать собственную конфигурацию.

Вы больше не пользователь, который надеется, что настройки применились. Вы знаете, как проверить, что загрузилось, и как объяснить, почему выиграло именно это определение. Это ровно та разница, которая отделяет случайный успех от воспроизводимого результата.

Куда двигаться дальше — выбирать вам. Попробуйте команды агентов, где несколько подагентов работают над задачей параллельно, и рабочие деревья git для изоляции таких запусков. Если хочется строить собственные инструменты поверх агента, посмотрите в сторону Agent SDK: всё, что вы узнали о контексте, разрешениях и хуках, там применяется напрямую. А если вы отвечаете за команду — самый ценный следующий шаг это корпоративное развёртывание: управляемые настройки, общие плагины и единый набор правил на весь коллектив. Спасибо, что прошли курс до конца, и удачи в работе.