Iron rule: do not first write a new agent and only then think about whether it should actually be a skill, or is merely 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 suitable, stop creating a new agent and hand it over to skill-creator.
- Step 2: Audit existing capabilities ⚠️ REQUIRED
- 2.1 Scan AGENTS.md, agents/, and skills/ to confirm whether there is already a highly overlapping role.
- 2.2 If it is merely an addition to an existing agent or skill, prefer adding it 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 call other agents.
- Step 4: Write or update .agent.md ⚠️ REQUIRED
- 4.1 Keep the frontmatter triggerable, and include role definition, integrated skills, reference documents, core responsibilities, and collaborative workflow in the body.
- 4.2 Do not use nonexistent document paths as mandatory reference materials.
- Step 5: Audit security and admission
- 5.1 Check whether it is highly duplicated with existing agents / skills.
- 5.2 Check whether it guides unauthorized operations, dangerous commands, or ambiguous responsibilities.
- 5.3 When review is needed, work 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 descriptions 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, prioritize considering an agent.
- When it is merely a reusable workflow, checklist, or a task with references/scripts, prioritize considering 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 nonexistent docs/ paths or fabricated processes in an agent.
Pre-delivery Checklist
- It has been clarified 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 are clear in .agent.md.
- AGENTS.md or other necessary indexes have been synced.