Tasks

Task Framework

The task framework provides reusable, structured workflows that can be invoked with /task:run <name>.

Core Concepts

Task Types

Precedence: Local tasks override global tasks with the same name.

Complex Tasks (Directories)

For multi-file tasks:

.claude/tasks/<name>/
├── prompt.md       # Main task instructions
├── template.md     # Template files
└── config.json     # Task configuration

Task Commands

/task:run <name> [args]

Execute a task by name with optional arguments.

# Run a global task
/task:run github-pr

# Run with arguments
/task:run gitflow-release-start 1.2.0

# Local task (if exists) takes precedence
/task:run custom-deploy

/task:list

List all available tasks (both local and global).

/task:new <name>

Create a new local task from template.

/task:install <source>

Install a task from URL or path.

Task File Format

---
description: Short description of what this task does
allowed-tools: ["Bash", "Read", "Write", "Glob", "Grep"]
requires:
  - Prerequisite 1
  - Prerequisite 2
---

# Task Title

[Task description and context]

## Arguments

- `$1` - First argument description
- `$2` - Second argument (optional)
- `--flag` - Flag description

## Steps

### 1. Step Name

[Step description]

```bash
# Commands to execute
VARIABLE="$1"
echo "Processing $VARIABLE"

2. Next Step

[Continue with workflow...]

Notes

[Important considerations, gotchas, tips]

Examples

/task:run task-name arg1 arg2
/task:run task-name --flag

## Advanced Frontmatter Options

### Agent Execution (`agent`)

Execute the task using a specialized sub-agent:

```yaml
---
description: Deep security audit
allowed-tools: ["Read", "Grep", "Glob"]
agent: security-auditor
---

When to use: Tasks requiring specialized domain expertise (code review, debugging, architecture analysis).

Available agents: code-reviewer, debugger, typescript-pro, architect-reviewer, security-auditor, golang-pro, python-pro, etc.

Forked Context (context: fork)

Run the task in an isolated sub-agent context:

---
description: Comprehensive codebase analysis
allowed-tools: ["Read", "Grep", "Glob", "Task"]
context: fork
---

When to use: Long-running, multi-step tasks that benefit from isolation. The forked agent has full conversation history but operates independently.

Combined Example

---
description: Architecture review with isolation
allowed-tools: ["Read", "Grep", "Glob", "Task"]
agent: architect-reviewer
context: fork
---

Runs in a forked context using the architect-reviewer agent - ideal for complex, autonomous analysis tasks.

Built-in Global Tasks

Git Workflows

GitFlow Tasks

CI/CD Tasks

Jujutsu Tasks

Creating Custom Tasks

Local Task Example

Create .claude/tasks/deploy-staging.md:

---
description: Deploy to staging environment
allowed-tools: ["Bash", "Read"]
requires:
  - kubectl configured
  - Staging namespace exists
---

# Deploy to Staging

Deploy the current build to the staging environment.

## Steps

### 1. Build Application

```bash
make build

2. Run Tests

make test

3. Deploy

kubectl apply -k deploy/staging/

4. Verify

kubectl rollout status deployment/app -n staging

Then invoke with: `/task:run deploy-staging`

### Task Best Practices

1. **Clear Description**: Frontmatter description appears in `/task:list`
2. **Minimal Tools**: Only request tools you actually need
3. **Prerequisites**: List what must exist before running
4. **Error Handling**: Include checks and graceful failures
5. **Idempotent**: Safe to run multiple times
6. **Arguments**: Document all parameters clearly

## Task Discovery

```bash
# List all tasks
/task:list

# View task contents
Read ~/.claude/tasks/<name>.md

# Find tasks by pattern
ls ~/.claude/tasks/ | grep deploy

Task Arguments

Arguments are passed positionally:

/task:run my-task arg1 arg2 arg3

In the task, reference as $1, $2, $3, etc.

Flags like --flag are parsed by the task implementation.

Task Variables

Tasks can access:

• $1, $2, etc. - Positional arguments
• Standard environment variables
• Git context (branch, remote, etc.)

Relationship to Skills

Use Tasks for: Repeatable workflows with concrete steps Use Skills for: Knowledge domains and best practices

Troubleshooting

Task Not Found

# Check if task exists
ls ~/.claude/tasks/
ls .claude/tasks/

# Verify file extension
# Must be .md or directory with prompt.md

Permissions Error

# Check allowed-tools in frontmatter
# Task can only use tools listed there

Arguments Not Working

# Ensure arguments are passed after task name
/task:run task-name "arg with spaces" arg2