> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velesagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Навыки Велеса: подробный справочник

> Подробное описание того, как устроены навыки Велес, откуда они берутся, как загружаются и какие встроенные навыки доступны сейчас.

# Навыки Велеса: подробный справочник

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

Если вам нужно простое объяснение без технических деталей, начните со статьи [Навыки Велеса: простое объяснение](/skills/index_ru).

Если вас интересует практический алгоритм проведения глубокого исследования, откройте [Глубокое исследование (Deep Research)](/skills/deep_research_ru).

***

## Что такое навык в Велес

В текущей реализации навык — это директория с файлом `SKILL.md`, который содержит:

* заголовок (frontmatter) с названием и описанием;
* дополнительные метаданные;
* инструкции в формате markdown для Велеса.

Идея заключается в том, что навык не является отдельным инструментом. Это слой инструкций, работающий поверх системы инструментов (tool-системы).

То есть навык говорит Велесу:

* в каких ситуациях применять данный сценарий;
* какой именно алгоритм действий использовать;
* какие ограничения следует учитывать;
* какие инструменты задействовать;
* каких действий следует избегать.

***

## Где Велес ищет навыки

Велес загружает навыки из двух основных источников:

```mermaid theme={null}
flowchart TD
    task[Запрос пользователя] --> summary[Сводка доступных навыков в системном контексте]
    summary --> choose{Нужен конкретный навык?}
    choose -- нет --> tools[Обычные инструменты и ответ]
    choose -- да --> load[Загрузка полного SKILL.md]
    load --> req{Требования выполнены?}
    req -- нет --> explain[Сообщить, что не хватает программы, ОС или секрета]
    req -- да --> run[Выполнить сценарий навыка]
    run --> tools
```

### 1. Навыки рабочей области (навыки рабочей области)

Это каталог проекта:

* `personalities/<id>/skills/<имя-навыка>/SKILL.md` - навыки только для активной личности;
* `workspace/skills/<имя-навыка>/SKILL.md` - общие навыки workspace;

Такие навыки имеют приоритет. Если в рабочей области (workspace) существует навык с тем же именем, что и встроенный, будет использована именно версия из workspace.

### 2. Встроенные навыки (Built-in skills)

Это стандартный каталог фреймворка:

* `veles/skills/<имя-навыка>/SKILL.md`

Если активна дополнительная личность, её навыки имеют приоритет над общими навыками workspace с тем же именем. Общие навыки workspace имеют приоритет над встроенными.

Именно здесь хранятся базовые навыки, поставляемые вместе с проектом.

***

## Как навыки попадают в контекст Велеса

В процессе работы предусмотрено несколько уровней интеграции:

### 1. Краткое описание (summary) всех навыков

При формировании системного промпта (system prompt) Велес добавляет сводку доступных навыков:

* название;
* описание;
* путь к файлу `SKILL.md`;
* статус доступности;
* сведения о недостающих технических требованиях (если есть).

Это не полный текст навыков, а обзорная информация, чтобы Велес понимал общие возможности системы.

### 2. Загрузка полного текста `SKILL.md` по мере необходимости

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

Это важно по ряду причин:

* навыки загружаются только по требованию;
* полный текст всех инструкций не перегружает промпт при каждом запросе;
* система остается масштабируемой и производительной.

### 3. Навыки с постоянной доступностью (always-on)

Некоторые навыки могут быть помечены параметром `always: true`. В этом случае их содержимое попадает в активный контекст сразу при условии доступности навыка.

В текущем встроенном наборе так работает навык `memory` (память).

***

## Как определяется доступность навыка

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

* наличие необходимых программ (CLI) в системном пути (PATH);
* наличие обязательных переменных окружения;
* иные предварительные условия (prerequisites), указанные в описании.

Практические последствия:

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

***

## Какие встроенные навыки доступны сейчас

В основном каталоге `veles/skills/` представлены следующие направления:

* `deep-research`
* `perplexity-search`
* `memory`
* `cron`
* `entrez-search`
* `fda-database`
* `weather`
* `summarize`
* `github`
* `google-workspace`
* `clawhub`
* `alor-calendar`
* `skill-creator`
* `tmux`
* `web-development`

Ниже приведено краткое описание каждого.

Быстрые ссылки на страницы навыков:

* [Навык: Глубокое исследование](/skills/deep_research_ru)
* [Навык: Память](/skills/memory_ru)
* [Навык: Cron (Расписание)](/skills/cron_ru)
* [Навык: Entrez Search (NCBI)](/skills/entrez_search_ru)
* [Навык: FDA Database](/skills/fda_database_ru)
* [Навык: Perplexity Search](/skills/perplexity_search_ru)
* [Навык: Погода](/skills/weather_ru)
* [Навык: Summarize (Выжимки)](/skills/summarize_ru)
* [Навык: GitHub](/skills/github_ru)
* [Навык: Google Workspace](/skills/google_workspace_ru)
* [Навык: ClawHub (Каталог)](/skills/clawhub_ru)
* [Навык: ALOR Calendar](/skills/alor_calendar_ru)
* [Навык: Tmux (Терминал)](/skills/tmux_ru)
* [Навык: Создание навыков](/skills/skill_creator_ru)
* [Навык: Веб-разработка](/skills/web_development_ru)

***

## Краткий каталог встроенных навыков

### `deep-research`

Назначение:

* проведение полноценных глубоких исследований по заданным темам;
* многошаговый процесс (pipeline) с подготовкой итогового структурированного отчёта.

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

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

### `perplexity-search`

Назначение:

* специализированный сценарий поиска в сети через OpenRouter и использование модели `perplexity/sonar-pro`.

### `memory`

Назначение:

