SuperCharged-Claude-Code-Upgrade/dexto/commands/README.md

Dexto Commands (File Prompts)

This directory contains File Prompts — reusable prompt templates that work like Claude Code's custom slash commands.

Prompt Types in Dexto

Dexto supports four types of prompts, each with different capabilities:

1. 📁 File Prompts (Commands)

Location:

• Local: commands/
• Global: ~/.dexto/commands Format: Markdown files with frontmatter Arguments: Positional placeholders ($1, $2, $ARGUMENTS) Best for: Simple, file-based prompts you can version control

2. 🔌 MCP Prompts

Source: Connected MCP servers Format: Defined by MCP protocol Arguments: Named arguments (e.g., report_type: "metrics") Best for: Complex prompts from external services (GitHub, databases, etc.)

3. ⚡ Starter Prompts

Source: Built into Dexto Format: Hardcoded in code Arguments: Varies by prompt Best for: Common operations provided out-of-the-box

4. ✨ Custom Prompts

Source: Created at runtime via API/UI Format: Stored in database Arguments: Positional placeholders like File Prompts Best for: User-created prompts that need persistence

---

Custom Commands (Create, Use, Manage)

Custom commands are prompts you create at runtime. They live in the local database (not on disk) and are available to the active agent across sessions. They support the same placeholder behavior as file prompts:

• $1..$9 and $ARGUMENTS positional placeholders
• $$ escapes a literal dollar
• {{name}} named placeholders (when you declare arguments)
• If no placeholders are used in the template: arguments/context are appended at the end

Create via Web UI

• Open the “Create Custom Prompt” modal in the web UI
• Provide name, optional title/description, and the prompt content
• Use $1..$9/$ARGUMENTS/{{name}} placeholders in content
• Optionally attach a resource file; it will be stored and included when the prompt runs

Create via API

• POST POST /api/prompts/custom with JSON:

{
  "name": "research-summary",
  "title": "Research Summary",
  "description": "Summarize research papers with key findings",
  "content": "Summarize in style $1 with length $2.\n\nContent:\n$ARGUMENTS",
  "arguments": [
    { "name": "style", "required": true },
    { "name": "length", "required": true }
  ],
  "resource": {
    "base64": "data:application/pdf;base64,...",
    "mimeType": "application/pdf",
    "filename": "paper.pdf"
  }
}

• Declaring arguments is optional but recommended; it enables inline argument hints in the slash UI and required-arg validation.
• The resource field is optional; attached data is stored in the blob store and sent alongside the prompt when executed.

Delete via API

• DELETE /api/prompts/custom/:name

Preview resolution (without sending to LLM)

• GET /api/prompts/:name/resolve?context=...&args={...}
  • context becomes _context for positional flows
  • args is a JSON string for structured argument values

Argument Handling Summary

• Positional tokens typed after /name appear in args._positional and are expanded into $1..$9 and $ARGUMENTS.
• Named args can be declared in arguments and referenced as {{name}}.
• If the template contains any placeholders ($1..$9, $ARGUMENTS, or {{name}}), arguments are considered deconstructed and are NOT appended.
• If the template contains no placeholders, providers append at the end:
  • Context: <_context> if provided, otherwise
  • Arguments: key: value, ...

---

Creating File Prompts

Basic Structure

Create a .md file in this directory with frontmatter:

---
description: Short description of what this prompt does
argument-hint: [required-arg] [optional-arg?]
---

# Prompt Title

Your prompt content here using $1, $2, or $ARGUMENTS placeholders.

Frontmatter Fields

Field	Required	Description	Example
description	✅ Yes	Brief description shown in UI	"Summarize text with style and length"
argument-hint	⚠️ Recommended	Argument names for UI hints	"[style] [length]"
name	❌ Optional	Override filename as command name	"quick-summary"
category	❌ Optional	Group prompts by category	"text-processing"
id	❌ Optional	Unique identifier	"summarize-v2"

Argument Placeholders

File prompts support Claude Code's positional argument system:

