Setting the file. One moment.
Subchapter 23.14
references/execution-shapes.mdMarkdown5 KBView on GitHub
Use this guide to choose the runtime shape of a skill before you decide its files. Default rule: choose the simplest adequate shape, then add complexity only when it clearly improves outcomes. Once you pick a shape, load only the concrete leaf references it needs.
Start from these questions, in order:
inline-guidance.reference-backed-expert.script-backed-workflow.argument-driven.Do not jump to advanced mechanics because they sound powerful.
Adding shape complexity should usually replace ambiguity, not add ceremony.
| Addition | Require |
|---|---|
| new reference | a routed lookup need that existing files cannot satisfy precisely |
| new script | a repeated operation that is fragile or error-prone in plain instructions |
| new route | distinct inputs that require different tools, references, or output contracts |
| provider-specific mechanic | a capability that portable prompt guidance cannot provide |
If the benefit is only “more thorough”, keep the simpler shape and tighten the existing instructions.
| Shape | Use when | Open next | Portability notes |
|---|---|---|---|
inline-guidance | one coherent policy, checklist, or procedure is enough | references/layout-inline-skill.md | most portable default |
reference-backed-expert | optional deep knowledge is the main complexity | references/layout-reference-backed-skill.md | portable if file references stay relative |
script-backed-workflow | repeated parsing, validation, APIs, or transformations are fragile in plain shell | references/layout-script-backed-workflow.md | portable if dependencies are explicit |
argument-driven | the skill is usually invoked with issue numbers, paths, targets, or modes | references/layout-argument-driven-skill.md | often provider-specific beyond basic manual invocation |
router | distinct categories need different downstream prompts, tools, or references | references/workflow-routing.md | portable if routing stays in prompt logic |
parallelization | independent subtasks or multiple votes improve speed or confidence | references/workflow-parallel.md | often implemented with tools or agents |
orchestrator-workers | the number or type of subtasks is discovered at runtime | references/workflow-orchestrator-workers.md | usually higher-latency and provider-sensitive |
subagent-fork | the skill needs isolated context, tools, or model defaults | references/claude-subagent-fork.md | Claude Code-specific |
hook-backed | deterministic enforcement is required beyond prompt guidance | references/claude-hook-backed.md | highly provider-specific and security-sensitive |
asset-template | reusable templates, schemas, or static artifacts carry most of the value | references/layout-asset-template-skill.md | portable if assets are generic files |
If the chosen shape also uses explicit arguments, Claude-specific frontmatter, or shell preprocessing, load the matching flat references/claude-* file listed in SKILL.md.
These are not usually primary execution shapes, but they often refine one:
references/workflow-prompt-chaining.mdreferences/workflow-validation-loops.mdreferences/workflow-plan-validate-execute.mdUse a hybrid only when one primary shape is insufficient.
Do not finalize a skill when any of these are true: