Поддержка символических ссылок

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

Понимать основную ценность символических ссылок и сценарии их применения
Освоить команду ln -s для создания символических ссылок
Понимать, как OpenSkills автоматически обрабатывает символические ссылки
Реализовать автоматическое обновление навыков на основе git
Эффективно выполнять локальную разработку навыков
Обрабатывать поврежденные символические ссылки

Необходимые знания

Этот учебник предполагает, что вы уже изучили Подробное описание установки источников и Установка первого навыка, понимая основной процесс установки навыков.

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

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

Сложности с обновлением локальной разработки: после изменения навыка необходимо переустановить или вручную скопировать файлы
Трудности с совместным использованием навыков в нескольких проектах: один и тот же навык используется в нескольких проектах, при каждом обновлении требуется синхронизация
Хаос в управлении версиями: файлы навыков разбросаны по разным проектам, сложно использовать git для централизованного управления
Сложный процесс обновления: для обновления навыков из git-репозитория требуется переустановить весь репозиторий

На самом деле OpenSkills поддерживает символические ссылки, что позволяет вам реализовать автоматическое обновление навыков на основе git и эффективный рабочий процесс локальной разработки с помощью symlink.

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

Сценарии применения символических ссылок:

Сценарий	Нужна символическая ссылка	Пример
Локальная разработка навыков	✅ Да	Разработка пользовательских навыков, частые изменения и тестирование
Совместное использование навыков в нескольких проектах	✅ Да	Командный репозиторий навыков, одновременное использование в нескольких проектах
Автоматическое обновление на основе git	✅ Да	После обновления репозитория навыков все проекты автоматически получают последнюю версию
Установка раз и навсегда	❌ Нет	Только установка без изменений, достаточно использовать `install`
Тестирование сторонних навыков	❌ Нет	Временное тестирование навыков, символическая ссылка не требуется

Рекомендуемый подход

Используйте символические ссылки для локальной разработки: при разработке собственных навыков используйте symlink, чтобы избежать повторного копирования
Используйте git + symlink для совместного использования командой: командный репозиторий навыков помещается в git, проекты используют symlink для совместного доступа
Используйте обычную установку для production: при стабильном развертывании используйте обычную install, чтобы избежать зависимости от внешних каталогов

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

Традиционный способ установки:

┌─────────────────┐
│  Git репозиторий       │
│  ~/dev/skills/ │
│  └── my-skill/ │
└────────┬────────┘
          │ Копирование
          ▼
┌─────────────────┐
│ .claude/skills/ │
│  └── my-skill/ │
│     └── Полная копия │
└─────────────────┘

Проблема: после обновления git-репозитория навыки в .claude/skills/ не обновляются автоматически.

Способ с символическими ссылками:

┌─────────────────┐
│  Git репозиторий       │
│  ~/dev/skills/ │
│  └── my-skill/ │ ← Реальные файлы находятся здесь
└────────┬────────┘
          │ Символическая ссылка (ln -s)
          ▼
┌─────────────────┐
│ .claude/skills/ │
│  └── my-skill/ │ → указывает на ~/dev/skills/my-skill
└─────────────────┘

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

Важное понятие

Символическая ссылка (Symlink): специальный тип файла, указывающий на другой файл или каталог. OpenSkills автоматически распознает символические ссылки при поиске навыков и следует за ними к фактическому содержимому. Поврежденные символические ссылки (указывающие на несуществующие цели) автоматически пропускаются, что предотвращает сбои.

Реализация в исходном коде (src/utils/skills.ts:10-25):

typescript

function isDirectoryOrSymlinkToDirectory(entry: Dirent, parentDir: string): boolean {
  if (entry.isDirectory()) {
    return true;
  }
  if (entry.isSymbolicLink()) {
    try {
      const fullPath = join(parentDir, entry.name);
      const stats = statSync(fullPath); // statSync следует за символическими ссылками
      return stats.isDirectory();
    } catch {
      // Поврежденная символическая ссылка или ошибка прав доступа
      return false;
    }
  }
  return false;
}

Ключевые моменты:

entry.isSymbolicLink() обнаруживает символические ссылки
statSync() автоматически следует за символическими ссылками к цели
try/catch перехватывает поврежденные символические ссылки, возвращает false для пропуска

Делайте вместе со мной

