Устранение распространенных проблем

INFO

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

Что вы узнаете

• Быстро определять причины отказа загрузки навыков
• Решать ошибки выполнения скриптов и проблемы с правами доступа
• Понимать принципы ограничений безопасности путей
• Выявлять проблемы семантического сопоставления и загрузки моделей

Навык не найден при запросе

Симптомы

При вызове get_available_skills возвращается No skills found matching your query.

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

1. Навык не установлен в пути обнаружения
2. Ошибка в написании имени навыка
3. Формат SKILL.md не соответствует спецификации

Решения

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

Плагин ищет навыки в следующем порядке приоритета (первое совпадение применяется):

Приоритет	Путь	Тип
1	.opencode/skills/	Уровень проекта (OpenCode)
2	.claude/skills/	Уровень проекта (Claude)
3	~/.config/opencode/skills/	Уровень пользователя (OpenCode)
4	~/.claude/skills/	Уровень пользователя (Claude)
5	~/.claude/plugins/cache/	Кэш плагина
6	~/.claude/plugins/marketplaces/	Установленные плагины

Команды проверки:

# Проверка навыков уровня проекта
ls -la .opencode/skills/
ls -la .claude/skills/

# Проверка навыков уровня пользователя
ls -la ~/.config/opencode/skills/
ls -la ~/.claude/skills/

Проверьте формат SKILL.md:

Директория навыка должна содержать файл SKILL.md, и формат должен соответствовать спецификации Anthropic Skills:

---
name: skill-name
description: Краткое описание навыка
license: MIT
allowed-tools:
  - read
  - write
metadata:
  author: your-name
---

Содержимое навыка...

Обязательные проверки:

• ✅ name должен содержать только строчные буквы, цифры и дефисы (например, git-helper)
• ✅ description не может быть пустым
• ✅ YAML frontmatter должен быть окружен ---
• ✅ Содержимое навыка должно следовать после второго ---

Используйте нечеткое сопоставление:

Плагин предоставляет предложения по исправлению написания. Например:

No skills found matching "git-helper". Did you mean "git-helper-tool"?

Если вы видите подобное сообщение, повторите попытку с предложенным именем.

---

Ошибка "навык не существует"

Симптомы

При вызове use_skill("skill-name") возвращается Skill "skill-name" not found.

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

1. Ошибка в написании имени навыка
2. Навык был переопределен навыком с тем же именем (конфликт приоритетов)
3. В директории навыка отсутствует SKILL.md или формат неверен

Решения

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

Используйте инструмент get_available_skills для отображения всех навыков

Поймите правила переопределения приоритетов:

Если навыки с одинаковым именем существуют в нескольких путях, применяется только навык с наивысшим приоритетом. Например:

• Уровень проекта .opencode/skills/git-helper/ → ✅ применяется
• Уровень пользователя ~/.config/opencode/skills/git-helper/ → ❌ переопределен

Проверка конфликтов имен:

# Поиск всех навыков с одинаковым именем
find .opencode/skills .claude/skills ~/.config/opencode/skills ~/.claude/skills \
  -name "git-helper" -type d

Проверьте наличие SKILL.md:

# Перейдите в директорию навыка
cd .opencode/skills/git-helper/

# Проверьте SKILL.md
ls -la SKILL.md

# Проверьте правильность формата YAML
head -10 SKILL.md

---

Ошибка выполнения скрипта

Симптомы

При вызове run_skill_script возвращается ошибка скрипта или ненулевой код выхода.

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

1. Неправильный путь к скрипту
2. Скрипт не имеет права на выполнение
3. В самом скрипте есть логическая ошибка

Решения

Проверьте, находится ли скрипт в списке scripts навыка:

При загрузке навыка отображается список доступных скриптов:

Skill loaded. Available scripts:
- tools/build.sh
- scripts/setup.js

Если при вызове указан несуществующий скрипт:

Script "build.sh" not found in skill "my-skill". Available scripts: tools/build.sh, scripts/setup.js

Используйте правильный относительный путь:

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

• ✅ Правильно: tools/build.sh
• ❌ Неправильно: /tools/build.sh

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

Плагин выполняет только файлы с битом выполнения (mode & 0o111).

macOS/Linux

# Предоставьте права на выполнение
chmod +x .opencode/skills/my-skill/tools/build.sh

# Проверьте права
ls -la .opencode/skills/my-skill/tools/build.sh
# Вывод должен содержать: -rwxr-xr-x

Windows

# Windows не использует биты разрешений Unix, убедитесь, что расширение файла правильно связано
# Скрипты PowerShell: .ps1
# Скрипты Bash (через Git Bash): .sh

Отладка ошибок выполнения скрипта:

Если скрипт возвращает ошибку, плагин отобразит код выхода и вывод:

Script failed (exit 1): Error: Build failed at /path/to/script.js:42

