Create Command
create-command is the command-authoring workflow packet of the sk-doc parent hub. It creates and improves OpenCode slash commands under .skilled/commands/ with executable workflows, precise frontmatter, required input gates, least-privilege tools, and router/presentation separation when needed.
This SKILL.md contains the core creation workflow. Use the references/ route map (references/README.md), assets/command-template.md, assets/command-router-template.md, assets/command-presentation-template.md, and ../shared/ only for exhaustive examples, edge cases, and validator implementation detail.
This packet is lean and self-contained. The advisor identity lives at the sk-doc hub root: do not add packet-local graph-metadata.json.
1. WHEN TO USE
Activation Triggers
Use this packet when the request involves:
- Creating a new OpenCode slash command.
- Refactoring a command into a thin router plus owned presentation asset.
- Adding or fixing command frontmatter, especially
argument-hintandallowed-tools. - Designing command argument handling with
$ARGUMENTS. - Authoring a namespace command such as
/namespace:action. - Separating visible prompts, dashboards, result templates, or next-step wording into a presentation contract.
- Checking whether a workflow should be a command instead of a skill, agent, or one-off task.
Keyword triggers: create command, /create:command, slash command, OpenCode command, argument-hint, allowed-tools, command template, router presentation split, thin router, presentation contract, paired /create, $ARGUMENTS.
When NOT to Use
Use another sk-doc packet when:
- The request is to create a skill or parent hub. Use
create-skill. - The request is to create an agent. Use
create-agent. - The task is a README, feature catalog, manual testing playbook, benchmark package, flowchart, or changelog. Use
create-readme,create-feature-catalog,create-manual-testing-playbook,create-benchmark,create-flowchart, orcreate-changelog. - The task audits, validates, scores, or optimizes an existing command document. Use
create-quality-control. - The task is one-time work that does not need a reusable slash command.
- The command already exists and the user only wants runtime debugging.
- The requested workflow is destructive or externally privileged but lacks confirmation and rollback requirements.
2. SMART ROUTING
The sk-doc hub routes command-authoring work here: a request to create, refactor or repair an OpenCode slash command, and the hub's sk-create-command signal selects this packet.
Execution-mode suffixes such as :auto and :confirm are command syntax, not packet-selection triggers.
references/README.md is the route map, and the fallback when the command purpose or component surface is unclear.
A resolved request loads this packet's flat references and its command templates under assets/ first.
Read ROUTER.md before selecting skill-local resources; open only the matched files.
3. HOW IT WORKS: CREATION WORKFLOW
Follow these steps in order.
Step 1: Decide Whether A Command Is Correct
Create a command only when the workflow is repeatable and has defined steps.
Use a command when the workflow:
- Automates a multi-step process.
- Needs repeatable execution across sessions.
- Needs
$ARGUMENTSparsing or mode routing. - Needs user-controlled execution pace such as
:autoor:confirm. - Needs confirmation gates for destructive or privileged actions.
- Benefits from explicit tool restrictions.
Use a skill instead when the content is reusable reference knowledge, domain guidance, standards, or patterns shared by multiple workflows. Do not create a command for one-off work.
Step 2: Resolve Invocation And Path
Determine the command invocation before writing:
- Root command:
.skilled/commands/<command>.mdbecomes/<command>. - Namespace command:
.skilled/commands/<namespace>/<action>.mdbecomes/<namespace>:<action>. - Namespace and action names use lowercase hyphen-case.
- Each command, namespace and action segment matches
^[a-z0-9]+(?:-[a-z0-9]+)*$. Reject underscores, empty segments and ambiguous normalization. The emitted.mdstem must equal the validated action name.
For grouped related actions, prefer a namespace directory:
.skilled/commands/
└── <namespace>/
├── <action1>.md
├── <action2>.md
└── <action3>.md
Step 3: Read Existing Files First
Before editing an existing command or owned asset, read it completely enough to understand current behavior. Preserve behavior unless the user explicitly asks to change it.
For new commands, inspect nearby commands in the same namespace when available so structure and vocabulary match the command family.
Step 4: Classify The Command Type
Choose the smallest command type that fits:
| Type | Use When | Typical Shape |
|---|---|---|
| Simple | Single action, few arguments | One .md file, direct steps |
| Workflow | Multi-step process with checkpoints | One .md file with overview, instructions, recovery |
| Mode-based | Supports :auto / :confirm |
Thin router plus owned assets when complex |
| Router | Thin dispatcher: verify agent, resolve mode/args, hand off to owned assets | Router .md plus owned presentation .txt and optional workflow YAML or scripts |
| Argument dispatch | Multiple action keywords or query forms | ASCII routing tree plus handlers |
| Destructive | Deletes data or irreversible changes | Explicit confirmation, affected-state display, recovery guidance |
| Namespace | Related commands grouped together | Directory under .skilled/commands/ |
If the command combines patterns, parse mode first, then dispatch remaining arguments.
Step 5: Choose The Output Package Shape
For a simple or medium command, create or update:
.skilled/commands/<command>.md
For a namespace command, create or update:
.skilled/commands/<namespace>/<action>.md
For a split mode-based workflow command, create or update:
.skilled/commands/<namespace>/<action>.md
.skilled/commands/<namespace>/assets/<namespace>-<action>-presentation.txt
.skilled/commands/<namespace>/assets/<namespace>-<action>-auto.yaml
.skilled/commands/<namespace>/assets/<namespace>-<action>-confirm.yaml
Use -auto.yaml and -confirm.yaml only for workflow-backed families that route execution into workflow assets. Direct-router families dispatch directly to tools/scripts and do not need workflow YAML.
Asset stems are hyphen-joined, never underscore-joined. The stem carries the namespace, the action and the kind:
create-readme-auto.yamlspeckit-plan-presentation.txtcreate-command-confirm.yaml
A family whose action names already read unambiguously on their own drops the namespace and names assets <action>-<kind>.
For example, memory ships save-presentation.txt and design ships extract-auto.yaml.
Follow the family you are extending.
A new family takes the namespace prefix.
The contract's metadata.asset_naming carries the same rule in machine-readable form, and generate-command-routers.cjs --check compares each router's tables against it.
For a compiled-stub router, the .md is a generated thin stub carrying the render-command-contract marker. Its section shape is rendered from a compiled source at invocation, not authored in the file. Do not hand-write section headings into a compiled stub, and keep its owned presentation/workflow assets alongside it:
.skilled/commands/<namespace>/<action>.md # compiled stub (render-command-contract marker)
.skilled/commands/<namespace>/assets/<namespace>-<action>-presentation.txt
Step 6: Author Frontmatter First
Every command starts with YAML frontmatter.
Required:
---
description: Action-oriented single-line description
---
Recommended when applicable:
argument-hint: "<required> [optional] [--flag]"
allowed-tools: Read, Write, Edit, Bash
Rules:
- Keep
descriptionsingle-line, action-oriented, and concise. - Target descriptions at or under 110 characters.
- Do not use YAML block scalars for
description. - Use
argument-hintwhenever the command expects user input. - Use
<angle-brackets>only for required arguments. - Use
[square-brackets]for optional arguments. - Keep
argument-hintat or under 140 characters: the hint summarizes the invocation shape while the router's EXECUTION TARGETS section enumerates the full flag surface. Over-budget hints warn (never block). Move the exhaustive flag list into the router body. - List every tool the command actually uses in
allowed-tools. - Do not add broad tools just in case.
- For MCP tools in
allowed-tools, use fully qualified names such asmcp__<server>__<tool>. - Bare tool names such as
advisor_recommendbelong in prose only, notallowed-tools.
Loader gating. Frontmatter is the load gate: allowed-tools authorizes exactly the tools and MCP surfaces a command may use, and any agent the router dispatches must both be admitted by that gate and resolve to a real agent definition in the active runtime's agent directory. Do not dispatch a handle the frontmatter does not admit or that does not exist.
Step 7: Add Mandatory Input Gates
If argument-hint contains any required <argument>, add the mandatory gate after the H1 and its purpose line, before mode routing, asset loading and every workflow step.
The gate must:
- Check whether
$ARGUMENTSis empty, undefined, or whitespace-only. - Ignore mode suffixes when determining whether required content exists.
- Stop immediately when required input is missing.
- Ask a context-specific question with clear options or expected reply format.
- Wait for the user response.
- Use only
$ARGUMENTSor the user's explicit answer as the input. - Forbid inference from context, screenshots, conversation history, or open files.
For multi-input commands, use a blocking phase pattern:
- Phase 1: input collection.
- Phase 2: prerequisite/context verification.
- Phase status verification table.
- Violation self-detection block.
Every workflow command with blocking phases must include violation self-detection: if a required phase was skipped, stop, state the violation, return to the phase, and complete it properly.
Step 8: Write The Command Body
Use executable, instruction-oriented sections. Commands are workflows, not long reference manuals.
Common section order:
- Title and purpose.
- Contract.
- Workflow overview or argument routing.
- Instructions.
- Failure recovery and error handling when needed.
- Examples.
- Status output patterns or completion report.
Use these conventions:
- H1: plain command title, or a blocking semantic title for mandatory gates.
- H2:
## N. SECTION-NAME, using full integers only. - H3 steps:
### Step N: Description. - Do not use decimal steps such as
1.5or2.5. - Put sub-activities in bullets under a numbered step.
- Use dividers between major sections when they improve scanability.
- Return structured statuses such as
STATUS=OK,STATUS=FAIL ERROR="<message>", orSTATUS=CANCELLED ACTION=cancelled. - Keep the body behavioral: routing, gates, contracts, and executable steps only. Do NOT embed design rationale, prose-register or prompt-framework labels (e.g. "written objective-first", "(COSTAR)") or development notes (benchmark timings, spec/packet cross-references). Do NOT embed maintainer chores ("keep AGENTS/skills synchronized to this entrypoint") or defensive self-attestations ("no workflow-asset gap exists"). That context belongs in the decision-record, changelog, or presentation asset (never in the shipped command a user sees rendered).
Approved common H2 section names include:
PURPOSECONTRACTWORKFLOW OVERVIEWINSTRUCTIONSARGUMENT ROUTINGREFERENCEEXAMPLESRELATED COMMANDSTOOL SIGNATURESUSER INPUT
Approved canonical H2 section names for router commands (see Step 11):
ROUTER CONTRACTOWNED ASSETSMODE ROUTINGEXECUTION TARGETSPRESENTATION BOUNDARYWORKFLOW SUMMARY
Step 9: Implement Argument Dispatch When Needed
For commands with multiple entry points, include an ASCII routing tree based on $ARGUMENTS.
Route by:
- Empty arguments.
- First-word action keywords, case-insensitive.
- Natural-language query patterns.
- Single ambiguous words.
- Flags and options.
Then define one handler section per action. Show example routing in a table so future maintainers can verify behavior quickly.
Argument-echo deprecation. Do not end a command with a bare User request: $ARGUMENTS line. The command already receives $ARGUMENTS. Echoing it verbatim adds no routing behavior and duplicates the argument surface the router resolves. Resolve arguments in the router body. The validator warns on the raw-echo idiom.
Step 10: Implement Mode Routing When Needed
For commands supporting :auto and :confirm, document mode detection:
| Pattern | Mode | Behavior |
|---|---|---|
/command:auto |
Autonomous | Execute without user approval gates |
/command:confirm |
Interactive | Pause at each step for user approval |
/command |
Prompt | Ask user to choose execution mode |
Autonomous mode self-validates at checkpoints, makes informed decisions, and records significant decisions.
Interactive mode pauses after each step for approval, presents options such as approve, review details, modify, skip, or abort, and records user decisions.
If the mode-based command is large or has visible dashboards/prompts/results, use the router/presentation split.
Mode completeness. Every mode a command advertises must be fully realized, not merely reachable.
For each mode in the argument hint (:auto, :confirm), the command must have both its workflow asset (the -auto.yaml / -confirm.yaml) and an EXECUTION TARGETS row that resolves the mode to that asset.
A hint that lists :auto with no -auto.yaml or no :auto execution row is incomplete, because a reader cannot route the advertised mode.
Declare only the modes you have wired end to end.
Step 11: Author The Router As A First-Class Command Type
A router is a first-class command type, not a loose refactor. Its .md is a thin dispatcher: verify the orchestrating agent, resolve mode and arguments, then hand off to owned assets (a presentation .txt, optional -auto.yaml / -confirm.yaml, or scripts). It carries no inline dashboards, prompts, or result templates.
Detection signature. The validator treats a command as a router when any of:
- a
render-command-contractmarker is present (the compiled-stub variant, which has no authored section requirements), or - a
Presentation Boundarysection is present, or - two or more of
{Router Contract, Owned Assets, Mode Routing, Execution Targets}co-occur.
Minimal core vs recommended. A router must include the blocking core only: Owned Assets and Presentation Boundary.
The remaining canonical sections (Router Contract, Mode Routing, Execution Targets, Workflow Summary) are recommended and surface as non-blocking warnings when absent.
Author the full shape for new routers.
The minimal core lets incremental migrations land without failing.
Canonical vocabulary (numbered ## N., full integers). Use exactly these H2 names, in this order, for a fully-shaped router:
## 1. ROUTER CONTRACT
## 2. OWNED ASSETS
## 3. MODE ROUTING
## 4. EXECUTION TARGETS
## 5. PRESENTATION BOUNDARY
## 6. WORKFLOW SUMMARY
Do not invent divergent synonyms (Routing Assets, Workflow Routing, Execution Order). The validator alias-normalizes those as a safety net, but the authored end state is the canonical names above.
Ownership boundary. The router owns:
- the mandatory input gate or Phase 0.
- the owned-assets table, mode resolution and argument routing.
- execution-target selection and the presentation boundary.
- a short workflow summary.
The presentation asset owns:
- startup prompts and consolidated setup questions.
- auto fail-fast display text.
- dashboard and checkpoint layouts.
- success and failure result templates.
- next-step suggestions.
The router must not contain inline startup-question wording, dashboard templates, result templates, or next-step wording when a presentation asset exists. The split is behavior-preserving: move display content, do not change routing semantics.
Variants (one type, differing only by hand-off, not by required sections). Each maps to the contract's topology field:
- Workflow-YAML-backed (
topology: mode-pair): routes execution into-auto.yaml/-confirm.yamlworkflow assets. EXECUTION TARGETS is the| Mode | Target |table. - Direct-dispatch-script (
topology: direct-dispatch): dispatches directly to tools or scripts, no workflow YAML. The mode table is not required. - Subaction route-manifest (
topology: subaction-route-manifest): a direct-dispatch router that resolves sub-actions through an owned_routes.yamlmanifest. - Compiled-stub: a generated stub carrying the
render-command-contractmarker whose contract is rendered at invocation. It is exempt from authored section requirements (retained variant, no command currently uses it).
Which family uses which topology is defined by the machine-readable command contract (assets/command-contract.json, validated by assets/command-contract.schema.json). Consult it rather than a hand-maintained family list. Use assets/command-router-template.md for the canonical numbered router skeleton, and assets/command-presentation-template.md for the full presentation asset skeleton.
Template self-sufficiency. Each router variant must be authorable from its template alone.
command-router-template.md plus the family's command-contract.json entry carry every section, vocabulary and asset-path shape a new router needs.
If a required shape is not derivable from the template and the contract, the template is incomplete.
Fix the template rather than copying a sibling command.
This keeps the contract the single source and lets generate-command-routers.cjs --check detect drift instead of it hiding in hand-copied prose.
Step 12: Add Destructive-Action Safety
For commands that delete data or make irreversible changes, include:
- Frontmatter that makes destructive intent visible when appropriate.
- Confirmation by default.
--confirmonly when explicitly designed to skip the prompt.- Affected-state display before execution.
- Clear list of items that will be deleted or changed.
- Execution logging.
- Completion verification.
- Recovery or rebuild guidance.
STATUS=CANCELLED ACTION=cancelledwhen the user aborts.
Do not ship destructive commands without confirmation and recovery design.
Step 13: Validate Before Delivery
Before publishing or claiming the command is valid, verify:
descriptionexists, is action-oriented, and is single-line.argument-hintexists when arguments are expected.allowed-toolslists only tools actually used.- Required
<arguments>have a mandatory gate after the H1 and its purpose line, before any workflow step. - The gate forbids inference and waits for explicit input.
- Section numbering uses full integers only.
- H2 headers follow
## N. SECTION-NAME. - Instructions are actionable.
- Examples cover two or three likely invocations.
- Status output uses a structured pattern.
- Thin routers contain no presentation templates when a presentation asset exists.
- Router commands carry the blocking core (
OWNED ASSETS+PRESENTATION BOUNDARY) and use the canonical numbered vocabulary from Step 11. The remaining router sections are present or intentionally left as warnings.
Run shared validators when available:
python3 ../shared/scripts/check_authored_name_kebab.py <command-file.md>
python3 ../shared/scripts/validate_document.py <command-file.md> --type command
python3 ../shared/scripts/extract_structure.py <command-file.md>
Exit code 0 from the authored-name checker and validate_document.py is required before stating that the command document is structurally valid. If validation cannot be run, say that explicitly.
4. RULES
ALWAYS
- Read existing target files before editing.
- Use the smallest command type that fits the workflow.
- Put executable workflow steps in the command, not only in references.
- Use
argument-hintfor expected user input. - Add a mandatory gate for required arguments.
- Keep
descriptionconcise, single-line, and invocation-oriented. - Keep
allowed-toolsleast-privilege and accurate. - Use fully qualified MCP tool IDs in
allowed-tools. - Keep presentation text in the presentation asset when using a split.
- Validate with shared create-quality-control scripts before delivery.
- Keep this nested packet free of
graph-metadata.json.
NEVER
- Never create a command for one-off work that does not need reuse.
- Never skip mandatory gates for required arguments.
- Never infer missing required input from context or conversation history.
- Never use broad
allowed-toolsjust in case. - Never put dashboards, startup prompts, or result templates inside a thin router when a presentation asset exists.
- Never omit confirmation gates for destructive or irreversible actions.
- Never turn a command into long reference documentation.
- Never add advisor identity metadata inside this nested packet.
- Never claim structural validity without running validation or stating it was not run.
ESCALATE IF
- The command name, namespace, or invocation contract is unclear.
- Required arguments cannot be safely defaulted.
- The command would perform destructive work without explicit confirmation requirements.
- Tool permissions are broader than the workflow appears to need.
- Router logic and presentation wording cannot be separated without changing behavior.
- The request belongs to a skill, agent, or one-off task instead of a slash command.
5. SUCCESS CRITERIA
A command produced through this packet is complete when:
- The correct component type was chosen: the workflow genuinely warrants a slash command rather than a skill, agent, or one-off task.
- Frontmatter is well-formed: a single-line, action-oriented
description, anargument-hintwhenever user input is expected, and a least-privilegeallowed-toolslist using fully qualified MCP tool IDs. - Every required
<argument>has a mandatory input gate after the H1 and its purpose line, before any workflow step, that forbids inference and waits for explicit input. - The body is executable and instruction-oriented, with full-integer
## N. SECTION-NAMEheadings, actionable steps, two or three example invocations, and structured status output. - Router commands keep the blocking core (
OWNED ASSETSplusPRESENTATION BOUNDARY), use the canonical numbered vocabulary, and hold no presentation templates when a presentation asset exists. - Shared validation was run:
validate_document.pyexits0, or its absence is stated explicitly rather than assumed.
6. DEEP DETAIL REFERENCES
Use these only for overflow detail, long examples, and exact skeletons:
references/README.md- overflow route map for this packet: it indexes the single-concern reference files below.references/worked-example.md- the canonical file contract plus a fully worked split command (router.mdand presentation.txt).references/router-presentation-split.md- router/presentation ownership, the before/after split transformation, and the behavior-preserving rule.references/argument-hints-and-modes.md- argument-hint design patterns,:auto/:confirmmode design, and frontmatter/description budget tips.references/common-pitfalls.md- command-vs-skill-vs-agent selection and the common command-authoring mistakes table.assets/command-template.md- exhaustive command type templates, examples, vocabulary, and validation checklist.assets/command-router-template.md- canonical numbered router skeleton with variant call-outs.assets/command-presentation-template.md- full-presentation.txtskeleton for split command families.assets/command-contract.json/assets/command-contract.schema.json- machine-readable behavioral contract for the command families and its schema.../shared/references/core-standards.md- shared document quality standards.../shared/references/validation.md- shared validation expectations.../shared/scripts/validate_document.py- blocking structure validation.../shared/scripts/extract_structure.py- structure extraction for review.