Использование навыков

Что вы узнаете

Использовать команду openskills read для чтения содержимого установленных навыков
Понимать, как ИИ-агенты загружают навыки в контекст с помощью этой команды
Освоить 4-уровневый порядок приоритета поиска навыков
Научиться читать несколько навыков за один раз (разделённых запятыми)

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

Это руководство предполагает, что вы уже установили хотя бы один навык. Если вы ещё не установили навык, пожалуйста, сначала выполните шаги установки навыка.

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

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

Не знаете, как заставить ИИ использовать навыки: навыки установлены, но как их читает ИИ-агент?
Не понимаете назначение команды read: знаете, что есть команда read, но не знаете, что она выводит
Не понятен порядок поиска навыков: есть навыки и глобально, и в проекте, какой использует ИИ?

Эти вопросы очень распространены. Давайте решим их шаг за шагом.

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

Использование навыков (команда read) подходит для этих сценариев:

ИИ-агенту необходимо выполнить конкретную задачу: например, обработка PDF, работа с Git-репозиторием и т.д.
Проверка правильности содержимого навыка: проверка соответствия инструкций в SKILL.md ожиданиям
Понимание полной структуры навыка: просмотр ресурсов навыка, таких как references/, scripts/ и т.д.

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

Обычно вы не используете команду read напрямую, а её автоматически вызывает ИИ-агент. Но понимание формата её вывода помогает при отладке и разработке пользовательских навыков.

🎒 Подготовка перед началом

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

[ ] Выполнена установка первого навыка
[ ] В директории проекта установлен хотя бы один навык
[ ] Можно просмотреть директорию .claude/skills/

Предварительная проверка

Если вы ещё не установили навыки, можно быстро установить тестовый навык:

bash

npx openskills install anthropics/skills
# В интерактивном интерфейсе выберите любой навык (например, pdf)

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

Команда read OpenSkills выполняет следующий процесс:

[Указанное имя навыка] → [Поиск по приоритету] → [Найти первый] → [Чтение SKILL.md] → [Вывод в стандартный вывод]

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

4-уровневый приоритет поиска:
1. .agent/skills/ (проект universal)
2. ~/.agent/skills/ (глобальный universal)
3. .claude/skills/ (проект claude)
4. ~/.claude/skills/ (глобальный claude)
Возврат первого совпадения: останавливается после нахождения первого, не проверяет последующие директории
Вывод базовой директории: ИИ-агенту нужен этот путь для разрешения файлов ресурсов в навыках

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

Шаг 1: Чтение одного навыка

Сначала попробуйте прочитать установленный навык.

Пример команды:

bash

npx openskills read pdf

Почему

pdf — это название навыка, который мы установили на предыдущем уроке. Эта команда найдёт и выведет полное содержимое этого навыка.

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

Reading: pdf
Base directory: /path/to/your/project/.claude/skills/pdf

---
name: pdf
description: Comprehensive PDF manipulation toolkit for extracting text and tables...
...

Skill read: pdf

Разбор структуры вывода:

Часть	Содержимое	Назначение
`Reading: pdf`	Имя навыка	Идентифицирует читаемый навык
`Base directory: ...`	Базовая директория навыка	ИИ использует этот путь для разрешения ресурсов, таких как references/, scripts/ и т.д.
Содержимое SKILL.md	Полное определение навыка	Содержит инструкции, ссылки на ресурсы и т.д.
`Skill read: pdf`	Метка завершения	Обозначает завершение чтения

Обратите внимание

Базовая директория (Base directory) очень важна. Пути вроде references/some-doc.md в навыках будут разрешены относительно этой директории.

Шаг 2: Чтение нескольких навыков

OpenSkills поддерживает чтение нескольких навыков за один раз, имена навыков разделяются запятыми.

Пример команды:

bash

npx openskills read pdf,git-workflow

Почему

Чтение нескольких навыков за один раз уменьшает количество вызовов команд и повышает эффективность.

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

