2026 OpenHands Skills или AGENTS.md? Как выбрать для iOS-репозитория

Если правила должны видеть все задачи, оставьте их в коротком AGENTS.md; если знания нужны только для конкретного фреймворка или операции, вынесите их в OpenHands Skills. Это работает для iOS-репозитория только при одном условии: сборка Xcode, подпись, тесты на симуляторе и проверка устройства проходят через отдельную Mac-приёмку, а не подтверждаются текстом инструкции.

Последнее обновление: 6 сентября 2026 года. Актуальность названий Skills, статуса старых Microagents-путей и рекомендаций по AGENTS.md сверена с официальным обзором OpenHands Skills и руководством по Skill в SDK.

Эта статья предназначена для трёх групп. Владельцам репозитория она помогает закрепить общие правила OpenHands. iOS-разработчикам — оформить процесс, который загружается только при мобильных задачах. Платформенным и командам безопасности — определить, кто управляет порядком загрузки, скриптами, инструментами и правами.

Начните с границы ответственности, а не с формата файла

Вопрос «OpenHands Skills или AGENTS.md?» нельзя решать только по объёму текста. Главный критерий — насколько широко правило должно действовать и кто отвечает за его актуальность.

AGENTS.md — это постоянный контекст репозитория. В нём уместны:

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

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

OpenHands Skills решают другую задачу. Skill описывает специализированное знание: например, как анализировать Swift-модуль, выбрать тестовый target, диагностировать ошибку схемы или подготовить изменения для конкретного iOS-процесса. Такой материал не обязан загружаться для задачи по документации, серверному коду или простой правке конфигурации.

Проблема возникает, когда одна и та же команда копируется в оба места. Тогда обновление AGENTS.md не меняет старый Skill, а Skill может незаметно вернуть устаревший способ сборки. В результате агент получает не «более подробные инструкции», а две конкурирующие версии политики.

Практическое правило простое: постоянное и общее — в AGENTS.md; условное и предметное — в Skill; доказательство фактического результата — в журнале CI или Mac-приёмки.

Владельцы репозитория: что должно оставаться в AGENTS.md

Поддерживайте AGENTS.md как контракт минимального уровня. В нём не нужно пересказывать внутреннюю документацию Apple, объяснять каждую ошибку компилятора или хранить длинный сценарий выпуска. Эти сведения быстро устаревают и увеличивают контекст каждой задачи.

Хороший базовый файл отвечает на пять вопросов:

1. Что находится в репозитории и какие изменения считаются допустимыми?
2. Где расположены приложение, пакеты, тесты и скрипты?
3. Как установить зависимости без ручного угадывания?
4. Какие проверки обязательны до создания коммита?
5. Какие действия запрещены без отдельного подтверждения?

Команды Xcode можно упомянуть на минимальном уровне, если они действительно являются общим входом для большинства изменений. Например, в базовом правиле допустимо указать, какая схема является основной и какой тестовый target должен быть затронут. Но полный набор параметров лучше не фиксировать без проверки проекта.

Apple отдельно описывает настройку build schemes в Xcode, поэтому правило должно ссылаться на реальные схемы проекта, а не на название, придуманное для инструкции. Сверяйте это с документацией Apple по настройке схем сборки.

Для каждого пункта задайте владельца. Структуру каталогов поддерживает команда репозитория, CI-команды — платформа, ограничения на секреты — безопасность. Если у пункта нет владельца, он почти неизбежно станет устаревшим исключением.

iOS-разработчики: специализированный процесс переносится в Skill

iOS Skill должен быть не энциклопедией Swift, а операционной инструкцией для конкретных задач. Его описание должно позволять OpenHands понять, когда Skill нужен: изменение SwiftUI-экрана, работа с определённым модулем, исправление тестов, обновление схемы или подготовка сборки для проверки.

Внутри Skill полезно разделить материал на уровни:

