| name | t1k:agent-creator |
| description | Create or update TheOneKit agent .md files with canonical structure. Use when adding a new agent, updating maxTurns/model, or fixing frontmatter fields. |
| keywords | ["agent","create","update","maxturn","model","frontmatter","scaffold"] |
| version | 1.0.0 |
| effort | medium |
| argument-hint | [agent-name] |
| origin | theonekit-core |
| repository | The1Studio/theonekit-core |
| module | null |
| protected | true |
Agent Creator
Create new agent .md files or update existing ones for TheOneKit. Enforces the canonical agent structure.
Required Frontmatter
| Field | Required | Notes |
|---|
name | Yes | kebab-case, must match filename |
description | Yes | 2-5 <example> blocks with <commentary> |
model | Yes | inherit, sonnet, opus, or haiku |
maxTurns | Yes | 15-50 based on role |
color | Suggested | Consistent per role |
origin/module/protected | NO | CI-injected only — never add manually |
Recommended maxTurns
| Role | Range |
|---|
| implementer / kit-developer | 40-50 |
| debugger | 35-40 |
| tester | 30-35 |
| planner / brainstormer | 25-30 |
| reviewer | 25-30 |
| docs / git / utility | 15-25 |
Required Body Sections (in order)
- Opening: "You are a [specific role]..."
- Routing guard (if applicable): scope boundary + delegation targets
- Mandatory skills: Ordered table with activation triggers
- Constraints: Enforced rules (NEVER/ALWAYS/DO NOT)
- Workflow: Numbered steps with verification checkpoints
- Output format: Structured markdown template
- Completion gates: Verifiable, tool-referenced, severity-marked (BLOCKING/MANDATORY)
- Module awareness (if applicable)
Process
- Ask user for: role name, scope, which kit/layer, key skills
- Read 2 existing agents as reference (matching role type)
- Draft agent following canonical structure
- Validate:
- All required frontmatter present
- 2+ examples in description
- All 7 body sections present
- Completion gates are verifiable
- maxTurns justified
- If routing needed: update
t1k-routing-{layer}.json
- If activation needed: update
t1k-activation-{layer}.json
Cognitive Framing (MANDATORY for all new agents)
Every new agent MUST include a persona line as the first sentence of the body (after frontmatter).
Format: "You are a {Role Title} who/performing {behavioral description in 1-2 sentences}."
Examples:
- "You are a Staff Engineer hunting production bugs — you distrust obvious answers and prove root cause before proposing any fix."
- "You are a Detective performing systematic investigation. You form hypotheses, gather evidence, and never assume."
- "You are a Tech Lead designing system architecture — you optimize for long-term maintainability over short-term convenience."
- "You are a QA Lead performing systematic verification — you hunt for untested code paths and think like someone burned by production incidents."
Why it matters: The persona shapes reasoning quality throughout the agent's entire run. Generic descriptions ("you are a developer") produce generic, shallow output. Specific behavioral frames ("you distrust obvious answers") activate different reasoning patterns.
Validation: If the opening line does not name a concrete role with a behavioral trait, reject and rewrite.
Anti-Patterns to Avoid
- Vague role ("a developer") — must be specific with behavioral trait
- Missing cognitive framing persona as first body line
- "Activate skills as needed" (must be explicit)
- No completion gates
- No routing guard when scope overlaps with other agents
- maxTurns >50
- Adding origin/module/protected manually
