Загрузка навыков в контекст сессии

Что вы сможете делать после изучения

Использовать инструмент use_skill для загрузки навыков в текущую сессию
Понимать, как содержимое навыков внедряется в контекст в формате XML
Освоить механизм Synthetic Message Injection (внедрение synthetic-сообщений)
Понимать структуру метаданных навыков (источник, каталог, скрипты, файлы)
Знать, как навыки остаются доступными после сжатия сессии

Ваша текущая проблема

Вы создали навык, но ИИ кажется не имеет доступа к его содержимому. Или в длинном диалоге руководство навыка вдруг исчезает, ИИ забывает предыдущие правила. Все это связано с механизмом загрузки навыков.

Когда использовать этот подход

Ручная загрузка навыков: когда автоматические рекомендации ИИ не подходят, напрямую укажите нужный навык
Поддержка длинных сессий: обеспечьте доступность содержимого навыков даже после сжатия контекста
Совместимость с Claude Code: загружайте навыки в формате Claude, получайте сопоставление инструментов
Точный контроль: необходимость загрузки конкретной версии навыка (через пространство имен)

Основная концепция

Инструмент use_skill внедряет содержимое SKILL.md навыка в контекст сессии, позволяя ИИ следовать правилам и рабочим процессам, определенным в навыке.

XML-внедрение содержимого

Содержимое навыка внедряется в структурированном XML-формате, содержащем три части:

xml

<skill name="skill-name">
  <metadata>
    <source>метка источника навыка</source>
    <directory>путь к каталогу навыка</directory>
    <scripts>
      <script>tools/script1.sh</script>
    </scripts>
    <files>
      <file>docs/guide.md</file>
    </files>
  </metadata>

  <tool-mapping>
    <!-- Сопоставление инструментов Claude Code -->
  </tool-mapping>

  <content>
    Полное содержимое SKILL.md
  </content>
</skill>

Synthetic Message Injection

Плагин использует метод session.prompt() из OpenCode SDK для внедрения содержимого навыков, устанавливая два ключевых флага:

Synthetic Message Injection

noReply: true — ИИ не отвечает на само внедрение
synthetic: true — помечает сообщение как системно-сгенерированное (скрыто от пользователя, не учитывается в пользовательском вводе)

Это означает:

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

Жизненный цикл сессии

При первом сообщении: плагин автоматически внедряет список <available-skills>, показывая все доступные навыки
При использовании use_skill: XML-содержимое выбранного навыка внедряется в контекст
После сжатия сессии: плагин слушает событие session.compacted и повторно внедряет список навыков

Следуйте за мной

Шаг 1: Загрузка базового навыка

В OpenCode попросите ИИ загрузить навык:

Пользовательский ввод:
Загрузи навык brainstorming

Ответ системы:
Skill "brainstorming" loaded.

Вы должны увидеть: ИИ возвращает подтверждение успешной загрузки, содержимое навыка уже внедрено в контекст.

Теперь вы можете протестировать, следует ли ИИ правилам навыка:

Пользовательский ввод:
Помоги написать описание продукта

Ответ системы:
(ИИ сгенерирует контент, следуя правилам навыка brainstorming, используя техники и процессы, определенные в нем)

Шаг 2: Просмотр доступных ресурсов после загрузки

При загрузке навыка система возвращает список доступных скриптов и файлов:

Пользовательский ввод:
Загрузи git-helper

Ответ системы:
Skill "git-helper" loaded.
Available scripts: tools/branch.sh, tools/commit.sh
Available files: docs/usage.md, examples/workflow.md

Эта информация сообщает вам, какие ресурсы доступны в каталоге навыка:

Скрипты: можно выполнить с помощью инструмента run_skill_script
Файлы: можно прочитать с помощью инструмента read_skill_file

Вы должны увидеть: сообщение об успешной загрузке, за которым следует список доступных скриптов и файлов (если есть).

