Agent Creator
Create a sub-agent that earns its context window. Most agents fail not because the model is weak but because the definition is vague - unclear trigger, sprawling tool list, a body that mixes persona and procedure, and no output contract. This skill walks you through a six-phase design so the resulting agent is focused, least-privileged, and predictable.
Core Principles
| Principle |
Meaning |
| One job, one agent |
An agent that does two things does neither well. Split the responsibility before writing. |
| Least privilege |
Grant the smallest tool set that lets the agent finish its job. Read-only by default. |
| Trigger-first description |
The description field is the only thing read before delegation. Pack it with keywords and "when to use". |
| Contract over conversation |
Define explicit input, process, and output. Agents are not chat sessions. |
| Isolation when writing |
If the agent edits files, run it in a worktree so the orchestrator can review before merging. |
| Portable body, platform frontmatter |
Keep the system prompt agent-agnostic. Adapt frontmatter fields per target platform. |
Agent vs Skill - Quick Disambiguation
Before creating an agent, confirm it is the right primitive.
| Use a Skill |
Use an Agent |
| Reference material (patterns, checklists, schemas) |
Work to perform (investigate, review, implement) |
| Loaded into an existing session |
Runs in its own context window |
| Passive knowledge |
Active actor with tools and a workflow |
| "Where do I learn about X" |
"Do X for me and return a result" |
If the answer is reference material, stop and use the skill-creator skill instead. If the answer is work, continue.
Archetype Selection
Agents fall into three archetypes. Pick one before designing.
| Archetype |
Scope |
Memory |
Modifies files |
Typical examples |
| Specialist |
Single, repeatable task type |
Stateless |
Rarely (doc writer, implementer) |
Investigator, Reviewer, Refactor Scout, Dependency Auditor, Test Gap Analyzer |
| Role |
Entire domain of responsibility |
Often persistent (project-level) |
Dev roles yes, others no |
Product Manager, Architect, Backend Dev, QA Engineer, Project Manager |
| Team-Lead |
Coordinates multiple workers in parallel |
Shared task list |
No (delegates) |
Orchestrator, release-train lead, review dispatcher |
Decision tree
- Does the agent do one repeatable task type (review this PR, investigate this area, audit dependencies)? -> Specialist
- Does the agent own a domain across many task types and benefit from remembering context across sessions (requirements, architecture decisions, risk register)? -> Role
- Does the agent need to spawn and coordinate other agents working in parallel (research teams, multi-layer refactors)? -> Team-Lead
If the user provided an archetype as an argument, use it. Otherwise present a selectable menu using AskUserQuestion (or the platform's equivalent interactive prompt) with the three options from the table above.
See references/archetypes.md for worked examples of each archetype and the anti-patterns to avoid.
Workflow
This skill uses guided phases - each phase is a separate file loaded one at a time. Every phase ends with a gate where you must wait for user confirmation before proceeding. Do not skip phases or merge them.
| Phase |
File |
What it covers |
| 1 |
Purpose and Trigger |
What the agent does, when to delegate, out-of-scope, output shape, archetype |
| 2 |
Name and Identity |
Kebab-case name, collision check, user confirmation |
| 3 |
Capabilities |
Tool permissions, isolation, memory, preloaded skills |
| 4 |
System Prompt |
Five-section contract: Input, Process, Rules, Output |
| 5 |
Placement and Scope |
Where the file lives: project, personal, plugin, session |
| 6 |
Validate and Write |
Checklist, file creation, marketplace registration |
Start by loading Phase 1. After the user confirms each phase, load the next. Never load multiple phases at once. Never skip a phase.
Reference Files
| Reference |
Contents |
| archetypes.md |
Worked examples of specialist, role, and team-lead agents, plus anti-patterns |
| frontmatter-fields.md |
Full field reference, portable vs platform-specific, and examples |
| tool-selection.md |
Least-privilege tool allowlists, per-archetype defaults, and denylist patterns |
| system-prompts.md |
System prompt patterns: role-input-process-rules-output contract, worked examples |
| platforms.md |
Scope paths, platform-specific frontmatter fields, and agent-team considerations |
| validation.md |
Pre-publish checklist and common rejection reasons |
Integration with Other Skills
| Situation |
Recommended Skill |
| Creating a reference skill instead of an agent |
skill-creator |
| Writing AI rules files for an agent platform |
agentic-rules-writer |
| Designing how multiple agents interact in a workflow |
See archetypes.md team-lead section |
| Authoring a ticket or PRD that spawns the agent |
ticket-writer |
1---2name: agent-creator3description: Interactive tool to design a well-scoped sub-agent definition - specialist, role, or team-lead - with the right frontmatter, tool permissions, isolation, memory, and system prompt. Use when the user asks to create a sub-agent, write an agent file, design a specialized worker, scaffold a role agent, bootstrap an agent team, or turn a repeated delegation pattern into a reusable agent. Runs a six-phase questionnaire and outputs a ready-to-commit agent markdown file plus marketplace registration.4---56# Agent Creator78Create a sub-agent that earns its context window. Most agents fail not because the model is weak but because the definition is vague - unclear trigger, sprawling tool list, a body that mixes persona and procedure, and no output contract. This skill walks you through a six-phase design so the resulting agent is focused, least-privileged, and predictable.910## Core Principles1112| Principle | Meaning |13|---|---|14| **One job, one agent** | An agent that does two things does neither well. Split the responsibility before writing. |15| **Least privilege** | Grant the smallest tool set that lets the agent finish its job. Read-only by default. |16| **Trigger-first description** | The `description` field is the only thing read before delegation. Pack it with keywords and "when to use". |17| **Contract over conversation** | Define explicit input, process, and output. Agents are not chat sessions. |18| **Isolation when writing** | If the agent edits files, run it in a worktree so the orchestrator can review before merging. |19| **Portable body, platform frontmatter** | Keep the system prompt agent-agnostic. Adapt frontmatter fields per target platform. |2021---2223## Agent vs Skill - Quick Disambiguation2425Before creating an agent, confirm it is the right primitive.2627| Use a Skill | Use an Agent |28|---|---|29| Reference material (patterns, checklists, schemas) | Work to perform (investigate, review, implement) |30| Loaded into an existing session | Runs in its own context window |31| Passive knowledge | Active actor with tools and a workflow |32| "Where do I learn about X" | "Do X for me and return a result" |3334If the answer is reference material, stop and use the `skill-creator` skill instead. If the answer is work, continue.3536---3738## Archetype Selection3940Agents fall into three archetypes. Pick one before designing.4142| Archetype | Scope | Memory | Modifies files | Typical examples |43|---|---|---|---|---|44| **Specialist** | Single, repeatable task type | Stateless | Rarely (doc writer, implementer) | Investigator, Reviewer, Refactor Scout, Dependency Auditor, Test Gap Analyzer |45| **Role** | Entire domain of responsibility | Often persistent (project-level) | Dev roles yes, others no | Product Manager, Architect, Backend Dev, QA Engineer, Project Manager |46| **Team-Lead** | Coordinates multiple workers in parallel | Shared task list | No (delegates) | Orchestrator, release-train lead, review dispatcher |4748### Decision tree49501. Does the agent do **one repeatable task type** (review this PR, investigate this area, audit dependencies)? -> **Specialist**512. Does the agent **own a domain** across many task types and benefit from remembering context across sessions (requirements, architecture decisions, risk register)? -> **Role**523. Does the agent need to **spawn and coordinate other agents** working in parallel (research teams, multi-layer refactors)? -> **Team-Lead**5354If the user provided an archetype as an argument, use it. Otherwise present a selectable menu using `AskUserQuestion` (or the platform's equivalent interactive prompt) with the three options from the table above.5556See [references/archetypes.md](references/archetypes.md) for worked examples of each archetype and the anti-patterns to avoid.5758---5960## Workflow6162This skill uses **guided phases** - each phase is a separate file loaded one at a time. Every phase ends with a gate where you must wait for user confirmation before proceeding. Do not skip phases or merge them.6364| Phase | File | What it covers |65|---|---|---|66| 1 | [Purpose and Trigger](phases/01-purpose-and-trigger.md) | What the agent does, when to delegate, out-of-scope, output shape, archetype |67| 2 | [Name and Identity](phases/02-name-and-identity.md) | Kebab-case name, collision check, user confirmation |68| 3 | [Capabilities](phases/03-capabilities.md) | Tool permissions, isolation, memory, preloaded skills |69| 4 | [System Prompt](phases/04-system-prompt.md) | Five-section contract: Input, Process, Rules, Output |70| 5 | [Placement and Scope](phases/05-placement-and-scope.md) | Where the file lives: project, personal, plugin, session |71| 6 | [Validate and Write](phases/06-validate-and-write.md) | Checklist, file creation, marketplace registration |7273**Start by loading Phase 1.** After the user confirms each phase, load the next. Never load multiple phases at once. Never skip a phase.7475---7677## Reference Files7879| Reference | Contents |80|---|---|81| [archetypes.md](references/archetypes.md) | Worked examples of specialist, role, and team-lead agents, plus anti-patterns |82| [frontmatter-fields.md](references/frontmatter-fields.md) | Full field reference, portable vs platform-specific, and examples |83| [tool-selection.md](references/tool-selection.md) | Least-privilege tool allowlists, per-archetype defaults, and denylist patterns |84| [system-prompts.md](references/system-prompts.md) | System prompt patterns: role-input-process-rules-output contract, worked examples |85| [platforms.md](references/platforms.md) | Scope paths, platform-specific frontmatter fields, and agent-team considerations |86| [validation.md](references/validation.md) | Pre-publish checklist and common rejection reasons |8788---8990## Integration with Other Skills9192| Situation | Recommended Skill |93|---|---|94| Creating a reference skill instead of an agent | `skill-creator` |95| Writing AI rules files for an agent platform | `agentic-rules-writer` |96| Designing how multiple agents interact in a workflow | See `archetypes.md` team-lead section |97| Authoring a ticket or PRD that spawns the agent | `ticket-writer` |
krzysztofsurdy