Iron rule: do not write a new agent first and then think about whether it should actually be a skill, or just an addition to an existing role.
Workflow
- Step 1: Determine whether it should be carried by a skill or an agent ⚠️ REQUIRED
- 1.1 Load references/admission-guide.md, and first determine whether this is a reusable workflow, or requires context isolation and multi-role orchestration.
- 1.2 If a skill is more appropriate, stop creating a new agent and hand it off to skill-creator.
- Step 2: Audit existing capabilities ⚠️ REQUIRED
- 2.1 Scan AGENTS.md, agents/ and skills/, and confirm whether a highly overlapping role already exists.
- 2.2 If it is merely an addition to an existing agent or skill, prefer adding to the original file rather than creating a new directory.
- Step 3: Design the agent boundary
- 3.1 Clarify the agent's responsibilities, inputs, outputs, handoff relationships and things it is not responsible for.
- 3.2 Clarify which skills it integrates and whether it needs to invoke other agents.
- Step 4: Write or update .agent.md ⚠️ REQUIRED
- 4.1 Keep the frontmatter triggerable, and include in the body the role definition, integrated skills, reference documents, core responsibilities and collaborative workflow.
- 4.2 Do not use non-existent document paths as mandatory reference materials.
- Step 5: Audit security and admission
- 5.1 Check whether it highly duplicates existing agents / skills.
- 5.2 Check whether it encourages unauthorized operations, dangerous commands or ambiguous responsibilities.
- 5.3 When review is needed, coordinate with code-reviewer to perform a structure and security audit.
- Step 6: Sync the project index
- 6.1 Update the agent/skill list and positioning description in AGENTS.md.
- 6.2 If what is added is a governance-type role, clarify its admission rules and management boundaries.
Core Rules
- When context isolation, multi-role collaboration, phased handoff or dedicated governance responsibilities are needed, prefer an agent.
- When it is merely a reusable workflow, checklist or task with references/scripts, prefer a skill.
- When high overlap with existing capabilities is found, by default add to the existing skill or agent rather than creating a new item.
Anti-patterns
- Using an agent to solve a problem for which a skill is actually more suitable.
- Creating a new agent that is almost duplicate of an existing role just to "look complete".
- Writing an agent as an all-purpose executor with no boundaries.
- Referencing non-existent docs/ paths or fabricated processes in an agent.
Pre-delivery checklist
- It is clear whether this is a skill problem or an agent problem.
- Existing skills / agents have been audited, confirming this is not a highly overlapping addition.
- Responsibilities, boundaries, handoff relationships and integrated skills in .agent.md are clear.
- AGENTS.md or other necessary indexes have been synced.