* инструкции для Велеса по работе с долгосрочной памятью, файлом `MEMORY.md`, сводками и механизмами припоминания (recall).

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

* является одним из ключевых навыков системы;
* работает в режиме постоянной доступности (always-on).

### `cron`

Назначение:

* помощь в корректном использовании планировщика задач и расписаний.

### `entrez-search`

Назначение:

* поиск литературы и биомедицинских записей через NCBI Entrez E-utilities;
* работа с PubMed, PMC, Gene, Protein, Nuccore, ClinVar, PubChem, MeSH и SNP;
* построение медицинских запросов с MeSH, publication type и date-фильтрами.

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

* API-ключ NCBI опционален и хранится как секрет `skills.entrez-search.env.NCBI_API_KEY`;
* отсутствие ключа не выключает навык, но оставляет обычный лимит запросов NCBI.

### `fda-database`

Назначение:

* поиск официальной информации FDA/openFDA о лекарствах и таблетках;
* работа с label, NDC, recalls/enforcement, Drugs\@FDA approvals, shortages, FAERS adverse events и substances/UNII;
* проверка medication safety facts до пациентских ответов.

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

* API-ключ openFDA опционален и хранится как секрет `skills.fda-database.env.OPENFDA_API_KEY`;
* перед персональным советом о лекарствах навык требует `memory_search`, чтение `docs/myhealth` при наличии и многоисточниковую проверку;
* FAERS используется только как safety-signal источник, не как доказательство причинности или частоты событий.

### `weather`

Назначение:

* алгоритм получения актуальных данных о погоде и прогнозов.

### `summarize`

Назначение:

* создание кратких пересказов содержимого ссылок, локальных файлов, PDF-документов и видео с YouTube.

### `github`

Назначение:

* решение задач на GitHub через интерфейс командной строки `gh` и связанные автоматизированные процессы.

### `google-workspace`

Назначение:

* работа с почтой Gmail, календарём, диском, контактами, таблицами и документами Google;
* пошаговая настройка доступа через OAuth 2.0 с обновлением токена;
* единый командный скрипт для чтения, поиска, создания и изменения данных после явного подтверждения пользователя.

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

* хранит файл клиента Google, токен и временное состояние авторизации в зашифрованном хранилище секретов Велеса;
* требует `VELES_SECRETS_MASTER_KEY` для записи и чтения локальных секретов;
* перед отправкой писем, созданием или удалением событий, изменением документов, таблиц и прав доступа требуется подтверждение пользователя;
* может использовать установленную программу `gws`, а без неё работает через библиотеки Google для Python.

### `clawhub`

Назначение:

* поиск и установка новых навыков из открытого каталога.

### `alor-calendar`

Назначение:

* чтение и управление Outlook/Exchange календарём ALOR через EWS;
* использование настроек и учетных данных из существующей конфигурации email-канала;
* просмотр, поиск и создание календарных событий после явного подтверждения пользователя.

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

* требует Python-пакеты `exchangelib` и `python-dateutil`;
* по умолчанию использует `Europe/Moscow`;
* операции изменения календаря требуют подтверждения, потому что меняют внешнюю систему.

### `skill-creator`

Назначение:

* помощь в проектировании и корректной упаковке новых навыков. Полезен, если вы хотите добавить собственный сценарий в рабочую область (workspace).

### `tmux`

Назначение:

* управление сессиями tmux для интерактивной или параллельной работы (актуально для Linux/macOS).

### `web-development`

Назначение:

* руководство (guidance) по задачам создания и развития веб-проектов.

***

## Чем навыки отличаются от инструментов на практике

Критическое различие заключается в следующем:

### Инструмент (Tool)

Это атомарная операция.
Примеры: `read_file`, `web_search`, `exec`, `session_history`.

### Навык (Skill)

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

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

***

## Deep Research как особый случай

Глубокое исследование заметно выделяется на фоне остальных навыков.

Причины:

* большая продолжительность выполнения;
* высокая потребность во времени и ресурсах;
* необходимость предварительного уточнения темы;
* сложная структура процесса (не сводится к паре действий);
* результатом является отдельный аналитический документ.

Поэтому для него выделена отдельная страница документации, а не просто раздел в общем обзоре.

***

## Что важно для автора собственного навыка

Исходя из текущей архитектуры, качественный навык должен:

* четко описывать контекст своего применения;
* опираться на существующие инструменты, не дублируя их логику;
* содержать информацию об ограничениях и типичных ошибках (anti-patterns);
* предоставлять Велесу понятный алгоритм действий;
* описывать необходимые предварительные условия (prerequisites).

Именно эти факторы делают навык рабочим инструментом, а не просто объемным текстовым файлом.

***

## Практические выводы

Текущая система навыков Велес обладает рядом преимуществ:

* позволяет расширять возможности без изменения основного кода;
* поддерживает как встроенные, так и пользовательские навыки;
* оптимизирует использование ресурсов, подгружая инструкции по требованию;
* учитывает особенности локального окружения;
* идеально подходит для сложных повторяющихся процессов.

Однако стоит учитывать:

* наличие навыка не гарантирует, что всё внешнее окружение уже настроено;
* эффективность работы напрямую зависит от качества написанных инструкций.

***

## Итог

В Велес навыки образуют интеллектуальный слой над инструментами:

* инструменты предоставляют возможности для действий;
* навыки задают логику и процесс выполнения;
* встроенные навыки обеспечивают базовую функциональность «из коробки»;
* навыки рабочей области позволяют адаптировать систему под специфику конкретного проекта или команды.

Если нужен обычный пользовательский взгляд, достаточно страницы [Навыки Велеса: простое объяснение](/skills/index_ru).

Если нужен сложный исследовательский алгоритм, открывайте [Глубокое исследование (Deep Research)](/skills/deep_research_ru).