Placeholder	Expands To	Use Case
$1, $2, ..., $9	Individual arguments by position	Structured parameters
$ARGUMENTS	Remaining arguments after $1..$9	Free-form text content
$$	Literal dollar sign	When you need $ in output

Examples

Example 1: Structured Arguments Only

---
description: Translate text between languages
argument-hint: [from-lang] [to-lang] [text]
---

Translate from $1 to $2:

$3

Usage: /translate english spanish "Hello world" Expands to:

Translate from english to spanish:

Hello world

Example 2: Mixed Structured + Free-form

---
description: Analyze code with focus area
argument-hint: [file] [focus]
---

Analyze the code in **$1** focusing on: $2

Full input for context:
$ARGUMENTS

Usage: /analyze utils.ts performance "function slow() { ... }" Expands to:

Analyze the code in **utils.ts** focusing on: performance

Full input for context:
utils.ts performance function slow() { ... }

Example 3: Free-form Only

---
description: Improve any text
argument-hint: [text-to-improve]
---

Please improve the following text:

$ARGUMENTS

Usage: /improve "This sentence not good" Expands to:

Please improve the following text:

This sentence not good

---

Usage in the UI

Invoking File Prompts

1. Type / in chat — opens slash command autocomplete
2. Select your prompt — shows inline argument hints
3. Provide arguments — positional order matters!

Argument Display

The UI shows:

• <argname> — Required argument
• <argname?> — Optional argument
• Hover tooltip — Argument description (if provided)

Example UI display for summarize:

/summarize <style> <length>
           ^required  ^required

---

How Different Prompt Types Handle Arguments

File Prompts vs MCP Prompts

File Prompts (like summarize):

User types: /summarize technical 100 "Machine learning..."
           ↓
Expands:    $1="technical", $2="100", $ARGUMENTS="technical 100 Machine learning..."
           ↓
Result:     Prompt text with placeholders replaced

MCP Prompts (like generate-report):

User types: /generate-report metrics
           ↓
Maps:       _positional=["metrics"] → report_type="metrics"
           ↓
Result:     MCP server receives {report_type: "metrics"}

Key difference:

• File prompts: Simple string replacement in markdown
• MCP prompts: Structured data passed to external servers

---

Best Practices

✅ DO:

• Use descriptive names — analyze-performance not analyze
• Add clear descriptions — help users understand what it does
• Include usage examples — in the prompt content or description
• Use argument-hint — enables inline UI hints
• Keep it focused — one clear purpose per prompt
• Use $1, $2 for structure — when you need specific parameters
• Use $ARGUMENTS for flexibility — when content is variable

❌ DON'T:

• Don't use spaces in filenames — use kebab-case: my-prompt.md
• Don't create overly complex prompts — split into multiple files
• Don't forget argument-hint — users need to know what to provide
• Don't rely on order if flexible — document expected argument positions

---

Testing Your Prompts

1. Create the .md file in this directory
2. Restart the agent (or wait for hot reload)
3. Type /your-prompt-name in chat
4. Test with different arguments — verify placeholders expand correctly

---

Advanced: Argument-Hint Parsing

The argument-hint field is parsed to create structured argument definitions:

argument-hint: [style] [length?] [extra-param]

Becomes:

[
  { "name": "style", "required": true },
  { "name": "length", "required": false },
  { "name": "extra-param", "required": true }
]

Rules:

• [name] = required argument
• [name?] = optional argument (with ?)
• Order matters — matches positional $1, $2 positions

---

Troubleshooting

Prompt doesn't appear in slash command list

• Check filename ends with .md
• Verify frontmatter is valid YAML
• Ensure description field is present
• Put your file in commands/ (local) or ~/.dexto/commands (global)
• Restart the agent

---

Further Reading

• Prompt Manager Architecture: packages/core/src/prompts/prompt-manager.ts
• File Prompt Provider: packages/core/src/prompts/providers/file-prompt-provider.ts
• Placeholder Expansion: packages/core/src/prompts/utils.ts (expandPlaceholders function)