Creating Custom Agents and Skills
Relevant source files
The following files were used as context for generating this wiki page:
Everything Claude Code (ECC) provides a modular framework for extending AI capabilities through specialized agents and domain-specific skills. This system allows developers to codify team practices, automate workflows, and create specialized assistants for various programming languages and frameworks.
Customization is achieved through two primary mechanisms: Agents, which are specialized assistants with defined toolsets and roles, and Skills, which serve as knowledge modules containing guidelines, patterns, and examples that Claude loads based on the current context.
Sources: AGENTS.md:3-8, CONTRIBUTING.md:41-43, CLAUDE.md:14-17
Agent Development
Agents in ECC are specialized sub-assistants designed to handle domain-specific tasks such as code reviews, security analysis, or build resolution. They are defined using Markdown files with YAML frontmatter to specify their operational parameters.
Agent Configuration
Each agent requires a YAML frontmatter block at the top of its Markdown file located in the agents/ directory.
| Field | Description | Required |
|---|---|---|
name | Lowercase, hyphenated unique identifier | Yes |
description | Specific criteria for when Claude should invoke the agent | Yes |
tools | List of allowed tools (e.g., Read, Write, Edit, Bash, Grep, Glob) | Yes |
model | Target complexity level (haiku, sonnet, or opus) | Yes |
Sources: CONTRIBUTING.md:109-114, RULES.md:14-18
Agent Workflow and Roles
The body of the agent file defines its persona and the step-by-step logic it must follow. A standard agent template includes a defined role, boundaries (what it does NOT do), and a three-step workflow: Understand, Execute, and Verify.
The diagram above illustrates the orchestration flow where the main assistant delegates a task to a specialized agent based on the agent's description.
Sources: AGENTS.md:57-65, CONTRIBUTING.md:92-107
Skill Development
Skills are modular knowledge bases used for "auto-activation" by Claude Code. They provide the necessary context for specific technologies, architectures, or internal workflows.
Skill Structure and Location
Skills are stored in the skills/ directory, with each skill having its own subdirectory containing a SKILL.md file.
skills/
└── your-skill-name/
└── SKILL.md
Sources: CONTRIBUTING.md:47-51, RULES.md:20-22
The SKILL.md Template
A skill file must contain specific sections to ensure effectiveness and proper discovery by the AI:
- When to Activate: Critical for auto-activation; describes the scenarios for use.
- Core Concepts: Explanation of patterns and guidelines.
- Code Examples: Practical, copy-pasteable snippets.
- Anti-Patterns: Examples of what to avoid.
- Best Practices: Actionable do's and don'ts.
Sources: CONTRIBUTING.md:53-77, RULES.md:23-25
Automatic Skill Generation
Developers can use the /skill-create command to automatically generate skills based on their repository's git history. This process analyzes commit messages, file change patterns, and folder structures to extract project-specific conventions.
The sequence above shows the automated process of extracting team practices from git history to create new skills.
Sources: commands/skill-create.md:9-25, CLAUDE.md:37
Validation and Surface Policies
ECC enforces strict policies for where workflows and skills should reside to maintain cross-harness compatibility.
Workflow Surface Policy
- Skills Directory: The canonical surface for all new workflows.
- Commands Directory: Reserved for legacy compatibility or shims required for migration.
- Codex Integration: Skills intended for Codex must be placed in
.agents/skills/and follow specific frontmatter constraints, including mandatoryname,description, andallowed-toolskeys.
Sources: AGENTS.md:126-130, tests/ci/codex-skill-surface.test.js:14-20
Testing and Quality Standards
All new agents and skills must adhere to the core principles of the project:
- Security-First: No hardcoded secrets or sensitive data.
- Technical Accuracy: Code examples must be tested and accurate.
- Immutability: Skills should encourage immutable updates over shared state mutation.
- Size Limits: Files should typically be 200-400 lines, with a maximum of 800 lines.
Sources: AGENTS.md:11-15, AGENTS.md:88-91, RULES.md:4-12
Summary
Creating custom agents and skills in ECC allows for a highly tailored development environment. By following the standardized templates for agents/*.md and skills/*/SKILL.md, developers ensure their specialized knowledge is properly leveraged by Claude. Whether manually crafted or automatically extracted via /skill-create, these modules form the backbone of a project-aware AI assistant.