Шаг 1: Создание репозитория навыков

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

Откройте терминал и выполните:

bash

# Создание каталога репозитория навыков
mkdir -p ~/dev/my-skills
cd ~/dev/my-skills

# Инициализация git-репозитория
git init

# Создание примера навыка
mkdir -p my-first-skill
cat > my-first-skill/SKILL.md << 'EOF'
---
name: my-first-skill
description: Пример навыка для демонстрации поддержки символических ссылок
---

# My First Skill

When user asks for help with this skill, follow these steps:
1. Check the symlink is working
2. Print "Symlink support is working!"
EOF

# Фиксация в git
git add .
git commit -m "Initial commit: Add my-first-skill"

Что вы должны увидеть: успешно созданный git-репозиторий и зафиксированный навык.

Объяснение:

Навыки хранятся в каталоге ~/dev/my-skills/
Используется управление версиями git для удобства командной работы
Этот каталог является "реальным местоположением" навыков

Шаг 2: Создание символической ссылки

Зачем Изучите, как создать символическую ссылку с помощью команды ln -s.

Продолжайте выполнять в каталоге проекта:

bash

# Возврат в корневой каталог проекта
cd ~/my-project

# Создание каталога навыков
mkdir -p .claude/skills

# Создание символической ссылки
ln -s ~/dev/my-skills/my-first-skill .claude/skills/my-first-skill

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

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

.claude/skills/
└── my-first-skill -> /Users/yourname/dev/my-skills/my-first-skill

Объяснение:

ln -s создает символическую ссылку
После -> отображается фактический путь к цели
Сама символическая ссылка — это просто "указатель", не занимающий реального места

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

Зачем Убедитесь, что OpenSkills может правильно распознавать и читать навыки с символическими ссылками.

Выполните:

bash

# Список навыков
npx openskills list

# Чтение содержимого навыка
npx openskills read my-first-skill

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

  my-first-skill           (project)
    Пример навыка для демонстрации поддержки символических ссылок

Summary: 1 project, 0 global (1 total)

Вывод чтения навыка:

markdown

---
name: my-first-skill
description: Пример навыка для демонстрации поддержки символических ссылок
---

# My First Skill

When user asks for help with this skill, follow these steps:
1. Check the symlink is working
2. Print "Symlink support is working!"

Объяснение:

OpenSkills автоматически распознает символические ссылки
Навыки с символическими ссылками помечаются тегом (project)
Считываемое содержимое поступает из исходного файла, на который указывает символическая ссылка

Шаг 4: Автоматическое обновление на основе git

Зачем Испытайте главное преимущество символических ссылок: после обновления git-репозитория навыки автоматически синхронизируются.

Измените навык в репозитории навыков:

bash

# Вход в репозиторий навыков
cd ~/dev/my-skills

# Изменение содержимого навыка
cat > my-first-skill/SKILL.md << 'EOF'
---
name: my-first-skill
description: Обновленная версия с новыми функциями
---

# My First Skill (Updated)

When user asks for help with this skill, follow these steps:
1. Check the symlink is working
2. Print "Symlink support is working!"
3. NEW: This feature was updated via git!
EOF

# Фиксация обновления
git add .
git commit -m "Update skill: Add new feature"

Теперь проверьте обновление в каталоге проекта:

bash

# Возврат в каталог проекта
cd ~/my-project

# Чтение навыка (переустановка не требуется)
npx openskills read my-first-skill

Что вы должны увидеть: содержимое навыка автоматически обновлено, включает описание новых функций.

Объяснение:

После обновления файла, на который указывает символическая ссылка, OpenSkills автоматически считывает последнее содержимое
Не требуется повторно выполнять openskills install
Реализуется принцип "одно обновление — везде生效"

Шаг 5: Совместное использование навыков в нескольких проектах

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

Создайте второй проект:

bash

# Создание второго проекта
mkdir ~/my-second-project
cd ~/my-second-project

# Создание каталога навыков и символической ссылки
mkdir -p .claude/skills
ln -s ~/dev/my-skills/my-first-skill .claude/skills/my-first-skill

# Проверка доступности навыка
npx openskills list

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

  my-first-skill           (project)
    Обновленная версия с новыми функциями

Summary: 1 project, 0 global (1 total)

Объяснение:

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

Шаг 6: Обработка поврежденных символических ссылок

