Skip to content
Skills Library
AI & agents · Building & coding

create-agent

/create-agent

Repo-specific SOP for adding a new agent to this repository — the frontmatter contract the auto-generated router feeds on (name, description one-liner, tier, model, tools, kb_domains, stop conditions, escalation targets), the thin-executor default, category placement, and the router/build/docs ship checklist. Use when the user wants to create an agent, add a new agent to this repository, or asks for a new specialist agent. Do not use for creating skills (use create-skill) or KB domains (use /create-kb); to decide whether an agent is even the right layer, run the component-model skill first — m

Repository
agentspec ↗
Licence
MIT
Last repository change
08.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 08.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Repo-specific SOP for adding a new agent to this repository — the frontmatter contract the auto-generated router feeds on (name, description one-liner, tier, model, tools, kb_domains, stop conditions, escalation targets), the thin-executor default, category placement, and the router/build/docs ship checklist. Use when the user wants to create an agent, add a new agent to this repository, or asks for a new specialist agent. Do not use for creating skills (use create-skill) or KB domains (use /create-kb); to decide whether an agent is even the right layer, run the component-model skill first — m

Original author description

Repo-specific SOP for adding a new agent to this repository — the frontmatter contract the auto-generated router feeds on (name, description one-liner, tier, model, tools, kb_domains, stop conditions, escalation targets), the thin-executor default, category placement, and the router/build/docs ship checklist. Use when the user wants to create an agent, add a new agent to this repository, or asks for a new specialist agent. Do not use for creating skills (use create-skill) or KB domains (use /create-kb); to decide whether an agent is even the right layer, run the component-model skill first — m

How it works

  1. Division of labor
  2. When to use / Skip if
  3. The agent contract (frontmatter)
  4. Thin executor by default
  5. Ship checklist
  6. References
Original SKILL.md headings · 122 lines, 1,351 words
SKILL.md preview
---
name: create-agent
description: |
  Repo-specific SOP for adding a new agent to this repository — the frontmatter
  contract the auto-generated router feeds on (name, description one-liner, tier,
  model, tools, kb_domains, stop conditions, escalation targets), the thin-executor
  default, category placement, and the router/build/docs ship checklist. Use when
  the user wants to create an agent, add a new agent to this repository, or asks
  for a new specialist agent. Do not use for creating skills (use create-skill) or
  KB domains (use /create-kb); to decide whether an agent is even the right layer,
  run the component-model skill first — most "new agent" requests turn out to be
  new skills plus a thin executor.
---

# Create an Agent (repo conventions)

Agents are the EXECUTION layer of the component model: identity, tool scope, model tier, stop conditions, escalation — a thin shell around capabilities. The scaffold and tier rules are owned by `.claude/agents/_template.md`; the layer decision is owned by the component model. This skill carries the repo mechanics between those two: the frontmatter contract as the router reads it, the thin-executor default, and the checklist an agent passes before it ships.

## Division of labor

| Concern | Owner |
|---|---|
| Is an agent even the right layer? | the `component-model` skill (gate), grounded in `.claude/kb/shared/component-model.md` |
| Section structure, tier line budgets, section-by-tier requirements | `.claude/agents/_template.md` (copy it) + `.claude/agents/README.md` |
| The methodology the agent executes | a skill, authored via `create-skill` |
| Frontmatter contract, router coupling, ship checklist | this skill |

## When to use / Skip if

**First, run the layer gate.** Before writing anything, apply the `component-model` skill (or read `.claude/kb/shared/component-model.md`). Most "new agent" asks are actually new skills plus a thin executor: if the request is "teach the system HOW to do X", that is a skill — the agent, if one is needed at all, is only the WHO (identity, tools, boundaries).

Use this skill when:

- Adding a new specialist agent under `.claude/agents/`.
- Splitting an overloaded agent into two roles with distinct tool scopes or KB domains.

Skip if:

- The capability is methodology or how-to knowledge → `create-skill`.
- The content is reference truth (facts, standards, deep dives) → `/create-kb`.
- An existing agent already covers most of the capability → extend it instead; apply the four-condition gate in `.claude/agents/README.md` ("When NOT to Create an Agent" — no existing agent covers >60%, unique KB/tool combination, ≥3 distinct triggers, no >80% overlap).
- Undecided which layer the logic belongs in → the `component-model` skill first.

## The agent contract (frontmatter)

