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

Agent Development

/Agent 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, deciding which tools an agent gets, or reviewing agent frontmatter for invalid/ignored fields.

Licence
MIT
Last repository change
15.10.2026

Assessment and security

90/ 100Class: good
Format15 / 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 15.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

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, deciding which tools an agent gets, or reviewing agent frontmatter for invalid/ignored fields.

Triggers from the description

t load or won
Original author description

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, deciding which tools an agent gets, or reviewing agent frontmatter for invalid/ignored fields.

How it works

  1. Where agents live
  2. Frontmatter — valid fields only
  3. The description IS the routing rule
  4. Gotchas
  5. Worked example — a leaf specialist
  6. Body structure that works here
  7. Coordination patterns
  8. Validation checklist before shipping an agent
  9. Learn from real agents
Original SKILL.md headings · 211 lines, 1,475 words
SKILL.md preview
---
name: Agent Development
description: >
  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,
  deciding which tools an agent gets, or reviewing agent frontmatter for invalid/ignored fields.
allowed-tools: Read, Grep, Glob
---

# Agent Development Guide

How to author a Claude Code subagent that loads, auto-delegates, and runs with the right tools.
Ground every new agent against the 33 real agents in this plugin (`agents/*.md`) — copy a close
match and adapt, don't start from a blank file.

## Where agents live