Шаг 3: Загрузка навыков с одинаковыми именами с помощью пространства имен

Предположим, на уровне проекта и пользователя есть навык build-helper:

Пользовательский ввод:
Загрузи build-helper

Ответ системы:
Skill "build-helper" loaded.
Available scripts: build.sh, optimize.sh

Пользовательский ввод:
(проверь, какую версию build-helper загрузили)

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

Пользовательский ввод:
Загрузи user:build-helper

Ответ системы:
Skill "build-helper" loaded.
Available scripts: ci.sh, test.sh
Available files: README.md

Вы должны увидеть: загрузку навыка из разных источников с помощью формата namespace:skill-name.

Шаг 4: Оценка эффекта руководства навыка

После загрузки навыка поведение ИИ должно соответствовать правилам, определенным в навыке. Возьмем навык brainstorming:

Пользовательский ввод:
Загрузи brainstorming
Помоги придумать ключевые преимущества продукта для умного дома

Ответ системы:
(ИИ будет использовать техники, определенные в навыке brainstorming, такие как:
- Сначала перечислить возможные направления, затем углубиться
- Избегать преждевременной оценки идей
- Использовать "да, и..." для расширения мыслей
- Записать все идеи перед отбором)

Давайте сначала перечислим возможные направления:
1. Удобство управления
2. Энергоэффективность
3. Безопасность
...

Вы должны увидеть: стиль и процесс ответов ИИ, соответствующие определенным в навыке.

Шаг 5: Понимание постоянства навыков в длинных сессиях

Проведите длительный диалог, наблюдая, остается ли навык эффективным:

Пользовательский ввод:
Загрузи docker-helper
(проведите многораундовый диалог, касающийся сборки, развертывания и т.д.)
...
(предположим, диалог очень длинный, что привело к сжатию контекста в OpenCode)
Пользовательский ввод:
Продолжи предыдущее развертывание Docker

Ответ системы:
(ИИ по-прежнему может получить доступ к содержимому docker-helper,
потому что плагин повторно внедряет список навыков после сжатия)

Механизм восстановления после сжатия

Плагин слушает событие session.compacted и повторно внедряет список навыков при сжатии сессии, обеспечивая доступ к уже загруженным навыкам после сжатия.

Вы должны увидеть: даже если диалог очень длинный и контекст сжат, ИИ по-прежнему может получить доступ к содержимому навыков.

Шаг 6: Загрузка навыков в формате Claude Code

Если у вас есть навыки Claude Code, они будут автоматически обнаружены:

Пользовательский ввод:
Перечисли все доступные навыки

Ответ системы:
...
claude-code-superpowers (claude-plugins)
  Полный рабочий процесс разработки программного обеспечения

Пользовательский ввод:
Загрузи claude-code-superpowers

Ответ системы:
Skill "claude-code-superpowers" loaded.

При загрузке навыков в формате Claude автоматически внедряется сопоставление инструментов (toolTranslation), сопоставляя названия инструментов Claude с инструментами OpenCode:

Пример сопоставления инструментов

TodoWrite Claude → todowrite OpenCode
Task Claude → task (подагент) OpenCode
Bash Claude → bash OpenCode

Вы должны увидеть: успешную загрузку навыка, ИИ может понять и использовать рабочие процессы в формате Claude.

Контрольные точки ✅

[ ] Можете ли вы использовать use_skill для загрузки навыков?
[ ] Можете ли вы понять механизм внедрения содержимого навыков в формате XML?
[ ] Можете ли вы назвать два ключевых флага synthetic-сообщений?
[ ] Можете ли вы объяснить, почему навыки остаются доступными после сжатия сессии?
[ ] Можете ли вы использовать пространства имен для загрузки разных версий навыков с одинаковыми именами?

Предупреждения о подводных камнях

Ловушка 1: Ошибка в написании названия навыка

Если введено неверное название навыка:

Пользовательский ввод:
Загрузи brainstormig

