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

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

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

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

По мере роста количества навыков вы можете столкнуться с этими проблемами:

Конфликт навыков с одинаковыми именами: Навыки в каталоге проекта и в пользовательском каталоге оба называются git-helper, и вы не знаете, какой загружен
Путаница в источниках навыков: Неясно, какие навыки относятся к уровню проекта, а какие к пользовательскому уровню или кэшу плагинов
Непонимание поведения переопределения: Вы изменили навык на уровне пользователя, но изменения не применяются, потому что он переопределен навыком уровня проекта
Сложность точного управления: Вы хотите принудительно использовать навык из конкретного источника, но не знаете, как это указать

Эти проблемы вызваны недопониманием пространств имен навыков и правил приоритета.

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

Пространство имен — это механизм, который OpenCode Agent Skills использует для различения навыков с одинаковыми именами из разных источников. Каждый навык имеет метку (label), указывающую его источник, и эти метки составляют пространство имен навыка.

Зачем нужны пространства имен?

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

Уровень проекта .opencode/skills/git-helper/ (настроенный для текущего проекта)
Уровень пользователя ~/.config/opencode/skills/git-helper/ (общая версия)

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

project:git-helper — принудительно использовать версию уровня проекта
user:git-helper — принудительно использовать версию уровня пользователя

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

Источники навыков и метки

OpenCode Agent Skills поддерживает несколько источников навыков, каждый из которых имеет соответствующую метку:

Источник	Метка (label)	Путь	Описание
Уровень проекта OpenCode	`project`	`.opencode/skills/`	Навыки, специфичные для текущего проекта
Уровень проекта Claude	`claude-project`	`.claude/skills/`	Навыки проекта, совместимые с Claude Code
Уровень пользователя OpenCode	`user`	`~/.config/opencode/skills/`	Общие навыки для всех проектов
Уровень пользователя Claude	`claude-user`	`~/.claude/skills/`	Навыки пользователя, совместимые с Claude Code
Кэш плагинов Claude	`claude-plugins`	`~/.claude/plugins/cache/`	Установленные плагины Claude
Маркетплейс плагинов Claude	`claude-plugins`	`~/.claude/plugins/marketplaces/`	Плагины Claude, установленные из маркетплейса

Практические рекомендации

Конфигурация, специфичная для проекта: размещайте в .opencode/skills/
Универсальные инструментальные навыки: размещайте в ~/.config/opencode/skills/
Миграция с Claude Code: перемещать ничего не нужно, система автоматически обнаружит

Приоритет обнаружения навыков

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

1. .opencode/skills/              (project)        ← Наивысший приоритет
2. .claude/skills/                (claude-project)
3. ~/.config/opencode/skills/     (user)
4. ~/.claude/skills/              (claude-user)
5. ~/.claude/plugins/cache/       (claude-plugins)
6. ~/.claude/plugins/marketplaces/ (claude-plugins)  ← Наименьший приоритет

Ключевые правила:

Первое совпадение побеждает: Первый найденный навык сохраняется
Удаление дубликатов с одинаковыми именами: Последующие навыки с таким же именем игнорируются (но выдается предупреждение)
Приоритет уровня проекта: Навыки уровня проекта переопределяют навыки уровня пользователя

Примеры приоритета

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

Директория проекта:
.opencode/skills/
  └── git-helper/              ← Версия A (проектная настройка)

Директория пользователя:
~/.config/opencode/skills/
  └── git-helper/              ← Версия B (общая)

Кэш плагинов:
~/.claude/plugins/cache/xxx/skills/
  └── git-helper/              ← Версия C (плагин Claude)

Результат: Система загружает Версия A (project:git-helper), последующие два навыка с таким же именем игнорируются.

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

Когда вы вызываете use_skill или другие инструменты, вы можете использовать префикс пространства имен для точного указания источника навыка.

Синтаксис

namespace:skill-name

или

skill-name  # Без указания пространства имен, используется приоритет по умолчанию

Список пространств имен

