Обновление навыков: поддержание синхронизации навыков с исходным репозиторием

Что вы сможете сделать

В этом уроке вы научитесь поддерживать навыки OpenSkills в актуальной версии. С помощью команды OpenSkills update вы сможете:

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

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

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

Возможно, вы уже сталкивались с такими ситуациями:

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

Каждый раз удалять и переустанавливать слишком хлопотно — вам нужен эффективный способ обновления.

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

Типичные сценарии использования команды update:

Сценарий	Действие
Обнаружено обновление навыка	Выполнить openskills update
Обновить только несколько навыков	openskills update skill1,skill2
Тестирование локально разрабатываемых навыков	Обновить из локального пути
Обновление из репозитория GitHub	Автоматически клонировать последний код

Рекомендации по частоте обновлений

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

🎒 Подготовка

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

• [x] OpenSkills установлен (см. Установка OpenSkills)
• [x] Установлен хотя бы один навык (см. Установка первого навыка)
• [x] Если установка производилась из GitHub, убедитесь, что есть подключение к сети

Основная идея

Механизм обновления OpenSkills очень прост:

При каждой установке записывается информация об источнике → При обновлении копируется из исходного источника заново

Зачем требуется переустановка?

Навыки старой версии (установленные без записи источника) невозможно обновить. В этом случае нужно переустановить один раз, OpenSkills запомнит источник, и тогда станет возможным автоматическое обновление.

Три способа обновления для разных источников установки:

Тип источника	Способ обновления	Применимые сценарии
Локальный путь	Непосредственное копирование из локального пути	Разработка собственных навыков
git-репозиторий	Клонирование последнего кода во временную директорию	Установка из GitHub/GitLab
GitHub shorthand	Преобразование в полный URL, затем клонирование	Установка из официального репозитория GitHub

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

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

Шаг 1: Просмотр установленных навыков

Сначала подтвердите, какие навыки можно обновить:

npx openskills list

Что вы должны увидеть: список установленных навыков, включая названия, описания и метки мест установки (project/global)

Шаг 2: Обновление всех навыков

Самый простой способ — обновить все установленные навыки:

npx openskills update

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

✅ Updated: git-workflow
✅ Updated: check-branch-first
Skipped: my-old-skill (no source metadata; re-install once to enable updates)
Summary: 2 updated, 1 skipped (3 total)

Значение пропущенных навыков

Если вы видите Skipped: xxx (no source metadata), это означает, что навык был установлен до добавления функции обновления. Необходимо переустановить его один раз, чтобы включить автоматическое обновление.

Шаг 3: Обновление указанных навыков

Если вы хотите обновить только несколько конкретных навыков, передайте их названия (разделённые запятыми):

npx openskills update git-workflow,check-branch-first

Что вы должны увидеть: обновлены только два указанных навыка

✅ Updated: git-workflow
✅ Updated: check-branch-first
Summary: 2 updated, 0 skipped (2 total)

Шаг 4: Обновление локально разрабатываемых навыков

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

npx openskills update my-skill

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

✅ Updated: my-skill
Summary: 1 updated, 0 skipped (1 total)

Рабочий процесс локальной разработки

Процесс разработки:

1. Установите навык: openskills install ./my-skill
2. Измените код
3. Обновите навык: openskills update my-skill
4. Синхронизируйте с AGENTS.md: openskills sync

Шаг 5: Обработка неудачных обновлений

Если некоторые навыки не удаётся обновить, OpenSkills отобразит подробные причины:

npx openskills update

Возможные ситуации, которые вы увидите:

Skipped: git-workflow (git clone failed)
Skipped: my-skill (local source missing)
Missing source metadata (1): old-skill
Clone failed (1): git-workflow

Соответствующие методы решения:

Сообщение об ошибке	Причина	Метод решения
no source metadata	Установка старой версии	Переустановите: openskills install <source>
local source missing	Локальный путь удалён	Восстановите локальный путь или переустановите
SKILL.md missing at local source	Локальный файл удалён	Восстановите файл SKILL.md
git clone failed	Проблема с сетью или репозиторий не существует	Проверьте сеть или адрес репозитория
SKILL.md not found in repo	Изменение структуры репозитория	Свяжитесь с автором навыка или обновите subpath

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

Убедитесь, что вы научились:

• [ ] Умение использовать openskills update для обновления всех навыков
• [ ] Умение обновлять указанные навыки, разделяя их запятыми
• [ ] Понимание значения "пропущенных" навыков и методов решения
• [ ] Знание процесса обновления локально разрабатываемых навыков

На что обратить внимание

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

Ошибка	Правильный способ
Видите пропущенный навык и не обращаете внимания	Переустановите или исправьте проблему согласно подсказке
Каждый раз удаляете и переустанавливаете	Использование команды update более эффективно
Не знаете, откуда установлен навык	Используйте openskills list для просмотра источника

⚠️ Меры предосторожности

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

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

1. Измените исходный файл (локальный путь или репозиторий)
2. Затем выполните openskills update

Навыки с символическими ссылками требуют специальной обработки

Если навык установлен с помощью символической ссылки (см. Поддержка символических ссылок), при обновлении ссылка будет создана заново, но связь символической ссылки не нарушится.

Глобальные и проектные навыки нужно обновлять отдельно

# Обновление только проектных навыков (по умолчанию)
openskills update

# Обновление глобальных навыков требует отдельной обработки
# Или используйте режим --universal для унифицированного управления

Итоги урока

В этом уроке вы изучили функцию обновления OpenSkills:

• Пакетное обновление: openskills update обновляет все навыки одним щелчком
• Указанное обновление: openskills update skill1,skill2 обновляет конкретные навыки
• Осведомлённость об источнике: автоматическое распознавание локальных путей и git-репозиториев
• Подсказки об ошибках: подробное описание причин пропуска и методов решения

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

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

На следующем уроке мы изучим Удаление навыков.

Вы узнаете:

• Как использовать интерактивную команду manage для удаления навыков
• Как использовать команду remove для автоматизированного удаления
• Меры предосторожности после удаления навыков

---

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

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

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

Функция	Путь к файлу	Номер строки
Основная логика обновления навыков	src/commands/update.ts	14-150
Обновление из локального пути	src/commands/update.ts	64-82
Обновление из git-репозитория	src/commands/update.ts	85-125
Копирование навыка из директории	src/commands/update.ts	152-163
Проверка безопасности пути	src/commands/update.ts	165-172
Определение структуры метаданных	src/utils/skill-metadata.ts	8-15
Чтение метаданных навыка	src/utils/skill-metadata.ts	17-27
Запись метаданных навыка	src/utils/skill-metadata.ts	29-36
Определение CLI-команды	src/cli.ts	58-62

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

• SKILL_METADATA_FILE = '.openskills.json': имя файла метаданных, записывает источник установки навыка

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

• updateSkills(skillNames): основная функция для обновления указанных или всех навыков
• updateSkillFromDir(targetPath, sourceDir): копирование навыка из исходной директории в целевую
• isPathInside(targetPath, targetDir): проверка безопасности пути установки (предотвращение обхода пути)
• readSkillMetadata(skillDir): чтение метаданных навыка
• writeSkillMetadata(skillDir, metadata): запись/обновление метаданных навыка

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

• BR-5-1: по умолчанию обновление всех установленных навыков (update.ts:37-38)
• BR-5-2: поддержка списка названий навыков, разделённых запятыми (update.ts:15)
• BR-5-3: пропуск навыков без метаданных источника (update.ts:56-62)
• BR-5-4: поддержка обновления из локального пути (update.ts:64-82)
• BR-5-5: поддержка обновления из git-репозитория (update.ts:85-125)
• BR-5-6: проверка безопасности пути (update.ts:156-162)