The frontmatter is machine-read, not decoration. `scripts/generate-agent-router.py` regenerates the `agent-router` skill (SKILL.md + routing.json) from every agent's frontmatter — it extracts `name`, `tier`, `model`, the **first line** of `description`, `kb_domains`, and every `escalation_rules` `target:`. Write these as routing signals.

| Field | Required | Contract |
|---|---|---|
| `name` | all tiers | Kebab-case, matches the filename, `{tech\|domain}-{role}` style: `dbt-specialist`, `code-cleaner`, `fabric-architect`. |
| `description` | all tiers | Literal block (`\|`). The first line is extracted verbatim as the agent's routing one-liner — write it as the routing sentence, not a teaser. Second line: `Use PROACTIVELY when {triggers}.` Then two example blocks per house convention (Context / user / assistant). |
| `tier` | all tiers | `T1` utility (80-150 lines) / `T2` domain expert (150-350) / `T3` platform specialist (350-600). Governs which template sections are required — see the tier guide comment in `_template.md`. |
| `model` | optional | Defaults to `sonnet`. Pick the cheapest tier that does the job: `haiku` for fast pattern work, `sonnet` for most agents, `opus` only where the judgment is genuinely complex. |
| `tools` | all tiers | Least privilege — scope to what the role needs. A read-only analyst gets no `Write`/`Edit`; grant `Bash` only if the role runs commands; include `Task` only for delegating agents (the build-phase executor is the precedent). |
| `kb_domains` | all tiers | Domains this agent reads. Every entry must exist in `.claude/kb/_index.yaml`; use `[]` if none. Feeds the router's KB-domain reverse index. |
| `color` | all tiers | One of blue, green, orange, purple, red, yellow. |
| `anti_pattern_refs` | all tiers | `[shared-anti-patterns]` → `.claude/kb/shared/anti-patterns.md`. |
| `stop_conditions` | T2+ | Conditions that make the agent halt or refuse and return control. |
| `escalation_rules` | T2+ | trigger / target / reason entries. Every `target:` must be a real agent `name` (or `user`) — the router builds the handoff graph from these, so a typo is a broken route. |
| `mcp_servers` | T3 optional | name / tools / purpose per server dependency. |

### Parser pitfalls

The router's parser is line-based, not a full YAML load. Silent failure modes:

- `kb_domains` must be the inline form `[a, b]` — a block-style YAML list is ignored, and the agent ships with no domains in the router.
- Escalation targets are read only from `target:` lines inside the `escalation_rules:` block, and must be lowercase kebab-case.
- `name`, `tier`, `model` must be single-line scalars; `description` must be a literal block (`|`) or a single line.
- The one-liner extractor takes the first non-blank description line and stops at example markers (`Example`, `**Example`, `-`, `Context`, `user:`, `assistant:`) — keep line one clean, complete, and self-contained.

### Worked example (thin T2 specialist)

```yaml
---
name: duckdb-specialist
description: |
  DuckDB specialist for local analytics, larger-than-memory queries, and Parquet-first pipelines.
  Use PROACTIVELY when users work with DuckDB, .duckdb files, or local OLAP queries.

  Example 1 — User wants warehouse-free analytics:
  user: "Query these Parquet files without spinning up a warehouse"
  assistant: "I'll use the duckdb-specialist agent to build the DuckDB query."

  Example 2 — User hits a memory limit:
  user: "My DuckDB aggregation runs out of memory"
  assistant: "Let me invoke the duckdb-specialist to configure spilling and rewrite the query."

tier: T2
model: sonnet
tools: [Read, Write, Edit, Grep, Glob, Bash, TodoWrite]
kb_domains: [modern-stack]
anti_pattern_refs: [shared-anti-patterns]
color: yellow
stop_conditions:
  - Query validated against sample data, results returned
  - Task requires a distributed engine — out of scope
escalation_rules:
  - trigger: Workload outgrows a single machine
    target: spark-engineer
    reason: Distributed processing is the Spark lane
---
```

From this contract the router derives: the one-liner (description line one), a `modern-stack` reverse-index entry, and a `duckdb-specialist` → `spark-engineer` edge in the handoff graph.

## Thin executor by default

New agents start thin: the frontmatter contract, an identity statement, the role's non-negotiable policies, and one loading instruction — *read the corresponding skill and execute it*. Write the methodology as a skill via `create-skill`, so it can be versioned, swapped, and reused by commands without touching the executor.

