Literate Commands Skill

Use this skill when you need to create guided, multi-step workflows that walk users through complex tasks with variable collection, conditional logic, and automated script execution.

When to Use Literate Commands

Use literate commands when you want to:

• Guide users through multi-step processes (setup wizards, onboarding flows)
• Collect structured data from users before executing commands
• Create reusable command templates with customizable parameters
• Build conditional workflows that branch based on user input
• Automate script execution with variable interpolation

Don't use them for: Simple one-off commands that just run a single script or tool.

Creating a Literate Command

1. Create a markdown file in .opencode/commands/
2. Add literate: true in the frontmatter
3. Define steps separated by ---

---
description: My guided workflow
literate: true
---

First step content...

---

Second step content...

Step Configuration

Each step can have a YAML config block to control behavior:

step: unique-step-name
parse:
  variable: type
next:
  "condition": target-step
stop: true

Config Options

Step Examples

Collect data:

parse:
  username: string
  age: number
  newsletter: bool

Route conditionally:

next:
  "role === 'admin'": admin-panel
  "confirmed": proceed
  _: fallback

End command:

stop: true

Variable Collection (parse)

Ask the model to respond with JSON containing specific variables:

parse:
  name: string
  count: number
  active: bool

The model will be prompted to respond with:

{"name": "...", "count": 0, "active": true}

Type Coercion

Variable Substitution

Use $variable in your prompts to inject collected data:

Example

Hello **$name**! You selected $count items.

If name=Alice and count=42:

Hello **Alice**! You selected 42 items.

Routing (next)

Control which step executes next based on variables:

Simple Redirect

next: other-step

Conditional Routing

next:
  "role === 'admin'": admin-panel
  "role === 'user'": user-panel
  _: default-panel

The _ key is the fallback when no condition matches.

Condition Syntax

Use JavaScript-style expressions:

• "confirmed === true"
• "count > 10"
• "role !== 'guest'"
• "name.includes('admin')"

Script Execution (exec)

Run scripts within steps. The agent sees the result, or you can store variables.

Basic Execution

echo "Hello $name"

Store Output as Variables

import json
print(json.dumps({"result": len("$name")}))

Exec Modes

Interpreters

Specify the interpreter explicitly if its not the default:

print("Python!")

echo "Bash!"

console.log("Node!");

Complete Example

---
description: Project setup wizard
literate: true
---

```yaml {config}
step: project-name
parse:
  name: string
  type: string
```

What would you like to name your project, and what type is it?

---

```yaml {config}
step: confirm
next:
  "confirmed === true": create
  _: cancel
```

Ready to create **$name** ($type)? Type `true` or `false`.

---

```yaml {config}
step: create
parse:
  confirmed: bool
```

Let me set that up for you:

```bash {exec mode=store}
mkdir -p "$name"
echo '{"created": true, "path": "'$name'"}'
```

---

```yaml {config}
step: success
stop: true
```

✓ Project **$name** created successfully!

---

```yaml {config}
step: cancel
stop: true
```

Project creation cancelled. Let me know if you need anything else!

Tips

1. Keep steps focused - One clear action per step
2. Use meaningful step names - Makes routing easier to debug
3. Validate early - Collect and validate data before expensive operations
4. Store, don't echo - Use mode=store for script results you want to keep
5. Test routing - Use stop: true on branches to verify they work

Testing Your Command

opencode run --print-logs --log-level DEBUG --command your-command-name

The command will run through steps sequentially. Check logs for:

• Step parsing
• Variable substitution
• Routing decisions
• Script execution