Agent Creation Skill

Overview

Provides actionable instructions for creating standards-compliant agent definitions using templates. Agents are defined in markdown files (AGENTS.md) with YAML frontmatter specifying metadata and a clear, readable structure. This skill enforces context gathering before agent creation to ensure robust and well-defined agents.

Objective

Enable agents and users to generate agent definitions that strictly follow the required structure and conventions using the provided template. Ensure sufficient context is gathered through clarifying questions before proceeding with agent creation. Validate each agent against the JSON schema and provide a compliance checklist to ensure all requirements are met.

When to Use

Use this skill when:

•Creating a new agent definition from scratch
•Setting up project-specific agents
•Documenting agent workflows and responsibilities
•Defining agent context and skill requirements

Don't use this skill for:

•Creating individual skills (use skill-creation instead)
•Creating context prompts (use prompt-creation instead)
•Modifying existing agents without full context

References

Instructions

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)
- •Link to Mandatory Skills table
•## Mandatory Skills (REQUIRED): Table with triggers, required skills, and paths. Use format: | Trigger (When to Read) | Required Skill | Path |
•## Supported stack (if applicable): List technologies, frameworks, libraries, and versions used in the project.
•## Skills Reference (optional but recommended): Table listing all skills with descriptions and paths.
•## Workflows (optional): Common workflows the agent handles (e.g., "Feature Development," "Code Review").
•## Policies (optional): Project-specific rules, constraints, or guidelines the agent must follow.

Step 5: Writing Guidelines

•Write all content in English with American spelling
•Use only ASCII apostrophes (') and hyphens (-)
•Ensure consistent punctuation, spacing, and capitalization
•Be token-efficient: precise and concise without losing specificity
•Use clear, direct language for both AI and human readers
•Organize content with proper markdown structure

Step 6: Validation

Before finalizing, verify:

Example: Complete Agent Definition

markdown

---
name: example-agent
description: Development assistant for Example Project. Provides guidance on TypeScript, React, and accessibility standards.
skills:
  - typescript
  - react
  - critical-partner
  - process-documentation
  - conventions
  - a11y
---

# Example Project Agent

## Purpose

This agent serves as the primary development assistant for the Example Project, ensuring code quality, accessibility compliance, and adherence to TypeScript and React best practices.

## Supported stack

- **Languages**: TypeScript 5.0+, JavaScript (ES2020+)
- **Framework**: React 18+
- **Build**: Vite

## Skills Reference

| Skill Name            | Description                 | Path                                  |
| --------------------- | --------------------------- | ------------------------------------- |
| typescript            | TypeScript best practices   | skills/typescript/SKILL.md            |
| react                 | React patterns and hooks    | skills/react/SKILL.md                 |
| critical-partner      | Code review and improvement | skills/critical-partner/SKILL.md      |
| process-documentation | Change documentation        | skills/process-documentation/SKILL.md |
| conventions           | General coding conventions  | skills/conventions/SKILL.md           |
| a11y                  | Accessibility standards     | skills/a11y/SKILL.md                  |

## Workflows

### Feature Development

1. Gather requirements
2. Design component architecture
3. Implement with TypeScript and React
4. Ensure accessibility compliance
5. Document changes

## Policies

- All code must be strictly typed (no `any`)
- Components must be keyboard-accessible
- Follow React hooks best practices

Compliance Checklist

References

•skill-creation: Creating new skills
•critical-partner: Code review guidance
•process-documentation: Change documentation