Ручная отладка:

# Перейдите в директорию навыка
cd .opencode/skills/my-skill/

# Выполните скрипт напрямую для просмотра подробной ошибки
./tools/build.sh

---

Ошибка небезопасного пути

Симптомы

При вызове read_skill_file или run_skill_script возвращается ошибка небезопасного пути.

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

1. Путь содержит .. (выход за пределы директории)
2. Путь является абсолютным
3. Путь содержит некорректные символы

Решения

Поймите правила безопасности путей:

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

Примеры разрешенных путей (относительно директории навыка):

• ✅ docs/guide.md
• ✅ config/settings.json
• ✅ tools/setup.sh

Примеры запрещенных путей:

• ❌ ../../../etc/passwd (выход за пределы директории)
• ❌ /tmp/file.txt (абсолютный путь)
• ❌ ./../other-skill/file.md (выход в другую директорию)

Используйте относительные пути:

Всегда используйте пути относительно директории навыка, не начинайте с / или ../:

# Чтение документации навыка
read_skill_file("my-skill", "docs/guide.md")

# Выполнение скрипта навыка
run_skill_script("my-skill", "tools/build.sh")

Отобразите список доступных файлов:

Если вы не уверены в имени файла, сначала просмотрите список файлов навыка:

После вызова use_skill возвращается:
Available files:
- docs/guide.md
- config/settings.json
- README.md

---

Ошибка загрузки модели Embedding

Симптомы

Функция семантического сопоставления не работает, в логах отображается Model failed to load.

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

1. Проблемы с сетевым подключением (первоначальная загрузка модели)
2. Повреждение файла модели
3. Проблемы с правами доступа к директории кэша

Решения

Проверьте сетевое подключение:

При первом использовании плагину необходимо загрузить модель all-MiniLM-L6-v2 (около 238 МБ) с Hugging Face. Убедитесь, что сеть имеет доступ к Hugging Face.

Очистите и повторно загрузите модель:

Модель кэшируется в ~/.cache/opencode-agent-skills/:

# Удалите директорию кэша
rm -rf ~/.cache/opencode-agent-skills/

# Перезапустите OpenCode, плагин автоматически повторно загрузит модель

Проверьте права доступа к директории кэша:

# Просмотрите директорию кэша
ls -la ~/.cache/opencode-agent-skills/

# Убедитесь, что есть права на чтение и запись
chmod -R 755 ~/.cache/opencode-agent-skills/

Ручная проверка загрузки модели:

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

Просмотрите логи OpenCode, выполните поиск "embedding" или "model"

---

Ошибка парсинга SKILL.md

Симптомы

Директория навыка существует, но не обнаружена плагином, или при загрузке возвращается ошибка формата.

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

1. Ошибка формата YAML frontmatter
2. Отсутствие обязательных полей
3. Значение поля не соответствует правилам валидации

Решения

Проверьте формат YAML:

Структура SKILL.md должна быть следующей:

---
name: my-skill
description: Описание навыка
---

Содержимое навыка...

Распространенные ошибки:

• ❌ Отсутствие разделителей ---
• ❌ Неправильный отступ в YAML (YAML использует отступ в 2 пробела)
• ❌ Отсутствие пробела после двоеточия

Проверьте обязательные поля:

Поле	Тип	Обязательное	Ограничения
name	string	✅	Строчные буквы, цифры, дефисы, не пустое
description	string	✅	Не пустое

Проверьте валидность YAML:

Используйте онлайн-инструменты для проверки формата YAML:

• YAML Lint

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

# Установите yamllint
pip install yamllint

# Проверьте файл
yamllint SKILL.md

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

Содержимое навыка должно следовать после второго ---:

---
name: my-skill
description: Описание навыка
---

Здесь начинается содержимое навыка, которое будет внедрено в контекст AI...

Если содержимое навыка пустое, плагин проигнорирует этот навык.

---

Автоматические рекомендации не работают

Симптомы

После отправки соответствующего сообщения AI не получает подсказки с рекомендацией навыка.

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

1. Сходство ниже порога (по умолчанию 0.35)
2. Описание навыка недостаточно подробное
3. Модель не загружена

Решения

Улучшите качество описания навыка:

Чем конкретнее описание навыка, тем точнее семантическое сопоставление.

❌ Плохое описание	✅ Хорошее описание
"Git инструмент"	"Помогает выполнять операции Git: создание веток, фиксация кода, слияние PR, разрешение конфликтов"
"Тестовая помощь"	"Генерация модульных тестов, запуск тестовых наборов, анализ покрытия тестами, исправление неудачных тестов"

Вызовите навык вручную:

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

Используйте инструмент use_skill("skill-name")

Настройка порога сходства (для продвинутых):

Порог по умолчанию составляет 0.35. Если вы считаете, что рекомендаций слишком мало, вы можете настроить его в исходном коде (src/embeddings.ts:10):

