Skills: декларация и роутинг
повторно-используемых способностей

Что такое skill и зачем его декларировать

Skill — это объявленная единица способности агента: «я умею X». Ключевое слово — объявленная. Способность мало иметь, её надо задекларировать так, чтобы машина (другой агент, оркестратор, реестр) поняла, что агент умеет, не запуская его и не читая исходники.

Зачем разбивать агента на навыки, а не описывать одним абзацем «что я умею»:

• Обнаружение. В реестре ищут по навыкам: «кто умеет translate?». Гранулярные skills = агента находят точно под задачу.
• Роутинг. Оркестратор/LLM сопоставляет задачу с конкретным навыком, а не гадает по общему описанию.
• Переиспользование. Чётко очерченный навык подключается в разные пайплайны как кирпичик.
• Контракт. Навык — обещание: объявил — обязан выполнять. Это единица ответственности и версионирования.

Анатомия skill

Хороший навык — самоописанный. Разберём поля, которые делают его находимым и вызываемым. Набор перекликается с skills[] в Agent Card и с JSON Schema инструмента (модуль 02) — это один и тот же принцип на разных уровнях.

{
  "id": "translate_ru_en",
  "name": "Перевод RU↔EN",
  "description": "Переводит текст между русским и английским с сохранением смысла и стиля. Подходит для документов, статей, писем. НЕ юридический/медицинский перевод.",
  "tags": ["translation", "ru", "en", "text"],
  "examples": [
    "Переведи это письмо на английский",
    "Translate this article to Russian",
    "Сделай англ. версию README"
  ],
  "inputModes": ["text/plain"],
  "outputModes": ["text/plain"]
}

Обрати внимание на description: он говорит не только что навык делает, но и границы («НЕ юридический перевод»). Это спасает роутер от ложного выбора. А examples — самое недооценённое поле: именно по ним LLM-роутер и семантический поиск понимают, о чём навык, лучше, чем по сухому названию.

Роутинг: как задача находит навык

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

На практике чаще всего работает LLM-роутер: оркестратору дают список навыков (из Agent Card или MCP list_tools), а он сам решает, какой вызвать под задачу — ровно как LLM выбирает tool по JSON Schema (модуль 02).

# Собираем каталог навыков из доступных агентов/серверов
catalog = [
    {"id": "translate_ru_en", "description": "перевод RU↔EN...", "examples": [...]},
    {"id": "web_research",    "description": "поиск и выжимка...", "examples": [...]},
    {"id": "summarize",       "description": "краткое содержание...", "examples": [...]},
]

# Роутер = LLM: даём каталог + задачу, просим выбрать навык(и)
prompt = f"""Задача: {task}
Доступные навыки:
{format_skills(catalog)}
Верни id навыка(ов), которые нужно вызвать, в порядке выполнения."""

chosen = llm(prompt)   # напр. ["web_research", "summarize", "translate_ru_en"]

# Именно поэтому description и examples важны:
# роутер выбирает по СМЫСЛУ, а не по названию функции

Гранулярность: как нарезать навыки

Главный вопрос дизайна: насколько мелко дробить? Две крайности одинаково плохи.

Переиспользование: навык как кирпичик

Смысл декларации навыков раскрывается, когда один навык живёт в разных системах. Хорошо описанный summarize подключается и в исследовательский пайплайн, и в почтового ассистента, и в новостной дайджест — без переписывания.

            навык summarize (объявлен один раз)
                        │
      ┌─────────────────┼─────────────────┐
      ▼                 ▼                 ▼
исследователь      почтовый бот      новостной дайджест
(сжать выжимку)   (краткий ответ)   (аннотации статей)

один контракт → много точек переиспользования

Условия, при которых навык реально переиспользуется:

• Самодостаточность — навык не зависит от скрытого контекста конкретной системы. Всё нужное — во входных параметрах.
• Стабильный контракт — id и сигнатура не меняются капризно; изменения — через версии.
• Честные границы — description говорит, где навык применим, а где нет. Тогда его подключают уместно.
• Идемпотентность где возможно — предсказуемый навык проще встроить в разные потоки.

Типичные ошибки

Шпаргалка

SKILL = объявленная единица способности: «что умею» + «как вызвать» (НЕ «как делаю»)
  свойства: декларируемый · обнаружимый · переиспользуемый · контракт

АНАТОМИЯ:
  id              — машинный ключ, стабильный, уникальный
  name/description— для человека и LLM-роутера + ГРАНИЦЫ («НЕ делает X»)
  tags[]          — поиск/категоризация в реестре
  examples[]      — примеры запросов → роутинг по смыслу (недооценено!)
  input/outputModes — форматы (текст/файлы/JSON)

РОУТИНГ (задача → навык):
  по ключам/тегам  — точное совпадение (клиент знает навык)
  семантический    — эмбеддинги description/examples ↔ запрос
  LLM-роутер       — LLM читает каталог и выбирает (как выбор tool по schema)
  → качество роутинга = качество description/examples

ГРАНУЛЯРНОСТЬ:
  слишком крупно (do_everything) → невидим, не переиспользовать
  слишком мелко (translate_word/_sentence) → раздутый каталог, путаница
  ОРИЕНТИР: 1 навык = 1 цель, глагол, одно предложение без «и»

ПЕРЕИСПОЛЬЗОВАНИЕ: самодостаточность · стабильный контракт · честные границы

СВЯЗЬ: Agent Card skills (A2A) + MCP tools = один принцип на разных протоколах

ГРАБЛИ: пустые examples · швейцарский нож · описание без границ · нестабильный id

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

Что дальше

Ты собрал весь словарь протоколов: A2A, Agent Card, MCP, Skills. Последний урок раздела — reference flows: как эти кирпичики складываются в типовые проверенные схемы взаимодействия агентов, которые можно брать за основу.