Step 1: Gather Context (CRITICAL - DO NOT SKIP)
Before creating an agent definition, you MUST ask clarifying questions when context is missing. Do not proceed until you have sufficient information.
Required context to gather:
- What is the primary purpose of this agent?
- What type of input will the agent receive? (e.g., files, text, objects, user queries)
- What is the expected output format? (e.g., markdown, JSON, text, files)
- Which skills does the agent need to accomplish its tasks?
- Are there any specific workflows, policies, or constraints the agent must follow?
- Who is the target audience for this agent? (e.g., developers, end-users, AI assistants)
- What technologies, frameworks, or tools will the agent interact with?
- What is the project context where this agent will operate?
- Are there any tone or communication style requirements? (e.g., formal, casual, technical)
Do not proceed with creating the agent until you have:
- A clear understanding of the agent's purpose and responsibilities
- Defined input and output formats (if applicable)
- Identified all required skills
- Understood any special policies, constraints, or workflows
- Gathered sufficient context about the project environment
Step 2: Directory and File Structure
- Create a new directory under
agents/ named after the project or agent (lowercase, hyphens, no spaces). - Add an
AGENTS.md file inside the directory.
Step 3: YAML Frontmatter
The frontmatter must include:
Required fields:
- name: Agent identifier (lowercase, hyphens only, e.g.,
my-project-agent). Keep concise. - description: Clear, concise explanation of purpose and responsibilities. Token-efficient: eliminate redundancy, keep specificity.
- skills: List required skills using YAML
- item syntax (never []). Must be existing skills from skills/ directory.
- Mandatory for ALL agents: Always include critical-partner
- Mandatory for technical/management agents: Always include process-documentation
Optional fields (include only if they add specificity):
- input: Expected input type/format (e.g.,
"user query | string"). Omit if obvious from description. - output: Expected output type/format (e.g.,
"markdown report"). Omit if obvious from description.
Formatting rules:
- Use YAML list syntax:
- item (never [] for arrays) - Omit empty fields completely
- Be precise and token-efficient: every word must serve AI and human understanding
Example frontmatter:
```yaml
---
name: my-project-agent
description: Development assistant for Project X. Expert in TypeScript, React, and MUI.
skills:
- typescript
- react
- mui
- critical-partner
- process-documentation
- conventions
- a11y
---
```
Step 4: Content Structure
After the frontmatter, include the following sections:
- # Agent Name (h1): Title describing the agent (e.g., "SBD Project Agent").
- ## Purpose: Clear statement of the agent's primary goal and responsibilities. Be specific and actionable.
- ## β οΈ Mandatory Skill Reading (REQUIRED): Critical instructions for reading skills before task execution. Must include:
- Skill Reading Protocol (5-step process)
- Warning about not proceeding without reading skills
- Notification Policy for multi-skill tasks (2+ skills)
- Reference to Extended Mandatory Read Protocol in AGENTS.md
- Link to Mandatory Skills table
- ## Mandatory Skills (REQUIRED): Table with triggers, required skills, and paths. Use format:
| Trigger (When to Read) | Required Skill | Path |
Critical trigger that MUST be included in all agents:
- "Write commit messages, PRs, or documentation" β technical-communication
Additional triggers based on agent's skills: Add specific triggers for each skill the agent uses (e.g., "Create React components" β react, "Create TypeScript types" β typescript)
Important: The Mandatory Skill Reading section must inform AI agents that when working with complex skills (40+ patterns), they should consult the skill's Decision Tree and Quick Reference Table to determine if reading references/ is required. See [AGENTS.md Extended Mandatory Read Protocol](../../AGENTS.md#extended-mandatory-read-protocol) for complete guidance. 5. ## Supported stack (if applicable): List technologies, frameworks, libraries, and versions used in the project. 6. ## Skills Reference (optional but recommended): Table listing all skills with descriptions and paths. 7. ## Workflows (optional): Common workflows the agent handles (e.g., "Feature Development," "Code Review"). 8. ## Policies (optional): Project-specific rules, constraints, or guidelines the agent must follow.
Step 5: Writing Guidelines
All generated code, documentation, comments, and prompt content must follow the [english-writing](../english-writing/SKILL.md) skill. Do not duplicate these rules here.
- Be token-efficient: precise and concise without losing specificity
- Organize content with proper markdown structure (headings, lists, code blocks, tables)
Step 6: Validation
Before finalizing, verify:
- [ ] Directory created under
agents/ with correct naming - [ ]
AGENTS.md file exists with proper frontmatter - [ ] Required fields:
name, description, skills - [ ]
critical-partner included in skills (mandatory for ALL agents) - [ ]
process-documentation included for technical/management agents - [ ] All referenced skills exist in
skills/ directory - [ ] Skills use YAML list syntax (
- item), not arrays ([]) - [ ] Empty fields omitted
- [ ] Content sections present: Purpose, and others as appropriate
- [ ] Token-efficient documentation: no redundancy
- [ ] Content in English with American spelling
---
|