- **Plugin agents** (shipped): `plugins/nxtg-forge/agents/<name>.md`.
- **Project-local agents** (a user's repo): `.claude/agents/<name>.md`.
- **Personal agents** (all your projects): `~/.claude/agents/<name>.md`.

An agent is a single markdown file: YAML frontmatter (config) + body (the system prompt).

## Frontmatter — valid fields only

```yaml
---
name: builder                 # REQUIRED. lowercase + digits + hyphens, ≤64 chars. No uppercase, no underscores.
description: |                 # REQUIRED. When Claude should delegate here. Add <example> blocks.
  Use this agent when ... This includes: ...
  <example>
  Context: ...
  user: "..."
  assistant: "I'll use the Task tool to launch the builder agent to ..."
  <commentary>Why builder is the right pick.</commentary>
  </example>
model: sonnet                  # optional. sonnet | opus | haiku. Omit to inherit the main thread's model.
color: green                   # optional. EXACTLY one of: purple cyan green orange blue red
tools: Glob, Grep, Read, Write, Edit, Bash, TodoWrite  # optional allowlist. Omit Task for leaf workers.
isolation: worktree            # optional. Own git worktree for conflict-free parallel file edits.
memory: project                # optional. project | user | local. Persists MEMORY.md across sessions.
skills: nxtg-forge:parallel-execution  # optional. Preloads FULL skill text at startup (token cost).
disallowedTools: WebFetch      # optional denylist, complements `tools`.
permissionMode: acceptEdits    # optional. default | acceptEdits | plan | dontAsk | bypassPermissions
---
```

**Field notes**
- **name** must match the delegate name Claude uses ("launch the builder agent"). It is also the
  discovery key — invalid casing/underscores make the agent silently not load.
- **description** is the routing engine, not documentation — see below.
- **model**: `sonnet` for most specialists; `opus` for orchestration/high-stakes judgment
  (`orchestrator`, `ceo-loop`); `haiku` only for cheap mechanical work. Omit to inherit.
- **tools**: allowlist. A leaf worker that must never spawn subagents omits `Task`.
- **isolation: worktree**: use for agents that write files in parallel with others (`builder`,
  `testing`) so edits land on separate branches instead of colliding.
- **memory: project**: use for agents that must remember across sessions (`learning`). Writes a
  git-tracked `MEMORY.md`.
- **skills**: preloads the entire skill body into the agent's context at startup — real routing
  cost, so only preload skills the agent uses every run.

## The description IS the routing rule

Claude reads only `description` (not the body) to decide whether to delegate. Write it for the
model, front-load the primary trigger, and enumerate concrete scenarios + keywords a user would
actually type. `<example>` blocks are the strongest matching signal — real agents carry 2+.

Shape from the real `testing` agent:

```yaml
description: |
  Use this agent when test generation, coverage analysis, or test infrastructure work is needed.
  This includes: generating unit/integration/e2e tests for new code, analyzing coverage gaps,
  creating test fixtures and mocks, improving flaky tests, or setting up test infrastructure.
  <example>
  Context: User has implemented a new service without tests.
  user: "I just wrote the NotificationService, can you generate tests?"
  assistant: "I'll use the testing agent to generate comprehensive tests for the NotificationService."
  <commentary>New code needs coverage — the testing agent's specialty.</commentary>
  </example>
```

## Gotchas

Real failure modes when authoring agents in this plugin — each one is a silent break, not an error.

1. **Invalid frontmatter fields are silently ignored — the agent still loads, but misconfigured.**
   Claude Code accepts ONLY the fields listed above. These common-looking fields do NOTHING:
   `shortname`, `avatar`, `whenToUse`, `exampleQueries`, `when_to_use`, `color: teal/pink/yellow`.
   Put "when to use" text INSIDE `description`, not in a separate key. (Origin: the old version of
   this very skill shipped a "minimal example" using `shortname/avatar/whenToUse/exampleQueries` —
   all four are ignored.)
2. **`name` casing breaks discovery.** `NXTG-CEO-LOOP` did not load until renamed to `ceo-loop`.
   Lowercase + hyphens only; no uppercase, no underscores, ≤64 chars.
3. **`color` is a fixed 6-value enum.** `purple cyan green orange blue red` — any other value
   (teal, yellow, pink, hex) is ignored and the agent falls back to default coloring.
4. **Leaf workers must omit `Task` or they can spawn subagents.** Pattern in this plugin: leaf
   workers (`testing`, `learning`, `crucible-detective`) have NO `Task`; orchestrators (`builder`,
   `guardian`, `orchestrator`) DO. Giving a leaf `Task` invites accidental fan-out and runaway cost.
5. **`skills:` preload is not free.** It injects the whole SKILL.md into the agent's context at
   startup every run. `crucible-detective` preloads three skills deliberately; don't preload a
   skill the agent only occasionally needs — reference it in the body instead.
6. **`read-only` agents still need `Bash` denied, not just `Write`/`Edit` omitted.**
   `crucible-detective` is read-only and lists `Glob, Grep, Read, Bash` — Bash is present because
   it runs test/coverage commands, but it never writes. If you want a truly read-only agent, omit
   Write/Edit AND scope or drop Bash; `permissionMode: plan` enforces read-only exploration.
7. **`model` omitted ≠ sonnet.** Omitting `model` inherits the *caller's* model, which may be opus
   or haiku. State `model:` explicitly when the agent's cost/quality tier matters.
8. **`isolation: worktree` needs a clean git repo.** It creates a worktree/branch; on a repo with a
   dirty index or detached HEAD the isolation can fail to set up. Reserve it for agents that
   genuinely edit files in parallel.

## Worked example — a leaf specialist

Goal: an agent that audits dependency licenses, read-only, never spawns subagents.

```markdown
---
name: license-auditor
description: |
  Use this agent to audit dependency licenses for compliance risk — flagging GPL/AGPL/copyleft
  in a permissive-licensed project, missing LICENSE files, or license changes across versions.
  This includes: scanning package.json/Cargo.toml/requirements, mapping each dep to its license,
  and reporting incompatibilities.
  <example>
  Context: User is prepping a proprietary release and worries about copyleft deps.
  user: "Do any of our npm dependencies have GPL licenses?"
  assistant: "I'll use the license-auditor agent to scan dependencies and flag copyleft licenses."
  <commentary>License-compatibility scanning is exactly this agent's job; it's read-only.</commentary>
  </example>
model: sonnet
color: orange
tools: Glob, Grep, Read, Bash
---

# ⚖️ License Auditor

You audit dependency licenses for compatibility risk. You never modify files.

## Responsibilities
- Enumerate dependencies from manifests (package.json, Cargo.toml, requirements.txt).
- Resolve each dependency to its SPDX license.
- Flag copyleft (GPL/AGPL/LGPL) in a permissive-licensed project and any missing LICENSE.

## Protocol
1. Detect the stack and locate manifest files.
2. Read declared licenses (Bash: `npm ls --json`, `cargo license`, `pip-licenses`).
3. Classify each into permissive / weak-copyleft / strong-copyleft.
4. Report incompatibilities with the project's own license, with remediation options.

## Done when
- Every dependency is classified.
- Every incompatibility names the dep, its license, and a remediation.
```

Why it's correct: valid `name`, real `color`, `Task` omitted (leaf), `Bash` kept (it runs
license tooling) but `Write`/`Edit` omitted (read-only), `description` front-loads the trigger
with a concrete `<example>`.