Зачем Понимайте, как OpenSkills элегантно обрабатывает поврежденные символические ссылки.

Смоделируйте поврежденную символическую ссылку:

bash

# Удаление репозитория навыков
rm -rf ~/dev/my-skills

# Попытка списка навыков
npx openskills list

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

Summary: 0 project, 0 global (0 total)

Объяснение:

try/catch в исходном коде перехватывает поврежденные символические ссылки
OpenSkills пропускает поврежденные ссылки и продолжает поиск других навыков
Не приводит к сбою команды openskills

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

Выполните следующие проверки, чтобы подтвердить освоение содержания этого урока:

[ ] Понимать основную ценность символических ссылок
[ ] Освоить использование команды ln -s
[ ] Понимать различие между символическими ссылками и копированием файлов
[ ] Уметь создавать репозиторий навыков на основе git
[ ] Уметь реализовать автоматическое обновление навыков
[ ] Знать, как совместно использовать навыки в нескольких проектах
[ ] Понимать механизм обработки поврежденных символических ссылок

Предупреждение о возможных проблемах

Частая ошибка 1: Ошибка пути символической ссылки

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

bash

# ❌ Ошибка: использование относительного пути
cd ~/my-project
ln -s ../dev/my-skills/my-first-skill .claude/skills/my-first-skill

# Ссылка становится недействительной после перемещения проекта
mv ~/my-project ~/new-location/project
npx openskills list  # ❌ Навык не найден

Проблема:

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

Правильный подход:

bash

# ✅ Правильно: использование абсолютного пути
ln -s ~/dev/my-skills/my-first-skill .claude/skills/my-first-skill

# Все еще работает после перемещения проекта
mv ~/my-project ~/new-location/project
npx openskills list  # ✅ Навык все еще можно найти

Частая ошибка 2: Путаница между жесткими ссылками и символическими ссылками

Сценарий ошибки: использование жесткой ссылки вместо символической ссылки.

bash

# ❌ Ошибка: использование жесткой ссылки (без параметра -s)
ln ~/dev/my-skills/my-first-skill .claude/skills/my-first-skill

# Жесткая ссылка — это еще одно имя входа в файл, а не указатель
# Невозможно реализовать "обновление в одном месте —生效 везде"

Проблема:

Жесткая ссылка — это еще одно имя входа в файл
При изменении любой жесткой ссылки другие жесткие ссылки также обновляются
Но после удаления исходного файла жесткая ссылка все еще существует, вызывая путаницу
Невозможно использовать через файловую систему

Правильный подход:

bash

# ✅ Правильно: использование символической ссылки (с параметром -s)
ln -s ~/dev/my-skills/my-first-skill .claude/skills/my-first-skill

# Символическая ссылка — это указатель
# После удаления исходного файла символическая ссылка становится недействительной (OpenSkills пропустит)

Частая ошибка 3: Символическая ссылка указывает на неправильное место

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

bash

# ❌ Ошибка: указывает на родительский каталог
ln -s ~/dev/my-skills .claude/skills/my-skills-link

# OpenSkills будет искать SKILL.md в .claude/skills/my-skills-link/
# Но на самом деле SKILL.md находится в ~/dev/my-skills/my-first-skill/SKILL.md

Проблема:

OpenSkills ищет <link>/SKILL.md
Но на самом деле навык находится в <link>/my-first-skill/SKILL.md
Приводит к тому, что файл навыка не найден

Правильный подход:

bash

# ✅ Правильно: напрямую указывает на каталог навыка
ln -s ~/dev/my-skills/my-first-skill .claude/skills/my-first-skill

# OpenSkills будет искать .claude/skills/my-first-skill/SKILL.md
# В каталоге, на который указывает символическая ссылка, содержится SKILL.md

Частая ошибка 4: Забыть синхронизировать AGENTS.md

Сценарий ошибки: после создания символической ссылки забыть синхронизировать AGENTS.md.

bash

# Создание символической ссылки
ln -s ~/dev/my-skills/my-first-skill .claude/skills/my-first-skill

# ❌ Ошибка: забыть синхронизировать AGENTS.md
# AI-агент не может узнать, что есть новые доступные навыки

Проблема:

Символическая ссылка создана, но AGENTS.md не обновлен
AI-агент не знает о новых навыках
Невозможно вызвать новые навыки

