Урок 6.2. Skill vs Rule vs Tool

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

В прошлом уроке мы определили skill как переиспользуемую процедуру для агента. Но в agentic development рядом со skills есть еще несколько сущностей: rules, tools, MCP, specs, tasks и tests.

Если смешать их в один файл, быстро возникает хаос:

• project rules превращаются в книгу;
• skill начинает хранить product requirements;
• tool используется как источник знаний;
• MCP server получает слишком широкие права;
• tests заменяются словами "агент проверил";
• specification смешивается с implementation procedure.

Этот урок нужен, чтобы научиться выбирать правильный механизм для каждого типа знания или действия. Отдельный акцент: как scripts и MCP могут дополнять skill, стоит ли это делать, как tools добавляются в agent workflow и как организовать это в репозитории.

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

В agent workflow разные механизмы отвечают на разные вопросы.

Главное правило:

Не кладите все в skill.
Не кладите все в rules.
Не превращайте каждый script в MCP.

Сначала определите природу знания или действия, потом выбирайте механизм.

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

Rule

Rule - это короткое стабильное ограничение.

Пример:

Controllers must not import database client directly.

Rule должен быть:

• коротким;
• применимым ко многим tasks;
• проверяемым;
• стабильным;
• безопасным для always-on context.

Rule не должен быть процедурой на 40 шагов. Если правило начинает объяснять "как добавить endpoint", это уже кандидат на skill.

Skill

Skill - это procedure.

Пример:

create-api-endpoint:
1. Прочитать feature spec.
2. Найти existing endpoint pattern.
3. Определить controller/service/test files.
4. Добавить или обновить tests.
5. Реализовать endpoint.
6. Запустить targeted verification.
7. Вернуть changed files, commands, AC status.

Skill полезен, когда workflow повторяется и содержит последовательность шагов. Он может быть просто текстовой процедурой в SKILL.md, а может иметь supporting files: references, templates, scripts.

Важно: skill не является tool. Он может сказать агенту "запусти script", но сам факт существования skill не дает агенту новых прав.

Tool

Tool - это действие, доступное agent runtime.

Примеры:

read_file(path)
edit_file(path, patch)
run_tests(command)
search_repository(query)
query_database(sql)
create_github_issue(...)
deploy_preview(...)

Tool должен иметь:

• понятный input;
• понятный output;
• permission boundary;
• auditability для важных действий;
• failure behavior.

Tool отвечает "что можно выполнить", а skill отвечает "в какой последовательности и зачем это выполнять".

MCP

MCP - это способ подключить внешние tools/resources/prompts к agent application через стандартный интерфейс.

Пример:

Agent
  ↓
MCP client
  ↓
MCP server
  ├── tools: query_database, create_issue
  ├── resources: schema://db, docs://api
  └── prompts: review_prompt

MCP нужен не для каждого script. Он полезен, когда capability:

• внешняя;
• переиспользуемая несколькими agents/tools;
• требует authentication/scopes;
• имеет structured schema;
• должна быть controlled и audited;
• предоставляет не только action, но и resources.

Если задача решается локальной командой:

npm test

MCP чаще всего не нужен.

Spec, Task и Test

Skill не должен подменять source of truth.

Spec:
Token действует 15 минут.

Task:
Добавить test для expired token.

Skill:
Как писать regression test в этом проекте.

Tool:
Запустить test command.

Test:
Проверить expired token behavior.

Если в skill записать "token действует 15 минут", skill станет feature-specific и быстро устареет.

Схема: кто за что отвечает

Spec и task говорят агенту, что делать сейчас. Rules ограничивают поведение всегда. Skill описывает процедуру. Tools/scripts/MCP выполняют действия. Tests и review проверяют результат.

Skill как prompt-процедура

Самый простой skill - это структурированный prompt, сохраненный в SKILL.md.

Он содержит:

Purpose
Inputs
Procedure
Constraints
Output
Verification
Failure handling

Такой skill полезен, даже если не содержит scripts или tools.

Пример:

review-code skill:
1. Read spec.
2. Read diff.
3. Check spec compliance.
4. Check architecture compliance.
5. Check tests.
6. Report findings by severity.

Это просто procedure. Но она уже полезна, потому что стандартизирует review.

Когда достаточно prompt-процедуры:

• task требует reasoning/review;
• действия выполняются обычными доступными tools;
• нет повторяемого script;
• verification command задается task;
• workflow легко описать текстом.

Skill + scripts

Skill может включать scripts рядом с SKILL.md.

Пример:

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

Зачем scripts внутри skill:

• автоматизировать повторяемую проверку;
• сгенерировать шаблон;
• нормализовать формат output;
• уменьшить количество ручных шагов;
• сделать procedure менее зависимой от памяти агента.

Пример instructions в SKILL.md:

Verification:
1. Run task-specific tests from Agent Task.
2. If API contract changed, run:
   skills/create-api-endpoint/scripts/check-openapi.sh
3. Include command output and exit code in final response.

Важно: script inside skill - это файл. Чтобы он реально выполнился, agent runtime должен иметь tool/permission для shell command или script execution.

Skill не должен прятать опасные действия в script.

Плохо:

scripts/deploy-production.sh

который запускается как часть обычного endpoint skill.

Лучше:

scripts/check-openapi.sh
scripts/generate-test-template.sh
scripts/validate-migration-name.sh

Scripts в skill должны быть:

• идемпотентными, если возможно;
• безопасными по умолчанию;
• локальными;
• понятными;
• с явным output;
• без secrets;
• без destructive actions.

Skill + MCP

Skill может использовать MCP, но важно правильно понимать связь.

Обычный skill не "устанавливает MCP server" сам по себе. Skill может:

• указать, что для процедуры нужен определенный MCP tool/resource;
• описать, когда его использовать;
• описать expected input/output;
• предупредить о permissions;
• сказать, когда нужен human approval.

Пример:

Skill: database-migration-review

Requires:
- database schema resource from MCP, read-only

Procedure:
1. Read migration diff.
2. Read schema://current from MCP resource.
3. Check backward compatibility.
4. Do not run write queries.
5. Report risks.

MCP server подключается на уровне agent harness, plugin, workspace или runtime configuration. Skill только использует уже доступную capability или документирует prerequisite.

Когда skill + MCP полезны:

• procedure зависит от external system;
• нужен read-only access к schema/docs/logs;
• tools должны быть доступны нескольким agents;
• нужна structured capability с permissions;
• действие нельзя надежно заменить локальным script.

Когда skill + MCP не нужен:

• достаточно прочитать локальный файл;
• достаточно запустить npm test;
• capability нужна один раз;
• нет authentication/permissions;
• MCP добавляет больше сложности, чем контроля.

Как tools добавляются

Tools добавляются не в skill как текст, а в agent environment.

Типовые способы:

Skill должен описывать, какие tools нужны, но не должен предполагать, что они всегда доступны.

Хорошая формулировка:

Required tools:
- repository search
- file read/edit
- shell command for tests

Optional tools:
- OpenAPI validator script
- API docs MCP resource

If a required tool is unavailable:
- stop and report the missing capability.

Как организовать tools и scripts в репозитории

Рекомендуемая структура:

project/
├── PROJECT.md
├── docs/
│   └── development/
│       ├── tool-policy.md
│       └── mcp-policy.md
├── scripts/
│   ├── verify
│   ├── test
│   └── lint
├── skills/
│   ├── create-api-endpoint/
│   │   ├── SKILL.md
│   │   ├── references/
│   │   ├── templates/
│   │   └── scripts/
│   └── review-code/
│       └── SKILL.md
├── tools/
│   └── mcp/
│       └── README.md
└── agent-config/
    └── README.md

Идея разделения:

Не смешивайте:

• общий scripts/verify и scripts конкретного skill;
• MCP server code и SKILL.md;
• secrets и tool configuration;
• feature requirements и skill procedure.

Стоит ли добавлять scripts в skill

Добавляйте script в skill, если:

• script повторяется во многих tasks этого типа;
• script безопасен и локален;
• script делает проверку более надежной;
• script имеет понятный output и exit code;
• script не требует secrets;
• script не выполняет destructive actions;
• script проще поддерживать рядом со skill.

Не добавляйте script в skill, если:

• он нужен всему проекту, а не одному skill;
• он deploy/delete/write-production;
• он зависит от локальной машины автора;
• он требует credentials;
• он скрывает сложную business logic;
• проще вызвать существующий project script.

Правило:

Project-wide automation -> scripts/
Skill-specific helper -> skills/<skill>/scripts/
External controlled capability -> MCP/tool config

Стоит ли добавлять MCP к skill

Добавляйте MCP dependency к skill, если:

• procedure требует external context;
• нужен controlled access к external service;
• capability переиспользуется разными agents;
• read/write permissions должны быть явно ограничены;
• нужен audit trail;
• resource лучше предоставить structured way, чем копировать в prompt.

Не добавляйте MCP dependency, если:

• skill может работать по локальным файлам;
• нужен только shell command;
• нет clear permission model;
• MCP server будет оберткой над одним trivial script;
• setup complexity выше пользы.

Skill должен gracefully degrade:

If MCP resource is unavailable:
- use local spec/design files if sufficient;
- otherwise stop and report missing context.

Decision table

Практика: классифицировать 15 примеров

Классифицируйте каждый пример:

Rule | Skill | Tool | MCP | Spec | Task | Test | Eval | Script

Примеры:

1. Всегда использовать UTC для server timestamps.
2. Как добавить REST endpoint в этом проекте.
3. npm test -- auth.
4. Token password reset действует 15 минут.
5. Получить database schema из external staging database.
6. Проверить, что controller не импортирует database client.
7. Добавить endpoint проверки reset token.
8. Запустить scripts/verify.
9. Создать GitHub issue.
10. Reviewer должен проверять spec compliance перед code style.
11. Agent всегда останавливается при изменении files outside allowed scope.
12. Как писать regression test для bug fix.
13. Test: expired token returns TOKEN_EXPIRED.
14. Eval: agent adds tests when creating endpoint.
15. Script: validate OpenAPI file against schema.

Итоговый артефакт:

labs/06-skills/skill-rule-tool-classification.md

Для каждого пункта объясните:

Почему это выбранный механизм?
Почему не skill/rule/tool?
Где это должно жить в репозитории?

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

Ошибка 1. Skill как свалка всего

Если skill содержит product behavior, architecture history, tool config, secrets и procedure, он становится giant prompt.

Ошибка 2. Rule как длинная процедура

Rules должны быть короткими. Длинные workflows лучше выносить в skills.

Ошибка 3. Tool без policy

Если tool может писать, удалять, deploy'ить или менять permissions, нужна явная policy и approval.

Ошибка 4. MCP для каждого script

MCP полезен для external controlled capabilities, но не нужен для обычного npm test.

Ошибка 5. Script без verification contract

Script должен иметь понятный exit code и output. Иначе агенту трудно использовать его как evidence.

Ошибка 6. Skill предполагает tools, которых нет

Если skill требует MCP или shell, а agent environment этого не дает, workflow сломается. Skill должен описывать required capabilities и fallback.

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

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

• отличить rule, skill, tool, MCP, spec, task, test, eval и script;
• объяснить, когда skill является просто prompt-процедурой;
• объяснить, когда к skill стоит добавить scripts;
• объяснить, как skill может использовать MCP и почему он не устанавливает MCP сам;
• описать, как tools добавляются в agent environment;
• предложить структуру репозитория для skills, scripts, tool policies и MCP docs;
• классифицировать практические примеры по правильным механизмам.

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

Skill нужен для повторяемой процедуры. Иногда это просто хорошо написанный SKILL.md: prompt-процедура с inputs, steps, constraints, output и verification. Иногда skill получает supporting files: references, templates и scripts. Иногда skill использует MCP tools/resources, но MCP подключается на уровне agent environment, а не магически внутри skill.

Правильное разделение:

Rule -> stable constraint
Skill -> repeatable procedure
Tool -> executable action
MCP -> standardized external capabilities
Spec -> expected behavior
Task -> one current outcome
Test -> software verification
Eval -> agent process verification

Если механизм выбран правильно, контекст остается чистым, agent workflow становится повторяемым, а результат проще проверить.

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

1. Чем skill отличается от tool?
2. Когда skill может быть просто prompt-процедурой без scripts?
3. Когда script лучше положить в scripts/, а когда в skills/<skill>/scripts/?
4. Почему skill не должен сам "добавлять MCP"?
5. Когда MCP оправдан, а когда это overengineering?

Что дальше

В следующем уроке мы перейдем к практике написания SKILL.md: разберем metadata, purpose, inputs, preconditions, procedure, constraints, output, verification и failure handling.