Чтение файлов навыков

Чему вы научитесь

• Использовать инструмент read_skill_file для чтения документации, конфигураций и примеров из каталога навыка
• Понимать механизм безопасности путей для предотвращения атак обхода каталогов
• Освоить метод внедрения содержимого файлов в формате XML
• Обрабатывать ошибки при отсутствии файла и получать список доступных файлов

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

SKILL.md навыка содержит только основные инструкции, но многие навыки предоставляют сопроводительную документацию, примеры конфигураций, руководства по использованию и другие вспомогательные файлы. Вы хотите получить доступ к этим файлам для более подробных инструкций, но не знаете, как безопасно читать файлы из каталога навыка.

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

• Просмотр подробной документации: В каталоге docs/ навыка есть подробные руководства по использованию
• Примеры конфигураций: Необходимо сослаться на примеры конфигурационных файлов в каталоге config/
• Примеры кода: Каталог examples/ навыка содержит примеры кода
• Помощь в отладке: Просмотр README или других объясняющих файлов навыка
• Изучение структуры ресурсов: Исследование, какие файлы доступны в каталоге навыка

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

Инструмент read_skill_file позволяет вам безопасно получать доступ к вспомогательным файлам в каталоге навыка. Он обеспечивает безопасность и удобство использования через следующие механизмы:

Механизм безопасности

Плагин строго проверяет путь к файлу для предотвращения атак обхода каталогов:

• Запрещено использование .. для доступа к файлам вне каталога навыка
• Запрещено использование абсолютных путей
• Разрешен доступ только к файлам в каталоге навыка и его подкаталогах

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

1. Проверка существования имени навыка (с поддержкой пространств имен)
2. Проверка безопасности запрашиваемого пути к файлу
3. Чтение содержимого файла
4. Обертывание в формат XML и внедрение в контекст сеанса
5. Возврат подтверждающего сообщения об успешной загрузке

Сохранение содержимого файла

Содержимое файла внедряется с помощью флагов synthetic: true и noReply: true, что означает:

• Содержимое файла становится частью контекста сеанса
• Содержимое остается доступным даже после сжатия сеанса
• Внедрение не вызывает немедленного ответа ИИ

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

Шаг 1: Чтение документации навыка

Предположим, в каталоге навыка есть подробная документация:

Пользовательский ввод:
Прочитать документацию git-helper

Системный вызов:
read_skill_file(skill="git-helper", filename="docs/usage-guide.md")

Системный ответ:
File "docs/usage-guide.md" from skill "git-helper" loaded.

Содержимое файла внедряется в контекст сеанса в формате XML:

<skill-file skill="git-helper" file="docs/usage-guide.md">
  <metadata>
    <directory>/path/to/project/.opencode/skills/git-helper</directory>
  </metadata>

  <content>
# Git Helper使用指南

本技能提供 Git 分支管理、提交规范和协作流程的指导...

[文档内容继续]
  </content>
</skill-file>

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

Шаг 2: Чтение примеров конфигурации

Просмотр примеров конфигурации навыка:

Пользовательский ввод:
Показать примеры конфигурации docker-helper

Системный вызов:
read_skill_file(skill="docker-helper", filename="config/docker-compose.yml.example")

Системный ответ:
File "config/docker-compose.yml.example" from skill "docker-helper" loaded.

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

Шаг 3: Использование пространства имен для чтения файлов

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

Пользовательский ввод:
Читать сценарий сборки project:build-helper

Системный вызов:
read_skill_file(skill="project:build-helper", filename="scripts/build.sh")

Системный ответ:
File "scripts/build.sh" from skill "build-helper" loaded.

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

Шаг 4: Обработка случая, когда файл не существует

Если вы пытаетесь прочитать несуществующий файл:

Пользовательский ввод:
Прочитать api-docs.md git-helper

Системный вызов:
read_skill_file(skill="git-helper", filename="api-docs.md")

Системный ответ:
File "api-docs.md" not found. Available files: docs/usage-guide.md, examples/branch-flow.md, README.md, SKILL.md

Инструмент перечислит все доступные файлы в каталоге навыка, чтобы помочь вам найти правильное имя файла.

Вы должны увидеть: Сообщение об ошибке и список доступных файлов.

Шаг 5: Опыт защиты безопасности пути

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

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

Системный вызов:
read_skill_file(skill="git-helper", filename="../secrets.txt")

Системный ответ:
Invalid path: cannot access files outside skill directory.

Инструмент отклонит любую попытку получить доступ к файлам вне каталога навыка.

Вы должны увидеть: Сообщение об ошибке безопасности пути.

Контрольная точка ✅

• [ ] Можете ли вы использовать read_skill_file для чтения файлов навыка?
• [ ] Понимаете ли вы роль механизма безопасности пути?
• [ ] Можете ли вы определить формат XML внедрения содержимого файла?
• [ ] Можете ли вы найти список доступных файлов из сообщения об ошибке?
• [ ] Можете ли вы использовать пространство имен для точного определения навыка?

Предупреждения о ловушках

Ловушка 1: Ошибка пути к файлу

Если вы забыли, что файл находится в подкаталоге:

Пользовательский ввод:
Прочитать usage-guide.md git-helper

Системный ответ:
File "usage-guide.md" not found. Available files: docs/usage-guide.md, examples/branch-flow.md, README.md

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