• условия применения — по каким словам задачи или путям репозитория его следует рассмотреть;
• точка входа — проектный файл, workspace, схема и тестовый target;
• порядок проверки — какие изменения просмотреть до запуска;
• диагностика — как различать ошибку исходного кода, зависимостей, схемы и среды;
• выходной результат — патч, список изменённых файлов, команды, логи и невыполненные проверки.

Описание Skill должно быть достаточно точным для выбора, но не превращаться в копию AGENTS.md. Если базовое правило требует не менять файл с секретами, iOS Skill не должен повторять этот запрет пять раз. Он должен сослаться на общий контракт и добавить только мобильную часть.

Нельзя считать установленную версию Xcode, состояние симулятора или наличие сертификата фактом только потому, что они перечислены в SKILL.md. Skill направляет агента, но не заменяет выполнение. Для интерпретации результата используйте официальное описание запуска тестов и чтения результатов в Xcode.

Команды, связанные с подписью и публикацией, разделяйте по риску. Обычная сборка и локальный тест не должны автоматически давать доступ к сертификатам, профилям или секретам CI. Если Skill вызывает скрипт, проверьте, какие переменные окружения он читает и какие каталоги может изменять.

Платформа и безопасность: загрузка правил должна быть видимой

Главная ошибка при масштабировании OpenHands — считать порядок загрузки очевидным. Проектные правила, пользовательские Skills и старые каталоги могут пересекаться по названию, назначению и области действия. Поэтому платформа должна документировать не только расположение файлов, но и фактический результат для одинаковой задачи.

Проверяйте четыре свойства:

• какое правило применяется на уровне репозитория;
• какие пользовательские Skills доступны агенту;
• какие старые Microagents-пути ещё поддерживаются или считаются устаревшими;
• что происходит при совпадении имён и противоречии инструкций.

На дату этой публикации OpenHands использует Skills как актуальное название, а отдельные Microagents-пути в официальной документации отмечены как старый или устаревающий формат. Это не означает, что каждый старый материал нужно немедленно удалить. Сначала сохраните обратный путь, зафиксируйте ожидаемый результат и сравните поведение на одинаковой задаче до и после миграции. Для деталей SDK сверяйтесь с официальным руководством по архитектуре Skill.

Общий Skill для нескольких репозиториев должен иметь:

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

Полезен эксперимент с двумя одинаковыми задачами: одна меняет небольшой Swift-файл, другая намеренно вызывает проверку схемы. Сравните не только итоговый патч, но и фактически загруженные инструкции, команды, обращения к инструментам и список пропущенных проверок. Если после миграции агент делает «правильный» патч, но перестал запускать обязательную проверку, миграция не завершена.

Безопасность Skill начинается за пределами Markdown

Файл SKILL.md может выглядеть безобидно, но связанный с ним скрипт способен изменить больше, чем написано в тексте. Поэтому аудит должен охватывать весь пакет:

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

Проверяйте не только успешный сценарий. Нужны отрицательные тесты: отсутствующий сертификат, неизвестный путь, поврежденный файл конфигурации, недоступный симулятор, пустая переменная окружения и команда с неожиданным параметром. Без этого команда видит лишь «зелёный» путь и не знает, как Skill поведёт себя в аварийном режиме.

Для опасных команд можно применять отдельные Hooks и запреты, но они не заменяют ревизию Skill. Официальная документация OpenHands по настройке Hooks и контролю действий полезна как часть общей модели, однако итоговое решение всё равно должно подтверждаться журналом выполнения.

Независимая Mac-приёмка отделяет инструкцию от результата

Результат OpenHands следует передавать на Mac не как фразу «тесты пройдены», а как комплект проверяемых артефактов:

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

Сборку, тесты симулятора, подпись и публикационные разрешения не объединяйте в одну кнопку. У них разный уровень риска и разные требования к доступу. Изменение Swift-кода может пройти обычную сборку и тесты, но это не доказывает корректность signing settings или готовность к установке на физическое устройство.

