Устранение неполадок: решение распространённых проблем OpenSkills

Что вы научитесь делать

Быстро диагностировать и исправлять распространённые проблемы при использовании OpenSkills
Понимать причины возникновения сообщений об ошибках
Освоить техники поиска неисправностей, связанных с Git-клонированием, правами доступа и форматами файлов
Знать, когда необходимо переустановить навык

Ваша текущая ситуация

При использовании OpenSkills возникает ошибка, и вы не знаете, что делать:

Error: No SKILL.md files found in repository

Или клонирование Git не удалось, ошибка прав доступа, неправильный формат файла... Все эти проблемы могут привести к тому, что навыки не будут работать должным образом.

Когда нужно читать этот туториал

Когда вы столкнётесь со следующими ситуациями:

Ошибка установки: ошибка при установке из GitHub или локального пути
Ошибка чтения: openskills read сообщает, что навык не найден
Ошибка синхронизации: openskills sync сообщает об отсутствии навыков или ошибке формата файла
Ошибка обновления: openskills update пропускает некоторые навыки
Ошибка прав доступа: сообщение об ограниченном доступе к пути или ошибке безопасности

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

Ошибки OpenSkills в основном делятся на 4 категории:

Тип ошибки	Распространённые причины	Подход к решению
Связанные с Git	Проблемы с сетью, конфигурация SSH, несуществующий репозиторий	Проверить сеть, настроить учётные данные Git, проверить адрес репозитория
Связанные с файлами	Отсутствие SKILL.md, ошибка формата, ошибка пути	Проверить существование файла, проверить формат YAML
Связанные с правами	Права доступа к каталогу, обход пути, символические ссылки	Проверить права доступа к каталогу, проверить путь установки
Связанные с метаданными	Потеря метаданных при обновлении, изменение исходного пути	Переустановить навык для восстановления метаданных

Техники поиска неисправностей:

Смотрите сообщение об ошибке: красный вывод обычно содержит конкретную причину
Смотрите жёлтые подсказки: обычно это предупреждения и советы, например Tip: For private repos...
Проверьте структуру каталогов: используйте openskills list для просмотра установленных навыков
Просмотрите расположение исходного кода: сообщения об ошибках перечисляют пути поиска (4 каталога)

Ошибка установки

Проблема 1: Ошибка клонирования Git

Сообщение об ошибке:

Failed to clone repository
fatal: repository '...' not found
Tip: For private repos, ensure git SSH keys or credentials are configured

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

Причина	Сценарий
Репозиторий не существует	Неправильно написан owner/repo
Приватный репозиторий	SSH key или учётные данные Git не настроены
Проблема с сетью	Нет доступа к GitHub

Решение:

Проверьте адрес репозитория:

bash

# Посетите URL репозитория в браузере
https://github.com/owner/repo

Проверьте конфигурацию Git (для приватных репозиториев):

bash

# Проверьте конфигурацию SSH
ssh -T [email protected]

# Настройте учётные данные Git
git config --global credential.helper store

Тест клонирования:

bash

git clone https://github.com/owner/repo.git

Вы должны увидеть:

Репозиторий успешно клонирован в локальный каталог

Проблема 2: SKILL.md не найден

Сообщение об ошибке:

Error: No SKILL.md files found in repository
Error: No valid SKILL.md files found

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

Причина	Описание
В репозитории нет SKILL.md	Это не репозиторий навыков
SKILL.md без frontmatter	Отсутствуют метаданные YAML
Неправильный формат SKILL.md	Ошибка синтаксиса YAML

Решение:

Проверьте структуру репозитория:

bash

# Просмотрите корневой каталог
ls -la

# Найдите SKILL.md
find . -name "SKILL.md"

Проверьте формат SKILL.md:
markdown
```
---
name: Название навыка
description: Описание навыка
---

Содержание навыка...
```
Обязательно:
- YAML frontmatter в разделителях ---
- Поля name и description

Посмотрите официальный пример:

bash

git clone https://github.com/anthropics/skills.git
cd skills
ls -la

Вы должны увидеть:

В репозитории один или несколько файлов SKILL.md
Каждый SKILL.md начинается с YAML frontmatter