Решение: Используйте полный путь, например docs/usage-guide.md.

Ловушка 2: Игнорирование конфликтов пространств имен

Когда навыки с одинаковым именем существуют в нескольких пространствах имен:

Пользовательский ввод:
Прочитать README build-helper

Системный ответ:
File "README.md" from skill "build-helper" loaded.

Вы можете прочитать навык уровня проекта, но ожидаете навык уровня пользователя.

Решение: Используйте пространство имен для четкого указания, например read_skill_file(skill="user:build-helper", filename="README.md").

Ловушка 3: Попытка обхода пути

Попробуйте использовать .. для доступа к вышестоящему каталогу:

Пользовательский ввод:
Читать файлы вне каталога навыка

Системный вызов:
read_skill_file(skill="my-skill", filename="../../../etc/passwd")

Системный ответ:
Invalid path: cannot access files outside skill directory.

Причина: Это ограничение безопасности для предотвращения атак обхода каталогов.

Решение: Можно получать доступ только к файлам внутри каталога навыка. Если нужны другие файлы, попросите ИИ использовать инструмент Read напрямую.

Ловушка 4: Файл уже существует в контексте сеанса

Если вы уже загрузили навык, содержимое файла может находиться в SKILL.md навыка или другом внедренном содержимом:

Пользовательский ввод:
Читать основную документацию навыка

Системный вызов:
read_skill_file(skill="my-skill", filename="core-guide.md")

Но это может быть ненужным, так как основное содержимое обычно находится в SKILL.md.

Решение: Сначала проверьте содержимое загруженного навыка, чтобы определить, нужны ли дополнительные файлы.

Резюме урока

Инструмент read_skill_file позволяет вам безопасно получать доступ к вспомогательным файлам в каталоге навыка:

• Проверка безопасности пути: Предотвращает обход каталогов, разрешает доступ только к файлам внутри каталога навыка
• Механизм внедрения XML: Содержимое файла обертывается тегом XML <skill-file>, включая метаданные
• Дружественные ошибки: При отсутствии файла перечисляет доступные файлы, помогая найти правильный путь
• Поддержка пространств имен: Можно точно定位 навыки с одинаковыми именами с помощью namespace:skill-name
• Сохранение контекста: Через флаг synthetic: true содержимое файла остается доступным после сжатия сеанса

Этот инструмент идеально подходит для чтения:

• Подробной документации (каталог docs/)
• Примеров конфигураций (каталог config/)
• Примеров кода (каталог examples/)
• README и объясняющих файлов
• Сценариев исходного кода (если необходимо просмотреть реализацию)

Предпросмотр следующего урока

В следующем уроке мы изучим Совместимость навыков Claude Code.

Вы узнаете:

• Как плагин совместим с системами навыков и плагинов Claude Code
• Понимание механизма отображения инструментов (преобразование инструментов Claude Code в инструменты OpenCode)
• Методы обнаружения навыков из места установки Claude Code

---

Приложение: Ссылка на исходный код

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

Время обновления: 2026-01-24

Функция	Путь к файлу	Строки
Определение инструмента ReadSkillFile	src/tools.ts	74-135
Проверка безопасности пути	src/utils.ts	130-133
Список файлов навыка	src/skills.ts	289-316
Функция resolveSkill	src/skills.ts	269-283
Функция injectSyntheticContent	src/utils.ts	147-162

Ключевые типы:

• Skill: Интерфейс метаданных навыка (skills.ts:43-52)
• OpencodeClient: Тип клиента OpenCode SDK (utils.ts:140)
• SessionContext: Контекст сеанса, содержащий информацию о модели и агенте (utils.ts:142-145)

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

• ReadSkillFile(directory: string, client: OpencodeClient): Возвращает определение инструмента, обрабатывает чтение файлов навыка
• isPathSafe(basePath: string, requestedPath: string): boolean: Проверяет, находится ли путь в базовом каталоге, предотвращает обход каталогов
• listSkillFiles(skillPath: string, maxDepth: number = 3): Promise<string[]>: Перечисляет все файлы в каталоге навыка (исключая SKILL.md)
• resolveSkill(skillName: string, skillsByName: Map<string, Skill>): Skill | null: Поддерживает разрешение навыка в формате namespace:skill-name
• injectSyntheticContent(client, sessionID, text, context): Внедряет содержимое в сеанс через noReply: true и synthetic: true

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

• Проверка безопасности пути использует path.resolve() для проверки, чтобы убедиться, что разрешенный путь начинается с базового каталога (utils.ts:131-132)
• При отсутствии файла пытается использовать fs.readdir() для перечисления доступных файлов, предоставляя дружественное сообщение об ошибке (tools.ts:126-131)
• Содержимое файла обертывается в формате XML, включая атрибуты skill, file и теги <metadata>, <content> (tools.ts:111-119)
• При внедрении получает текущий контекст модели и агента сеанса, чтобы обеспечить внедрение содержимого в правильный контекст (tools.ts:121-122)

Механизм безопасности:

• Защита от обхода каталогов: isPathSafe() проверяет, находится ли путь в базовом каталоге (utils.ts:130-133)
• При отсутствии навыка предоставляет предложения на основе нечеткого сопоставления (tools.ts:90-95)
• При отсутствии файла перечисляет доступные файлы, помогая пользователю найти правильный путь (tools.ts:126-131)