Ответ системы:
Skill "brainstormig" not found. Did you mean "brainstorming"?

Плагин предоставляет предложения на основе расстояния редактирования.

Решение: проверьте правописание или используйте get_available_skills для просмотра правильных названий.

Ловушка 2: Путаница с навыками с одинаковыми именами

Если на уровне проекта и пользователя есть навыки с одинаковыми именами, вы можете загрузить не ту версию:

Пользовательский ввод:
Загрузи build-helper

Ответ системы:
Skill "build-helper" loaded.
Available scripts: build.sh, optimize.sh  # это уровень проекта

Ожидалась загрузка пользовательской версии, но по умолчанию загружается проектная

Решение: используйте пространство имен для явного указания, например user:build-helper.

Ловушка 3: Содержимое навыка не применяется

Иногда вы загружаете навык, но ИИ кажется не следует правилам:

Пользовательский ввод:
Загрузи my-conventions
(ожидание следования кодовым соглашениям)
Пользовательский ввод:
Напиши функцию

Ответ системы:
(ИИ пишет код, не соответствующий ожидаемым соглашениям)

Возможные причины:

Содержимое SKILL.md недостаточно четкое
Описание навыка недостаточно подробное, ИИ неправильно понимает
В длинном диалоге контекст сжат, список навыков нуждается в повторном внедрении

Решение:

Проверьте, четкие ли frontmatter и содержимое навыка
Явно скажите ИИ использовать конкретные правила: "Пожалуйста, используй правила из навыка my-conventions"
Перезагрузите навык после сжатия

Ловушка 4: Проблемы сопоставления инструментов навыков Claude

После загрузки навыка Claude Code ИИ может по-прежнему использовать неверные названия инструментов:

Пользовательский ввод:
Загрузи claude-code-superpowers
Используй инструмент TodoWrite

Ответ системы:
(ИИ может попытаться использовать неверное название инструмента, потому что сопоставление не сработало правильно)

Причина: при загрузке навыка сопоставление инструментов внедряется автоматически, но ИИ может нуждаться в явном указании.

Решение: после загрузки навыка явно скажите ИИ использовать сопоставленные инструменты:

Пользовательский ввод:
Загрузи claude-code-superpowers
Обрати внимание, используй инструмент todowrite (вместо TodoWrite)

Резюме урока

Инструмент use_skill внедряет содержимое навыков в формате XML в контекст сессии, используя механизм Synthetic Message Injection:

Структурированное XML-внедрение: содержит метаданные, сопоставление инструментов и содержимое навыка
Synthetic-сообщения: флаги noReply: true и synthetic: true гарантируют, что сообщения скрыты от пользователя
Постоянная доступность: содержимое навыков остается доступным даже после сжатия контекста
Поддержка пространств имен: формат namespace:skill-name для точного указания источника навыка
Совместимость с Claude: автоматическое внедрение сопоставления инструментов, поддержка навыков Claude Code

Загрузка навыков — это ключевой механизм, позволяющий ИИ следовать определенным рабочим процессам и правилам. Через внедрение содержимого ИИ может поддерживать согласованный стиль поведения на протяжении всего диалога.

Анонс следующего урока

Следующий урок: Автоматическая рекомендация навыков: принципы семантического сопоставления.
Вы узнаете:
Как плагин автоматически рекомендует релевантные навыки на основе семантического сходства
Основные принципы работы embedding-моделей и вычисления косинусного сходства
Техники оптимизации описаний навыков для улучшения рекомендаций
Как механизм кэширования embeddings повышает производительность

Приложение: Справочник по исходному коду

Нажмите, чтобы развернуть расположение исходного кода

Обновлено: 2026-01-24

Функциональность	Путь к файлу	Строки
Определение инструмента UseSkill	`src/tools.ts`	200-267
Функция injectSyntheticContent	`src/utils.ts`	147-162
Функция injectSkillsList	`src/skills.ts`	345-370
Функция resolveSkill	`src/skills.ts`	269-283
Функция listSkillFiles	`src/skills.ts`	289-316