Если у команды нет постоянно доступного Mac для проверки, это не повод расширять AGENTS.md обещаниями вроде «агент обязан убедиться, что приложение запускается». Текстовое правило не создаёт Xcode, симулятор, сертификат или физическое устройство. Сначала выполните низкорисковую задачу и проверьте передачу артефактов, а затем решайте, нужен ли отдельный удалённый Mac. Для оценки такого сценария можно изучить варианты аренды Mac mini для удалённой разработки.

Частые вопросы

OpenHands Skills и AGENTS.md решают разные задачи

AGENTS.md отвечает за неизменный минимум, который должен быть виден всем задачам. OpenHands Skills добавляют контекст только тогда, когда задача действительно требует специализированной процедуры. Разделение уменьшает дублирование, облегчает ревизию и позволяет не загружать каждый запрос подробностями iOS-инструментария.

Старые Microagents требуют анализа, а не слепого переноса

Переносите не файл целиком, а его ответственность. Постоянные ограничения возвращаются в AGENTS.md, специализированные инструкции становятся Skills, а скрипты и инструменты проходят отдельную проверку. На время миграции оставляйте обратный путь и сравнивайте фактическую загрузку на одной и той же задаче.

Команды Xcode должны быть короткими в базовом файле

В AGENTS.md оставляйте только общий вход, если он нужен почти каждой задаче. Подробности о workspace, схемах, тестовых целях, диагностике и окружении переносите в iOS Skill. Фактические версии и доступность устройств проверяйте в проекте или CI, а не принимайте на веру по инструкции.

Skill может включать исполняемые ресурсы, но это увеличивает риск

Связанные скрипты, справочные файлы и настройки инструментов допустимы, если у них есть владелец и процедура аудита. Проверяйте права, пути, динамические данные, MCP-вызовы и секреты. Разрешение на выполнение должно быть минимальным, а вывод — доступным для последующей проверки.

Сводное сравнение перед внедрением

По пяти практическим критериям схема получает следующую оценку:

Чек-лист перед включением схемы

• [ ] В AGENTS.md оставлены только правила, применимые к большинству задач.
• [ ] Для каждого постоянного правила указан источник проверки в репозитории или CI.
• [ ] iOS Skill имеет описание, по которому агент может определить условия вызова.
• [ ] В Skill нет второй, расходящейся версии базовых ограничений.
• [ ] Названия workspace, схемы и test target сверены с реальным проектом.
• [ ] Версия Xcode и состояние симулятора проверяются в среде, а не предполагаются по тексту.
• [ ] Команды сборки, тестирования и подписи разделены по уровню доступа.
• [ ] Скрипты Skill проверены на права, пути, переменные окружения и MCP-вызовы.
• [ ] Для миграции с Microagents сохранён временный путь возврата.
• [ ] Одинаковая тестовая задача выполнена до и после изменения загрузки правил.
• [ ] В Mac-приёмку передаются патч, зависимости, команды и журналы.
• [ ] Невыполненные проверки явно отмечены и не заменяются утверждением агента.

На практике вариант «только AGENTS.md» кажется проще, но быстро превращается в длинный файл с условиями, исключениями и устаревшими командами. Вариант «только Skills» лучше масштабируется по технологиям, однако оставляет без общего контракта базовые ограничения репозитория. Для iOS-команды наиболее устойчивой остаётся трёхслойная модель: короткий AGENTS.md, специализированные OpenHands Skills и отдельная Mac-приёмка.

Если локальный Mac уже занят разработчиками, нестабилен для длительных проверок или не предоставляет безопасный доступ к нужной Apple-среде, удалённая рабочая станция может быть разумнее попытки расширить полномочия агента. При этом аренда Mac не отменяет разделение правил: она лишь даёт место для воспроизводимой Xcode-проверки после работы OpenHands. Перед решением сравните срок задачи, требования к физическому устройству, чувствительность signing-данных и необходимость постоянной нагрузки; для временного тестового окружения можно рассмотреть аренду Mac через SSHMac, сохранив независимую проверку каждого результата.