Агенты и skills

Когда OpenCode начинает использоваться всерьёз, почти всегда возникает вопрос: как разделить работу по ролям и куда выносить переиспользуемое знание. Ответ — в грамотном использовании subagents и skills, но только если эти сущности спроектированы осмысленно.

Что дают встроенные агенты, а что нужно проекту добавить самому

OpenCode уже поставляется со встроенными primary agents и subagents. Этого достаточно для старта, но не всегда достаточно для зрелого проектного setup. Встроенные агенты хорошо закрывают общие сценарии: реализацию, планирование, исследование. Но как только у проекта появляется своя архитектура и своя командная модель, возникает смысл в проектных subagents.

Когда создание project-specific subagent действительно оправдано

Новый агент нужен не тогда, когда хочется «больше магии», а тогда, когда у роли появляется устойчивый operational boundary. Иначе вы просто плодите лишние промпты.

• Роль решает повторяемый тип задач.
• У роли есть своя инженерная логика и свои критерии хорошего результата.
• Есть смысл ограничить доступ к части инструментов или команд.
• Роль должна мыслить на языке конкретной предметной области проекта.

Как выглядит сильный project subagent

Хороший subagent говорит не только «я бэкенд-разработчик», а объясняет, с каким слоем проекта он работает, какие принципы обязательны и чего делать не следует. В примере ai-agent-codex это хорошо видно по агентам уровня data и backend.

---
description: Builds FastAPI and asyncio backend services that expose analytical data, filters, and realtime market updates over HH-based datasets.
mode: subagent
temperature: 0.1
steps: 12
permission:
  bash:
    "*": allow
    "git push*": ask
---

Даже один этот frontmatter уже задает важные ограничения: это не просто «любой backend», а backend над аналитическими данными и realtime market updates. Значит, агент будет мыслить в привязке к этому контексту.

Как писать хорошие prompts для агентов

Для чего вообще нужны skills

Skills в OpenCode — это не «еще одно место, куда можно положить текст». Их смысл в том, чтобы хранить on-demand playbooks. То есть знания и инструкции, которые не должны занимать базовый контекст всегда, но очень полезны в определенных типах задач.

Например, skill по requirements-spec полезен не в каждой сессии, а только когда идет проработка требований. Skill по docker-compose-local нужен не всегда, а при локальной инфраструктуре. Именно это делает skills сильным инструментом: они загружаются по ситуации.

Как отличать rules, skills и commands

Как выглядит сильный skill

---
name: docker-compose-local
description: Design a reproducible local Docker Compose setup for Airflow, PostgreSQL, and related developer workflows.
compatibility: opencode
metadata:
  audience: infrastructure-engineers
  domain: local-runtime
---
## What I do
- Define service topology and startup order.
- Recommend env vars and volume mounts.
- Keep optional services behind Compose profiles.

Обратите внимание: здесь сразу видно, когда skill использовать и какую форму мышления он даёт. Это не вики-заметка, а reusable playbook.

Каталог skills в проекте-примере

В ai-agent-codex skills разбиты достаточно логично: есть инфраструктурные, аналитические, backend-oriented и delivery-oriented. Это хороший паттерн, потому что каталог остается компактным, но при этом покрывает основные repeatable domains проекта.

Практическое правило