t1k:agent-creator
| Field | Value |
|---|---|
| Module | t1k-maintainer |
| Version | 4.10.58 |
| Effort | medium |
| Tools | AskUserQuestion, Bash, Edit, Glob, Grep, Read, Write |
Keywords: agent, create, frontmatter, maxturn, model, scaffold, update
How to invoke
Section titled “How to invoke”/t1k:agent-creator[agent-name]Agent Creator
Section titled “Agent Creator”Create new agent .md files or update existing ones for TheOneKit. Enforces the canonical agent structure.
Required Frontmatter
Section titled “Required Frontmatter”Canonical field order: name → description → model → effort → background → routable → deliverable → extends → extendsPin → extendsInherited → color → roles → tools → context → origin → repository → module → protected → version (extends* and <list>Add/<list>Remove are optional authoring keys, see § Extending another agent)
| Field | Required | Notes |
|---|---|---|
name | Yes | Universal t1k- prefix, kebab-case, MUST match filename basename. Core: t1k-{slug}. Kit-wide: t1k-{kit}-{slug}. Module-scoped: t1k-{kit}-{module}-{slug}. Module == kit short name collapses to kit-wide (t1k-model-router-proxy). See references/architecture-rules.md § 0 (SSOT). CI gate validate-agent-prefix.cjs is strict. |
description | Yes | | block scalar; 1-sentence intent, ≤400 chars (agentDescChars in release-action scripts/data/skill-listing-ceilings.json; blocking). A kit with a measured override may raise it, never past 992. Put <example> blocks in the body, not the description |
model | Yes | The FALLBACK tier (the router’s tier step may pick another per spawn, and falls back to this pin on any doubt) — pin the CHEAPEST tier that can do the job, then justify every step up: haiku (mechanical sweeps, fan-out, verification/reconciliation) · sonnet (implementation/authoring — the default when genuinely unsure) · opus (judgment, orchestration, adversarial review) · fable (advisory-only, never edits). inherit is BANNED. Rubric + the cheap-first default: references/architecture-rules.md § 0.3 |
tierFloor | Optional | haiku|sonnet|opus|fable — the router’s tier step never places this agent below it; never above model: (validate-frontmatter.cjs rejects it). fable only on advisory keep-list agents (t1k-kongming, t1k-advisor, Q2). Detail: references/architecture-rules.md § 0.3a |
gitEgress | Optional | true on every agent that pushes or opens PRs (git push, gh pr create); the router then routes it only for a brief carrying delivery: local-commit. Absent ⇒ false. Detail: § 0.3a |
effort | Yes (default medium) | low|medium|high|xhigh|max — reasoning-effort level while this agent is active; overrides the session default. Kit agents declare effort: medium by default (decided 2026-09-28); a different level is a deliberate per-agent choice, stated as such. Applies only when spawned as a subagent (Agent/Task) — ignored when the agent runs as the main thread. No per-spawn Agent/Task parameter exists for this — the frontmatter field is the only lever. Carried through and translated to reasoning_effort on a model-router ROUTED hop (xhigh/max clamp to high; Haiku hops honour it too). Full detail: references/architecture-rules.md § 0.6 |
maxTurns | No | Retired 2026-10-20: the fleet carries NO turn cap. Do not add one back — omit the key. Historical values and their measurements are kept for the record in references/max-turns-measured.md; a value that is still PRESENT must be a plain integer, but nothing sizes itself off it. |
background | Optional | true = run in the background by default. Set only when the spawner’s next step never reads this agent’s result, or a rule already mandates a background spawn; absent ⇒ foreground. Full guidance: references/architecture-rules.md § 0.4 |
routable | Optional | false = never routed by model-router, always runs natively on its pinned model:. Set it only together with an excludeAgents entry in model-router’s config — the key declares intent, excludeAgents enforces it. It is the precondition for a sonnet agent holding Agent(...) (references/architecture-rules.md § 0.3, native-sonnet exception). Absent ⇒ routable per model-router’s normal rules |
deliverable | Yes | return (the deliverable IS the returned summary) or disk (a file/commit). Pick by what the CALLER consumes, NOT by which tools are granted. Body must carry the matching ## Delivery Contract block — SSOT references/delivery-contract.md; gate validate-agent-checkpoint.cjs checks 5–6 (core#806) |
color | Yes | 14/14 agents use it — required, not suggested. See color-by-role below |
roles | Yes | [routing-role] registers in routing JSON · none (scalar) = callable by name only · [] = same as none, prefer none |
tools | Yes | Explicit minimal array [Read, Glob, Bash] — omitting inherits the ~70-tool default. This line is the agent’s tool surface: a spawner cannot narrow it at the call site, so anything over-granted here is granted for every spawn |
context | If fork-context | fork when agent runs as fork child of a skill |
origin | CI-injected | Never hand-author — CI pre-injects it before the origin-coverage gate on PR branches. |
repository | CI-injected | Never hand-author (same rule) |
module | CI-injected | Never hand-author (same rule) |
protected | CI-injected | Never hand-author (same rule) |
version | CI-managed | CI injects from module.json. Appears post-release — do NOT hand-edit. |
Agents do NOT have keywords: in frontmatter. Keywords live in t1k-activation-{layer}.json only.
skills: — preloads a SKILL.md BODY into this agent’s context at spawn. Per the Claude Code platform docs the field stands alone (nothing else required); pairing it with omitClaudeMd: true is a fleet convention, not a platform requirement — a native leaf that has dropped CLAUDE.md/rules loading needs skills: to hand it a condensed substitute, so every current use in this kit pairs the two (skills: [t1k:leaf-kernel] on .claude/agents/t1k-ci-watcher.md, t1k-fact-fetcher.md, t1k-tree-leaf.md, kernel body at .claude/skills/t1k-leaf-kernel/SKILL.md). Value is an array of the target skill’s frontmatter name: (e.g. t1k:leaf-kernel), not a filename, path, or description. This is loading-mechanism M1 (docs/rule-vs-skill-placement.md § “Loading Mechanisms”, paraphrased from plan.md) — reaches ONLY a native sub-agent of that type, never the main session and never a routed (model-router claude -p) hop (M1c, unverified — do not rely on it for a routed agent).
Gotchas:
- A non-matching skill name is skipped silently — no error surfaced to the caller, only a debug-level log line — so a typo in
skills:boots an agent with no kernel loaded and no visible complaint. - A skill with
disable-model-invocation: truecannot be preloaded viaskills:— check the target’s frontmatter before wiring a new leaf to it. references/*.mdof a preloaded skill are NOT pulled in automatically (M1b — ASSUMED lazy, not independently verified by the loading-mechanisms plan) — the body needs its own “Read references/.md before Y” instruction. - Loading is not the same as compliance. Kernel-preload measured 36/36 (the body DOES load), but the kernel’s own mandated
Scope:line — an OUTPUT line the child is instructed to STATE in its own final report, not a trigger that pulls in more content — was produced on only 23/36 attempts even when the kernel had loaded (plans/260922-token-cost-program/eval/leaf/results/FINDINGS.md:77). Do not assume 100% instruction-following just becauseskills:is set.
Color-by-role convention: references/color-convention.md.
Extending another agent
Section titled “Extending another agent”A kit agent on a core role MUST extends: it or carry standalone: <reason> (gate validate-agent-core-role-extends; references/kit-core-role-rule.md).
A child agent may write extends: <parent> (canonical post-prefix name) and omit the values it shares with the parent. CI expands the file (expand-agent-extends.cjs --write); the committed file is always fully expanded. Full spec: docs/agent-extends.md.
- Override: write the key, and remove it from
extendsInherited. Editing the value alone fails thedriftgate. - Lists (
tools,skills): usetoolsAdd/toolsRemove(skillsAdd/skillsRemove). An author-writtentools:/skills:line with no Add/Remove that is NOT listed inextendsInheritedfails aslist-op-invalid; a bare line listed inextendsInheritedis CI-owned and valid. - Never inherited:
name,description,roles,routingSuggest,color. The parent body is never spliced in; shared prose becomes a skill both agents list inskills:. - Cross-kit parent: also write
extendsPin: theonekit-core:<module>@<semver>. - Not
model: inherit(banned tier) and notinheritsFrom(install-scope inheritance, doctor #68). - Gate:
validate-agent-extends.cjs. Never hand-edit a line listed inextendsInherited.
maxTurns is RETIRED — do not add one back (2026-10-20)
Section titled “maxTurns is RETIRED — do not add one back (2026-10-20)”No agent carries a turn cap. A spawn runs until its work is done or its context window runs out; a fixed turn number was cutting agents off mid-task (the #528 failure mode) on work that was nowhere near its token ceiling. maxTurns: is therefore absent from every shipped agent, and validate-agent-checkpoint.cjs treats absence as valid. data/agent-turn-floors.json is deleted.
The budget checkpoint below is what bounds a run, and it is window-relative. The old measured-turn sizing rule, the per-bucket floors and their data stay on disk purely as a historical record in references/max-turns-measured.md and docs/agent-budget-calibration.md — read them to understand past incidents, never to choose a number.
Budget checkpoint (MANDATORY in every agent body)
Section titled “Budget checkpoint (MANDATORY in every agent body)”Per skills/t1k-team/references/agent-completion-discipline.md, every NEW agent body MUST carry a budget checkpoint — and it MUST be RELATIVE to the agent’s model: context window, NEVER a flat token number:
- ~75% of a ≤200K window (
fable,haiku) ≈150K · ~55% of a 1M window (opus,sonnet) ≈550K — tighten the % as the window grows. A flat “150K” mis-fires at ~15% on a 1M opus window. Derive it from the agent’smodel:when authoring/updating (opus/sonnet→ 1M curve;haiku/fable→ 200K curve; the tier→window SSOT ishooks/lib/model-window.cjs). Name every tier the window maps to, or check 8 flags the clause as ambiguous. - There is no second, turn-based ceiling —
maxTurnsis retired (see above).
On reaching it: git status → commit pending work NOW → dispatch pending Writes → only then resume or summarize. Tool-heavy/Bash-write agents (implementers, kit-developers, fork verifiers that mutate) REQUIRE this; pure read-only discovery agents may omit it. See skills/t1k-team/references/agent-completion-discipline.md (SSOT) — cite it, do not paste the full rule.
Required Body Sections (in order)
Section titled “Required Body Sections (in order)”- Opening persona: “You are a {Role Title} …” — see Cognitive Framing
- “Delegate to” table (premium agents only —
opus/fable, per § 0.3): right after Cognitive Framing, before the routing guard.| Job | Helper | Parallel group |, helper names spelled as runtimename:values. Full shape, the verbatim parallel-spawn rule, and everything else a thin premium agent’s body must carry:references/architecture-rules.md§ “Thin premium”. - Routing guard (if applicable): scope boundary + delegation targets
- Mandatory skills: Ordered table with activation triggers; names each skill by its
frontmatter
name:(colon form) or askills/<dir>path — P06’s gate resolves both. - Constraints: Enforced rules (NEVER/ALWAYS/DO NOT)
- Workflow: Numbered steps with verification checkpoints
- Output format: Constant-shape markdown template (no variable-cardinality keys in headers)
- Domain Agent Orchestration (if applicable): see pattern below
- Skills served: one line per skill this agent is the canonical executor for, or the literal
none — this agent serves no skill directly. Not a frontmatter field — routing fragments are CI-generated fromroles:(theonekit-release-action/scripts/generate-routing-from-agents.cjs); the body is where the executor linkage lives. - Behavioral Checklist: 6–10 checkbox lines, brutal-honesty framing — MANDATORY for all agents
- Module awareness (if applicable):
metadata.json has modules/schemaVersion >= 2conditions
Auto-register (fast path) — never hand-stamp + hand-place
Section titled “Auto-register (fast path) — never hand-stamp + hand-place”Second occurrence ⇒ automate, never repeat by hand (docs/replicate-and-automate.md): don’t repeat the manual create-file → stamp-frontmatter → edit-module.json → regen dance. Use the scaffolder:
t1k agent new <name> --module <owner> --model <tier> # haiku | sonnetIt creates the t1k--prefixed agent .md (dash-form name: == basename per references/architecture-rules.md § 0) with stamped frontmatter including an explicit model: tier (NO model: inherit — every kit agent pins a concrete tier per references/architecture-rules.md § 0.3), appends to the owning module.json agents[], and regenerates t1k-modules.json (via generate-modules-registry.cjs). You then write the body. Requires CLI ≥ 5.4.0 (t1k --version).
Manual fallback (CLI < 5.4.0): create the agent .md yourself, write frontmatter without origin keys (pin a concrete model: tier), append to module.json agents[], then run bun <release-action>/scripts/generate-modules-registry.cjs <kit-root> and stage t1k-modules.json in the SAME commit (agents/t1k-kit-developer.md § “Module Registry Sync”).
Process
Section titled “Process”- Ask user for: role name, scope, which kit/layer, key skills, and the
description:the agent will claim — the split test reads that description. - Run the split test before naming anything (§0.5, four questions in order): shape — do any two claimed tasks differ in deliverable, tier, write surface, or mergeability? yes → split, name the second agent · tier — can
haikudo it? if not, why in one sentence? thensonnet? (§0.3) · orchestration (premium only) — which sub-questions are divisible, which cheap agent answers each, what stays inline? (§0.5.1) · mergeability — could a spawner merge two of these without reading the bodies? Refusing to split is how a cheap agent gets re-tiered up to premium. - Read 2 existing agents as reference (matching role type)
- Draft agent following canonical structure above
- Do not hand-author origin frontmatter —
origin/repository/module/protectedare CI-injected before the coverage gate. See “Required Frontmatter” above. - Post-write check — read the new agent .md back; verify no
TODO-placeholder remains. - Validate using
references/validation-checklist.md - If routing needed: update
t1k-routing-{layer}.json - If activation needed: update
t1k-activation-{layer}.json
Cognitive Framing (MANDATORY — first line of body)
Section titled “Cognitive Framing (MANDATORY — first line of body)”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 QA Lead performing systematic verification — you hunt for untested code paths and think like someone burned by production incidents.”
- “You are a Tech Lead designing system architecture — you optimize for long-term maintainability over short-term convenience.”
Validation: If the opening line does not name a concrete role with a behavioral trait, reject and rewrite.
Domain Agent Orchestration (6/14 agents use this)
Section titled “Domain Agent Orchestration (6/14 agents use this)”Thin premium agents: this pattern is itself a helper-delegation job — it has no “generic
implementation” of its own to complete first, because a thin premium agent never implements; it
routes. Give it one row in the “Delegate to” table (Helper column reads e.g. *-{role}.md glob
match; Parallel group per the runtime targets found) rather than treating it as a step that runs
after inline work. Matched targets are runtime-resolved, so the agent keeps a bare Agent grant
for this row (a scoped Task(...) allowlist would make it structurally blind to engine-kit agents
core cannot name) — see references/validation-checklist.md § “Spawn-grant shape”. Editor-bound
domain agents (UnityMCP, Cocos editor MCP: stateful, single instance) never share a parallel group
with another domain agent, or with any other helper (references/architecture-rules.md §
“Thin premium” item 8).
**Domain Agent Orchestration:**1. Use Glob to find `.claude/agents/*-{role}.md`2. Evaluate which are relevant to the task (engine-specific, module-specific)3. For relevant domain agents: spawn via Agent tool with implementation context (`subagent_type` = agent identity; the task goes in `description:`)4. Spawn one per matched domain agent — width is not capped (the per-depth figures in rules/agent-security-boilerplate.md are advisory).5. If no domain agents found — proceed with generic output only
At the leaf level of the depth budget (depth 3): skip Domain Orchestrationentirely; report "domain-agents-skipped: depth-limit-reached". Depth isassigned by `fork-depth-guard.cjs` — never read it from the environment,never pass it to a child.Fork-context agents
Section titled “Fork-context agents”If an agent may run as a fork child of a skill (verifier, t1k-researcher, t1k-planner, reviewer, t1k-tester, t1k-debugger):
Frontmatter required:
tools: [Read, Grep, Glob](minimal explicit array) — omitting inherits the ~70-tool default. A read-only verifier that declaresEdit/Writeis write-capable no matter what its body says; the frontmatter is the only enforcement.
Body required (verifier agents — testers, reviewers, debuggers):
**Anti-Avoidance Checklist (read before every run):**- No "should work" without evidence — run the command, paste the output.- No "looks fine to me" without a root-cause sentence.- No "I'll skip this edge case" without explicit risk justification.- No "this is unrelated" without a 1-line proof.Constant-shape Output Format: headers MUST NOT interpolate counts, timestamps, or commit hashes into top-level keys. Variable values go inside leaf nodes.
- GOOD:
### Files Modified\n[list] - BAD:
### Files Modified (3 files, 187 lines):— count busts cache
Spawn budget: If body contains Domain Agent Orchestration, state the depth budget in prose (depths 0/1/2 spawn, depth 3 is a leaf) — no env-var check, no depth propagation. Never reference the gitStatus block — run git status yourself if needed.
See skills/t1k-architecture/references/fork-hygiene.md for parent-side rules.
Anti-Patterns to Avoid
Section titled “Anti-Patterns to Avoid”Severity: Blocker (security/correctness) · High (cache/recursion/cost) · Medium (drift/clarity) · Low (style)
| Anti-pattern | Severity | Fix |
|---|---|---|
Agent/Task tool in tools: with no stated depth budget | Blocker | State the budget in prose: depths 0/1/2 spawn, depth 3 is a leaf; refuse to spawn self. Never require an env-var check or depth propagation (#767). Spawn-capability itself is NOT a finding. |
| The kitchen-sink agent — the split test was never run, so the description claims two shapes | High | A second shape is a second AGENT, not a second <example>: split per §0.5 on deliverable / tier / write surface / mergeability, then pin only the judgment lane premium (§0.5.1). Verb variety over ONE artifact is fine and is not the test |
| A fan-out width stated as an enforced cap (flat N or copied literal) | Medium | Width is advisory, not enforced (rules/agent-security-boilerplate.md) — drop the number; only the depth budget binds |
Inlining rules/agent-security-boilerplate.md content | High | Auto-loaded from rules/. Inlining drifts. Current offender: t1k-skills-manager.md:47-56 |
Volatile content in body (gitStatus, date +, “Last Updated”, live shell `...`) | High | Move to a tool call AFTER the static prefix. See architecture-rules.md §E |
tools: includes Bash for read-only agents | Medium | Read-only agents declare [Read, Glob, Grep] — Bash grants rm, git push --force |
| Flat-token budget checkpoint (e.g. literal “150K”) instead of window-relative | High | Derive from model: window (~75%@200K / ~55%@1M). See Budget checkpoint above + agent-completion-discipline |
| Tool-heavy/Bash-write agent with NO budget checkpoint in body | High | Add the window-relative checkpoint per agent-completion-discipline (no turn half — maxTurns is retired) |
| Vague persona (“a developer”) | Medium | Concrete role + behavioral trait — see Cognitive Framing above |
roles: [] instead of roles: none | Low | Prefer none scalar for no-routing agents |
An agent meant ONLY for a narrow orchestration mode (e.g. features.mergeUpTree) has no routingSuggest: false | High | roles: none only opts out of generic ROLE-keyword resolution — the agent is still harvested BY NAME from its own <example> prose (#659) and can surface as a suggestAgent() false positive on an incidental shared word (fingerprint ca86efde: a PR-merge brief matched t1k-tree-leaf on “merge”). Add frontmatter routingSuggest: false to withhold the agent from EVERY registration path in hooks/lib/agent-routing-index.cjs (role, engine-keyword, harvested-example) — see t1k-tree-leaf.md/t1k-tree-node.md |
Copy-pasted <example> blocks across agents | Medium | Each agent’s examples must be domain-specific for routing disambiguation |
Adding origin, module, protected, version with wrong values | High | never hand-author any of them: CI injects origin/module/protected before the coverage gate and version at release |
| Verifier agent without Anti-Avoidance Checklist | Medium | Testers/reviewers/debuggers MUST include the 4-bullet checklist |
Agent body recommends raw rm -rf .claude/ | Blocker | Wrap in t1k install --reset / t1k doctor --nuke (CLAUDE.md #10) |
Full architecture checklist: references/architecture-rules.md
Pre-merge agent checklist: references/validation-checklist.md
Delivery-contract blocks (paste-ready, per class): references/delivery-contract.md