| name | smelter |
| description | Use when: User wants to run a SUBSTANTIAL multi-step coding task as a workflow
(fix/implement a whole issue or feature, comprehensive review), CREATE workflows
or commands, set up workflow automation, or manage workflow configuration.
Triggers (run): "use workflow to", "run workflow", "with workflow",
"workflow to", "workflow run", "use a workflow to", "run a workflow",
and generic task-completion intents that imply a full coding deliverable:
"실행해줘", "돌려줘", "구현해줘", "고쳐줘", "이슈 고쳐줘", "PR 만들어줘",
"implement this", "fix this issue", "build this feature", "ship this".
Triggers (create): "create a workflow", "write a workflow", "make a command",
"author a workflow", "new workflow", "new command", "workflow yaml".
Triggers (setup): "set up workflows", "install workflow automation", "how to use workflows",
"configure workflows", "workflow setup", "get started with workflows".
Triggers (config): "change my workflow config", "modify workflow config", "workflow config",
"change workflow settings", "update my config", "help me change my config",
"edit workflow config", "workflow configuration".
Triggers (init): "initialize workflows", "set up .smelter", "workflow init", "add workflows to repo".
Capability: Runs AI workflows in isolated git worktrees for parallel development.
Also: Creates and manages workflow YAML files, command files, and configuration.
NOT for: trivial single-file edits, quick questions, explanations, read-only
exploration, or anything completable in a few in-session steps - do those directly,
do NOT delegate. Delegate to Smelter ONLY when isolated worktree execution of a
substantial deliverable clearly helps. When in doubt, do it in-session.
|
| argument-hint | [workflow] [message or issue number] |
Smelter CLI Skill
Smelter is a remote agentic coding platform that runs AI workflows in isolated git worktrees. This skill teaches you how to run workflows, create new workflows and commands, and manage Smelter configuration.
When to delegate to Smelter (rule, not regex)
The generic triggers in the description (e.g. "실행해줘", "fix this issue") can match everyday requests. Before invoking a Smelter workflow, apply this rule so it does not over-fire:
- Delegate only for a substantial, self-contained coding deliverable that benefits from an isolated git worktree: fixing/implementing a whole GitHub issue or feature, a comprehensive multi-file change, or a full PR review.
- Do NOT delegate — do the work directly in the current session — for trivial or single-file edits, quick questions, explanations, read-only exploration, config tweaks, or anything you can finish in a few steps. A bare "실행해줘"/"run it" that refers to a small in-session task is NOT a Smelter trigger.
- When uncertain, ask which the user wants, or default to doing it in-session.
Available Workflows (live)
!smelter workflow list 2>&1 || echo "Smelter CLI not installed. Read guides/setup.md to set it up."
Routing
Determine the user's intent and dispatch to the appropriate guide:
| Intent | Action |
|---|
| Setup / install / "how to use" | Read guides/setup.md — interactive setup wizard |
| Config / settings | Read guides/config.md — interactive config editor |
| Initialize .smelter/ in a repo | Read references/repo-init.md |
| Create a workflow | Read references/workflow-dag.md — the complete workflow authoring guide |
| Quick parameter lookup — which field works on which node type | Read references/parameter-matrix.md — master matrix, intent-based lookup, silent-failure catalog |
| Advanced features (hooks/MCP/skills) | Read references/dag-advanced.md |
| Create a command file | Read references/authoring-commands.md |
| Variable substitution reference | Read references/variables.md |
| CLI command reference | Read references/cli-commands.md |
| Run an interactive workflow | Read references/interactive-workflows.md — transparent relay protocol |
| Workflow good practices / anti-patterns | Read references/good-practices.md — read before designing a non-trivial workflow |
| Troubleshoot a failing / stuck workflow | Read references/troubleshooting.md — log locations, common failure modes |
| Run a workflow (default) | Continue with "Running Workflows" below |
If the intent is ambiguous, ask the user to clarify.
The references in this skill are a distilled subset. The full, canonical docs live at smelter.diy (Starlight site from packages/docs-web/). If the skill's reference pages don't cover what you need — an edge case, a worked example, a diagram, a deeper section on a feature — fetch the matching page from smelter.diy.
When to reach for the live docs
- You need an end-to-end example that's longer than what the skill shows (e.g. full patterns for hooks, MCP config, sandbox schema, approval flows)
- You're explaining a concept to the user and want the most readable framing (the
book/ series is written as a tutorial, not a reference)
- You hit a feature the skill only mentions in passing (e.g.
agents: inline sub-agents, advanced Codex options, the full SyncHookJSONOutput schema)
- The user asks "where is this documented?" — point them at the smelter.diy URL, not a skill file path
URL map
| Topic | URL |
|---|
| Landing + install | smelter.diy |
| Getting started (installation, quick start, concepts) | smelter.diy/getting-started/ |
| The book (tutorial-style walkthrough) | smelter.diy/book/ |
| Workflow authoring guide | smelter.diy/guides/authoring-workflows/ |
| Command authoring guide | smelter.diy/guides/authoring-commands/ |
| Node type guides | smelter.diy/guides/loop-nodes/, /approval-nodes/, /script-nodes/ |
| Per-node features (Claude only) | /hooks/, /mcp-servers/, /skills/ |
| Global workflows/commands/scripts | smelter.diy/guides/global-workflows/ |
| Variables reference | smelter.diy/reference/variables/ |
| CLI reference | smelter.diy/reference/cli/ |
Security model (env, sandbox, target-repo .env stripping) | smelter.diy/reference/security/ |
| Architecture | smelter.diy/reference/architecture/ |
Configuration (.smelter/config.yaml full schema) | smelter.diy/reference/configuration/ |
| Troubleshooting | smelter.diy/reference/troubleshooting/ |
| Adapter setup (Slack/Telegram/GitHub/Web/Discord/Gitea/GitLab) | smelter.diy/adapters/ |
| Deployment (Docker, cloud, Windows) | smelter.diy/deployment/ |
URL shape is smelter.diy/<section>/<page>/ — the paths mirror the filenames under packages/docs-web/src/content/docs/.
Precedence
This skill's reference pages are the primary source for routine workflow authoring, CLI use, and setup. Reach for smelter.diy when the skill is incomplete for your case — don't go to the live docs first by default (skill refs load into context faster and are tuned for agents).
Running Workflows
Core Command
smelter workflow run <workflow-name> --branch <branch-name> "<message>"
CRITICAL RULES:
-
Always run in background — Smelter workflows are long-running. Always invoke the Bash tool with run_in_background: true. Use /tasks or the TaskOutput tool to check on progress.
-
Always use worktree isolation — Use the --branch flag unless the user explicitly requests otherwise. This creates an isolated environment so Smelter works without affecting the main branch.
-
One workflow per shell — Each workflow blocks its shell. Run multiple workflows as separate background tasks.
Isolation Modes
| Mode | Flag | When to Use |
|---|
| Worktree (Default) | --branch <name> | Always use this unless told otherwise |
| Custom start-point | --branch <name> --from <base> | Start from a specific branch |
| Direct checkout | --no-worktree | Only if user explicitly requests no isolation |
| Resume failed run | --resume | Resume from the last failure point |
Workflow Selection
Match the user's intent to a workflow from the live list above. Common patterns:
| User Intent | Typical Workflow | Branch Pattern |
|---|
| "Fix issue #X" / "Resolve bug" | smelter-fix-github-issue | fix/issue-{N} |
| "Review PR #X" / "Full review" | smelter-comprehensive-pr-review | review/pr-{N} |
| "Quick review PR #X" | smelter-smart-pr-review | review/pr-{N} |
| "Validate PR #X" / "Check PR" | smelter-validate-pr | review/pr-{N} |
| "Implement from plan" | smelter-feature-development | feat/{name} |
| "Plan and implement feature" | smelter-idea-to-pr | feat/{name} |
| "Execute plan file" | smelter-plan-to-pr | feat/{name} |
| "Run ralph" / "Implement PRD" | smelter-ralph-dag | feat/{name} |
| "Resolve conflicts" | smelter-resolve-conflicts | resolve/pr-{N} |
| "Create issue" / "File a bug" | smelter-create-issue | issue/{name} |
| "Review issue #X fully" | smelter-issue-review-full | review/issue-{N} |
| "Refactor safely" | smelter-refactor-safely | refactor/{name} |
| "Architecture review" | smelter-architect | review/{name} |
| "PIV loop" / "guided dev" | smelter-piv-loop ⚡ | piv/{name} |
| "Create a PRD" / "interactive PRD" | smelter-interactive-prd ⚡ | prd/{name} |
| General / debugging | smelter-assist | assist/{description} |
⚡ = Interactive workflow — requires the transparent relay protocol. Read references/interactive-workflows.md before running.
If no specific workflow matches, use smelter-assist as the fallback. The live workflow list above is always authoritative — it may include workflows not in this table.
Multi-Issue Invocation
When the user mentions multiple issues, PRs, or tasks — run each as a separate background task:
smelter workflow run smelter-fix-github-issue --branch fix/issue-10 "Fix issue #10"
smelter workflow run smelter-fix-github-issue --branch fix/issue-11 "Fix issue #11"
smelter workflow run smelter-fix-github-issue --branch fix/issue-12 "Fix issue #12"
Never combine multiple issues into a single command.
Other CLI Commands
smelter workflow list
smelter workflow list --json
smelter isolation list
smelter isolation cleanup
smelter isolation cleanup --merged
smelter complete <branch>
smelter version
For the full CLI reference with all flags: Read references/cli-commands.md
Authoring Quick Start
Smelter uses a single workflow format: nodes (DAG). Workflows are YAML files in .smelter/workflows/.
IMPORTANT: The examples below are starting points. Always design the workflow around what the user actually needs — the number of nodes, their types, dependencies, and configuration should match the user's requirements, not these templates.
Workflow Structure
name: my-workflow
description: What this workflow does
provider: claude
model: sonnet
nodes:
- id: first-node
command: my-command
- id: second-node
prompt: "Use the output: $first-node.output"
depends_on: [first-node]
Node Types
Each node has exactly ONE of: command, prompt, bash, script, loop, approval, or cancel.
Command node — runs a .smelter/commands/*.md file:
- id: investigate
command: investigate-issue
Prompt node — inline AI prompt:
- id: classify
prompt: "Classify this issue: $ARGUMENTS"
model: haiku
allowed_tools: []
Bash node — shell script, no AI, stdout captured as output:
- id: fetch-data
bash: "gh issue view 42 --json title,body"
timeout: 15000
Script node — TypeScript/JavaScript (via bun) or Python (via uv), no AI, stdout captured as output:
- id: transform
script: |
const raw = process.argv.slice(2).join(' ') || '{}';
console.log(JSON.stringify({ parsed: JSON.parse(raw) }));
runtime: bun
timeout: 30000
- id: analyze
script: analyze-metrics
runtime: uv
deps: ["pandas>=2.0"]
Loop node — iterates AI prompt until completion:
- id: implement
loop:
prompt: "Implement next story. When done: <promise>COMPLETE</promise>"
until: COMPLETE
max_iterations: 10
fresh_context: true
until_bash: "bun run test"
Approval node — pauses the workflow for human review. Requires interactive: true at the workflow level for Web UI delivery:
interactive: true
nodes:
- id: review-gate
approval:
message: "Review the plan above before proceeding."
capture_response: true
on_reject:
prompt: "Revise based on feedback: $REJECTION_REASON"
max_attempts: 3
depends_on: [plan]
Cancel node — terminates the workflow with a reason. Typically gated with when::
- id: stop-if-unsafe
cancel: "Refusing to proceed: input flagged UNSAFE."
depends_on: [classify]
when: "$classify.output != 'SAFE'"
For the full authoring guide with all fields, conditions, trigger rules, and patterns: Read references/workflow-dag.md
Creating a Command File
Commands are .md files in .smelter/commands/ containing AI prompt templates:
---
description: What this command does
argument-hint: <expected arguments>
---
# My Command
User request: $ARGUMENTS
Workflow artifacts: $ARTIFACTS_DIR
[Instructions for the AI agent]
For the full command authoring guide: Read references/authoring-commands.md
Key Variables
| Variable | Description |
|---|
$ARGUMENTS | User's input message |
$ARTIFACTS_DIR | Pre-created directory for workflow artifacts |
$BASE_BRANCH | Base branch (auto-detected from git) |
$WORKFLOW_ID | Unique workflow run ID |
$nodeId.output | Output from upstream node |
Full variable reference: Read references/variables.md
Advanced Features (Command/Prompt Nodes, Claude Only)
hooks (tool interception), mcp (external tool servers), skills (domain knowledge injection), output_format (structured JSON output), allowed_tools/denied_tools (tool restrictions).
For details: Read references/dag-advanced.md
Example Files
examples/dag-workflow.yaml — workflow with conditions, bash + script + loop nodes, structured outputexamples/command-template.md — Command file skeleton with all variables
Example Interactions
User: "Use Smelter to fix issue #42"
smelter workflow run smelter-fix-github-issue --branch fix/issue-42 "Fix issue #42"
User: "Have Smelter review PR #15"
smelter workflow run smelter-comprehensive-pr-review --branch review/pr-15 "Review PR #15"
User: "Create a workflow that reviews code and runs tests"
→ Read references/workflow-dag.md and create a workflow with parallel review nodes.
User: "Make a workflow with conditional routing"
→ Read references/workflow-dag.md and create nodes with when: conditions and output_format.
User: "Write a command file for investigating bugs"
→ Read references/authoring-commands.md and create an .md file in .smelter/commands/.
User: "Set up Smelter in this repo"
→ Read references/repo-init.md to create the .smelter/ directory structure.
User: "Initialize .smelter and create a custom workflow"
→ First read references/repo-init.md, then the appropriate workflow reference.
