
agent-alchemy-claude-tools
Reference skills for Claude Code Tasks and Agent Teams features
- version
- 0.2.5
- GitHub stars
- 45
Install
/plugin install agent-alchemy-claude-tools@agent-alchemyRun it inside Claude Code after adding the marketplace with /plugin marketplace add sequenzia/agent-alchemy.
Contents
Discovered from sourceSkills 2
Claude Code Tasks Reference
This skill is a shared reference for Claude Code's 6 Task Management tools. Load it when your skill or agent needs to create, manage, or coordinate tasks.
The tools serve two distinct purposes:
- Structured tracking — TaskCreate, TaskGet, TaskList, TaskUpdate — for organizing work items, tracking progress, managing dependencies, and coordinating agents
- Background execution — TaskOutput, TaskStop — for monitoring and controlling background processes (shells, agents, remote sessions)
Both share the task ID namespace but serve different operational needs.
This reference covers:
- Complete tool parameter tables for all six Task tools
- Status lifecycle, transition rules, and completion rules
- Naming conventions (subject vs. activeForm)
- Dependency management with DAG design principles
- Metadata conventions for categorization and tracking
For deeper content, load the reference files listed at the end of this document.
TaskCreate
Creates a new task. Returns the created task object with a system-assigned id.
Use TaskCreate for complex multi-step tasks (3+ distinct steps), plan mode tracking, or when the user provides multiple tasks or requests a todo list. Skip it for single straightforward tasks or trivial work completable in under 3 steps.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
subject | string | Yes | Short imperative title for the task (e.g., "Create user schema"). Displayed in the task list UI. |
description | string | Yes | Detailed description including context and acceptance criteria. Supports markdown. |
activeForm | string | No | Present-continuous description shown while the task is in progress (e.g., "Creating user schema"). Displayed in the task list UI during execution. Falls back to subject if omitted. |
metadata | object | No | Key-value pairs for categorization and tracking. Keys and values are strings. Common keys documented in the Metadata Conventions section below. |
Behavior
- All tasks are created with status
pending - No owner is assigned at creation — use TaskUpdate to assign
- Use TaskUpdate after creation to set up dependencies (
blocks/blockedBy)
Return Value
Returns the full task object including:
id— System-assigned unique identifiersubject— The subject provideddescription— The description providedactiveForm— The activeForm provided (if any)status— Alwayspendingfor newly created tasksmetadata— The metadata provided (if any)blockedBy— Empty array (no dependencies yet)blocks— Empty array (no dependents yet)
Example
TaskCreate:
subject: "Create user authentication module"
description: "Implement JWT-based auth with login, logout, and token refresh endpoints."
activeForm: "Creating user authentication module"
metadata:
priority: "high"
complexity: "medium"
task_group: "user-auth"
TaskGet
Retrieves a single task by its ID. Use this to get full task details including description, metadata, and dependency information.
Use TaskGet before starting work on a task to get the full description with acceptance criteria. Also use it to verify the blockedBy list is empty before beginning work, and to read the latest state before calling TaskUpdate (staleness check). Use TaskList first for an overview, then TaskGet for full details on a specific task.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
taskId | string | Yes | The ID of the task to retrieve. |
Return Value
Returns the full task object:
id— Task identifiersubject— Task titledescription— Full description (may be long)activeForm— Present-continuous form (if set)status— Current status (pending,in_progress,completed,deleted)metadata— Key-value pairsblockedBy— Array of task IDs this task depends onblocks— Array of task IDs that depend on this taskowner— The agent or session that owns this task (if set)
TaskUpdate
Updates an existing task. Only the fields you provide are changed; omitted fields remain unchanged.
Always read the latest state via TaskGet before updating to avoid acting on stale data.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
taskId | string | Yes | The ID of the task to update. |
status | string | No | New status. Valid values: pending, in_progress, completed, deleted. See Status Lifecycle below. |
subject | string | No | Updated subject line. |
description | string | No | Updated description. |
activeForm | string | No | Updated present-continuous description. |
owner | string | No | Set or change the task owner (agent name or session identifier). |
metadata | object | No | Metadata keys to merge with existing metadata. Set a key to null to delete it. |
addBlocks | string[] | No | Add task IDs to this task's blocks list (tasks that depend on this one). |
addBlockedBy | string[] | No | Add task IDs to this task's blockedBy list (tasks this one depends on). |
Return Value
Returns the updated task object with all current fields.
Example
TaskUpdate:
taskId: "5"
status: "in_progress"
activeForm: "Implementing user authentication module"
TaskList
Lists all tasks in the current task list. Takes no parameters.
Use TaskList to see available work (pending, unblocked tasks), check overall progress, or find the next task after completing one. For teammate workflows: call TaskList, find tasks with pending status and empty blockedBy, prefer the highest-priority unblocked task, then claim it via TaskUpdate.
Parameters
None.
Return Value
Returns an array of task summary objects. Each summary includes:
id— Task identifiersubject— Task titlestatus— Current statusowner— Agent ID if assigned, empty if availableblockedBy— Array of blocking task IDsblocks— Array of dependent task IDsmetadata— Key-value pairs
Note: TaskList returns summary objects. Use TaskGet to retrieve the full description for a specific task.
TaskOutput
Retrieves output from a running or completed background task. Works with background shells, async agents, and remote sessions.
Use TaskOutput to check on background task progress, retrieve results from completed background work, or monitor long-running operations.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
task_id | string | Yes | — | The task ID to get output from. |
block | boolean | Yes | true | Whether to wait for task completion before returning. |
timeout | number | Yes | 30000 | Maximum wait time in milliseconds. Range: 0–600000 (0–10 minutes). |
Behavior
block: true— Waits for the task to finish (up totimeoutms), then returns the output. Use this when you need the result before proceeding.block: false— Returns immediately with current status and any available output. Use this for progress checks without blocking.
TaskStop
Terminates a running background task.
Use TaskStop to cancel a long-running task that is no longer needed or to force-terminate a background process (e.g., a timed-out executor agent).
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
task_id | string | No | The ID of the background task to stop. |
shell_id | string | No | Deprecated — use task_id instead. |
Return Value
Returns success or failure status of the stop operation.
Status Lifecycle
Tasks follow a three-state lifecycle with an additional terminal state.
┌──────────┐ TaskUpdate ┌─────────────┐ TaskUpdate ┌───────────┐
│ pending │ ──────────────→ │ in_progress │ ──────────────→ │ completed │
└──────────┘ status: └─────────────┘ status: └───────────┘
TaskCreate in_progress completed
│ │
│ TaskUpdate │ TaskUpdate
│ status: deleted │ status: deleted
▼ ▼
┌───────────┐ ┌───────────┐
│ deleted │ │ deleted │
└───────────┘ └───────────┘
States
| Status | Meaning | Entry Condition |
|---|---|---|
pending | Task is created and waiting to be started | Default on creation via TaskCreate |
in_progress | Task is actively being worked on | Explicitly set via TaskUpdate |
completed | Task is finished | Explicitly set via TaskUpdate |
deleted | Task is removed (soft delete) | Explicitly set via TaskUpdate from any state |
Transition Rules
- pending -> in_progress: Set when an agent begins working on the task.
- in_progress -> completed: Set when the task is verified as done. Only mark complete after verification passes.
- in_progress -> pending: Valid for resetting a task (e.g., after a failed attempt or interrupted session).
- pending -> deleted: Remove a task that is no longer needed.
- in_progress -> deleted: Cancel a task that is in progress.
- Blocked tasks: A task with non-empty
blockedBy(where blockers are not yet completed) should not be started. The system does not enforce this automatically — your orchestration logic must check dependencies before transitioning toin_progress.
Completion Rules
These rules prevent premature completion, which wastes execution resources on retries:
- Only mark
completedwhen the task is fully accomplished — all acceptance criteria met - If errors or blockers are encountered, keep the task as
in_progressand address them - Never mark completed if: tests are failing, implementation is partial, errors are unresolved, or dependencies are missing
- Always read the latest state via TaskGet before updating status (staleness check)
Naming Conventions
Subject (Imperative)
The subject field uses imperative mood — a command that describes what the task will accomplish:
| Good | Bad |
|---|---|
| "Create user schema" | "Creating user schema" |
| "Add JWT authentication" | "JWT authentication addition" |
| "Fix login timeout bug" | "Login timeout bug" |
| "Implement rate limiting" | "Rate limiting implementation" |
activeForm (Present-Continuous)
The activeForm field uses present-continuous tense — describing what is happening while the task runs:
| Subject | activeForm |
|---|---|
| "Create user schema" | "Creating user schema" |
| "Add JWT authentication" | "Adding JWT authentication" |
| "Fix login timeout bug" | "Fixing login timeout bug" |
| "Implement rate limiting" | "Implementing rate limiting" |
The activeForm appears in the task list UI while the task status is in_progress. If omitted, the UI falls back to the subject.
Dependency Management
Tasks support dependency tracking via blockedBy and blocks fields, forming a Directed Acyclic Graph (DAG).
Fields
blockedBy: Array of task IDs that must complete before this task can start. Set viaaddBlockedByin TaskUpdate.blocks: Array of task IDs that are waiting on this task. Set viaaddBlocksin TaskUpdate. This is the inverse ofblockedBy.
Setting Dependencies
Dependencies are set after task creation using TaskUpdate:
TaskUpdate:
taskId: "5"
addBlockedBy: ["3", "4"]
This means task 5 cannot start until tasks 3 and 4 are both completed.
DAG Design Principles
- No cycles: Never create circular dependencies (A blocks B, B blocks C, C blocks A). This creates deadlocks where no task can proceed.
- Minimize depth: Prefer wider, shallower dependency graphs. Deep chains (A -> B -> C -> D -> E) serialize execution and slow throughput.
- Depend on producers, not peers: A task should depend on the task that produces what it needs, not on unrelated tasks at the same level.
- One-way information flow: Dependencies should follow the data flow — upstream tasks produce artifacts that downstream tasks consume.
- Independent tasks run in parallel: Tasks at the same dependency level (no dependencies between them) can execute concurrently.
Common Dependency Patterns
| Pattern | Structure | Use Case |
|---|---|---|
| Linear chain | A -> B -> C | Sequential steps where each builds on the previous |
| Fan-out | A -> [B, C, D] | One task produces input for multiple parallel tasks |
| Fan-in | [A, B, C] -> D | Multiple tasks must complete before a summary/merge task |
| Diamond | A -> [B, C] -> D | Fan-out followed by fan-in; B and C are independent but D needs both |
Metadata Conventions
The metadata field accepts arbitrary string key-value pairs. These common keys are used across the agent-alchemy ecosystem:
| Key | Values | Purpose |
|---|---|---|
priority | critical, high, medium, low, unprioritized | Execution ordering within a wave; higher priority tasks run first |
complexity | trivial, low, medium, high | Estimate of implementation effort; used for planning |
task_group | Any string (e.g., user-auth, payments) | Groups related tasks for filtered execution via --task-group |
spec_path | File path (e.g., internal/specs/auth-SPEC.md) | Links the task back to its source specification |
feature_name | Any string (e.g., user-authentication) | Associates the task with a feature for tracking |
task_uid | Composite key (e.g., auth:create-schema) | Enables idempotent merge mode — matching UIDs update existing tasks instead of creating duplicates |
spec_phase | Phase identifier (e.g., phase-1) | Tracks which spec phase generated this task |
source_section | Section reference (e.g., Section 5.1) | Links to the specific spec section that defined this task |
Metadata Merge Behavior
TaskUpdate's metadata field performs a merge with the existing metadata. Keys you provide are added or updated; keys you omit remain unchanged. Set a key to null to delete it.
# Task 5 currently has metadata: { priority: "high", task_group: "auth" }
# Add complexity without affecting existing keys:
TaskUpdate:
taskId: "5"
metadata:
complexity: "medium"
# Result: { priority: "high", task_group: "auth", complexity: "medium" }
# Delete a key by setting it to null:
TaskUpdate:
taskId: "5"
metadata:
task_group: null
# Result: { priority: "high", complexity: "medium" }
Reference Files
For deeper content on task design patterns and common mistakes, load these reference files. These cover patterns for the structured tracking tools (TaskCreate, TaskGet, TaskList, TaskUpdate).
Task Patterns
Covers dependency graph design patterns (linear, fan-out, fan-in, diamond), task right-sizing guidance, multi-agent coordination via tasks, and metadata strategies.
Read ${CLAUDE_PLUGIN_ROOT}/skills/claude-code-tasks/references/task-patterns.md
Anti-Patterns
Documents common mistakes when using Tasks: circular dependencies, over-granular tasks, missing activeForm, batch status update pitfalls, duplicate task creation, and more. Each anti-pattern includes the problem, why it matters, and the correct alternative.
Read ${CLAUDE_PLUGIN_ROOT}/skills/claude-code-tasks/references/anti-patterns.md
Claude Code Agent Teams Reference
A shared reference for Claude Code's Agent Teams features. Load this skill when building skills or agents that create teams, spawn teammates, coordinate multi-agent workflows, or integrate with team hooks.
This skill covers team lifecycle, tool parameters, spawning mechanics, and file structure. For deeper topics, load the reference files listed in Loading Reference Files.
Cross-reference: For Claude Code Tasks (TaskCreate, TaskGet, TaskUpdate, TaskList), see the companion skill:
Read ${CLAUDE_PLUGIN_ROOT}/skills/claude-code-tasks/SKILL.md
TeamCreate Tool
Creates a new named team and registers the caller as team lead.
| Parameter | Type | Required | Description |
|---|---|---|---|
team_name | string | Yes | Unique team identifier. Used in file paths, environment variables, and member discovery. Use kebab-case (e.g., analysis-team). |
description | string | No | Human-readable description of the team's purpose. Shown in team config and used by teammates to understand their team's mission. |
agent_type | string | No | The type of agent running as team lead. Informational; stored in config.json for member discovery. |
Return behavior: Returns a confirmation with the team name. The team is immediately ready for member spawning after creation. Teams have a 1:1 correspondence with task lists — creating a team also creates a task list at ~/.claude/tasks/{team-name}/. A config.json file is created at ~/.claude/teams/{team-name}/config.json with team metadata including lead identity, description, and a members array where each member has name, agentId, and agentType.
Constraints:
- Team names must be unique across all active teams
- The creating agent becomes team lead automatically
- Only team leads can send shutdown requests to members
TeamDelete Tool
Deletes a team and cleans up its resources. Takes no parameters — the team name is determined from the current session's team context.
Prerequisites: All team members must be shut down before deletion. Attempting to delete a team with active members will fail.
Cleanup behavior: Removes the team directory (~/.claude/teams/{team-name}/) and the task directory (~/.claude/tasks/{team-name}/), clears inbox directories, and deregisters the team.
Team Lifecycle
The full lifecycle of an agent team follows seven steps:
Create Team --> Create Tasks --> Spawn Teammates --> Assign Tasks --> Work --> Shutdown --> Cleanup
stateDiagram-v2
[*] --> Created: TeamCreate
Created --> TasksReady: TaskCreate
TasksReady --> Spawning: Agent tool (team_name, name)
Spawning --> Assigning: TaskUpdate (owner)
Spawning --> Spawning: Spawn more members
Assigning --> Working: Teammates active
Working --> Assigning: More tasks to assign
Working --> ShuttingDown: All work complete
ShuttingDown --> Cleanup: All members stopped
Cleanup --> [*]: TeamDelete
classDef active fill:#e8f5e9,color:#000
classDef transition fill:#fff3e0,color:#000
class Created,TasksReady,Cleanup transition
class Spawning,Assigning,Working,ShuttingDown active
Step Details
1. Create team: Team lead calls TeamCreate with a name. The team config file is written, a task list is created, and the lead is registered.
2. Create tasks: Team lead uses TaskCreate to add tasks. Tasks auto-use the team's task list at ~/.claude/tasks/{team-name}/.
3. Spawn teammates: Team lead uses the Agent tool with team_name and name parameters to spawn teammates. Each teammate runs as an isolated Claude Code session. Members can be spawned incrementally as work demands change.
4. Assign tasks: Team lead uses TaskUpdate with owner to assign tasks to specific teammates.
5. Teammates work: Members complete assigned tasks, communicate via SendMessage, and report results. The team lead monitors progress, assigns new work, and handles issues. Members go idle between turns — this is normal, not an error.
6. Shutdown: When all work is complete, the team lead sends shutdown_request messages to each member. Members acknowledge with shutdown_response and terminate. The lead waits for all members to confirm shutdown.
7. Cleanup: After all members have stopped, the team lead calls TeamDelete to remove the team and task directories.
Teammate Spawning
Teammates are spawned using the Agent tool with the team_name parameter. Each teammate runs as a separate Claude Code session.
Plugin tool name: In Claude Code plugin frontmatter (
allowed-toolsin skills,toolsin agents), the Agent tool is listed asTask. Both names refer to the same spawning capability with identical parameters (prompt,team_name,name,description,subagent_type,run_in_background). UseTaskin frontmatter definitions andAgentorTaskin skill/agent body instructions.
Spawn Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
prompt | string | Yes | The task/prompt for the teammate. This is the initial instruction the teammate receives. |
team_name | string | Yes | Associates the spawned agent with this team. Must match an existing team name. |
name | string | Yes | Human-readable name for the teammate (e.g., "researcher-1"). Appears in team config and messages. |
description | string | Yes | Short (3-5 word) description of the agent's task. |
subagent_type | string | No | Model tier for the teammate: "default" (Opus), "fast" (Sonnet). Choose based on task complexity. |
run_in_background | boolean | No | If true, the spawning agent does not block waiting for the teammate to finish. Essential for parallel teammate workflows. Default: false. |
Subagent Type Selection
| Type | Model Tier | Best For |
|---|---|---|
"default" | Opus | Complex reasoning, synthesis, architecture decisions, autonomous multi-step work |
"fast" | Sonnet | Parallel exploration, data gathering, straightforward implementation, high-volume tasks |
Isolation
Each teammate runs in its own Claude Code session with:
- Independent context window (no shared memory with other teammates)
- Own tool permissions and approval state
- Own working directory (same project root)
- Communication only through
SendMessage(file-based inbox delivery)
Background Spawning Pattern
For parallel teammates, spawn all with run_in_background: true:
Task(prompt="Analyze module A", team_name="analysis-team", name="analyzer-1",
description="Analyze module A", run_in_background=true)
Task(prompt="Analyze module B", team_name="analysis-team", name="analyzer-2",
description="Analyze module B", run_in_background=true)
Task(prompt="Analyze module C", team_name="analysis-team", name="analyzer-3",
description="Analyze module C", run_in_background=true)
Note: In skill/agent instructions, this tool may be referenced as either Task or Agent. Both are equivalent.
The team lead continues running and can coordinate via messages while teammates work.
Idle State Semantics
Understanding idle state is critical for correct team coordination.
Idle is normal, not an error. When a teammate finishes its current task and has no pending messages, it enters an idle state. This is expected behavior between work assignments.
Key rules:
- Idle teammates can still receive and process messages
- Claude Code sends automatic idle notifications to the team lead when a teammate becomes idle
- Do NOT interpret idle as "broken" or "stuck" — it means the teammate is waiting for work
- Do NOT react to idle notifications unless you have new work to assign
- Send new work to idle teammates via
SendMessagewhen ready - Only send
shutdown_requestwhen the teammate's role is fully complete
Anti-pattern: Immediately shutting down teammates when they go idle. This wastes the spawning cost and prevents reuse for follow-up tasks.
Environment Variables
Claude Code automatically sets these environment variables in every teammate session:
| Variable | Description | Example Value |
|---|---|---|
CLAUDE_CODE_TEAM_NAME | Name of the team this agent belongs to | analysis-team |
CLAUDE_CODE_AGENT_NAME | This agent's name within the team | researcher-1 |
CLAUDE_CODE_AGENT_TYPE | Role of this agent (lead or member) | member |
CLAUDE_CODE_TASK_LIST_ID | The task list ID associated with this team | abc123 |
These variables allow teammates to:
- Know which team they belong to (for SendMessage routing)
- Identify themselves in messages and logs
- Determine if they are lead or member (for permission checks)
- Access the shared task list for the team
Spawn Backends
Claude Code supports multiple backends for running teammate sessions.
| Backend | Environment | Characteristics |
|---|---|---|
| in-process | Default | Runs within the same process group. Simplest setup. No external dependencies. Suitable for most workflows. |
| tmux | Terminal | Each teammate runs in a separate tmux pane. Requires tmux installed. Provides visual monitoring of teammate sessions. Good for debugging and development. |
| iTerm2 | macOS | Each teammate runs in a separate iTerm2 tab. macOS only. Provides native tab-based visual monitoring. Requires iTerm2 application. |
Selection Guidance
- Use in-process (default) for production workflows, CI/CD, and when you do not need visual monitoring of individual teammate sessions.
- Use tmux when debugging multi-agent workflows and you want to watch each teammate's session in real time. Requires
tmuxto be installed. - Use iTerm2 on macOS when you prefer native terminal tabs over tmux panes for visual monitoring during development.
The backend is configured at the Claude Code application level, not per-team or per-spawn call.
File Structure
Agent Teams use a file-based coordination system rooted in the user's home directory.
Directory Layout
~/.claude/
├── teams/
│ └── {team-name}/
│ └── config.json # Team metadata, member roster, lead identity
├── tasks/
│ └── {team-name}/
│ ├── {task-id}.json # Individual task files for team members
│ └── ...
└── inboxes/
└── {team-name}/
├── {agent-name}/ # Per-agent inbox directory
│ ├── msg-001.json # Delivered message files
│ └── ...
└── ...
config.json
The team configuration file at ~/.claude/teams/{team-name}/config.json contains:
- Team name and description
- Team lead identity and agent type
- Member roster with names, types, and status
- Creation timestamp
Other teammates discover team membership by reading this file.
Inbox Delivery
Messages sent via SendMessage are written as JSON files to the recipient's inbox directory. Claude Code monitors these directories and delivers messages automatically — teammates do not poll for messages.
Task Files
Each teammate's assigned work is tracked as task files under ~/.claude/tasks/{team-name}/. These follow the standard Claude Code Tasks format (same as non-team tasks). The task directory is removed when TeamDelete is called.
SendMessage Overview
SendMessage is the communication tool for inter-agent messaging within a team. It supports five message types, each with different routing and semantics.
| Type | Routing | Purpose |
|---|---|---|
message | Direct (one recipient) | Send a targeted message to a specific teammate by name |
broadcast | All members | Send to every team member simultaneously. Costs N messages for N members. |
shutdown_request | Direct (one recipient) | Request a teammate to shut down gracefully. Includes a request_id. |
shutdown_response | Direct (requester) | Teammate acknowledges shutdown. Includes matching request_id. |
plan_approval_response | Direct (requester) | Approve or reject a teammate's proposed plan with optional feedback. |
Message delivery is automatic — Claude Code writes message files to recipient inboxes and notifies them. No polling required.
Key rules:
- Don't send structured JSON status messages — use
TaskUpdateinstead - Idle notifications are sent automatically by the system when a teammate's turn ends
- Prefer
messageoverbroadcastin almost all cases
Peer DM visibility: Team leads can see direct messages between team members for oversight and coordination purposes.
For complete field tables, usage guidance, and examples for each message type, load the messaging protocol reference:
Read ${CLAUDE_PLUGIN_ROOT}/skills/claude-code-teams/references/messaging-protocol.md
Loading Reference Files
This skill provides an overview of Agent Teams. For detailed coverage of specific topics, load these reference files as needed:
Messaging Protocol
Complete documentation of all 5 SendMessage types with field tables, delivery mechanics, and usage patterns.
Read ${CLAUDE_PLUGIN_ROOT}/skills/claude-code-teams/references/messaging-protocol.md
Orchestration Patterns
Proven multi-agent workflow patterns including Parallel Specialists, Pipeline, Swarm, Research-then-Implement, and Plan Approval Gate. Each pattern includes structure, task design, and communication flow.
Read ${CLAUDE_PLUGIN_ROOT}/skills/claude-code-teams/references/orchestration-patterns.md
Hooks Integration
TeammateIdle and TaskCompleted hook events for quality gates and automation. Includes hook schemas, exit code behavior, and practical examples.
Read ${CLAUDE_PLUGIN_ROOT}/skills/claude-code-teams/references/hooks-integration.md
Sponsors
Details
- Marketplace
- sequenzia/agent-alchemy
- Source
- claude/claude-tools
- Category
- Community
- License
- MIT