Проблема 3: Путь не существует или не является каталогом

Сообщение об ошибке:

Error: Path does not exist: /path/to/skill
Error: Path must be a directory

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

Причина	Описание
Ошибка в пути	Введён неверный путь
Путь указывает на файл	Должен быть каталог, а не файл
Путь не развёрнут	При использовании `~` необходимо разворачивать

Решение:

Проверьте существование пути:

bash

# Проверьте путь
ls -la /path/to/skill

# Проверьте, является ли каталогом
file /path/to/skill

Используйте абсолютный путь:

bash

# Получите абсолютный путь
realpath /path/to/skill

# Используйте при установке
openskills install /absolute/path/to/skill

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

bash

# В каталоге проекта
openskills install ./skills/my-skill

Вы должны увидеть:

Путь существует и является каталогом
В каталоге есть файл SKILL.md

Проблема 4: Недействительный SKILL.md

Сообщение об ошибке:

Error: Invalid SKILL.md (missing YAML frontmatter)

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

Причина	Описание
Отсутствуют обязательные поля	Обязательны `name` и `description`
Ошибка синтаксиса YAML	Проблемы с форматированием двоеточий, кавычек и т.д.

Решение:

Проверьте YAML frontmatter:

markdown

---              ← Начальный разделитель
name: my-skill   ← Обязательно
description: Описание навыка  ← Обязательно
---              ← Конечный разделитель

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

Посмотрите официальный пример:

bash