project:skill-name         # Навык уровня проекта OpenCode
claude-project:skill-name  # Навык уровня проекта Claude
user:skill-name            # Навык уровня пользователя OpenCode
claude-user:skill-name     # Навык уровня пользователя Claude
claude-plugins:skill-name  # Навык плагина Claude

Примеры использования

Сценарий 1: Загрузка по умолчанию (по приоритету)

use_skill("git-helper")

Система ищет по порядку приоритета и загружает первый найденный навык
То есть project:git-helper (если существует)

Сценарий 2: Принудительное использование навыка уровня пользователя

use_skill("user:git-helper")

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

Сценарий 3: Загрузка навыка плагина Claude

use_skill("claude-plugins:plugin-name")

Явно загружает навык из плагина Claude
Подходит для сценариев, требующих специфических функций плагина

Логика сопоставления пространств имен

Когда используется формат namespace:skill-name, логика сопоставления системы следующая:

Разбор ввода: Разделить пространство имен и имя навыка
Перебор всех навыков: Поиск соответствующего навыка
Условия сопоставления:
- Имя навыка совпадает
- Поле label навыка равно указанному пространству имен
- Или пользовательское поле namespace навыка равно указанному пространству имен
Возврат результата: Первый навык, удовлетворяющий условиям

Исходный код логики сопоставления

typescript

export function resolveSkill(
  skillName: string,
  skillsByName: Map<string, Skill>
): Skill | null {
  if (skillName.includes(':')) {
    const [namespace, name] = skillName.split(':');
    for (const skill of skillsByName.values()) {
      if (skill.name === name &&
          (skill.label === namespace || skill.namespace === namespace)) {
        return skill;
      }
    }
    return null;
  }
  return skillsByName.get(skillName) || null;
}

Пространства имен в режиме Superpowers

Когда вы включаете режим Superpowers, система вводит объяснение приоритета пространств имен при инициализации сессии:

markdown

**Приоритет пространств имен навыков:**
1. Project: `project:skill-name`
2. Claude project: `claude-project:skill-name`
3. User: `skill-name`
4. Claude user: `claude-user:skill-name`
5. Marketplace: `claude-plugins:skill-name`

Первое найденное совпадение побеждает.

Это гарантирует, что AI следует правильным правилам приоритета при выборе навыков.

Как включить режим Superpowers

Установите переменную окружения:

bash

OPENCODE_AGENT_SKILLS_SUPERPOWERS_MODE=true opencode

Распространенные сценарии использования

Сценарий 1: Пользовательская настройка проекта переопределяет общий навык

Требование: Вашему проекту нужен специальный Git-рабочий процесс, но на уровне пользователя уже есть общий навык git-helper.

Решение:

Создайте в каталоге проекта .opencode/skills/git-helper/
Настройте рабочий процесс Git, специфичный для проекта
При вызове по умолчанию use_skill("git-helper") будет автоматически использоваться версия уровня проекта

Проверка:

bash

## Просмотрите список навыков, обратите внимание на теги
get_available_skills("git-helper")

Пример вывода:

git-helper (project)
  Project-specific Git workflow

Сценарий 2: Временное переключение на общий навык

Требование: Для определенной задачи нужно использовать общий навык уровня пользователя, а не пользовательскую версию уровня проекта.

Решение:

use_skill("user:git-helper")

Явно укажите пространство имен user:, чтобы обойти переопределение уровня проекта.

Сценарий 3: Загрузка навыка из плагина Claude

Требование: Вы перешли с Claude Code и хотите продолжать использовать определенный навык плагина Claude.

Решение:

Убедитесь, что путь кэша плагинов Claude настроен правильно: ~/.claude/plugins/cache/
Просмотрите список навыков:

get_available_skills()

Загрузите, используя пространство имен:

use_skill("claude-plugins:plugin-name")

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

❌ Ошибка 1: Не знать, что навык с таким же именем был переопределен

Симптомы: Вы изменили навык уровня пользователя, но AI все еще использует старую версию.

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

Решение:

Проверьте, есть ли в каталоге проекта навык с таким же именем
Используйте пространство имен для принудительного указания: use_skill("user:skill-name")
Или удалите навык уровня проекта с таким же именем

❌ Ошибка 2: Неправильное написание пространства имен

