krzysztofsurdy/agent-creator

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

1. Does the agent do one repeatable task type (review this PR, investigate this area, audit dependencies)? -> Specialist
2. Does the agent own a domain across many task types and benefit from remembering context across sessions (requirements, architecture decisions, risk register)? -> Role
3. 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 |