Skip to content

t1k:agent-creator

FieldValue
Modulet1k-maintainer
Version4.10.58
Effortmedium
ToolsAskUserQuestion, Bash, Edit, Glob, Grep, Read, Write

Keywords: agent, create, frontmatter, maxturn, model, scaffold, update

/t1k:agent-creator
[agent-name]

Create new agent .md files or update existing ones for TheOneKit. Enforces the canonical agent structure.

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)

FieldRequiredNotes
nameYesUniversal 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.
descriptionYes| 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
modelYesThe 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
tierFloorOptionalhaiku|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
gitEgressOptionaltrue 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
effortYes (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
maxTurnsNoRetired 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.
backgroundOptionaltrue = 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
routableOptionalfalse = 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
deliverableYesreturn (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)
colorYes14/14 agents use it — required, not suggested. See color-by-role below
rolesYes[routing-role] registers in routing JSON · none (scalar) = callable by name only · [] = same as none, prefer none
toolsYesExplicit 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
contextIf fork-contextfork when agent runs as fork child of a skill
originCI-injectedNever hand-author — CI pre-injects it before the origin-coverage gate on PR branches.
repositoryCI-injectedNever hand-author (same rule)
moduleCI-injectedNever hand-author (same rule)
protectedCI-injectedNever hand-author (same rule)
versionCI-managedCI 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: true cannot be preloaded via skills: — check the target’s frontmatter before wiring a new leaf to it.
  • references/*.md of 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 because skills: is set.

Color-by-role convention: references/color-convention.md.

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 the drift gate.
  • Lists (tools, skills): use toolsAdd / toolsRemove (skillsAdd / skillsRemove). An author-written tools:/skills: line with no Add/Remove that is NOT listed in extendsInherited fails as list-op-invalid; a bare line listed in extendsInherited is 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 in skills:.
  • Cross-kit parent: also write extendsPin: theonekit-core:<module>@<semver>.
  • Not model: inherit (banned tier) and not inheritsFrom (install-scope inheritance, doctor #68).
  • Gate: validate-agent-extends.cjs. Never hand-edit a line listed in extendsInherited.

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’s model: when authoring/updating (opus/sonnet → 1M curve; haiku/fable → 200K curve; the tier→window SSOT is hooks/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 — maxTurns is 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.

  1. Opening persona: “You are a {Role Title} …” — see Cognitive Framing
  2. “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 runtime name: 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”.
  3. Routing guard (if applicable): scope boundary + delegation targets
  4. Mandatory skills: Ordered table with activation triggers; names each skill by its frontmatter name: (colon form) or a skills/<dir> path — P06’s gate resolves both.
  5. Constraints: Enforced rules (NEVER/ALWAYS/DO NOT)
  6. Workflow: Numbered steps with verification checkpoints
  7. Output format: Constant-shape markdown template (no variable-cardinality keys in headers)
  8. Domain Agent Orchestration (if applicable): see pattern below
  9. 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 from roles: (theonekit-release-action/scripts/generate-routing-from-agents.cjs); the body is where the executor linkage lives.
  10. Behavioral Checklist: 6–10 checkbox lines, brutal-honesty framing — MANDATORY for all agents
  11. Module awareness (if applicable): metadata.json has modules / schemaVersion >= 2 conditions

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:

Terminal window
t1k agent new <name> --module <owner> --model <tier> # haiku | sonnet

It 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”).

  1. Ask user for: role name, scope, which kit/layer, key skills, and the description: the agent will claim — the split test reads that description.
  2. 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 haiku do it? if not, why in one sentence? then sonnet? (§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.
  3. Read 2 existing agents as reference (matching role type)
  4. Draft agent following canonical structure above
  5. Do not hand-author origin frontmatter — origin/repository/module/protected are CI-injected before the coverage gate. See “Required Frontmatter” above.
  6. Post-write check — read the new agent .md back; verify no TODO- placeholder remains.
  7. Validate using references/validation-checklist.md
  8. If routing needed: update t1k-routing-{layer}.json
  9. 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 Orchestration
entirely; report "domain-agents-skipped: depth-limit-reached". Depth is
assigned by `fork-depth-guard.cjs` — never read it from the environment,
never pass it to a child.

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 declares Edit/Write is 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.

Severity: Blocker (security/correctness) · High (cache/recursion/cost) · Medium (drift/clarity) · Low (style)

Anti-patternSeverityFix
Agent/Task tool in tools: with no stated depth budgetBlockerState 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 shapesHighA 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)MediumWidth is advisory, not enforced (rules/agent-security-boilerplate.md) — drop the number; only the depth budget binds
Inlining rules/agent-security-boilerplate.md contentHighAuto-loaded from rules/. Inlining drifts. Current offender: t1k-skills-manager.md:47-56
Volatile content in body (gitStatus, date +, “Last Updated”, live shell `...`)HighMove to a tool call AFTER the static prefix. See architecture-rules.md §E
tools: includes Bash for read-only agentsMediumRead-only agents declare [Read, Glob, Grep] — Bash grants rm, git push --force
Flat-token budget checkpoint (e.g. literal “150K”) instead of window-relativeHighDerive from model: window (~75%@200K / ~55%@1M). See Budget checkpoint above + agent-completion-discipline
Tool-heavy/Bash-write agent with NO budget checkpoint in bodyHighAdd the window-relative checkpoint per agent-completion-discipline (no turn half — maxTurns is retired)
Vague persona (“a developer”)MediumConcrete role + behavioral trait — see Cognitive Framing above
roles: [] instead of roles: noneLowPrefer none scalar for no-routing agents
An agent meant ONLY for a narrow orchestration mode (e.g. features.mergeUpTree) has no routingSuggest: falseHighroles: 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 agentsMediumEach agent’s examples must be domain-specific for routing disambiguation
Adding origin, module, protected, version with wrong valuesHighnever hand-author any of them: CI injects origin/module/protected before the coverage gate and version at release
Verifier agent without Anti-Avoidance ChecklistMediumTesters/reviewers/debuggers MUST include the 4-bullet checklist
Agent body recommends raw rm -rf .claude/ BlockerWrap 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