Урок 6.1. Что такое Agent Skill

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

В модуле 5 мы разобрали Context Engineering: не нужно держать все знания проекта в giant prompt или project rules. Но тогда возникает практический вопрос: где хранить повторяемые процедуры?

Например, в проекте может быть устойчивый способ:

• добавить REST endpoint;
• создать database migration;
• написать regression test;
• провести code review;
• подготовить release note;
• проверить security-sensitive изменение;
• обновить OpenAPI contract.

Если каждый раз писать эту процедуру в prompt, она будет теряться, меняться и раздувать контекст. Если положить ее в project rules, rules быстро превратятся в энциклопедию. Skill решает эту проблему: он хранит переиспользуемый workflow и подключается только тогда, когда задача действительно этого требует.

Главная цель урока - понять, что такое Agent Skill, когда skills полезны, как выбирать skill под проект и задачу, а когда skill становится лишним слоем.

Основная идея

Agent Skill - это переиспользуемая процедура, которую агент умеет применять по необходимости.

Skill отвечает на вопрос:

Как обычно выполнять этот тип работы?

Specification отвечает на другой вопрос:

Что должно быть построено в этой feature?

Task отвечает:

Какой маленький результат нужен сейчас?

Rule отвечает:

Что агент обязан соблюдать всегда?

Tool отвечает:

Какое действие можно выполнить?

Skill находится между rules и tools. Он не является действием сам по себе, но описывает последовательность действий, проверок и ограничений для повторяемого workflow.

Ключевые термины

Как устроен skill

Типичная директория skill:

skills/
└── create-api-endpoint/
    ├── SKILL.md
    ├── references/
    │   └── api-style.md
    ├── templates/
    │   └── endpoint-test.ts
    └── scripts/
        └── verify.sh

Минимальный skill содержит SKILL.md. Дополнительные файлы нужны не всегда, но полезны, когда процедура опирается на примеры, шаблоны или проверки.

Пример назначения:

create-api-endpoint:
Использовать при добавлении или изменении REST API endpoint,
request validation, service method и API tests.

Важно: skill не должен содержать всю архитектуру проекта. Он должен описывать одну повторяемую процедуру и ссылаться на relevant references.

Progressive disclosure для skills

Skills хорошо сочетаются с Progressive Context.

Агенту не нужно читать все SKILL.md заранее. Обычно ему достаточно видеть:

Skill name
Skill description

Если текущая task совпадает с trigger, агент открывает полный skill.

Так skill не раздувает always-on context. Он становится Level 4 context из модуля 5: подключается только при необходимости.

Когда skills полезны

Skill полезен, когда работа:

• повторяется в проекте много раз;
• имеет устойчивую последовательность шагов;
• требует соблюдения локальных conventions;
• часто приводит к ошибкам у агента;
• должна заканчиваться verification;
• применима к разным features;
• слишком длинная для project rules;
• не является просто одним tool call.

Примеры хороших skills:

Skill особенно ценен там, где ошибка агента повторяется. Если агент снова и снова забывает добавлять integration test при API endpoint, это сигнал: нужен skill или existing skill нужно улучшить.

Когда skill не нужен

Skill может быть лишним, если:

• задача одноразовая;
• procedure еще не устоялась;
• достаточно короткого project rule;
• достаточно конкретной Agent Task;
• задача сводится к одному tool call;
• knowledge является feature-specific requirement;
• нет понятного trigger;
• skill будет длиннее самой задачи.

Примеры:

Правило:

Если это stable constraint -> rule.
Если это expected behavior -> spec.
Если это action -> tool.
Если это repeatable procedure -> skill.

Как выбирать skill под задачу

Выбор skill должен начинаться не с названия skill, а с анализа task.

Алгоритм:

1. Прочитать current task.
2. Определить тип работы.
3. Проверить, есть ли повторяемая procedure.
4. Найти skills с подходящим description.
5. Проверить skill fit: project, stack, scope, risk.
6. Загрузить skill только при совпадении.
7. Выполнить procedure вместе с task constraints.
8. Проверить результат по task verification.

Вопросы для выбора

Как выбирать skills под проект

На уровне проекта skills выбирают не "чем больше, тем лучше", а по повторяемым engineering workflows.

Сначала посмотрите на типовые задачи проекта:

- API endpoints
- database migrations
- UI forms
- auth/permission changes
- background jobs
- bug fixes
- code review
- documentation updates
- release preparation

Затем для каждой категории ответьте:

1. Есть ли устойчивая последовательность действий?
2. Есть ли частые ошибки у агентов?
3. Есть ли локальные conventions, которые трудно держать в rules?
4. Есть ли verification command или checklist?
5. Можно ли описать trigger в 1-2 предложениях?

Если ответы в основном "да", skill полезен.

Если procedure еще постоянно меняется, лучше сначала описать ее в docs или task examples, а skill создать позже.

Skill Fit Matrix

Перед добавлением или использованием skill оцените fit.

Оценка:

5-7 good fit signals -> skill стоит использовать или создать.
3-4 signals -> возможно, нужен reference doc или task template.
0-2 signals -> skill, скорее всего, лишний.

Пример: create-api-endpoint

Task:

TASK AUTH-017:
Добавить endpoint проверки reset token.

Skill candidate:

create-api-endpoint

Почему skill подходит:

• task добавляет API endpoint;
• нужно соблюдать controller -> service layering;
• нужно добавить/обновить tests;
• нужно сохранить error format;
• нужно проверить route behavior;
• процедура повторяется во многих features.

Как skill может вести агента:

