Creating Agents

Overview

This skill provides capabilities for creating and reviewing agent definition files (agents.md / agent.md) that transform a general-purpose AI assistant into a focused specialist. Agent definitions give an AI coding agent a specific persona, project knowledge, executable commands, and explicit boundaries.

A well-written agent definition follows the principle: specific beats vague. "You are a helpful coding assistant" fails. "You are a test engineer who writes tests for React components, follows these examples, and never modifies source code" succeeds.

This skill is informed by analysis of over 2,500 agents.md files across public repositories (source).

Capabilities

| Capability | Action | Description | |------------|--------|-------------| | Create | actions/create.md | Generate a new agent definition with persona, commands, and boundaries | | Review | actions/review.md | Analyse an existing agent definition for quality and completeness |

Standards

This skill bundles the following standards in standards/:

| Standard | File | Description | |----------|------|-------------| | Agent Structure | agent-structure.md | Required sections and organisation for agent definitions | | Persona | persona.md | Writing effective agent personas and role definitions | | Boundaries | boundaries.md | Defining always-do, ask-first, and never-do rules | | Commands and Tools | commands-and-tools.md | Documenting executable commands agents can run | | Code Style | code-style.md | Providing code examples and style guidance to agents | | Checklist | checklist.md | Consolidated compliance and quality checklist |

Principles

1. Specific Beats Vague

Every successful agent definition gives the agent a clear, narrow job. State the exact role, tech stack with versions, file paths, and commands. Ambiguity leads to unpredictable behavior.

2. Show, Don't Tell

One real code snippet showing your preferred style beats three paragraphs describing it. Provide concrete examples of good output — naming conventions, error handling patterns, test structures.

3. Commands Early, Boundaries Clear

Put executable commands (npm test, pytest -v, cargo build) near the top of the agent definition. Agents reference these often. Define boundaries using a three-tier system: ✅ Always do, ⚠️ Ask first, 🚫 Never do.

4. Cover the Six Core Areas

The best agent definitions address six areas:

1. Commands — Executable commands with flags and options
2. Testing — Test framework, commands, and coverage expectations
3. Project structure — File layout and what lives where
4. Code style — Naming, patterns, and concrete examples
5. Git workflow — Branch naming, commit messages, PR process
6. Boundaries — What the agent must never touch

5. Start Small, Iterate

Begin with a minimal agent definition for one specific task. Test it with real work. Add detail when the agent makes mistakes. The best agent definitions grow through iteration, not upfront planning.

Usage

1. Load this skill manifest
2. Identify the required capability (create or review)
3. Load the bundled standards from standards/
4. Execute the action following actions/<capability>.md

References

• How to write a great agents.md — Lessons from over 2,500 repositories
• GitHub Copilot Custom Agents — Official documentation
• Agent Skills Specification — Open format for agent capabilities