The SDD workflow agents (`.claude/agents/workflow/`) are the reference shape for this split — phase executors whose method lives in the workflow skills, per the component model.

A fat body — methodology written inline — is the exception and needs a stated reason (for example: the method is inseparable from the role's tool scope and nothing else will ever reuse it). "It was faster to inline" is not a reason; it is the first anti-pattern in `.claude/kb/shared/component-model.md`.

## Ship checklist

Every new agent passes this before review:

| # | Check | How |
|---|---|---|
| 1 | Scaffold from the template | Copy `.claude/agents/_template.md` into the right category folder — `architect/`, `cloud/`, `data-engineering/`, `dev/`, `platform/`, `python/`, `test/`, or `workflow/` (the directory becomes the router category). Keep only the sections your tier requires. |
| 2 | Frontmatter contract complete | All required fields for the tier; description first line = the router one-liner; `kb_domains` all exist in `.claude/kb/_index.yaml`; every escalation `target:` is a real agent name. |
| 3 | Regenerate the router | `python3 scripts/generate-agent-router.py` — CI runs it with `--check` and fails on drift, so never hand-edit the `agent-router` skill. |
| 4 | Rebuild the plugin mirror | Run `./build-plugin.sh` and commit the regenerated `plugin/` tree together with the agent (agents ship wholesale; the build strips `_template.md`). |
| 5 | Update the hand-maintained catalog | Add the agent to `.claude/agents/README.md` — category table, tier distribution, escalation map if it escalates — and to the docs reference tables (`docs/reference/README.md`). |
| 6 | Agent count references | If the total changes, update the counts in `CLAUDE.md`, `README.md`, `docs/README.md`, `plugin/README.md`, and `.claude/agents/README.md`. |
| 7 | CHANGELOG | Entry under `[Unreleased]` in `CHANGELOG.md`. |

## References

- `.claude/kb/shared/component-model.md` — the four-layer model, thin-executor pattern, anti-patterns (the `component-model` skill is its operational gate)
- `.claude/agents/_template.md` — the scaffold: frontmatter schema, tier guide, section-by-tier requirements
- `.claude/agents/README.md` — the hand-maintained catalog: categories, tiers, escalation map, "When NOT to Create an Agent"
- `.claude/skills/create-skill/SKILL.md` — the sibling SOP for the skill that carries the new agent's methodology
- `scripts/generate-agent-router.py` — the generator this frontmatter contract feeds

Versions

RepositoryScoreLicence
This page · luanmorenommaciel/agentspec100MIT
terryspov/claudeclaw-plus100MIT
fairladyz625/harness-anything100AGPL-3.0
gcwing/openbitfun100MIT
nirholas/three.ws100Apache-2.0
harness/harness-skills100Apache-2.0
khaledsaeed18/dotclaude100MIT
cognitedata/builder-skills100Apache-2.0
microsoft/copilot-studio-plugin100MIT

Database snapshot: 13.11.2026 · package version 1f5f58d5f7be (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90create-skill
    Repo-specific layer for adding a new Claude Code skill to this repository — naming conventions, where the skill lives (distributed, plugin-only, or repo-local), YAML frontmatter pitfalls, and the build/mirror/docs checklist a skill must pass before it ships in the plugin. For…
  • 100skill-writer
    Guide users through creating Agent Skills for Claude Code. Use when the user wants to create, write, author, or design a new Skill, or needs help with SKILL.md files, frontmatter, or skill structure.
  • 100skill-creator
    How to create new skills for this HQ — format, frontmatter, content structure. Use when you need to add a new skill to this repository, or when reviewing whether an existing skill is well-formed.
  • 100skill-writer
    Guide users through creating Agent Skills for Claude Code. Use when the user wants to create, write, author, or design a new Skill, or needs help with SKILL.md files, frontmatter, or skill structure.
  • 90Agent Development
    Author and configure Claude Code subagents — valid YAML frontmatter (name, description, model, color, tools, isolation, memory, skills) plus a system-prompt body. Use when creating a new agent .md, fixing an agent that won't load or won't auto-delegate, choosing a model/color,…
  • 100create-skill
    Scaffolds new agent skills for the dotnet/skills repository. Use when creating a new skill, generating SKILL.md files, writing a skill description that the runtime will actually route to, or setting up skill directory structures. Handles frontmatter generation, section…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.