Симптомы: При использовании use_skill("project:git-helper") возвращается ошибка 404.

Причина: Неправильное написание пространства имен (например, projcet вместо project) или неправильный регистр.

Решение:

Сначала просмотрите список навыков: get_available_skills()
Обратите внимание на теги в скобках (например, (project))
Используйте правильное имя пространства имен

❌ Ошибка 3: Путаница между метками и пользовательскими пространствами имен

Симптомы: При использовании use_skill("project:custom-skill") навык не найден.

Причина: project — это метка (label), а не пользовательское пространство имен. Если поле namespace навыка не явно установлено в project, совпадение не произойдет.

Решение:

Используйте имя навыка напрямую: use_skill("custom-skill")
Или просмотрите поле label навыка и используйте правильное пространство имен

Резюме урока

Система пространств имен OpenCode Agent Skills через метки и правила приоритета реализует унифицированное управление навыками из нескольких источников:

5 меток источников: project, claude-project, user, claude-user, claude-plugins
6 уровней приоритета: Уровень проекта > Уровень Claude проекта > Уровень пользователя > Уровень Claude пользователя > Кэш плагинов > Маркетплейс плагинов
Первое совпадение побеждает: Навыки с одинаковыми именами загружаются по приоритету, последующие игнорируются
Префикс пространства имен: Используйте формат namespace:skill-name для точного указания источника навыка

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

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

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

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

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

Дата обновления: 2026-01-24

Функция	Путь к файлу	Номер строки
Определение типа SkillLabel	`src/skills.ts`	30
Список приоритетов обнаружения	`src/skills.ts`	241-246
Логика удаления дубликатов навыков с одинаковыми именами	`src/skills.ts`	258-259
Обработка пространств имен в resolveSkill	`src/skills.ts`	269-283
Описание пространств имен Superpowers	`src/superpowers.ts`	18-25

Ключевые типы:

SkillLabel: Перечисление меток источников навыков
Skill: Интерфейс метаданных навыка (содержит поля namespace и label)

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

discoverAllSkills(): Обнаруживает навыки по приоритету, автоматически удаляет дубликаты
resolveSkill(): Разбирает префикс пространства имен, ищет навык
maybeInjectSuperpowersBootstrap(): Вводит описание приоритета пространств имен

Список путей обнаружения (в порядке приоритета):

project — .opencode/skills/
claude-project — .claude/skills/
user — ~/.config/opencode/skills/
claude-user — ~/.claude/skills/
claude-plugins — ~/.claude/plugins/cache/ и ~/.claude/plugins/marketplaces/

Пространства имен и приоритет навыков ​

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

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

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

Источники навыков и метки ​

Приоритет обнаружения навыков ​

Примеры приоритета ​

Использование пространств имен для указания навыков ​

Синтаксис ​

Список пространств имен ​

Примеры использования ​

Логика сопоставления пространств имен ​

Пространства имен в режиме Superpowers ​

Распространенные сценарии использования ​

Сценарий 1: Пользовательская настройка проекта переопределяет общий навык ​

Сценарий 2: Временное переключение на общий навык ​

Сценарий 3: Загрузка навыка из плагина Claude ​

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

❌ Ошибка 1: Не знать, что навык с таким же именем был переопределен ​

❌ Ошибка 2: Неправильное написание пространства имен ​

❌ Ошибка 3: Путаница между метками и пользовательскими пространствами имен ​

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

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

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

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

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

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

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

Источники навыков и метки

Приоритет обнаружения навыков

Примеры приоритета

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

Синтаксис

Список пространств имен

Примеры использования

Логика сопоставления пространств имен

Пространства имен в режиме Superpowers

Распространенные сценарии использования

Сценарий 1: Пользовательская настройка проекта переопределяет общий навык

Сценарий 2: Временное переключение на общий навык

Сценарий 3: Загрузка навыка из плагина Claude

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

❌ Ошибка 1: Не знать, что навык с таким же именем был переопределен

❌ Ошибка 2: Неправильное написание пространства имен

❌ Ошибка 3: Путаница между метками и пользовательскими пространствами имен

Резюме урока

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

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