---
name: task-planner
description: MUST be called first for ALL user queries before calling any other skill. Decomposes any user query into a structured, ordered execution plan and returns a JSON plan for the agent to execute step by step.
---

## ⚠️ ABSOLUTE RULE — APPLIES TO ALL QUERIES

**You MUST call `task-planner` FIRST before calling ANY other skill, for EVERY user query without exception.**

- Do NOT call `report-generation`, `carbon-footprint`, `data-analysis-echarts`, or any other business skill directly.
- Do NOT attempt to judge whether the query is "simple" or "complex" — always call `task-planner` first.
- The ONLY exception is when you are already executing a step returned by a `task-planner` plan.

**Correct flow for every query:**

```
User query → task-planner → JSON plan → execute each step in the plan
```

**Incorrect flow (NEVER do this):**

```
User query → report-generation   ❌
User query → carbon-footprint    ❌
User query → data-analysis-echarts  ❌
```

---

## Description

`task-planner` is the **universal entry point** for all user queries. It does not execute any business logic itself. It analyzes the user query, discovers all available business skills, and returns a JSON-formatted execution plan. You (the OpenClaw Agent) then execute each step in the plan in order.

Even for queries that map to a single skill, `task-planner` must be called first — it will return a one-step plan, and you then execute that single step.

---

## Workflow

### Stage 1: Planning (Always call this first)

```bash
python /home/admin/.openclaw/workspace/skills/task-planner/scripts/task_planner.py --query "<user's original query>"
```

The script returns a JSON object with a `plan` array.

### Stage 2: Execution (Execute the plan step by step)

For each step in the `plan` array, in order:

1. Read the `skill_name` and `input_query`.
2. If `depends_on` is set, replace `{step_N_output}` in `input_query` with the actual output from that step.
3. Call the specified skill with the resolved `input_query`.

After all steps complete, synthesize a final answer for the user.

---

## Example A — Multi-step query

**User Query**: "帮我生成动力电池（磷酸铁锂）的产品碳足迹报告，并分析报告给我提供优化方案"

**Step 1 — Call `task-planner`:**

```bash
python /home/admin/.openclaw/workspace/skills/task-planner/scripts/task_planner.py \
  --query "帮我生成动力电池（磷酸铁锂）的产品碳足迹报告，并分析报告给我提供优化方案"
```

**Returns:**

```json
{
  "total_steps": 2,
  "plan": [
    {
      "step": 0,
      "skill_name": "report-generation",
      "input_query": "生成动力电池（磷酸铁锂）的产品碳足迹报告",
      "depends_on": null,
      "purpose": "生成产品碳足迹报告，作为后续分析的数据基础"
    },
    {
      "step": 1,
      "skill_name": "carbon-footprint",
      "input_query": "根据以下报告内容，分析磷酸铁锂电池碳足迹并提供优化方案：{step_0_output}",
      "depends_on": 0,
      "purpose": "基于报告内容进行深度分析并给出优化建议"
    }
  ]
}
```

**Step 2 — Execute the plan:**
- Execute Step 0: call `report-generation` → get report output
- Execute Step 1: replace `{step_0_output}` → call `carbon-footprint`
- Synthesize both outputs into a final answer

---

## Example B — Single-step query

**User Query**: "松山园区今年能耗多少？"

**Step 1 — Call `task-planner`:**

```bash
python /home/admin/.openclaw/workspace/skills/task-planner/scripts/task_planner.py \
  --query "松山园区今年能耗多少？"
```

**Returns:**

```json
{
  "total_steps": 1,
  "plan": [
    {
      "step": 0,
      "skill_name": "data-analysis-echarts",
      "input_query": "松山产业园今年能耗多少？",
      "depends_on": null,
      "purpose": "查询松山产业园今年的能耗数据"
    }
  ]
}
```

**Step 2 — Execute the plan:**
- Execute Step 0: call `data-analysis-echarts` → return result to user

---

## Bundled Resources

- **Script**: `/home/admin/.openclaw/workspace/skills/task-planner/scripts/task_planner.py`
- **Usage**: `python /home/admin/.openclaw/workspace/skills/task-planner/scripts/task_planner.py --query "<query>" [--skills_dir /path/to/skills]`