AI Skill Development

ai-skill-development

Перед созданием или существенной правкой переносимого навыка получи ai-work-control/full; используй его решение и не дублируй контроль.

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

Обязательный порядок

1. Зафиксируй цель навыка: кто его вызовет, в какой задаче, какую ошибку он должен предотвратить и почему обычной инструкции недостаточно.
2. Проверь основание: реальная задача, повторяемая ошибка, проектный артефакт, внешний источник или другое проверяемое свидетельство.
3. Определи границы: когда навык обязан сработать, когда не должен, какие соседние навыки или правила проекта имеют приоритет.
4. Перед изменением существующего навыка прочитай целиком его SKILL.md и релевантные references/, evals/, agents/, assets/ или scripts/. Выбери класс изменения по качеству результата: локальное уточнение, переработка процедуры, перенос деталей в справку, удаление или объединение правил, обновление description, проверок или соседних материалов. Не ограничивайся добавлением нового правила, если корневая проблема в структуре навыка, порядке применения, проверяемости или устаревших частях. 4а. Для переносимого навыка проверь все поставляемые материалы на границу продукта. Оставляй только правила, примеры, данные и зависимости, нужные пользователю навыка или его проекту. Сведения из внутренней работы преобразуй в самостоятельное правило, вымышленный пример или проверку; не переноси путь, данные, настройку, процесс, средство или историю проекта-разработчика. Новую точку интеграции добавляй только с явно описанным назначением для пользователя. 4б. Если изменяется исходник публикуемого навыка в .apm/skills/**, до запуска Python или APM подключи ai-setup-apm. Этот навык отвечает за содержание и проверки навыка, а ai-setup-apm — за чистоту исходного дерева, проекций и файла блокировки при самоприменении коллекции. Не откладывай второй маршрут до момента, когда apm audit уже обнаружил дрейф.
5. Спроектируй description как маршрутизатор. Оно должно описывать намерения пользователя и ситуации загрузки, а не пересказывать внутренний процесс. Держи его достаточно коротким для бюджетов контекста и проверяй это отдельной командой коллекции, если она существует.
6. Держи SKILL.md коротким: триггеры, обязательный порядок, ограничения, умолчания и навигация к дополнительным материалам.
7. Для каждого создаваемого или изменяемого навыка отдельно оцени действия, которые можно вынести из работы модели в скрипт. Скрипт предпочтителен для повторяемой, наблюдаемой и детерминированной механики, если его создание, запуск и сопровождение дешевле повторного рассуждения модели. Не выноси в скрипт интерпретацию, неоднозначный выбор или решение владельца. Зафиксируй решение и основание; для критериев, контракта и проверки скрипта читай references/script-decision.md. 7а. Если у навыка есть или появляется scripts/**, классифицируй основной маршрут и каждый скрипт по классам P0, P1 и P2 из references/portability.md. Сохрани полезный P0 без запуска поставляемого кода, кроме навыка с неотделимой платформенной зависимостью. До P1 и P2 выполни предварительную проверку среды. При недоступности необязательной автоматизации продолжи P0 и явно назови непроверенную часть результата. Заполни поле compatibility в SKILL.md и не объявляй более широкий охват, чем подтверждает процедура. 7б. Не оставляй __pycache__, .pyc или .pyo в исходниках .apm, развёрнутых проекциях .agents, .claude, .codex, поставляемой оснастке и apm.lock.yaml. Для обычного запуска Python предпочитай PYTHONDONTWRITEBYTECODE=1, когда защита должна наследоваться дочерними процессами. Ключ -B допустим для одного подтверждённого процесса. Обе меры не останавливают явные py_compile и compileall, поэтому не применяй эти компиляторы к защищённым деревьям даже вместе с -B или переменной среды. Синтаксис проверяй чтением исходника и compile(..., mode="exec") в памяти либо поставляемым валидатором. До и после тестов и самоприменения APM запускай проверку физических деревьев и семантических путей в файле блокировки. 7в. Для каждого публичного Python-скрипта P1 первого уровня в scripts/ добавь evals/script-contract-tests.json. Сценарий запускает именно поставляемую команду в копии реалистичной фикстуры и проверяет наблюдаемый результат, а не только внутреннюю функцию, --help или ожидаемый отказ. В operations контракта объяви обязательные операции, а в covers успешного сценария укажи покрываемую операцию. Сопоставь команды из процедуры навыка с operations. Скрипт, который создаёт или изменяет состояние, обязан успешно пройти этот путь и сохранить его в проверяемом внешнем формате. Для JSON проверь повторное чтение созданного файла. Для каждой операции явно укажи inputs: перечисли условные входные файлы и настройки, которые меняют результат, либо запиши пустой массив после проверки кода. Контрактный запускатель наблюдает проверки действительно отсутствующих путей внутри успешной фикстуры. Проверка типа существующего файла или каталога с отрицательным результатом не делает путь отсутствующим входом. Запускатель исключает пути, созданные или заменённые самой операцией, и отклоняет оставшиеся необъявленные пути. Отсутствие поля не считается завершённой инвентаризацией. Подключи поставляемую команду run-skill-script-contract-tests.py к scripts.tests, если коллекция использует оснастку ai-setup-apm.
8. Выноси условные сведения в references/, повторяемую механику в scripts/, шаблоны и примеры входа в assets/.
9. Синхронизируй agents/openai.yaml, если он есть или нужен для интерфейса навыка.
10. Проверь тестовое покрытие сопровождаемого навыка по references/validation.md.
11. Сначала запускай самый узкий достаточный набор проверок: изменённый файл, каталог навыка или отдельный сценарий. Расширяй запуск до соседних навыков и всей коллекции, когда меняется маршрутизация, общая процедура, инфраструктура тестов или несколько навыков.
12. Для каждого теста результата зафиксируй, какую поверхность применения навыка он проверяет: маршрутизацию, обязательный шаг, ограничение, изменение артефакта, качество результата или остановку по правилу.
13. Не принимай тест как достаточный, если он проверяет только косвенный сигнал: формат без ошибок, наличие модельного вызова, отдельный внешний признак ответа или совпадение фрагмента без доказательства применения навыка.
14. Если тестов нет, они устарели, их не хватает или навык меняется, создай либо обнови постоянные тесты в рамках текущей правки.
15. Добавь или обнови evals/triggers.json, если меняется description, область применения или границы с соседними навыками.
16. Если проект использует автоматическую проверку бюджета description, обнови её вместе с правкой и не оставляй описание длиннее, чем нужно для маршрутизации.
17. Если постоянный тест нельзя создать в текущей задаче, явно укажи, какого теста не хватает, почему он не добавлен сейчас и какой риск остаётся. Не заменяй создание доступного теста одним предложением добавить его позже.
18. Перед созданием или изменением навыка проверь, не дешевле ли решить задачу локальной проектной инструкцией вместо нового или расширенного навыка.
19. Если изменение создаёт или меняет текст, предназначенный для человека, маршрут должен включать роль технического писателя. Это относится к инструкциям, справкам, описаниям, примерам использования, заметкам и другим человеко-ориентированным текстам независимо от имени файла и места хранения.

Что читать дополнительно

• Для проектных навыков читай references/project-specific-skills.md.
• Для проверки существующего навыка читай references/review-checklist.md.
• Для решения о скрипте читай references/script-decision.md.
• Для классов переносимости, предварительной проверки и поведения без среды выполнения читай references/portability.md.
• Для проверок срабатывания, качества результата и состава исполнимого контракта скрипта читай references/validation.md.

Читай только те справки, которые нужны для текущей задачи.

Ограничения

• Не превращай навык в переносной AGENTS.md: правила конкретного проекта, команды, Git-политики и локальные запреты должны оставаться в проекте.
• Не используй в поставляемых материалах внутренние сведения проекта-разработчика как входные данные, примеры, зависимости или скрытые предположения о среде проекта-потребителя.
• Разработка навыка не заменяет технического писателя при подготовке текста для человека.
• Не дублируй одно правило в SKILL.md и references/.
• Не фиксируй быстро меняющиеся внешние факты без процедуры проверки или обновления.
• Не делай интерпретатор, сторонний пакет, сеть или POSIX-оболочку скрытой зависимостью основного результата общего навыка.
• Если идея навыка слишком широкая или дешевле решается локальной инструкцией, прямо назови риск и предложи меньший вариант.
• Размер изменения не является мерой качества изменения навыка. Меньший вариант уместен только если он устраняет причину проблемы без ухудшения проверяемости, маршрутизации и будущей стоимости контекста.

Проверка результата

Для существенного изменения навыка сообщи:

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