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 |