Reading: pdf
Base directory: /path/to/your/project/.claude/skills/pdf

---
name: pdf
description: Comprehensive PDF manipulation toolkit...
...

Skill read: pdf

Reading: git-workflow
Base directory: /path/to/your/project/.claude/skills/git-workflow

---
name: git-workflow
description: Git workflow: Best practices...
...

Skill read: git-workflow

Особенности:

Вывод каждого навыка разделён пустой строкой
У каждого навыка есть независимые метки Reading: и Skill read:
Навыки читаются в порядке, указанном в команде

Расширенное использование

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

bash

npx openskills read pdf, git-workflow  # пробелы будут проигнорированы

Шаг 3: Проверка приоритета поиска навыков

Давайте проверим правильность 4-уровневого порядка поиска.

Подготовка окружения:

Сначала установите навыки в директории проекта и глобальной директории (используя разные источники установки):

bash

# Локальная установка в проекте (в текущей директории проекта)
npx openskills install anthropics/skills

# Глобальная установка (с помощью --global)
npx openskills install anthropics/skills --global

Проверка приоритета:

bash

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

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

Available skills:

pdf (project)      /path/to/your/project/.claude/skills/pdf
pdf (global)       /home/user/.claude/skills/pdf

Total: 2 skills (1 project, 1 global)

Чтение навыка:

bash

npx openskills read pdf

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

Reading: pdf
Base directory: /path/to/your/project/.claude/skills/pdf  ← Приоритет возвращается навыку проекта
...

Вывод: поскольку приоритет .claude/skills/ (проект) выше, чем ~/.claude/skills/ (глобальный), читается локальный навык проекта.

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

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

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

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

Навык содержит не только SKILL.md, но и может иметь ресурсы, такие как references/, scripts/ и т.д.

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

bash

ls -la .claude/skills/pdf/

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

.claude/skills/pdf/
├── SKILL.md
├── .openskills.json
├── references/
│   ├── pdf-extraction.md
│   └── table-extraction.md
└── scripts/
    └── extract-pdf.js

Чтение навыка и наблюдение за выводом:

bash

npx openskills read pdf

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

SKILL.md содержит ссылки на ресурсы, например:

markdown

## References

See [PDF extraction guide](references/pdf-extraction.md) for details.

## Scripts

Run `node scripts/extract-pdf.js` to extract text from PDF.

Ключевой момент

Когда ИИ-агент читает навык, он:

Получает путь Base directory
Объединяет относительные пути из SKILL.md (например, references/...) с базовой директорией
Читает содержимое фактического файла ресурсов

Вот почему команда read должна выводить Base directory.

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

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

[ ] Командная строка отобразила полное содержимое SKILL.md навыка
[ ] Вывод содержит Reading: <name> и Base directory: <path>
[ ] В конце вывода есть метка завершения Skill read: <name>
[ ] При чтении нескольких навыков каждый навык разделён пустой строкой
[ ] Приоритетное чтение локального навыка проекта, а не глобального навыка

Если все пункты проверки пройдены, поздравляем! Вы освоили основной процесс чтения навыков.

Предупреждения о проблемах

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

Симптом:

Error: Skill(s) not found: pdf

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

Install skills: npx openskills install owner/repo

Причина:

Навык не установлен
Ошибка в написании имени навыка

Решение:

Список установленных навыков: npx openskills list
Подтвердите правильность имени навыка
Если не установлен, используйте openskills install для установки

Проблема 2: Чтение неправильного навыка

Симптом:

Ожидалось чтение навыка проекта, но фактически прочитался глобальный навык.

Причина:

Директория проекта не находится в правильном месте (использована неправильная директория)

Решение:

Проверьте текущую рабочую директорию: pwd
Убедитесь, что находитесь в правильной директории проекта
Используйте openskills list для просмотра метки location навыка

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

Симптом:

bash

npx openskills read skill-a,skill-b

Ожидалось сначала чтение skill-b, но фактически сначала прочитался skill-a.