export const SIMILARITY_THRESHOLD = 0.35; // Уменьшение этого значения увеличит количество рекомендаций

WARNING

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

---

Навык перестает работать после сжатия контекста

Симптомы

После длительного разговора AI как будто "забывает" загруженные навыки.

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

1. Версия плагина ниже v0.1.0
2. Инициализация сессии не завершена

Решения

Проверьте версию плагина:

Функция восстановления после сжатия поддерживается в версии v0.1.0 и выше. Если плагин установлен через npm, проверьте версию:

# Просмотрите package.json в директории плагина OpenCode
cat ~/.config/opencode/plugins/opencode-agent-skills/package.json | grep version

Подтвердите завершение инициализации сессии:

Плагин внедряет список навыков при первом сообщении. Если инициализация сессии не завершена, восстановление после сжатия может не работать.

Симптомы:

• После первого сообщения не отображается список навыков
• AI не знает о доступных навыках

Перезапустите сессию:

Если проблема сохраняется, удалите текущую сессию и создайте новую:

Удалите сессию в OpenCode и начните новый разговор

---

Ошибка рекурсивного поиска скриптов

Симптомы

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

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

1. Глубина рекурсии превышает 10 уровней
2. Скрипт находится в скрытой директории (начинается с .)
3. Скрипт находится в директории зависимостей (например, node_modules)

Решения

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

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

• Максимальная глубина: 10 уровней
• Пропускает скрытые директории (имена начинаются с .): .git, .vscode и т.д.
• Пропускает директории зависимостей: node_modules, __pycache__, vendor, .venv, venv, .tox, .nox

Настройте расположение скриптов:

Если скрипт находится в глубокой директории, вы можете:

• Переместить его в более мелкую директорию (например, tools/ вместо src/lib/utils/tools/)
• Использовать символическую ссылку на расположение скрипта (Unix системы)

# Создайте символическую ссылку
ln -s ../../../scripts/build.sh tools/build.sh

Отобразите обнаруженные скрипты:

После загрузки навыка плагин возвращает список скриптов. Если скрипт отсутствует в списке, проверьте:

1. Есть ли у файла права на выполнение
2. Соответствует ли директория правилам пропуска

---

Резюме урока

Этот урок охватывает 9 категорий распространенных проблем при использовании плагина OpenCode Agent Skills:

Тип проблемы	Ключевые проверки
Навык не найден при запросе	Путь обнаружения, формат SKILL.md, написание
Навык не существует	Правильность имени, переопределение приоритетов, наличие файла
Ошибка выполнения скрипта	Путь к скрипту, права на выполнение, логика скрипта
Небезопасный путь	Относительный путь, без .., без абсолютного пути
Ошибка загрузки модели	Сетевое подключение, очистка кэша, права директории
Ошибка парсинга	Формат YAML, обязательные поля, содержимое навыка
Автоматические рекомендации не работают	Качество описания, порог сходства, ручной вызов
Навык перестает работать после сжатия	Версия плагина, инициализация сессии
Ошибка рекурсивного поиска скриптов	Ограничение глубины, правила пропуска директорий, права на выполнение

---

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

В следующем уроке мы изучим Рекомендации по безопасности.

Вы узнаете:

• Дизайн механизмов безопасности плагина
• Как писать безопасные навыки
• Принципы валидации путей и контроля прав доступа
• Лучшие практики безопасности

---

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

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

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

Функция	Путь к файлу	Номера строк
Нечеткое сопоставление навыков и предложения	src/tools.ts	49-59
Обработка ошибки "навык не существует"	src/tools.ts	89-97
Обработка ошибки "скрипт не существует"	src/tools.ts	167-177
Обработка ошибки выполнения скрипта	src/tools.ts	184-195
Проверка безопасности пути	src/utils.ts	130-133
Обработка ошибки парсинга SKILL.md	src/skills.ts	127-152
Ошибка загрузки модели	src/embeddings.ts	38-40
Алгоритм нечеткого сопоставления	src/utils.ts	88-125

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

• SIMILARITY_THRESHOLD = 0.35 (порог сходства): src/embeddings.ts:10
• TOP_K = 5 (количество возвращаемых наиболее похожих навыков): src/embeddings.ts:11

Другие важные значения:

• maxDepth = 10 (максимальная глубина рекурсии скриптов, параметр по умолчанию функции findScripts): src/skills.ts:59
• 0.4 (порог нечеткого сопоставления, условие возврата функции findClosestMatch): src/utils.ts:124

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

• findClosestMatch(): Алгоритм нечеткого сопоставления, используется для генерации предложений по исправлению написания
• isPathSafe(): Проверка безопасности пути, предотвращает выход за пределы директории
• ensureModel(): Обеспечивает загрузку модели embedding
• parseSkillFile(): Парсинг SKILL.md и проверка формата