## Body structure that works here

The plugin's agents follow a consistent house style. A workable skeleton:

```markdown
# <emoji> Display Name

You are the **Role** — one-line identity.

## Responsibilities
- What this agent owns (3–5 bullets).

## Protocol
1. Discovery → 2. Plan → 3. Execute → 4. Validate  (concrete steps, not narration)

## Decision framework
Criteria for the judgment calls this agent makes.

## Done when
Explicit completion gates — what "finished" means.
```

Keep the body tight: it is the system prompt and costs tokens every invocation. State what to do,
not why. Match the tone of a sibling agent (read one before writing).

## Coordination patterns

- **Sequential**: `planner → builder → guardian` (plan, build, gate).
- **Parallel**: an orchestrator with `Task` fans out to isolated (`isolation: worktree`) workers,
  then merges — up to the measured concurrency ceiling, not unbounded.
- **Iterative**: `builder ⇄ testing` feedback loop until gates pass.

Only agents with `Task` in `tools` can launch other agents — that is the coordinator/leaf split.

## Validation checklist before shipping an agent

- `name` is lowercase-hyphen, ≤64 chars, and matches how you delegate to it.
- `description` front-loads the primary trigger and has ≥1 `<example>` block.
- `color` is one of the 6 valid values; `model` is stated when tier matters.
- `tools` is minimal; `Task` present only if the agent orchestrates.
- No ignored fields (`shortname/avatar/whenToUse/exampleQueries`).
- Body has explicit "done when" gates.
- Diff against a sibling real agent (`agents/*.md`) for house-style consistency.

## Learn from real agents

Instead of a template, open a close match in `plugins/nxtg-forge/agents/`:
- `builder.md` — worktree-isolated specialist that writes code + tests (`isolation`, `skills` preload).
- `testing.md` — leaf worker, no `Task`.
- `orchestrator.md` — opus coordinator with `Task`.
- `learning.md` — cross-session `memory: project`.
- `crucible-detective.md` — read-only auditor (`Glob, Grep, Read, Bash`), multi-skill preload.

Copy the nearest one, then change `name`, `description`, and the body.

---

**Remember**: the `description` decides whether your agent is ever used, and only valid frontmatter
fields take effect. Ground every new agent against a real sibling in `agents/`.

Versions

The database has no other skills named Agent Development.

Database snapshot: 13.11.2026 · package version 0ca83a6a8010 (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

  • 90Skill Development
    How to author a Claude Code Agent Skill — SKILL.md structure, routing-optimized descriptions, progressive disclosure, valid frontmatter fields, bundling scripts/reference files. Use when creating a new skill, writing or fixing a SKILL.md, deciding what belongs in frontmatter,…
  • 96agent-identifier
    Use when creating or configuring Claude Code agents and their frontmatter.
  • 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.
  • 100agent-authoring
    Creates and configures Claude Code subagents (custom agents). Covers frontmatter fields, tool restrictions, model selection, hooks, memory, skills preloading, and common patterns. Follows official Anthropic best practices. USE WHEN: user mentions "create agent", "subagent",…
  • 100skill-frontmatter
    Write the YAML frontmatter for a SKILL.md file so it activates reliably — name, description, and activation keywords that the model matches against. Covers length, tone, and the most common frontmatter mistakes. Use this skill when authoring a new skill, fixing a skill that…
  • 100agent-development
    This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts,…

Feedback and reports

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