Причина:

Команда read читает в порядке, указанном в параметрах, не сортирует автоматически

Решение:

Если нужен определённый порядок, укажите имена навыков в нужном порядке в команде

Проблема 4: Содержимое SKILL.md обрезано

Симптом:

Выводимое содержимое SKILL.md неполное, отсутствует конечная часть.

Причина:

Файл навыка повреждён или содержит ошибку формата
Проблема с кодировкой файла

Решение:

Проверьте файл SKILL.md: cat .claude/skills/<name>/SKILL.md
Подтвердите, что файл完整 и формат правильный (обязательно должен быть YAML frontmatter)
Переустановите навык: openskills update <name>

Итог урока

На этом уроке вы узнали:

Использование openskills read <name> для чтения содержимого установленных навыков
Понимание 4-уровневого приоритета поиска: проект universal > глобальный universal > проект claude > глобальный claude
Поддержка чтения нескольких навыков: использование запятых для разделения имён навыков
Формат вывода: содержит метки Reading:, Base directory, содержимое навыка, Skill read:

Основные концепции:

Концепция	Описание
Приоритет поиска	Поиск по 4 директориям по порядку, возврат первого совпадения
Базовая директория	Справочная директория, которую ИИ-агент использует для разрешения относительных путей в навыках
Чтение нескольких навыков	Разделение запятыми, чтение в указанном порядке

Основные команды:

Команда	Назначение
`npx openskills read <name>`	Чтение одного навыка
`npx openskills read name1,name2`	Чтение нескольких навыков
`npx openskills list`	Просмотр установленных навыков и их расположения

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

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

После того как вы научились использовать навыки,接下来 нужно понять все команды, которые предоставляет OpenSkills, и их назначение.

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

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

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

Функция	Путь к файлу	Строки
Вход команды read	`src/commands/read.ts`	8-48
Поиск навыков (findSkill)	`src/utils/skills.ts`	69-84
Нормализация имён навыков	`src/utils/skill-names.ts`	1-8
Получение директорий поиска	`src/utils/dirs.ts`	18-25
Определение команд CLI	`src/cli.ts`	52-55

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

readSkill(skillNames) — Читает навыки в стандартный вывод, поддерживает несколько имён навыков
findSkill(skillName) — Ищет навыки по 4-уровневому приоритету, возвращает первое совпадение
normalizeSkillNames(input) — Нормализует список имён навыков, поддерживает разделение запятыми и удаление дубликатов
getSearchDirs() — Возвращает 4 директории поиска, отсортированные по приоритету

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

SkillLocation — Информация о местоположении навыка, содержит path, baseDir, source

Приоритет директорий (из dirs.ts:18-24):

typescript

[
  process.cwd() + '/.agent/skills',   // 1. Project universal
  homedir() + '/.agent/skills',       // 2. Global universal
  process.cwd() + '/.claude/skills',  // 3. Project claude
  homedir() + '/.claude/skills',      // 4. Global claude
]

Использование навыков ​

Что вы узнаете ​

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

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

🎒 Подготовка перед началом ​

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

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

Шаг 1: Чтение одного навыка ​

Шаг 2: Чтение нескольких навыков ​

Шаг 3: Проверка приоритета поиска навыков ​

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

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

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

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

Проблема 2: Чтение неправильного навыка ​

Проблема 3: Порядок чтения нескольких навыков не соответствует ожиданиям ​

Проблема 4: Содержимое SKILL.md обрезано ​

Итог урока ​

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

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

Использование навыков

Что вы узнаете

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

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

🎒 Подготовка перед началом

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

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

Шаг 1: Чтение одного навыка

Шаг 2: Чтение нескольких навыков

Шаг 3: Проверка приоритета поиска навыков

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

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

Предупреждения о проблемах

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

Проблема 2: Чтение неправильного навыка

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

Проблема 4: Содержимое SKILL.md обрезано

Итог урока

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

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