Skip to main content
Навыки (Skills) упаковывают специфичные для задачи инструкции, которые Harvi Code загружает по требованию, когда твой запрос соответствует назначению навыка. В отличие от пользовательских инструкций, которые применяются ко всему, навыки активируются только когда нужны — это делает Harvi Code более эффективным в специализированных задачах без засорения базового промпта.

​
Зачем это нужно

Пользовательские инструкции применяются широко ко всей работе. Они отлично подходят для общих стандартов кодирования или предпочтений стиля, но не идеальны для специфичных workflow вроде “обработка PDF файлов” или “генерация API документации”. Навыки решают это: Создай навык для обработки PDF, и Harvi Code загрузит эти инструкции только когда ты действительно попросишь работать с PDF. Это держит системный промпт сфокусированным и даёт Harvi Code глубокую экспертизу в конкретных областях без влияния на несвязанные задачи. Ты не можешь упаковать связанные ресурсы (скрипты, шаблоны, справочники) с пользовательскими инструкциями. Навыки позволяют хранить связанные файлы рядом с инструкциями, создавая самодостаточные пакеты workflow.

​
Что позволяют навыки

  • Экспертиза для конкретных задач: Упаковывай детальные инструкции для специализированных workflow (обработка данных, генерация документации, паттерны миграции кода)
  • Связанные ресурсы: Включай вспомогательные скрипты, шаблоны или справочные файлы рядом с инструкциями
  • Таргетинг по режимам: Создавай навыки, которые активируются только в конкретных режимах (например, навыки рефакторинга только в режиме Code)
  • Командная работа: Храни навыки проекта в .harvi/skills/ под контролем версий для консистентных workflow команды
  • Личная библиотека: Создай глобальную библиотеку навыков в ~/.harvi/skills/, которая работает во всех проектах
  • Контроль переопределения: Навыки проекта переопределяют глобальные, специфичные для режима переопределяют общие

​
Как работают навыки

Навыки используют прогрессивное раскрытие для эффективной загрузки контента только когда нужно: Уровень 1: Обнаружение — Harvi Code читает каждый файл SKILL.md и парсит его frontmatter для извлечения name и description. Только эти метаданные хранятся для сопоставления — полное содержимое не держится в памяти до необходимости. Уровень 2: Инструкции — Когда твой запрос соответствует описанию навыка, Harvi Code использует read_file для загрузки полных инструкций SKILL.md в контекст. Уровень 3: Ресурсы — Промпт сообщает Harvi Code, что могут быть доступны связанные файлы (скрипты, шаблоны, справочники) рядом с навыком. Нет отдельного манифеста ресурсов — Harvi Code обнаруживает эти файлы по требованию, когда инструкции ссылаются на них. Эта архитектура означает, что навыки остаются неактивными до активации — они не раздувают твой базовый промпт. Можешь установить много навыков, и Harvi Code загрузит только релевантные для каждой задачи.

​
Создание первого навыка

​
1. Выбери расположение

Глобальные навыки (доступны во всех проектах): 
# macOS/Linux
~/.harvi/skills/{имя-навыка}/SKILL.md

# Windows
%USERPROFILE%\.harvi\skills\{имя-навыка}\SKILL.md
Навыки проекта (специфичны для текущего workspace): 
<корень-проекта>/.harvi/skills/{имя-навыка}/SKILL.md

​
2. Создай директорию и файл навыка

# Пример: навык обработки PDF
mkdir -p ~/.harvi/skills/pdf-processing
touch ~/.harvi/skills/pdf-processing/SKILL.md

​
3. Напиши файл SKILL.md

Файл требует frontmatter с name и description: 
---
name: pdf-processing
description: Извлечение текста и таблиц из PDF файлов с помощью Python библиотек
---

## Инструкции по обработке PDF

Когда пользователь запрашивает обработку PDF:

1. Проверь, установлены ли PyPDF2 или pdfplumber
2. Для извлечения текста используй pdfplumber для лучшего определения таблиц
3. Для простых текстовых PDF достаточно PyPDF2
4. Всегда обрабатывай ошибки кодировки корректно
5. Предложи сохранить извлечённый контент в файл

## Шаблон кода

[Твои детальные паттерны кода здесь]

## Частые проблемы

- Зашифрованные PDF: Объясни, что требуется параметр пароля
- Отсканированные PDF: Рекомендуй OCR инструменты вроде pytesseract
- Большие файлы: Предложи постраничную обработку
Правила именования:
  • Поле name должно точно совпадать с именем директории (или именем символической ссылки)
  • Имена должны быть 1–64 символа, только строчные буквы/цифры/дефисы
  • Без начальных/конечных дефисов, без последовательных дефисов (например, my--skill недопустимо)
  • Оба поля name и description обязательны
  • Описания должны быть 1–1024 символа (обрезаются)
  • Описание сообщает Harvi Code, когда использовать этот навык — будь конкретным

​
4. Протестируй навык

Спроси Harvi Code что-то, соответствующее описанию: 
"Можешь помочь мне извлечь таблицы из этого PDF файла?"
Harvi Code должен распознать, что запрос соответствует описанию навыка, загрузить файл SKILL.md и следовать его инструкциям.

​
Структура директорий

​
Базовая структура

