Create Agent - Runtime Persona Authoring
create-agent is the sk-doc workflow packet for creating or updating one runtime agent markdown file. The executable contract lives here: decide whether an agent is the right component, place it in the active runtime directory, author current frontmatter and authority boundaries, then validate before delivery.
Use references/README.md (the overflow route map) and assets/agent-template.md only for deeper examples, exhaustive variants, and long-form reference detail. Do not make those files the primary workflow contract.
1. WHEN TO USE
Activation Triggers
Use this workflow when the request involves:
- Creating a new OpenCode or Claude Code agent file.
- Updating an agent's frontmatter, permissions, authority boundary, workflow, verification contract, or anti-patterns.
- Converting a durable role description into a runtime persona with explicit authority and tool policy.
- Deciding whether the requested component should be an agent, skill, or command.
- Running or supporting
/create:agent.
Keyword triggers: create agent, /create:agent, OpenCode agent, Claude Code agent, agent file, new agent, agent persona, agent frontmatter, permission object, authority boundary, agent template, agent and paired, agent registry.
Create an agent only when the system needs a stable named persona with explicit tool permissions, denied capabilities, behavioral constraints, orchestration authority, or reusable execution posture.
When NOT to Use
Use another sk-doc packet when:
- The request needs reusable knowledge, standards, templates, or long-form workflow guidance. Use
create-skill.
- The request needs a slash-command entry point without a new runtime persona. Use
create-command.
- The request needs a README, feature catalog, manual testing playbook, benchmark package, or changelog. Use
create-readme, create-feature-catalog, create-manual-testing-playbook, create-benchmark, or create-changelog. A flowchart or any other diagram belongs to the sk-design hub (/design:diagram), which this hub does not register a packet for.
- The request audits, validates, scores, or optimizes an existing agent document. Use
create-quality-control.
2. SMART ROUTING
The sk-doc hub routes runtime-persona work here: a request to create or update one agent file.
The hub's sk-create-agent signal selects this packet.
Stay in this packet only when the artifact is a concrete runtime agent file whose authority boundary no existing agent already covers.
A skill, a command or an existing agent answers the rest.
references/README.md is the route map.
It is also the fallback when the component or runtime is unclear.
A resolved request loads this packet's flat references and assets first, with assets/agent-template.md as the scaffold.
Read ROUTER.md before selecting skill-local resources.
Open only the matched files.
3. HOW IT WORKS
Component Choice
Choose the component type before authoring: an agent answers who should do the work, a skill answers how the work should be done, and a command answers how a user should trigger the workflow. Healthy systems often pair all three: the agent provides persona and boundaries, the skill provides detailed domain knowledge, and the command provides the ergonomic entry point.
Output Package
Create or update one markdown file in the active runtime agent directory.
| Runtime profile |
Agent directory |
| OpenCode |
.opencode/agents/ |
| Claude Code |
.claude/agents/ |
| Copilot/default OpenCode profile |
.opencode/agents/ |
The output file contract:
- The filename is kebab-case and ends in
.md.
- The filename stem matches frontmatter
name exactly.
- The stem matches
^[a-z0-9]+(?:-[a-z0-9]+)*$; reject underscores, empty segments, and ambiguous normalization instead of rewriting the name silently.
- The file lives in the active runtime directory, not under
sk-doc.
- The body is self-sufficient for the agent's role, boundaries, workflow, limits, and output contract.
- Reusable or deep domain guidance stays in skills or references and is linked, not pasted into the agent.
Canonical Frontmatter
Frontmatter schema is runtime-specific — never emit the same schema for both runtime directories:
| Runtime directory |
Canonical schema |
Rationale |
.opencode/agents/ |
permission: object |
OpenCode enforces the permission: object; it ignores a standalone tools: key. |
.claude/agents/ |
tools: allow-list |
Claude Code enforces only tools: (a comma-separated allow-list); it silently ignores permission:. Omitting tools: makes the agent inherit the parent session's full, unrestricted tool set. |
Decision rule:
Authoring for .skilled/agents/? -> emit `permission:` (never bare `tools:`)
Authoring for .claude/agents/? -> emit `tools:` (never `permission:`)
OpenCode (.opencode/agents/) frontmatter:
---
name: agent-name
description: One-line purpose statement with scope and boundary
mode: subagent
temperature: 0.1
permission:
read: allow
write: allow
edit: allow
bash: allow
grep: allow
glob: allow
webfetch: deny
chrome_devtools: deny
task: deny
list: allow
patch: deny
external_directory: deny
---
Claude Code (.claude/agents/) frontmatter:
---
name: agent-name
description: One-line purpose statement with scope and boundary
tools: Read, Write, Edit, Bash, Grep, Glob
---
Map the permission: allow-set to the tools: list when authoring the same role for both runtimes: include only the tools with allow (or ask) and drop the ones with deny. mode and temperature are OpenCode-only fields with no Claude Code equivalent — omit both from .claude/agents/ frontmatter.
Frontmatter rules:
name must match the filename stem.
description is one line describing role and scope.
mode and temperature are OpenCode-only fields; set mode to match runtime invocation (commonly subagent for specialists) and temperature to reflect determinism needs (commonly 0.1) — .claude/agents/ frontmatter omits both.
- Under
.skilled/agents/, permission values must be explicit, least-authority, justified by the role, and use only allow, deny, or ask.
- Under
.claude/agents/, tools: is the runtime-specific canonical schema — a comma-separated least-authority allow-list; never emit permission: there, and never leave tools: absent or empty (an absent tools: inherits the parent session's full tool set).
- Set
task: allow (or include Task in tools:) only for agents whose explicit authority is orchestration.
Required Body Shape
Start from assets/agent-template.md when creating a new agent. At minimum, a production-ready agent includes:
- H1 and short purpose statement.
- Hard boundary section that states nesting, delegation, and write limits.
- Core workflow section that describes how the agent acts.
- Capability scan section that identifies relevant skills, tools, commands, or companion agents.
- Output verification section that defines checks required before claiming completion.
- Anti-patterns section that names failure modes.
- Related resources section with real supporting paths.
Boundary variants:
- LEAF write-capable agents deny nested sub-agent dispatch and restrict mutation to explicitly scoped paths.
- LEAF read-only agents deny nested dispatch and all file mutation.
- Orchestrators may dispatch only when orchestration is their explicit authority and
task permission allows it.
- Command-driven or machine-validated agents may need input/scope gates before workflow steps.
Sanctioned Section-Vocabulary Dialects
The skeleton above is the default, so start new agents from it.
One alternate section vocabulary is also sanctioned for the deep-loop leaf-iteration agents (@deep-review / @deep-research, in both runtime directories).
A per-iteration loop worker reads more clearly under lane-named headings, so these agents carry the same responsibilities under a different vocabulary:
ROUTING SCAN.
- a lane
CONTRACT, which is REVIEW CONTRACT, or ITERATION PROTOCOL for the leaner research variant.
STATE MANAGEMENT, plus + WRITE SAFETY where the agent mutates.
- a lane
ADVERSARIAL CHECK, which is ADVERSARIAL SELF-CHECK.
RULES.
This is a documented shape, not drift.
--type agent requires only ## 1. CORE WORKFLOW, and the dialect still carries every hard-block boundary, capability, verification and anti-pattern responsibility from "Required Body Shape" above.
Reach for it only when authoring another member of the deep-loop iteration family.
Do not invent a fresh dialect for a one-off agent.
The concrete section order and its two sub-variants are in assets/agent-template.md §9.
Ordered Creation Workflow
Follow this order for new agents and material rewrites:
- Read the request and define the proposed role, authority boundary, and likely runtime directory.
- Decide whether the task truly needs a new agent instead of a skill, command, or existing agent.
- Search existing agents for overlap before creating a new one.
- Resolve the active runtime directory and target filename.
- Read
assets/agent-template.md and use it as the scaffold; do not invent a new structure from scratch.
- Draft frontmatter first, especially
mode, temperature, and each permission value.
- Confirm permissions against actual role needs before writing tool-heavy instructions.
- Write the hard boundary section before the general workflow.
- Write the core workflow and capability scan.
- Add explicit output verification, anti-patterns, and related resources.
- Link supporting skills, commands, references, and companion agents rather than copying their full guidance.
- Remove template placeholders and check that the document stays focused on the runtime role.
- For a new agent under
.skilled/agents/, add a record to .skilled/agents/agent-registry.json, copying an existing record as the pattern. A record carries name, tier, priority, dispatchers, taskType, skills, notes and summary, and templateExceptions only when the file leaves out a required section. Then run node .skilled/bin/sync-agent-roster.cjs so the generated rosters pick the agent up. An agent that exists only in .claude/agents/ gets no record: the roster check reads .skilled/agents/ alone and fails a record that has no file there.
- Validate markdown structure, frontmatter, runtime placement, permission consistency, and related links. Run
node .skilled/bin/sync-agent-roster.cjs --check after adding or editing an agent file and after editing the required-sections list in assets/agent-template.md: it compares every agent's outline with that list. A new agent file under .skilled/agents/ with no registry record fails it with agent file without a registry record: <name>.
- Deliver only after validation passes or after reporting the exact blocker.
When the user invokes /create:agent, treat the command as the preferred entry point, but keep this same creation contract as the source of truth for the generated file.
Validation Gate
Before delivery, verify document quality and runtime correctness.
python3 .skilled/skills/sk-doc/shared/scripts/validate_document.py .skilled/agents/agent-name.md --type agent
python3 .skilled/skills/sk-doc/shared/scripts/extract_structure.py .skilled/agents/agent-name.md
python3 .skilled/skills/sk-doc/shared/scripts/check_authored_name_kebab.py .skilled/agents/agent-name.md
Use .claude/agents/agent-name.md instead when Claude Code is the active runtime.
Required checks: frontmatter parses, filename stem matches name, the shared authored-name checker passes, required sections are present, runtime directory is correct, permissions match authority, task matches orchestration intent, related resources exist, and unresolved markdown links are reported.
4. RULES
✅ ALWAYS
- Decide agent vs skill vs command before writing the file.
- Search existing agents before creating a new one.
- Use the active runtime agent directory, not a convenient nearby path.
- Keep filename stem and frontmatter
name identical.
- Use the runtime-correct frontmatter schema —
permission: object for .skilled/agents/, tools: allow-list for .claude/agents/ — with explicit least-authority choices.
- Set
task: allow only when orchestration is the agent's explicit authority.
- Include hard boundary, core workflow, capability scan, output verification, anti-patterns, and related resources.
- Keep deep domain knowledge in skills or references and link to it.
- Validate with
../shared/scripts/validate_document.py before delivery.
- Keep this packet self-contained and leave advisor graph identity at the
sk-doc hub root.
⛔ NEVER
- Never add
graph-metadata.json to this packet.
- Never create an agent for reusable knowledge alone.
tools: is runtime-specific, not obsolete: it is Claude Code's canonical schema. Never emit tools: under .skilled/agents/, and never emit a bare permission: block under .claude/agents/.
- Never grant broad permissions because they might be useful later.
- Never give a LEAF agent
task: allow.
- Never paste full skill guidance into an agent body.
- Never write an agent into the wrong runtime directory.
- Never leave placeholders from
assets/agent-template.md in the final file.
- Never claim completion before validation passes or the blocker is reported.
⚠️ ESCALATE IF
- The requested role's authority boundary is unclear.
- Existing agents already cover the requested role.
- The requested permissions exceed the stated purpose.
- Runtime placement is ambiguous.
- The user asks for a component that mixes agent, skill, and command responsibilities without a clear owner.
- Validation fails with blocking frontmatter, section, or markdown errors.
5. SUCCESS CRITERIA
The agent file is done only when all of the following hold:
- The file lives in the active runtime agent directory, and the filename stem matches frontmatter
name.
- Frontmatter uses the runtime-correct schema —
permission: object for .skilled/agents/, tools: allow-list for .claude/agents/ — with explicit least-authority choices, and task/Task granted only when orchestration is the agent's explicit authority.
- The body carries every required section: hard boundary, core workflow, capability scan, output verification, anti-patterns, and related resources.
- Deep domain knowledge is linked to skills or references rather than pasted into the agent body, and no template placeholders remain.
validate_document.py and extract_structure.py run clean, and completion is claimed only after they pass or the exact blocker is reported.
6. REFERENCES
Use these only when the core path above is not enough:
references/README.md — route map over the overflow references below.
references/agent-vs-skill-vs-command.md for the deeper agent vs skill vs command decision and its signals.
references/permission-design.md for mode selection and least-authority permission design.
references/common-pitfalls.md for recurring mistakes with why-it-breaks and correct fixes.
assets/agent-template.md for exhaustive body variants, binding/refusal contracts, and scaffold examples.
../shared/references/validation.md for validation pipeline details.
../shared/references/core-standards.md for shared document structure rules.
1---2name: sk-create-agent3description: Scaffold OpenCode agents with runtime placement, permission frontmatter, authority boundaries, workflow sections, and validation.4allowed-tools: [Read, Write, Edit, Bash, Grep, Glob]5version: 1.0.10.06metadata:7 source: https://skillmd.com/skills/michelkerkmeester/sk-create-agent8---910# Create Agent - Runtime Persona Authoring1112`create-agent` is the `sk-doc` workflow packet for creating or updating one runtime agent markdown file. The executable contract lives here: decide whether an agent is the right component, place it in the active runtime directory, author current frontmatter and authority boundaries, then validate before delivery.1314Use `references/README.md` (the overflow route map) and `assets/agent-template.md` only for deeper examples, exhaustive variants, and long-form reference detail. Do not make those files the primary workflow contract.1516---1718## 1. WHEN TO USE1920### Activation Triggers2122Use this workflow when the request involves:23241. Creating a new OpenCode or Claude Code agent file.252. Updating an agent's frontmatter, permissions, authority boundary, workflow, verification contract, or anti-patterns.263. Converting a durable role description into a runtime persona with explicit authority and tool policy.274. Deciding whether the requested component should be an agent, skill, or command.285. Running or supporting `/create:agent`.2930Keyword triggers: `create agent`, `/create:agent`, `OpenCode agent`, `Claude Code agent`, `agent file`, `new agent`, `agent persona`, `agent frontmatter`, `permission object`, `authority boundary`, `agent template`, `agent and paired`, `agent registry`.3132Create an agent only when the system needs a stable named persona with explicit tool permissions, denied capabilities, behavioral constraints, orchestration authority, or reusable execution posture.3334### When NOT to Use3536Use another `sk-doc` packet when:37381. The request needs reusable knowledge, standards, templates, or long-form workflow guidance. Use `create-skill`.392. The request needs a slash-command entry point without a new runtime persona. Use `create-command`.403. The request needs a README, feature catalog, manual testing playbook, benchmark package, or changelog. Use `create-readme`, `create-feature-catalog`, `create-manual-testing-playbook`, `create-benchmark`, or `create-changelog`. A flowchart or any other diagram belongs to the `sk-design` hub (`/design:diagram`), which this hub does not register a packet for.414. The request audits, validates, scores, or optimizes an existing agent document. Use `create-quality-control`.4243---4445## 2. SMART ROUTING4647The `sk-doc` hub routes runtime-persona work here: a request to create or update one agent file.48The hub's `sk-create-agent` signal selects this packet.49Stay in this packet only when the artifact is a concrete runtime agent file whose authority boundary no existing agent already covers.50A skill, a command or an existing agent answers the rest.5152`references/README.md` is the route map.53It is also the fallback when the component or runtime is unclear.54A resolved request loads this packet's flat references and assets first, with `assets/agent-template.md` as the scaffold.5556Read [`ROUTER.md`](./ROUTER.md) before selecting skill-local resources.57Open only the matched files.5859---6061## 3. HOW IT WORKS6263### Component Choice6465Choose the component type before authoring: an agent answers who should do the work, a skill answers how the work should be done, and a command answers how a user should trigger the workflow. Healthy systems often pair all three: the agent provides persona and boundaries, the skill provides detailed domain knowledge, and the command provides the ergonomic entry point.6667### Output Package6869Create or update one markdown file in the active runtime agent directory.7071| Runtime profile | Agent directory |72| --- | --- |73| OpenCode | `.opencode/agents/` |74| Claude Code | `.claude/agents/` |75| Copilot/default OpenCode profile | `.opencode/agents/` |7677The output file contract:78791. The filename is kebab-case and ends in `.md`.802. The filename stem matches frontmatter `name` exactly.813. The stem matches `^[a-z0-9]+(?:-[a-z0-9]+)*$`; reject underscores, empty segments, and ambiguous normalization instead of rewriting the name silently.824. The file lives in the active runtime directory, not under `sk-doc`.835. The body is self-sufficient for the agent's role, boundaries, workflow, limits, and output contract.846. Reusable or deep domain guidance stays in skills or references and is linked, not pasted into the agent.8586### Canonical Frontmatter8788Frontmatter schema is runtime-specific — never emit the same schema for both runtime directories:8990| Runtime directory | Canonical schema | Rationale |91| --- | --- | --- |92| `.opencode/agents/` | `permission:` object | OpenCode enforces the `permission:` object; it ignores a standalone `tools:` key. |93| `.claude/agents/` | `tools:` allow-list | Claude Code enforces only `tools:` (a comma-separated allow-list); it silently ignores `permission:`. Omitting `tools:` makes the agent inherit the parent session's full, unrestricted tool set. |9495Decision rule:9697```text98Authoring for .skilled/agents/? -> emit `permission:` (never bare `tools:`)99Authoring for .claude/agents/? -> emit `tools:` (never `permission:`)100```101102**OpenCode (`.opencode/agents/`) frontmatter:**103104```yaml105---106name: agent-name107description: One-line purpose statement with scope and boundary108mode: subagent109temperature: 0.1110permission:111 read: allow112 write: allow113 edit: allow114 bash: allow115 grep: allow116 glob: allow117 webfetch: deny118 chrome_devtools: deny119 task: deny120 list: allow121 patch: deny122 external_directory: deny123---124```125126**Claude Code (`.claude/agents/`) frontmatter:**127128```yaml129---130name: agent-name131description: One-line purpose statement with scope and boundary132tools: Read, Write, Edit, Bash, Grep, Glob133---134```135136Map the `permission:` allow-set to the `tools:` list when authoring the same role for both runtimes: include only the tools with `allow` (or `ask`) and drop the ones with `deny`. `mode` and `temperature` are OpenCode-only fields with no Claude Code equivalent — omit both from `.claude/agents/` frontmatter.137138Frontmatter rules:1391401. `name` must match the filename stem.1412. `description` is one line describing role and scope.1423. `mode` and `temperature` are OpenCode-only fields; set `mode` to match runtime invocation (commonly `subagent` for specialists) and `temperature` to reflect determinism needs (commonly `0.1`) — `.claude/agents/` frontmatter omits both.1434. Under `.skilled/agents/`, `permission` values must be explicit, least-authority, justified by the role, and use only `allow`, `deny`, or `ask`.1445. Under `.claude/agents/`, `tools:` is the runtime-specific canonical schema — a comma-separated least-authority allow-list; never emit `permission:` there, and never leave `tools:` absent or empty (an absent `tools:` inherits the parent session's full tool set).1456. Set `task: allow` (or include `Task` in `tools:`) only for agents whose explicit authority is orchestration.146147### Required Body Shape148149Start from `assets/agent-template.md` when creating a new agent. At minimum, a production-ready agent includes:1501511. H1 and short purpose statement.1522. Hard boundary section that states nesting, delegation, and write limits.1533. Core workflow section that describes how the agent acts.1544. Capability scan section that identifies relevant skills, tools, commands, or companion agents.1555. Output verification section that defines checks required before claiming completion.1566. Anti-patterns section that names failure modes.1577. Related resources section with real supporting paths.158159Boundary variants:160161- LEAF write-capable agents deny nested sub-agent dispatch and restrict mutation to explicitly scoped paths.162- LEAF read-only agents deny nested dispatch and all file mutation.163- Orchestrators may dispatch only when orchestration is their explicit authority and `task` permission allows it.164- Command-driven or machine-validated agents may need input/scope gates before workflow steps.165166### Sanctioned Section-Vocabulary Dialects167168The skeleton above is the default, so start new agents from it.169One alternate section vocabulary is also sanctioned for the **deep-loop leaf-iteration agents** (`@deep-review` / `@deep-research`, in both runtime directories).170A per-iteration loop worker reads more clearly under lane-named headings, so these agents carry the same responsibilities under a different vocabulary:171- `ROUTING SCAN`.172- a lane `CONTRACT`, which is `REVIEW CONTRACT`, or `ITERATION PROTOCOL` for the leaner research variant.173- `STATE MANAGEMENT`, plus `+ WRITE SAFETY` where the agent mutates.174- a lane `ADVERSARIAL CHECK`, which is `ADVERSARIAL SELF-CHECK`.175- `RULES`.176177This is a documented shape, not drift.178`--type agent` requires only `## 1. CORE WORKFLOW`, and the dialect still carries every hard-block boundary, capability, verification and anti-pattern responsibility from "Required Body Shape" above.179Reach for it only when authoring another member of the deep-loop iteration family.180Do not invent a fresh dialect for a one-off agent.181The concrete section order and its two sub-variants are in `assets/agent-template.md` §9.182183### Ordered Creation Workflow184185Follow this order for new agents and material rewrites:1861871. Read the request and define the proposed role, authority boundary, and likely runtime directory.1882. Decide whether the task truly needs a new agent instead of a skill, command, or existing agent.1893. Search existing agents for overlap before creating a new one.1904. Resolve the active runtime directory and target filename.1915. Read `assets/agent-template.md` and use it as the scaffold; do not invent a new structure from scratch.1926. Draft frontmatter first, especially `mode`, `temperature`, and each `permission` value.1937. Confirm permissions against actual role needs before writing tool-heavy instructions.1948. Write the hard boundary section before the general workflow.1959. Write the core workflow and capability scan.19610. Add explicit output verification, anti-patterns, and related resources.19711. Link supporting skills, commands, references, and companion agents rather than copying their full guidance.19812. Remove template placeholders and check that the document stays focused on the runtime role.19913. For a new agent under `.skilled/agents/`, add a record to `.skilled/agents/agent-registry.json`, copying an existing record as the pattern. A record carries `name`, `tier`, `priority`, `dispatchers`, `taskType`, `skills`, `notes` and `summary`, and `templateExceptions` only when the file leaves out a required section. Then run `node .skilled/bin/sync-agent-roster.cjs` so the generated rosters pick the agent up. An agent that exists only in `.claude/agents/` gets no record: the roster check reads `.skilled/agents/` alone and fails a record that has no file there.20014. Validate markdown structure, frontmatter, runtime placement, permission consistency, and related links. Run `node .skilled/bin/sync-agent-roster.cjs --check` after adding or editing an agent file and after editing the required-sections list in `assets/agent-template.md`: it compares every agent's outline with that list. A new agent file under `.skilled/agents/` with no registry record fails it with `agent file without a registry record: <name>`.20115. Deliver only after validation passes or after reporting the exact blocker.202203When the user invokes `/create:agent`, treat the command as the preferred entry point, but keep this same creation contract as the source of truth for the generated file.204205### Validation Gate206207Before delivery, verify document quality and runtime correctness.208209```bash210python3 .skilled/skills/sk-doc/shared/scripts/validate_document.py .skilled/agents/agent-name.md --type agent211python3 .skilled/skills/sk-doc/shared/scripts/extract_structure.py .skilled/agents/agent-name.md212python3 .skilled/skills/sk-doc/shared/scripts/check_authored_name_kebab.py .skilled/agents/agent-name.md213```214215Use `.claude/agents/agent-name.md` instead when Claude Code is the active runtime.216217Required checks: frontmatter parses, filename stem matches `name`, the shared authored-name checker passes, required sections are present, runtime directory is correct, permissions match authority, `task` matches orchestration intent, related resources exist, and unresolved markdown links are reported.218219---220221## 4. RULES222223### ✅ ALWAYS2242251. Decide agent vs skill vs command before writing the file.2262. Search existing agents before creating a new one.2273. Use the active runtime agent directory, not a convenient nearby path.2284. Keep filename stem and frontmatter `name` identical.2295. Use the runtime-correct frontmatter schema — `permission:` object for `.skilled/agents/`, `tools:` allow-list for `.claude/agents/` — with explicit least-authority choices.2306. Set `task: allow` only when orchestration is the agent's explicit authority.2317. Include hard boundary, core workflow, capability scan, output verification, anti-patterns, and related resources.2328. Keep deep domain knowledge in skills or references and link to it.2339. Validate with `../shared/scripts/validate_document.py` before delivery.23410. Keep this packet self-contained and leave advisor graph identity at the `sk-doc` hub root.235236### ⛔ NEVER2372381. Never add `graph-metadata.json` to this packet.2392. Never create an agent for reusable knowledge alone.2403. `tools:` is runtime-specific, not obsolete: it is Claude Code's canonical schema. Never emit `tools:` under `.skilled/agents/`, and never emit a bare `permission:` block under `.claude/agents/`.2414. Never grant broad permissions because they might be useful later.2425. Never give a LEAF agent `task: allow`.2436. Never paste full skill guidance into an agent body.2447. Never write an agent into the wrong runtime directory.2458. Never leave placeholders from `assets/agent-template.md` in the final file.2469. Never claim completion before validation passes or the blocker is reported.247248### ⚠️ ESCALATE IF2492501. The requested role's authority boundary is unclear.2512. Existing agents already cover the requested role.2523. The requested permissions exceed the stated purpose.2534. Runtime placement is ambiguous.2545. The user asks for a component that mixes agent, skill, and command responsibilities without a clear owner.2556. Validation fails with blocking frontmatter, section, or markdown errors.256257---258259## 5. SUCCESS CRITERIA260261The agent file is done only when all of the following hold:2622631. The file lives in the active runtime agent directory, and the filename stem matches frontmatter `name`.2642. Frontmatter uses the runtime-correct schema — `permission:` object for `.skilled/agents/`, `tools:` allow-list for `.claude/agents/` — with explicit least-authority choices, and `task`/`Task` granted only when orchestration is the agent's explicit authority.2653. The body carries every required section: hard boundary, core workflow, capability scan, output verification, anti-patterns, and related resources.2664. Deep domain knowledge is linked to skills or references rather than pasted into the agent body, and no template placeholders remain.2675. `validate_document.py` and `extract_structure.py` run clean, and completion is claimed only after they pass or the exact blocker is reported.268269---270271## 6. REFERENCES272273Use these only when the core path above is not enough:2742751. `references/README.md` — route map over the overflow references below.2762. `references/agent-vs-skill-vs-command.md` for the deeper agent vs skill vs command decision and its signals.2773. `references/permission-design.md` for `mode` selection and least-authority permission design.2784. `references/common-pitfalls.md` for recurring mistakes with why-it-breaks and correct fixes.2795. `assets/agent-template.md` for exhaustive body variants, binding/refusal contracts, and scaffold examples.2806. `../shared/references/validation.md` for validation pipeline details.2817. `../shared/references/core-standards.md` for shared document structure rules.