feat: Add intelligent auto-router and enhanced integrations
- Add intelligent-router.sh hook for automatic agent routing - Add AUTO-TRIGGER-SUMMARY.md documentation - Add FINAL-INTEGRATION-SUMMARY.md documentation - Complete Prometheus integration (6 commands + 4 tools) - Complete Dexto integration (12 commands + 5 tools) - Enhanced Ralph with access to all agents - Fix /clawd command (removed disable-model-invocation) - Update hooks.json to v5 with intelligent routing - 291 total skills now available - All 21 commands with automatic routing 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
admin
319
dexto/commands/README.md
Normal file
319
dexto/commands/README.md
Normal file
@@ -0,0 +1,319 @@
|
||||
# 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:
|
||||
|
||||
```markdown
|
||||
---
|
||||
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
|
||||
|
||||
```markdown
|
||||
---
|
||||
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
|
||||
|
||||
```markdown
|
||||
---
|
||||
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
|
||||
|
||||
```markdown
|
||||
---
|
||||
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:
|
||||
|
||||
```markdown
|
||||
argument-hint: [style] [length?] [extra-param]
|
||||
```
|
||||
|
||||
Becomes:
|
||||
```json
|
||||
[
|
||||
{ "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)
|
||||
Reference in New Issue
Block a user