openskills install anthropics/skills
cat .claude/skills/*/SKILL.md | head -20

Вы должны увидеть:

SKILL.md начинается с правильного YAML frontmatter
Содержит поля name и description

Проблема 5: Ошибка безопасности обхода пути

Сообщение об ошибке:

Security error: Installation path outside target directory

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

Причина	Описание
В названии навыка есть `..`	Попытка доступа к пути за пределами целевого каталога
Символическая ссылка указывает наружу	symlink указывает за пределы целевого каталога
Вредоносный навык	Навык пытается обойти ограничения безопасности

Решение:

Проверьте название навыка:
- Убедитесь, что название навыка не содержит .., / и других спецсимволов

Проверьте символические ссылки:

bash

# Просмотрите символические ссылки в каталоге навыков
find .claude/skills/skill-name -type l

# Просмотрите цель символической ссылки
ls -la .claude/skills/skill-name

Используйте безопасные навыки:
- Устанавливайте навыки только из доверенных источников
- Просматривайте код навыка перед установкой

Вы должны увидеть:

Название навыка содержит только буквы, цифры, дефисы
Отсутствуют символические ссылки, указывающие наружу

Ошибка чтения

Проблема 6: Навык не найден

Сообщение об ошибке:

Error: Skill(s) not found: my-skill

Searched:
  .agent/skills/ (project universal)
  ~/.agent/skills/ (global universal)
  .claude/skills/ (project)
  ~/.claude/skills/ (global)

Install skills: npx openskills install owner/repo

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

Причина	Описание
Навык не установлен	Этот навык не установлен ни в одном из каталогов
Ошибка в названии навыка	Название не совпадает
Установлен в другом месте	Навык установлен в нестандартный каталог

Решение:

Просмотрите установленные навыки:
bash
```
openskills list
```
Проверьте название навыка:
- Сравните с выводом openskills list
- Убедитесь в точном совпадении названия (с учётом регистра)
Установите отсутствующий навык:
bash
```
openskills install owner/repo
```

Поиск во всех каталогах:

bash

# Проверьте 4 каталога навыков
ls -la .agent/skills/
ls -la ~/.agent/skills/
ls -la .claude/skills/
ls -la ~/.claude/skills/

Вы должны увидеть:

openskills list показывает целевой навык
Навык существует в одном из 4 каталогов

Проблема 7: Название навыка не указано

Сообщение об ошибке:

Error: No skill names provided

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

Причина	Описание
Забыли передать параметр	После `openskills read` нет параметров
Пустая строка	Передана пустая строка

Решение:

Укажите название навыка:

bash

# Один навык
openskills read my-skill

# Несколько навыков (через запятую)
openskills read skill1,skill2,skill3

Сначала просмотрите доступные навыки:
bash
```
openskills list
```

Вы должны увидеть:

Содержимое навыка успешно выведено в стандартный вывод

Ошибка синхронизации

Проблема 8: Выходной файл не является Markdown

Сообщение об ошибке:

Error: Output file must be a markdown file (.md)

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

Причина	Описание
Выходной файл не .md	Указан формат .txt, .json и т.д.
Ошибка в параметре --output	Путь не заканчивается на .md

Решение:

Используйте файл .md:

bash

# Правильно
openskills sync -o AGENTS.md
openskills sync -o custom.md

# Неправильно
openskills sync -o AGENTS.txt
openskills sync -o AGENTS

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

bash

# Вывод в подкаталог
openskills sync -o .ruler/AGENTS.md
openskills sync -o docs/agents.md

Вы должны увидеть:

Файл .md успешно создан
Файл содержит разделы XML навыков

Проблема 9: Навыки не установлены

Сообщение об ошибке:

No skills installed. Install skills first:
  npx openskills install anthropics/skills --project

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

Причина	Описание
Навыки никогда не устанавливались	Первое использование OpenSkills
Каталог навыков удалён	Файлы навыков удалены вручную

Решение:

Установите навыки:

bash

# Установка официальных навыков
openskills install anthropics/skills

# Установка из другого репозитория
openskills install owner/repo

Проверьте установку:
bash
```
openskills list
```

Вы должны увидеть:

openskills list показывает хотя бы один навык
Синхронизация успешна

Ошибка обновления

Проблема 10: Отсутствуют исходные метаданные

Сообщение об ошибке:

Skipped: my-skill (no source metadata; re-install once to enable updates)

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

Причина	Описание
Установка старой версии	Навык установлен до появления функции метаданных
Ручное копирование	Прямое копирование каталога навыка без установки через OpenSkills
Повреждение файла метаданных	`.openskills.json` повреждён или потерян

Решение:

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

bash

# Удалите старый навык
openskills remove my-skill

# Переустановите
openskills install owner/repo

Проверьте файл метаданных:

bash

# Просмотр метаданных навыка
cat .claude/skills/my-skill/.openskills.json

Сохранение навыка с добавлением метаданных:
- Вручную создайте .openskills.json (не рекомендуется)
- Переустановка проще и надёжнее

Вы должны увидеть:

Обновление успешно, нет предупреждений о пропуске

Проблема 11: Отсутствует локальный источник

Сообщение об ошибке:

Skipped: my-skill (local source missing)

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

Причина	Описание
Локальный путь перемещён	Изменилось расположение исходного каталога
Локальный путь удалён	Исходный каталог не существует
Путь не развёрнут	Используется `~`, но в метаданных сохранён развёрнутый путь

Решение:

Проверьте локальный путь в метаданных:
bash
```
cat .claude/skills/my-skill/.openskills.json
```

Восстановите исходный каталог или обновите метаданные:

bash

# Если исходный каталог перемещён
openskills remove my-skill
openskills install /new/path/to/skill

# Или редактируйте метаданные вручную (не рекомендуется)
vi .claude/skills/my-skill/.openskills.json

Вы должны увидеть:

Локальный путь источника существует и содержит SKILL.md

Проблема 12: SKILL.md не найден в репозитории

Сообщение об ошибке:

SKILL.md missing for my-skill
Skipped: my-skill (SKILL.md not found in repo at subpath)

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

Причина	Описание
Изменилась структура репозитория	Изменился подпуть или название навыка
Навык удалён	Репозиторий больше не содержит этот навык
Ошибка в подпути	Неправильно записанный подпуть в метаданных

Решение:

Посетите репозиторий для просмотра структуры:

bash

# Клонируйте репозиторий для просмотра
git clone https://github.com/owner/repo.git
cd repo
ls -la
find . -name "SKILL.md"

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

bash

openskills remove my-skill
openskills install owner/repo/subpath

Проверьте историю обновлений репозитория:
- На GitHub просмотрите историю коммитов репозитория
- Найдите записи о перемещении или удалении навыка

Вы должны увидеть:

Обновление успешно
SKILL.md существует по записанному подпути

Проблемы с правами доступа

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

Проявления:

Операция	Проявление
Ошибка установки	Сообщение об ошибке прав доступа
Ошибка удаления	Сообщение о невозможности удалить файл
Ошибка чтения	Сообщение об ограничении доступа к файлу

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

Причина	Описание
Недостаточные права доступа к каталогу	У пользователя нет прав на запись
Недостаточные права доступа к файлу	Файл только для чтения
Защита системы	Ограничения macOS SIP, Windows UAC

Решение:

Проверьте права доступа к каталогу:

bash

# Просмотрите права доступа
ls -la .claude/skills/

# Измените права доступа (используйте осторожно)
chmod -R 755 .claude/skills/

Используйте sudo (не рекомендуется):
bash
```
# Крайняя мера
sudo openskills install owner/repo
```

Проверьте защиту системы:

bash

# macOS: проверьте статус SIP
csrutil status

# Чтобы отключить SIP (требуется режим восстановления)
# Не рекомендуется, использовать только при необходимости

Вы должны увидеть:

Нормальное чтение и запись каталогов и файлов

Проблемы с символическими ссылками

Проблема 14: Повреждённые символические ссылки

Проявления:

Проявление	Описание
Пропуск навыка при перечислении	`openskills list` не показывает этот навык
Ошибка чтения	Сообщение о несуществующем файле
Ошибка обновления	Недействительный исходный путь

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

Причина	Описание
Целевой каталог удалён	Символическая ссылка указывает на несуществующий путь
Повреждение символической ссылки	Сам файл ссылки повреждён
Межустройственная ссылка	Некоторые системы не поддерживают символические ссылки между устройствами

Решение:

Проверьте символические ссылки:

bash

# Найдите все символические ссылки
find .claude/skills -type l

# Просмотрите цель ссылки
ls -la .claude/skills/my-skill

# Протестируйте ссылку
readlink .claude/skills/my-skill

Удалите повреждённые символические ссылки:
bash
```
openskills remove my-skill
```
Переустановите:
bash
```
openskills install owner/repo
```

Вы должны увидеть:

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

Полезные советы

Распространённые ошибочные операции

❌ Не делайте этого:

Непосредственное копирование каталога навыков → Приведёт к отсутствию метаданных и сбою обновления
Ручное редактирование .openskills.json → Легко повредить формат, что приведёт к сбою обновления
Использование sudo для установки навыков → Создаст файлы, принадлежащие root, и последующие операции могут потребовать sudo
Удаление .openskills.json → Приведёт к пропуску навыка при обновлении

✅ Делайте это:

Устанавливайте через openskills install → Автоматически создаётся метаданные
Удаляйте через openskills remove → Правильная очистка файлов
Обновляйте через openskills update → Автоматическое обновление из источника
Проверяйте через openskills list → Подтверждение состояния навыка

Техники поиска неисправностей

Начните с простого: сначала запустите openskills list для подтверждения состояния
Смотрите полное сообщение об ошибке: жёлтые подсказки обычно содержат советы по решению
Проверьте структуру каталогов: используйте ls -la для просмотра файлов и прав доступа
Проверьте расположение исходного кода: сообщения об ошибках перечисляют 4 каталога поиска
Используйте -y для пропуска интерактива: используйте флаг -y в CI/CD или скриптах

Резюме урока

В этом уроке мы изучили методы поиска и устранения неисправностей для распространённых проблем OpenSkills:

Тип проблемы	Ключевое решение
Ошибка клонирования Git	Проверьте сеть, настройте учётные данные, проверьте адрес репозитория
SKILL.md не найден	Проверьте структуру репозитория, проверьте формат YAML
Ошибка чтения	Используйте `openskills list` для проверки состояния навыка
Ошибка обновления	Переустановите навык для восстановления метаданных
Проблемы с правами доступа	Проверьте права доступа к каталогу, избегайте использования sudo

Запомните:

Сообщения об ошибках обычно содержат чёткие подсказки
Переустановка — это самый простой способ решить проблемы с метаданными
Устанавливайте навыки только из доверенных источников

Следующие шаги

Просмотрите FAQ (Часто задаваемые вопросы) → Ответы на дополнительные вопросы
Изучите Лучшие практики → Как избежать распространённых ошибок
Ознакомьтесь с Инструкциями по безопасности → Узнайте о механизмах безопасности

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

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

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

Функция	Путь к файлу	Номера строк
Обработка ошибки клонирования Git	`src/commands/install.ts`	162-168
Ошибка несуществующего пути	`src/commands/install.ts`	205-207
Ошибка "не является каталогом"	`src/commands/install.ts`	210-213
Недействительный SKILL.md	`src/commands/install.ts`	241-243
Ошибка безопасности обхода пути	`src/commands/install.ts`	256-259
SKILL.md не найден	`src/commands/install.ts`	378-380
Не указано название навыка	`src/commands/read.ts`	10-12
Навык не найден	`src/commands/read.ts`	26-34
Выходной файл не Markdown	`src/commands/sync.ts`	23-25
Навыки не установлены	`src/commands/sync.ts`	40-43
Пропуск из-за отсутствия метаданных источника	`src/commands/update.ts`	57-61
Отсутствует локальный источник	`src/commands/update.ts`	66-71
SKILL.md не найден в репозитории	`src/commands/update.ts`	102-107

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

hasValidFrontmatter(content): проверяет, имеет ли SKILL.md действительный YAML frontmatter
isPathInside(targetPath, targetDir): проверяет, находится ли путь внутри целевого каталога (проверка безопасности)
findSkill(name): ищет навык в 4 каталогах по приоритету
readSkillMetadata(path): читает метаданные источника установки навыка

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

Порядок поиска в каталогах (src/utils/skills.ts):
1. .agent/skills/ (project universal)
2. ~/.agent/skills/ (global universal)
3. .claude/skills/ (project)
4. ~/.claude/skills/ (global)

Устранение неполадок: решение распространённых проблем OpenSkills ​

Что вы научитесь делать ​

Ваша текущая ситуация ​

Когда нужно читать этот туториал ​

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

Ошибка установки ​

Проблема 1: Ошибка клонирования Git ​

Проблема 2: SKILL.md не найден ​

Проблема 3: Путь не существует или не является каталогом ​

Проблема 4: Недействительный SKILL.md ​

Проблема 5: Ошибка безопасности обхода пути ​

Ошибка чтения ​

Проблема 6: Навык не найден ​

Проблема 7: Название навыка не указано ​

Ошибка синхронизации ​

Проблема 8: Выходной файл не является Markdown ​

Проблема 9: Навыки не установлены ​

Ошибка обновления ​

Проблема 10: Отсутствуют исходные метаданные ​

Проблема 11: Отсутствует локальный источник ​

Проблема 12: SKILL.md не найден в репозитории ​

Проблемы с правами доступа ​

Проблема 13: Ограниченные права доступа к каталогу ​

Проблемы с символическими ссылками ​

Проблема 14: Повреждённые символические ссылки ​

Полезные советы ​

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

Следующие шаги ​

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

Устранение неполадок: решение распространённых проблем OpenSkills

Что вы научитесь делать

Ваша текущая ситуация

Когда нужно читать этот туториал

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

Ошибка установки

Проблема 1: Ошибка клонирования Git

Проблема 2: SKILL.md не найден

Проблема 3: Путь не существует или не является каталогом

Проблема 4: Недействительный SKILL.md

Проблема 5: Ошибка безопасности обхода пути

Ошибка чтения

Проблема 6: Навык не найден

Проблема 7: Название навыка не указано

Ошибка синхронизации

Проблема 8: Выходной файл не является Markdown

Проблема 9: Навыки не установлены

Ошибка обновления

Проблема 10: Отсутствуют исходные метаданные

Проблема 11: Отсутствует локальный источник

Проблема 12: SKILL.md не найден в репозитории

Проблемы с правами доступа

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

Проблемы с символическими ссылками

Проблема 14: Повреждённые символические ссылки

Полезные советы

Резюме урока

Следующие шаги

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