creating-agents

# 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](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/)).

## 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](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/) — Lessons from over 2,500 repositories
- [GitHub Copilot Custom Agents](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot) — Official documentation
- [Agent Skills Specification](https://agentskills.io/specification) — Open format for agent capabilities