# Runner

The runner takes an installed skill and generates a structured prompt for any agent target. It does not execute code or call LLMs — it assembles a prompt from the skill's files and the provided task/context.

---

## Usage

```bash
skilllane run <name> [task] [options]
```

| Option | Description |
|--------|-------------|
| `--task <task>` | Task description (or positional argument) |
| `--context <text>` | Context string to include |
| `--target <target>` | Agent target for prompt formatting |
| `--out <path>` | Save result as JSON to file |

---

## How It Works

1. Loads the skill by name from the registry
2. Reads all skill files (metadata, instructions, tools, examples)
3. Builds prompt sections from the skill and input
4. Renders the prompt in the specified output mode
5. Returns the result (prompt string, target, tools list)

---

## Prompt Sections

The generated prompt includes these sections in order:

| Section | Source |
|---------|--------|
| **Role** | Skill title + description |
| **Context** | User-provided context (optional) |
| **Task** | User-provided task description |
| **Instructions** | Full content of `SKILL.md` |
| **Available Tools** | Tool definitions from `tools.json` |
| **Target Environment** | Description based on target |
| **Reference Examples** | Content from `examples.md` (truncated to 1500 chars) |

---

## Output Modes

### prompt (default)

Plain text with bracketed section headers:

```
[Role]
You are executing the "Systematic Debugging" skill.
A structured approach to diagnosing and fixing code errors...

[Task]
Debug a TypeError in UserProfile component

[Instructions]
## Role
You are an expert debugging specialist...
```

### markdown

Markdown with heading headers and dividers:

```
## Role

You are executing the "Systematic Debugging" skill.
A structured approach to diagnosing and fixing code errors...

---

## Task

Debug a TypeError in UserProfile component

---

## Instructions

## Role
You are an expert debugging specialist...
```

### json

JSON array of section objects:

```json
[
  {"section": "Role", "content": "You are executing..."},
  {"section": "Context", "content": "TypeError at line 42..."},
  {"section": "Task", "content": "Debug a TypeError..."},
  {"section": "Instructions", "content": "## Role\nYou are..."},
  {"section": "Available Tools", "content": "- **read_file**..."},
  {"section": "Target Environment", "content": "Targeting OpenCode CLI..."},
  {"section": "Reference Examples", "content": "## Scenario\n..."}
]
```

---

## Target Descriptions

Each target gets a specific description injected into the prompt:

| Target | Description in Prompt |
|--------|----------------------|
| `codex` | Targeting OpenAI Codex CLI. Use terminal commands and file operations. |
| `opencode` | Targeting OpenCode CLI. Use bash tool for commands, file tools for edits. |
| `codra` | Targeting Codra. Leverage codebase context and editor features. |
| `tera` | Targeting Tera. Focus on code generation and inline suggestions. |
| `mcp` | Targeting MCP protocol. Use tool-based interactions. |
| `clipboard` | Output to clipboard. Copy the result for the user. |
| `stdout` | Output to stdout. Provide plain text response. |
| `all` | No specific target — generate general-purpose instructions. |

---

## Examples

### Basic run

```bash
skilllane run systematic-debugging --task "Fix the login bug"
```

### With context and target

```bash
skilllane run systematic-debugging \
  --task "Debug a TypeError" \
  --context "Cannot read property 'name' of undefined at line 42" \
  --target opencode
```

### Save output

```bash
skilllane run agent-code-review \
  --task "Review PR #42" \
  --out review-result.json
```

---

## Programmatic Usage

```typescript
import { runSkill } from '@talocode/skilllane';

const result = await runSkill({
  skillName: 'systematic-debugging',
  task: 'Debug a TypeError',
  context: 'Cannot read property of undefined',
  target: 'opencode',
  mode: 'markdown',
});

console.log(result.prompt);    // The generated prompt
console.log(result.tools);     // ['read_file', 'grep', 'run_command']
console.log(result.outputMode); // 'markdown'
```