Ключевые константы:

Нет

Ключевые функции:

UseSkill(): принимает параметр skill, формирует содержимое навыка в формате XML и внедряет в сессию
injectSyntheticContent(client, sessionID, text, context): внедряет synthetic-сообщение через client.session.prompt(), устанавливая noReply: true и synthetic: true
injectSkillsList(): внедряет список <available-skills> при первом сообщении
resolveSkill(skillName: string, skillsByName: Map<string, Skill>): поддерживает разбор навыков в формате namespace:skill-name
listSkillFiles(skillPath: string, maxDepth: number): рекурсивно перечисляет все файлы в каталоге навыка (исключая SKILL.md)

Бизнес-правила:

Содержимое навыка внедряется в формате XML, содержит метаданные, сопоставление инструментов и содержимое (tools.ts:238-249)
Внедряемое сообщение помечается как synthetic, не учитывается в пользовательском вводе (utils.ts:159)
Уже загруженные навыки не рекомендуются повторно в текущей сессии (plugin.ts:128-132)
Список навыков автоматически внедряется при первом сообщении (plugin.ts:70-105)
После сжатия сессии список навыков повторно внедряется (plugin.ts:145-151)

Формат XML-содержимого:

xml

<skill name="${skill.name}">
  <metadata>
    <source>${skill.label}</source>
    <directory>${skill.path}</directory>
    <scripts>
      <script>${script.relativePath}</script>
    </scripts>
    <files>
      <file>${file}</file>
    </files>
  </metadata>

  ${toolTranslation}

  <content>
  ${skill.template}
  </content>
</skill>

Загрузка навыков в контекст сессии ​

Что вы сможете делать после изучения ​

Ваша текущая проблема ​

Когда использовать этот подход ​

Основная концепция ​

XML-внедрение содержимого ​

Synthetic Message Injection ​

Жизненный цикл сессии ​

Следуйте за мной ​

Шаг 1: Загрузка базового навыка ​

Шаг 2: Просмотр доступных ресурсов после загрузки ​

Шаг 3: Загрузка навыков с одинаковыми именами с помощью пространства имен ​

Шаг 4: Оценка эффекта руководства навыка ​

Шаг 5: Понимание постоянства навыков в длинных сессиях ​

Шаг 6: Загрузка навыков в формате Claude Code ​

Контрольные точки ✅ ​

Предупреждения о подводных камнях ​

Ловушка 1: Ошибка в написании названия навыка ​

Ловушка 2: Путаница с навыками с одинаковыми именами ​

Ловушка 3: Содержимое навыка не применяется ​

Ловушка 4: Проблемы сопоставления инструментов навыков Claude ​

Резюме урока ​

Анонс следующего урока ​

Приложение: Справочник по исходному коду ​

Загрузка навыков в контекст сессии

Что вы сможете делать после изучения

Ваша текущая проблема

Когда использовать этот подход

Основная концепция

XML-внедрение содержимого

Synthetic Message Injection

Жизненный цикл сессии

Следуйте за мной

Шаг 1: Загрузка базового навыка

Шаг 2: Просмотр доступных ресурсов после загрузки

Шаг 3: Загрузка навыков с одинаковыми именами с помощью пространства имен

Шаг 4: Оценка эффекта руководства навыка

Шаг 5: Понимание постоянства навыков в длинных сессиях

Шаг 6: Загрузка навыков в формате Claude Code

Контрольные точки ✅

Предупреждения о подводных камнях

Ловушка 1: Ошибка в написании названия навыка

Ловушка 2: Путаница с навыками с одинаковыми именами

Ловушка 3: Содержимое навыка не применяется

Ловушка 4: Проблемы сопоставления инструментов навыков Claude

Резюме урока

Анонс следующего урока

Приложение: Справочник по исходному коду