| name | gaia-agents |
| description | Use this skill to create, revise, audit, or rationalize Gaia custom-agent definitions when role boundaries, naming, descriptions, tool scopes, delegation rules, or overlap concerns need maintenance. Use it when adding a role, evaluating whether a new role is justified, expanding an existing role, rewriting agent instructions, or aligning agent files to the global contract. Do not use it to bypass architecture decisions or to create new roles just because one workflow feels inconvenient. Its output is a clear agent definition set with strong descriptions, explicit boundaries, valid tool scopes, and no unnecessary role duplication. |
| license | MIT |
Gaia Agents
Scope and when to use
Use this skill to keep Gaia's custom agents clear, distinct, and aligned with
the global contract.
Use this skill when:
- adding or revising a custom agent definition
- auditing role overlap or ambiguous tool scopes
- rewriting agent descriptions or instructions for better invocation quality
- aligning agent files to a new shared contract or architecture update
Do not use this skill when:
- the missing step is still an architecture decision
- an existing role can be extended cleanly without creating a new one
- the change belongs in reusable procedural guidance instead of a role definition
Required inputs
- the current agent roster and
AGENTS.md
- the purpose, scope, and intended users of the proposed role change
- required tools, MCP servers, and any access constraints
- any overlapping definitions or maintenance pain the change is meant to solve
Owned outputs
- valid agent definitions with clear names and scopes
- decision-grade descriptions that explain when to invoke or avoid each role
- explicit role boundaries, delegates, and anti-patterns
- overlap decisions that explain why a role was added, merged, or rejected
Decision tree
- If the gap is global policy, update
AGENTS.md instead of a role file.
- If an existing role can absorb the behavior cleanly, revise it rather than create a new role.
- If a truly new role is needed, define its mission, adjacent roles, tools, and failure boundaries explicitly.
- If tool access is unclear, make it explicit before considering the definition complete.
Core workflow
- Read the agent specification and current roster before editing anything.
- Identify whether the change is global contract work or local role work.
- Test the proposal against neighboring roles to avoid overlap.
- Write or revise the agent with clear mission, use-when rules, delegates, and anti-patterns.
- Confirm that the role improves routing instead of adding organizational noise.
New-agent justification checklist
- what gap exists that current agents do not already cover cleanly
- why expanding an existing role would be worse than creating a new one
- what explicit invocation signal should trigger the new role
- what tool scope is truly necessary and how overlap will be prevented
Failure recovery
| Failure mode | Recovery | Owner | Escalation |
|---|
| overlap with existing role | merge or narrow the proposal | maintainer | reject new role if still redundant |
| unclear tool scope | define least-privilege access | maintainer | block adoption until explicit |
| weak description | rewrite for invocation quality | maintainer | compare against neighboring roles |
| contract mismatch | update local role or contract as appropriate | maintainer | involve architecture if the operating model changed |
Anti-patterns
- do not create a new agent because one current role feels temporarily overloaded
- do not leave delegation or tool access implied
- do not store global policy inside every role file
- do not let role descriptions stay too short to drive good invocation choices
Handoff and downstream impact
- tell maintainers whether the change belongs in
AGENTS.md or only in local role files
- tell engineering when agent maintenance requires direct file edits after design approval
- tell architecture when a role change implies a workflow-model change
- tell skill maintainers when procedural guidance must be updated to match a role rewrite
Examples
- Good fit: rewrite all six Gaia agents to a shared execution template after the contract layer changes.
- Good fit: decide whether a proposed analyzer role is actually needed or should be folded into intake and architecture.
- Not a fit: define planning procedures or architecture artifacts; those belong to skills and docs.
Completion checklist
- every changed role has a clear mission and anti-mission
- tool scopes and delegation rules are explicit
- role overlap has been reduced rather than increased
- local role files align with the global contract
References