Правильный подход:

bash

# Создание символической ссылки
ln -s ~/dev/my-skills/my-first-skill .claude/skills/my-first-skill

# ✅ Правильно: синхронизировать AGENTS.md
npx openskills sync

# Теперь AI-агент может видеть новые навыки

Итог урока

Ключевые моменты:

Символическая ссылка — это указатель: создается с помощью ln -s, указывает на реальные файлы или каталоги
Автоматическое следование ссылкам: OpenSkills использует statSync() для автоматического следования символическим ссылкам
Автоматический пропуск поврежденных ссылок: try/catch перехватывает исключения, предотвращая сбои
Автоматическое обновление на основе git: после обновления git-репозитория навыки автоматически синхронизируются
Совместное использование в нескольких проектах: несколько проектов могут создавать символические ссылки на один и тот же навык

Процесс принятия решений:

[Нужно использовать навыки] → [Требуется частое изменение?]
                         ↓ Да
                 [Использовать символическую ссылку (локальная разработка)]
                         ↓ Нет
                 [Используется в нескольких проектах?]
                         ↓ Да
                 [Использовать git + символическую ссылку]
                         ↓ Нет
                 [Использовать обычную install]

Мнемоническое правило:

Локальная разработка с symlink: частые изменения, избегайте повторного копирования
Командное совместное использование с git-ссылкой: одно обновление —生效 везде
Абсолютный путь обеспечивает стабильность: избегайте недействительности относительного пути
Поврежденные ссылки автоматически пропускаются: OpenSkills автоматически обрабатывает

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

В следующем уроке мы изучим Создание пользовательских навыков.
Вы узнаете:
Как создать свои навыки с нуля
Понимать формат SKILL.md и YAML frontmatter
Как организовать структуру каталогов навыков (references/, scripts/, assets/)
Как писать высококачественные описания навыков

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

Нажмите для просмотра местоположения исходного кода

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

Функция	Путь к файлу	Строка
Обнаружение символических ссылок	`src/utils/skills.ts`	10-25
Поиск навыков	`src/utils/skills.ts`	30-64
Поиск отдельного навыка	`src/utils/skills.ts`	69-84

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

isDirectoryOrSymlinkToDirectory(entry, parentDir): определяет, является ли элемент каталога реальным каталогом или символической ссылкой, указывающей на каталог
- Использует entry.isSymbolicLink() для обнаружения символических ссылок
- Использует statSync() для автоматического следования символическим ссылкам к цели
- try/catch перехватывает поврежденные символические ссылки, возвращает false
findAllSkills(): находит все установленные навыки
- Проходит по 4 каталогам поиска
- Вызывает isDirectoryOrSymlinkToDirectory для распознавания символических ссылок
- Автоматически пропускает поврежденные символические ссылки

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

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

Поддержка символических ссылок ​

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

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

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

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

Делайте вместе со мной ​

Шаг 1: Создание репозитория навыков ​

Шаг 2: Создание символической ссылки ​

Шаг 3: Проверка правильности работы символической ссылки ​

Шаг 4: Автоматическое обновление на основе git ​

Шаг 5: Совместное использование навыков в нескольких проектах ​

Шаг 6: Обработка поврежденных символических ссылок ​

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

Предупреждение о возможных проблемах ​

Частая ошибка 1: Ошибка пути символической ссылки ​

Частая ошибка 2: Путаница между жесткими ссылками и символическими ссылками ​

Частая ошибка 3: Символическая ссылка указывает на неправильное место ​

Частая ошибка 4: Забыть синхронизировать AGENTS.md ​

Итог урока ​

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

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

Поддержка символических ссылок

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

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

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

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

Делайте вместе со мной

Шаг 1: Создание репозитория навыков

Шаг 2: Создание символической ссылки

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

Шаг 4: Автоматическое обновление на основе git

Шаг 5: Совместное использование навыков в нескольких проектах

Шаг 6: Обработка поврежденных символических ссылок

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

Предупреждение о возможных проблемах

Частая ошибка 1: Ошибка пути символической ссылки

Частая ошибка 2: Путаница между жесткими ссылками и символическими ссылками

Частая ошибка 3: Символическая ссылка указывает на неправильное место

Частая ошибка 4: Забыть синхронизировать AGENTS.md

Итог урока

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

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