Глобальная установка vs установка в проект

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

Понимать различия между двумя местами установки навыков OpenSkills (глобальная vs в проект)
Выбирать подходящее место установки в зависимости от сценария
Освоить использование флага --global
Понимать правила приоритета поиска навыков
Избегать распространённых ошибок при выборе места установки

Предварительные знания

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

Текущая дилемма

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

Где установлены навыки?: После выполнения openskills install вы не знаете, в какой каталог скопированы файлы навыков
Нужно ли переустанавливать для нового проекта?: При переключении на другой проект установленные навыки исчезают
Как быть с навыками, которые нужны только один раз глобально?: Некоторые навыки нужны всем проектам, и вы не хотите устанавливать их в каждый проект
Общие навыки для нескольких проектов?: Некоторые навыки являются общими для команды, и вы хотите управлять ими централизованно

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

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

Сценарии применения для двух мест установки:

Место установки	Сценарий применения	Пример
В проект (по умолчанию)	Навыки, специфичные для проекта, требующие контроля версий	Правила бизнес-логики команды, инструменты специфичные для проекта
Глобальная установка (`--global`)	Навыки, общие для всех проектов, без контроля версий	Универсальные инструменты генерации кода, конвертация форматов файлов

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

По умолчанию используйте установку в проект: Навыки следуют за проектом, что облегчает командное взаимодействие и контроль версий
Для общих инструментов используйте глобальную установку: Например, git-helper, docker-generator и другие межпроектные инструменты
Избегайте чрезмерной глобализации: Глобально установленные навыки будут доступны всем проектам, что может привести к конфликтам или несовместимости версий

Основная идея: два места, гибкий выбор

Место установки навыков OpenSkills контролируется флагом --global:

По умолчанию (установка в проект):

Место установки: ./.claude/skills/ (корневой каталог проекта)
Применение: Навыки, специфичные для отдельного проекта
Преимущество: Навыки следуют за проектом, могут быть закоммичены в Git, облегчая командное взаимодействие

Глобальная установка:

Место установки: ~/.claude/skills/ (домашний каталог пользователя)
Применение: Навыки, общие для всех проектов
Преимущество: Доступны всем проектам, не требуют повторной установки

Важные концепции

В проект: Навык устанавливается в каталог .claude/skills/ текущего проекта, виден только для текущего проекта.

Глобальная установка: Навык устанавливается в каталог .claude/skills/ домашнего каталога пользователя, виден для всех проектов.

Пошаговое руководство

Шаг 1: Проверка поведения установки по умолчанию

Зачем Сначала узнайте способ установки по умолчанию, чтобы понять логику проектирования OpenSkills.

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

bash

# Установка тестового навыка (по умолчанию в проект)
npx openskills install anthropics/skills -y

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

Что вы должны увидеть: В списке навыков после каждого навыка есть метка (project)

  codebase-reviewer         (project)
    Review code changes for issues...

Summary: 3 project, 0 global (3 total)

Объяснение:

По умолчанию навык устанавливается в каталог ./.claude/skills/
Команда list показывает метку (project) или (global)
Если не использовать флаг --global, навык виден только для текущего проекта

Шаг 2: Проверка места установки навыка

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

Выполните в корневом каталоге проекта:

bash

# Просмотр каталога навыков в проекте
ls -la .claude/skills/

# Просмотр содержимого каталога навыка
ls -la .claude/skills/codebase-reviewer/

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

.claude/skills/
├── codebase-reviewer/
│   ├── SKILL.md
│   └── .openskills.json    # Метаданные установки
├── file-writer/
│   ├── SKILL.md
│   └── .openskills.json
└── ...

Объяснение:

У каждого навыка есть свой каталог
SKILL.md — это основное содержимое навыка
.openskills.json — записывает источник установки и метаданные (используется для обновлений)

Шаг 3: Глобальная установка навыка

Зачем Узнайте команду и эффект глобальной установки.

