sk-create-command

Create Command

create-command is the command-authoring workflow packet of the sk-doc parent hub. It creates and improves OpenCode slash commands under .opencode/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-hint and allowed-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, install guide, feature catalog, manual testing playbook, benchmark package, flowchart, or changelog. Use create-readme, create-feature-catalog, create-manual-testing-playbook, create-benchmark, create-flowchart, or create-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

These triggers route a request into this command-authoring packet. Execution-mode suffixes are command syntax, not packet-selection triggers. When the surface is a slash command, stay in this packet and continue to the creation workflow below.

Router Resilience

This packet routes by command-authoring intent and the requested component surface. It does not use runtime keyed resource discovery through references/<key>/ because its references are flat.

• Load optional markdown resources only after resolving them under this packet and confirming they exist.
• Treat references/README.md as the fallback route map when command intent or component surface is unclear.
• Ask for the missing command purpose, invocation shape, or component type instead of silently loading no resources.
• Do not add a full references/<key>/ or assets/<key>/ runtime-key router unless this packet gains real keyed resource subdirectories.

Resource Loading Sequence

The packet keeps its existing flat-resource routing while using the shared resilience call sequence:

def discover_markdown_resources():
    return flat markdown resources under this packet's `references/` and `assets/` folders

def _guard_in_skill(relative_path):
    # Keep packet-local markdown paths in scope; retain explicitly documented shared routes.
    confirm the path is an allowed markdown resource for this packet

def load_if_available(relative_path, inventory, seen):
    guarded = _guard_in_skill(relative_path)
    if guarded in inventory and guarded not in seen:
        load(guarded)
        seen.add(guarded)

def route_create_command_request(request):
    inventory = discover_markdown_resources()
    intents = score_intents(request)  # command-authoring intent and component surface
    selected = select_intents(intents)
    routing_key = get_routing_key(request, selected)
    if not selected or the command purpose or component surface is unclear:
        load_if_available("references/README.md", inventory, seen)
        return UNKNOWN_FALLBACK
    return route by the existing command-authoring intent and component-surface rules

UNKNOWN_FALLBACK asks for the command purpose, invocation shape, or component type. The sequence discovers the current flat resources at routing time, guards and loads only available resources without duplicates, then applies the activation triggers and command-type rules already defined below.

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 $ARGUMENTS parsing or mode routing.
• Needs user-controlled execution pace such as :auto or :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: .opencode/commands/<command>.md becomes /<command>.
• Namespace command: .opencode/commands/<namespace>/<action>.md becomes /<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 .md stem must equal the validated action name.

For grouped related actions, prefer a namespace directory:

.opencode/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:

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:

.opencode/commands/<command>.md

For a namespace command, create or update:

.opencode/commands/<namespace>/<action>.md

For a split mode-based workflow command, create or update:

.opencode/commands/<namespace>/<action>.md
.opencode/commands/<namespace>/assets/<namespace>_<action>_presentation.txt
.opencode/commands/<namespace>/assets/<namespace>_<action>_auto.yaml
.opencode/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.

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:

.opencode/commands/<namespace>/<action>.md            # compiled stub (render-command-contract marker)
.opencode/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 description single-line, action-oriented, and concise.
• Target descriptions at or under 110 characters.
• Do not use YAML block scalars for description.
• Use argument-hint whenever the command expects user input.
• Use <angle-brackets> only for required arguments.
• Use [square-brackets] for optional arguments.
• Keep argument-hint at 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 as mcp__<server>__<tool>.
• Bare tool names such as memory_context belong in prose only, not allowed-tools.

Step 7: Add Mandatory Input Gates

If argument-hint contains any required <argument>, add the mandatory gate immediately after frontmatter, before all other content.

The gate must:

• Check whether $ARGUMENTS is 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 $ARGUMENTS or 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:

1. Title and purpose.
2. Contract.
3. Workflow overview or argument routing.
4. Instructions.
5. Failure recovery and error handling when needed.
6. Examples.
7. 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.5 or 2.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>", or STATUS=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)"), development notes (benchmark timings, spec/packet cross-references), 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:

• PURPOSE
• CONTRACT
• WORKFLOW OVERVIEW
• INSTRUCTIONS
• ARGUMENT ROUTING
• REFERENCE
• EXAMPLES
• RELATED COMMANDS
• TOOL SIGNATURES
• USER INPUT

Approved canonical H2 section names for router commands (see Step 11):

• ROUTER CONTRACT
• OWNED ASSETS
• MODE ROUTING
• EXECUTION TARGETS
• PRESENTATION BOUNDARY
• WORKFLOW 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.

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 10: Implement Mode Routing When Needed

For commands supporting :auto and :confirm, document mode detection:

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 — a reader cannot route the advertised mode — so 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-contract marker is present (the compiled-stub variant, which has no authored section requirements); or
• a Presentation Boundary section 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, argument routing, execution-target selection, the presentation boundary, and 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, and 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.yaml workflow 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.yaml manifest.
• Compiled-stub — a generated stub carrying the render-command-contract marker whose contract is rendered at invocation; 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.
• --confirm only 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=cancelled when 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:

• description exists, is action-oriented, and is single-line.
• argument-hint exists when arguments are expected.
• allowed-tools lists only tools actually used.
• Required <arguments> have a mandatory gate immediately after frontmatter.
• 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; 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:

1. Read existing target files before editing.
2. Use the smallest command type that fits the workflow.
3. Put executable workflow steps in the command, not only in references.
4. Use argument-hint for expected user input.
5. Add a mandatory gate for required arguments.
6. Keep description concise, single-line, and invocation-oriented.
7. Keep allowed-tools least-privilege and accurate.
8. Use fully qualified MCP tool IDs in allowed-tools.
9. Keep presentation text in the presentation asset when using a split.
10. Validate with shared create-quality-control scripts before delivery.
11. Keep this nested packet free of graph-metadata.json.

Never:

1. Never create a command for one-off work that does not need reuse.
2. Never skip mandatory gates for required arguments.
3. Never infer missing required input from context or conversation history.
4. Never use broad allowed-tools just in case.
5. Never put dashboards, startup prompts, or result templates inside a thin router when a presentation asset exists.
6. Never omit confirmation gates for destructive or irreversible actions.
7. Never turn a command into long reference documentation.
8. Never add advisor identity metadata inside this nested packet.
9. Never claim structural validity without running validation or stating it was not run.

Escalate if:

1. The command name, namespace, or invocation contract is unclear.
2. Required arguments cannot be safely defaulted.
3. The command would perform destructive work without explicit confirmation requirements.
4. Tool permissions are broader than the workflow appears to need.
5. Router logic and presentation wording cannot be separated without changing behavior.
6. 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, an argument-hint whenever user input is expected, and a least-privilege allowed-tools list using fully qualified MCP tool IDs.
• Every required <argument> has a mandatory input gate immediately after frontmatter that forbids inference and waits for explicit input.
• The body is executable and instruction-oriented, with full-integer ## N. SECTION-NAME headings, actionable steps, two or three example invocations, and structured status output.
• Router commands keep the blocking core (OWNED ASSETS plus PRESENTATION BOUNDARY), use the canonical numbered vocabulary, and hold no presentation templates when a presentation asset exists.
• Shared validation was run: validate_document.py exits 0, 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; indexes the single-concern reference files below.
• references/worked-example.md - the canonical file contract plus a fully worked split command (router .md and 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/:confirm mode 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.txt skeleton 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.