design-task

What this skill does

# CrewAI Task Design Guide

How to write effective tasks that produce reliable, high-quality output from your agents.

---

## The 80/20 Rule

**Spend 80% of your effort on task design, 20% on agent design.** The task is the most important lever you have. A well-designed task with a mediocre agent will outperform a poorly designed task with an excellent agent.

---

## 1. Anatomy of an Effective Task

Every task needs two things: a **description** (what to do and how) and an **expected_output** (what the result looks like).

### Description — The Instructions

A good description includes:
1. **What** to do — the core action
2. **How** to do it — specific steps or approach
3. **Context** — why this matters, what it feeds into
4. **Constraints** — scope limits, things to avoid
5. **Inputs** — what data or context is available

```yaml
research_task:
  description: >
    Conduct thorough research about {topic} for the year {current_year}.

    Your research should:
    1. Identify the top 5 key trends and breakthroughs
    2. For each trend, find at least 2 credible sources
    3. Note any controversies or competing viewpoints
    4. Assess potential industry impact (high/medium/low)

    Focus on developments from the last 6 months.
    Do NOT include speculation or unverified claims.
    The output will feed into a report for {target_audience}.
  expected_output: >
    A structured research brief with 5 sections, one per trend.
    Each section includes: trend name, 2-3 paragraph summary,
    source citations, impact assessment (high/medium/low),
    and a confidence level for your findings.
  agent: researcher
```

### Expected Output — The Success Criteria

The `expected_output` tells the agent what "done" looks like. Be specific about:
- **Format** — bullet points, paragraphs, JSON, table
- **Structure** — sections, headings, order
- **Length** — approximate word count or number of items
- **Quality markers** — citations required, confidence levels, specific fields

| Bad Expected Output | Good Expected Output |
|---|---|
| `A research report` | `A structured brief with 5 sections, each containing: trend name, 2-3 paragraph summary, source citations, and impact rating` |
| `An analysis of the data` | `A markdown table with columns: metric name, current value, 30-day trend, and recommended action. Include at least 10 metrics.` |
| `A blog post` | `A 1000-1500 word technical blog post with: title, introduction, 3-4 main sections with code examples, and a conclusion with next steps` |

---

## 2. The Single Purpose Principle

**One task = one objective.** Never combine multiple operations into a single task.

### Bad: "God Task"

```yaml
# DON'T do this — too many objectives in one task
research_and_write_task:
  description: >
    Research {topic}, analyze the findings, write a blog post,
    and proofread it for grammar errors.
  expected_output: >
    A polished blog post about {topic}.
```

### Good: Focused Tasks

```yaml
research_task:
  description: >
    Research {topic} and identify the top 5 key developments.
  expected_output: >
    A research brief with 5 sections covering key trends.
  agent: researcher

writing_task:
  description: >
    Using the research findings, write a technical blog post about {topic}.
  expected_output: >
    A 1000-1500 word blog post with introduction, main sections,
    and conclusion. Include code examples where relevant.
  agent: writer

editing_task:
  description: >
    Review and edit the blog post for grammar, clarity, and consistency.
  expected_output: >
    The final edited blog post with all corrections applied.
    Include a brief editor's note listing what was changed.
  agent: editor
```

Each task has one clear objective. The sequential flow passes context automatically.

---

## 3. Task Configuration Reference

### Essential Parameters

```python
Task(
    description="...",          # Required: what to do
    expected_output="...",      # Required: what the result looks like
    agent=researcher,           # Optional for hierarchical process; required for sequential
)
```

### Task Dependencies with `context`

```python
analysis_task = Task(
    description="Analyze the research findings...",
    expected_output="...",
    agent=analyst,
    context=[research_task],    # Receives research_task's output as context
)
```

**In sequential process:** Each task auto-receives all prior task outputs. Use `context` only when you need non-linear dependencies.

**In hierarchical process:** `context` is how you create explicit data flow between tasks.

### Structured Output

Use `output_pydantic` or `output_json` when downstream code needs to parse the result:

```python
from pydantic import BaseModel

class ResearchReport(BaseModel):
    trends: list[str]
    confidence: float
    sources: list[str]

research_task = Task(
    description="...",
    expected_output="A structured report with trends, confidence score, and sources.",
    agent=researcher,
    output_pydantic=ResearchReport,   # Agent's output is parsed into this model
)
```

**Important:** `expected_output` is always a **string description** — never a class name. The Pydantic model goes in `output_pydantic`, and the `expected_output` text tells the agent what fields to include.

Access structured output:
```python
result = crew.kickoff(inputs={...})
last_task_output = result.pydantic          # Pydantic model from the last task
all_outputs = result.tasks_output           # List of all TaskOutput objects
first_task = all_outputs[0].pydantic        # Pydantic from a specific task
```

### File Output

```python
Task(
    ...,
    output_file="output/report.md",    # Save output to file
    create_directory=True,             # Create directory if missing (default: True)
)
```

File output and structured output can be combined — the file gets the raw text, and `output_pydantic` gets the parsed model.

### Async Execution

```python
Task(
    ...,
    async_execution=True,     # Run without blocking the next task
)
```

Use for tasks that can run in parallel. The crew continues to the next task while this one executes. Use `context` on downstream tasks to wait for async results.

### Human Review

```python
Task(
    ...,
    human_input=True,         # Pause for human review before finalizing
)
```

When enabled, the agent presents its result and waits for human feedback before marking the task complete. Use for critical outputs that need human approval.

### Markdown Formatting

```python
Task(
    ...,
    markdown=True,            # Add markdown formatting instructions
)
```

Automatically instructs the agent to format output with proper markdown headers, lists, emphasis, and code blocks.

### Callbacks

```python
def log_completion(output):
    print(f"Task completed: {output.description[:50]}...")
    save_to_database(output.raw)

Task(
    ...,
    callback=log_completion,  # Called after task completion
)
```

---

## 4. Task Guardrails — Quality Control

Guardrails validate task output before it passes to the next step. If validation fails, the agent retries.

### Function-Based Guardrails

```python
def validate_word_count(output) -> tuple[bool, Any]:
    """Ensure output is between 500-2000 words."""
    word_count = len(output.raw.split())
    if word_count < 500:
        return (False, f"Output too short ({word_count} words). Expand to at least 500 words.")
    if word_count > 2000:
        return (False, f"Output too long ({word_count} words). Condense to under 2000 words.")
    return (True, output)

Task(
    ...,
    guardrail=validate_word_count,
    guardrail_max_retries=3,       # Max retry attempts (default: 3)
)
```

**Return format:** `(bool, Any)` — first element is pass/fail, second is the result (on success) or error message (on failure).

### LLM-Based Guardrails

```python
Task(
    ...,
    guardrail="Verify the output contains at least 3 source citations and no speculative claims.",
)
```

String guardrails use the