Выполните:

bash

# Глобальная установка навыка
npx openskills install anthropics/skills --global -y

# Снова просмотрите список навыков
npx openskills list

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

  codebase-reviewer         (project)
    Review code changes for issues...
  file-writer              (global)
    Write files with format...

Summary: 1 project, 2 global (3 total)

Объяснение:

После использования флага --global навык устанавливается в ~/.claude/skills/
Команда list показывает метку (global)
Навыки с одинаковым именем будут использовать сначала локальную версию проекта (приоритет поиска)

Шаг 4: Сравнение двух мест установки

Зачем Понимание различий между двумя местами установки путём фактического сравнения.

Выполните следующие команды:

bash

# Просмотр каталога глобально установленных навыков
ls -la ~/.claude/skills/

# Сравнение навыков, установленных в проект и глобально
echo "=== Project Skills ==="
ls .claude/skills/

echo "=== Global Skills ==="
ls ~/.claude/skills/

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

=== Project Skills ===
codebase-reviewer
file-writer

=== Global Skills ===
codebase-reviewer
file-writer
test-generator

Объяснение:

Навыки в проекте: ./.claude/skills/
Глобальные навыки: ~/.claude/skills/
Два каталога могут содержать навыки с одинаковыми именами, но приоритет локальной версии проекта выше

Шаг 5: Проверка приоритета поиска

Зачем Понимание того, как OpenSkills ищет навыки в нескольких местах.

Выполните:

bash

# Установка навыков с одинаковым именем в двух местах
npx openskills install anthropics/skills -y  # В проекте
npx openskills install anthropics/skills --global -y  # Глобально

# Чтение навыка (будет использована версия в проекте)
npx openskills read codebase-reviewer | head -5

Что вы должны увидеть: Выводится содержимое навыка локальной версии проекта.

Правила приоритета поиска (исходный код dirs.ts:18-24):

typescript

export function getSearchDirs(): string[] {
  return [
    join(process.cwd(), '.claude/skills'),   // 1. В проекте (высший приоритет)
    join(homedir(), '.claude/skills'),       // 2. Глобально
  ];
}

Объяснение:

Приоритет навыков в проекте выше, чем у глобальных
При наличии навыков с одинаковыми именами приоритет имеет версия в проекте
Это позволяет реализовать гибкую конфигурацию "проект переопределяет глобальное"

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

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

[ ] Способны различать установку в проект и глобальную установку
[ ] Знаете назначение флага --global
[ ] Понимаете правила приоритета поиска навыков
[ ] Способны выбрать подходящее место установки в зависимости от сценария
[ ] Знаете, как просматривать метки местоположения установленных навыков

Предупреждение о распространённых ошибках

Распространённая ошибка 1: Неправильное использование глобальной установки

Сценарий ошибки: Глобальная установка навыков, специфичных для проекта

bash

# ❌ Ошибка: Правила бизнес-логики команды не должны устанавливаться глобально
npx openskills install my-company/rules --global

Проблема:

Другие участники команды не смогут получить этот навык
Навык не будет под контролем версий
Может конфликтовать с навыками других проектов

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

bash

# ✅ Правильно: Навыки, специфичные для проекта, устанавливаются по умолчанию (в проект)
npx openskills install my-company/rules

Распространённая ошибка 2: Забыть флаг `--global`

Сценарий ошибки: Хотите, чтобы навык был доступен всем проектам, но забыли добавить --global

bash

# ❌ Ошибка: По умолчанию устанавливается в проект, другие проекты не могут использовать
npx openskills install universal-tool

Проблема:

Навык устанавливается только в ./.claude/skills/ текущего проекта
При переключении на другой проект нужно переустановить

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

bash

# ✅ Правильно: Для общих инструментов используйте глобальную установку
npx openskills install universal-tool --global

Распространённая ошибка 3: Конфликт навыков с одинаковыми именами

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