~/.harvi/skills/                    # Глобальные навыки
├── pdf-processing/
│   ├── SKILL.md                   # Обязательно
│   ├── extract.py                 # Опционально: связанные скрипты
│   └── templates/                 # Опционально: связанные файлы
│       └── output-template.md
└── api-docs-generator/
    └── SKILL.md

.harvi/skills/                      # Навыки проекта (переопределяют глобальные)
└── custom-pdf-workflow/
    └── SKILL.md

​
Навыки для конкретных режимов

Создавай навыки, которые активируются только в определённых режимах: 
~/.harvi/skills-code/              # Только в режиме Code
└── refactoring-patterns/
    └── SKILL.md

.harvi/skills-architect/           # Только в режиме Architect
└── system-design-templates/
    └── SKILL.md

~/.harvi/skills-{режим}/           # Любой режим
Когда использовать навыки для конкретных режимов:
  • Паттерны рефакторинга кода (только режим Code)
  • Шаблоны системного дизайна (только режим Architect)
  • Стандарты документации (специфичны для режима написания документации)

​
Приоритет переопределения

Когда навыки с одинаковым именем существуют в нескольких местах, применяется такой приоритет:
  1. Проект, специфичный для режима (.harvi/skills-code/my-skill/)
  2. Проект, общий (.harvi/skills/my-skill/)
  3. Глобальный, специфичный для режима (~/.harvi/skills-code/my-skill/)
  4. Глобальный, общий (~/.harvi/skills/my-skill/)
Это означает, что общий навык проекта переопределяет специфичный для режима глобальный навык — расположение проекта имеет приоритет над специфичностью режима. Это позволяет:
  • Устанавливать глобальные стандарты, работающие везде
  • Переопределять их для конкретного проекта при необходимости
  • Специализировать навыки для конкретных режимов внутри каждого расположения

​
Обнаружение навыков

Harvi Code автоматически обнаруживает навыки:
  • При запуске: Все навыки индексируются чтением и парсингом каждого SKILL.md
  • Во время разработки: Наблюдатели файлов обнаруживают изменения в файлах SKILL.md
  • Фильтрация по режимам: Доступны только навыки, релевантные текущему режиму
Не нужно регистрировать или настраивать навыки — просто создай структуру директорий.

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

Навыки поддерживают символические ссылки для совместного использования библиотек навыков между проектами: 
# Совместное использование библиотеки навыков между проектами
ln -s /shared/company-skills ~/.harvi/skills/company-standards
Имя навыка берётся из имени символической ссылки (или имени директории, если не используется ссылка). Поле name в frontmatter должно точно совпадать с этим именем — нельзя создавать алиасы с разными именами, указывающими на один навык.

​
Решение проблем

​
Навык не загружается

Симптом: Harvi Code не использует твой навык, даже когда ты запрашиваешь что-то, соответствующее описанию. Причины и решения:
  1. Несовпадение имён: Поле name в frontmatter должно точно совпадать с именем директории
  2. Отсутствуют обязательные поля: Оба поля name и description обязательны в frontmatter
  3. Неправильный режим: Если навык в skills-code/, но ты в режиме Architect, он не загрузится
  4. Слишком расплывчатое описание: Делай описания конкретными, чтобы Harvi Code мог сопоставить их с запросами

​
Навык загружается, но не помогает

Симптом: Harvi Code читает навык, но не следует инструкциям. Причина: Инструкции могут быть слишком общими или не хватает критических деталей. Решение: Делай инструкции действенными:
  • Включай конкретные имена функций или выбор библиотек
  • Предоставляй шаблоны кода
  • Перечисляй частые крайние случаи и как их обрабатывать
  • Добавляй руководство по решению проблем для конкретной задачи

​
Конфликт нескольких навыков

Симптом: Неясно, какой навык Harvi Code будет использовать, когда несколько могут подойти. Причина: Пересекающиеся описания или конфигурации режимов. Профилактика:
  • Делай описания различными и конкретными
  • Используй директории для конкретных режимов для разделения задач
  • Полагайся на приоритет переопределения — навыки проекта переопределяют глобальные

​
Навыки vs Пользовательские инструкции vs Slash-команды

ФункцияНавыкиПользовательские инструкцииSlash-команды
Когда загружаютсяПо требованию (когда запрос соответствует)Всегда (часть базового промпта)По требованию (при вызове)
Лучше дляСпецифичных для задачи workflowОбщих стандартов кодированияПолучения предварительно написанного контента
Могут включать файлыДаНетНет
Таргетинг по режимамДа (skills-{режим} директории)Да (rules-{режим} директории)Нет
Приоритет переопределенияПроект > Глобальный, Режим > ОбщийПроект > ГлобальныйПроект > Глобальный
ФорматSKILL.md с frontmatterЛюбой текстовый файлJSON метаданные + контент
ОбнаружениеАвтоматическое (сканирование директорий)Автоматическое (сканирование директорий)Автоматическое (сканирование директорий)
Когда использовать каждое:
  • Навыки: “Генерировать API документацию по спецификации OpenAPI” → Детальные инструкции обработки OpenAPI загружаются только когда нужно
  • Пользовательские инструкции: “Всегда использовать TypeScript strict mode” → Применяется ко всей работе с TypeScript
  • Slash-команды: /init → Возвращает стандартизированные инструкции настройки проекта
Используй навыки для создания специализированной экспертизы Harvi Code в конкретных областях!