1. Прочитать relevant spec sections.
2. Найти существующий endpoint с похожим style.
3. Определить controller/service/test files.
4. Проверить architecture constraints.
5. Написать или обновить tests.
6. Реализовать минимальный endpoint.
7. Запустить targeted tests.
8. Вернуть changed files, verification и AC status.

Но skill не решает за task:

• какой exact endpoint path использовать, если spec этого не сказал;
• какие product/security decisions принять;
• можно ли менять database schema;
• какой behavior у unknown token.

Эти решения должны быть в spec, ADR, design или clarification.

Skill precedence: что важнее

Если skill противоречит task/spec/ADR, не нужно слепо следовать skill.

Приоритет:

Safety / permissions
    ↓
Current task constraints
    ↓
Approved specification
    ↓
ADR / architecture constraints
    ↓
Skill procedure
    ↓
Agent preference

Skill - это помощь, а не верховный источник истины. Он описывает обычный workflow. Текущая task и approved source of truth могут ограничивать или переопределять его.

Пример:

Skill create-api-endpoint говорит:
"Добавь OpenAPI update".

Task говорит:
"Do not modify API contract files in this task".

Правильное поведение агента:

Остановиться или отметить follow-up task,
а не нарушать allowed scope.

Как понять, что проекту пора создать skill

Сигналы:

• команда повторяет один и тот же prompt для похожих задач;
• агенты регулярно забывают один и тот же шаг;
• review часто находит одинаковые нарушения;
• procedure длинная, но стабильная;
• есть готовые templates/scripts;
• workflow нужен в нескольких modules;
• project rules начали разрастаться процедурными деталями.

Пример:

Каждый новый endpoint требует:
- controller method;
- request validation;
- service method;
- error mapping;
- API tests;
- OpenAPI update;
- changelog note.

Если это происходит часто, create-api-endpoint skill снизит нагрузку на prompt и review.

Что должно быть внутри skill на уровне идеи

Подробно SKILL.md мы будем писать в уроке 6.3. Сейчас важно понять состав.

Хороший skill содержит:

Purpose:
Когда применять skill.

Inputs:
Какие данные нужны.

Procedure:
Какие шаги выполнить.

Constraints:
Что нельзя нарушать.

Verification:
Как доказать результат.

Failure handling:
Когда остановиться.

Supporting files:

references/
templates/
scripts/

используются только если они реально помогают procedure.

Практика: выбрать skills для проекта

Возьмите учебный проект курса: SaaS Task Manager.

Составьте файл:

labs/06-skills/project-skill-map.md

Заполните таблицу:

| Task type | Repeats? | Local conventions? | Common agent mistakes? | Verification? | Skill candidate |
|---|---|---|---|---|---|

Минимум рассмотрите task types:

• add REST API endpoint;
• create database migration;
• add React form;
• write regression test;
• perform code review;
• change authorization logic;
• update documentation.

Для каждого решите:

Use skill
Do not use skill yet
Use project rule
Use task template
Use tool only

Затем выберите 2 skills, которые стоит создать первыми для проекта.

Рекомендация для курса:

1. create-api-endpoint
2. review-code

Почему:

• API endpoints часто повторяются;
• review нужен для каждого diff;
• оба workflow легко связать с verification;
• оба помогают контролировать agent drift.

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

Ошибка 1. Создать skill на каждую мелочь

Если задача одноразовая или проще task prompt'ом, skill добавит overhead.

Ошибка 2. Делать skill слишком широким

Skill "build-feature" будет таким же размытым, как one-shot prompt. Skill должен описывать один repeatable workflow.

Ошибка 3. Класть product requirements в skill

Skill не должен знать, что password reset token действует 15 минут. Это feature spec.

Ошибка 4. Игнорировать project fit

Готовый skill может быть полезным, но его нужно проверить против stack, architecture и conventions проекта.

Ошибка 5. Использовать skill без verification

Procedure без verification превращается в инструкцию "сделай шаги", но не доказывает результат.

Ошибка 6. Считать skill заменой мышления

Skill помогает агенту следовать процедуре. Он не отменяет approved spec, task constraints, review и human gates.

Критерии готовности

После урока студент должен уметь:

• объяснить, что такое Agent Skill;
• описать структуру skill directory;
• объяснить progressive disclosure для skills;
• определить, когда skill полезен, а когда лишний;
• выбрать skill под конкретную Agent Task;
• выбрать первые skills для проекта по повторяемым workflows;
• объяснить, почему skill не заменяет spec, rule, tool и task.

Краткое резюме

Agent Skill - это переиспользуемая процедура для агента. Он помогает вынести повторяемые engineering workflows из prompt и project rules, подключая их только тогда, когда они нужны.

Skills особенно полезны для задач, которые часто повторяются, имеют локальные conventions, типовые ошибки и понятную verification.

Хороший выбор skill начинается с task и проекта:

Какая работа выполняется?
Повторяется ли она?
Есть ли устойчивый workflow?
Есть ли clear trigger?
Есть ли verification?
Не конфликтует ли skill со spec/task/ADR?

Skill должен снижать неопределенность, а не добавлять ceremony.

Вопросы для самопроверки

1. Чем skill отличается от project rule?
2. Почему skill не должен содержать feature-specific requirements?
3. Какие признаки говорят, что проекту нужен новый skill?
4. Как выбрать skill для task Добавить endpoint проверки reset token?
5. Что важнее при конфликте: task constraints или skill procedure?

Что дальше

В следующем уроке мы явно разведем Skill, Rule, Tool, MCP, Spec и Test. Это важно, потому что надежный agent workflow строится не на одном большом файле инструкций, а на правильном выборе механизма для каждого типа знания и действия.