bash

# codebase-reviewer есть и в проекте, и глобально
# Но нужно использовать глобальную версию (новую)
npx openskills install codebase-reviewer --global  # Установка новой версии
npx openskills read codebase-reviewer  # ❌ Всё равно читается старая версия

Проблема:

Приоритет локальной версии проекта выше
Даже если глобально установлена новая версия, всё равно читается старая версия проекта

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

bash

# Решение 1: Удалить локальную версию проекта
npx openskills remove codebase-reviewer  # Удаление в проекте
npx openskills read codebase-reviewer  # ✅ Теперь читается глобальная версия

# Решение 2: Обновить в проекте
npx openskills update codebase-reviewer  # Обновление локальной версии проекта

Итог урока

Основные моменты:

По умолчанию установка в проект: Навык устанавливается в ./.claude/skills/, виден только для текущего проекта
Глобальная установка с использованием --global: Навык устанавливается в ~/.claude/skills/, доступен всем проектам
Приоритет поиска: В проекте > Глобально
Рекомендуемый принцип: Для специфичных навыков проекта — локально, для общих инструментов — глобально

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

[Нужно установить навык] → [Специфичен для проекта?]
                      ↓ Да
              [Установка в проект (по умолчанию)]
                      ↓ Нет
              [Нужен контроль версий?]
                      ↓ Да
              [Установка в проект (может быть закоммичен в Git)]
                      ↓ Нет
              [Глобальная установка (--global)]

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

В проект: Навыки следуют за проектом, командное взаимодействие не вызывает трудностей
Глобальная установка: Общие инструменты — в глобальное пространство, все проекты могут использовать

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

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

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

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

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

Функция	Путь к файлу	Строки
Определение места установки	`src/commands/install.ts`	84-92
Утилиты путей каталогов	`src/utils/dirs.ts`	7-25
Отображение списка навыков	`src/commands/list.ts`	20-43

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

.claude/skills: каталог навыков по умолчанию (совместимость с Claude Code)
.agent/skills: каталог универсальных навыков (мультиагентная среда)

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

getSkillsDir(projectLocal, universal): возвращает путь к каталогу навыков в зависимости от флага
getSearchDirs(): возвращает список каталогов поиска навыков (упорядоченных по приоритету)
listSkills(): перечисляет все установленные навыки, отображая метки местоположения

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

По умолчанию установка в проект (!options.global)
Приоритет поиска навыков: в проекте > глобально
Команда list отображает метки (project) и (global)

Глобальная установка vs установка в проект ​

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

Текущая дилемма ​

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

Основная идея: два места, гибкий выбор ​

Пошаговое руководство ​

Шаг 1: Проверка поведения установки по умолчанию ​

Шаг 2: Проверка места установки навыка ​

Шаг 3: Глобальная установка навыка ​

Шаг 4: Сравнение двух мест установки ​

Шаг 5: Проверка приоритета поиска ​

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

Предупреждение о распространённых ошибках ​

Распространённая ошибка 1: Неправильное использование глобальной установки ​

Распространённая ошибка 2: Забыть флаг --global ​

Распространённая ошибка 3: Конфликт навыков с одинаковыми именами ​

Итог урока ​

Предварительный просмотр следующего урока ​

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

Глобальная установка vs установка в проект

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

Текущая дилемма

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

Основная идея: два места, гибкий выбор

Пошаговое руководство

Шаг 1: Проверка поведения установки по умолчанию

Шаг 2: Проверка места установки навыка

Шаг 3: Глобальная установка навыка

Шаг 4: Сравнение двух мест установки

Шаг 5: Проверка приоритета поиска

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

Предупреждение о распространённых ошибках

Распространённая ошибка 1: Неправильное использование глобальной установки

Распространённая ошибка 2: Забыть флаг `--global`

Распространённая ошибка 3: Конфликт навыков с одинаковыми именами

Итог урока

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

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