Building Command → Agent → Skill Orchestration Workflows with Claude Code

The claude-code-best-practice repository demonstrates a production-ready orchestration pattern that separates user interaction, data fetching, and output generation into distinct Command, Agent, and Skill layers, enabling reusable and maintainable AI workflows.

This guide examines a complete implementation of Command → Agent → Skill orchestration workflows in the shanraisshan/claude-code-best-practice repository. The weather forecasting example provides a canonical reference for structuring complex Claude Code automations that scale across real-world projects.

Architectural Overview

The orchestration pattern divides responsibilities across three Claude Code primitives:

Layer	Responsibility	Key File
Command	Captures user intent, orchestrates workflow execution, and coordinates between agents and skills	.claude/commands/weather-orchestrator.md
Agent	Runs in an isolated context with pre-loaded skills, executes tool-based logic (e.g., WebFetch), and returns raw data	.claude/agents/weather-agent.md
Skill	Provides reusable, self-contained instructions that can be pre-loaded into agents or invoked directly from commands	.claude/skills/weather-fetcher/SKILL.md and .claude/skills/weather-svg-creator/SKILL.md

Data Flow Through the System

The workflow follows a strict unidirectional data flow:

User → /weather-orchestrator (Command)
      ├─ asks for unit (C/F) → stores preference
      ├─ Task → weather-agent (Agent)  ← pre-loaded weather-fetcher (Skill)
      │      → returns temperature + unit
      └─ Skill → weather-svg-creator (Skill)
             → writes weather.svg & output.md

The command never writes files directly; it only coordinates. The agent never creates UI artifacts; it returns raw data. The SVG skill is the only component that performs file I/O, ensuring clear separation of concerns.

The Three Core Primitives

Command Layer

Commands serve as user-invokable entry points that handle interaction and workflow coordination. In .claude/commands/weather-orchestrator.md, the command defines the entry point and orchestrates the entire flow using the Task tool for agents and the Skill tool for direct skill invocation.

Key configuration elements include:

• Model specification: Declares model: haiku for cost-effective coordination
• Tool usage: Uses the Task tool (not shell commands) to launch agents deterministically
• Context passing: Transfers user preferences (Celsius/Fahrenheit) through prompt parameters

Agent Layer

Agents provide sandboxed execution contexts that can load pre-loaded skills and run tools. The .claude/agents/weather-agent.md file defines an agent with memory: project for persistence and skills: weather-fetcher for capability injection.

Critical agent configuration:

• subagent_type: weather-agent identifies the agent type
• tools: WebFetch, Read, Write, Edit declares available capabilities
• maxTurns: 5 limits execution scope
• permissionMode: acceptEdits automates file operations within the sandbox

Skill Layer

Skills represent reusable logic packages. The repository demonstrates two invocation patterns:

Pre-loaded Skills: The weather-fetcher skill attaches to the agent via the skills: array in the agent definition. The agent receives the full skill instructions at startup and follows them to fetch Dubai temperature data from the Open-Meteo API.

Direct Skills: The weather-svg-creator skill is invoked directly from the command via the Skill tool, consuming the temperature data returned by the agent to generate visual artifacts.

Real-World Implementation

Defining the Entry Point

The command file .claude/commands/weather-orchestrator.md establishes the workflow entry point:

---
description: Fetch weather data for Dubai and create an SVG weather card
model: haiku
---

# Weather Orchestrator Command

## Step 1: Get Temperature Unit

Ask the user whether they want the temperature in Celsius or Fahrenheit.

## Step 2: Fetch Weather Data

Use the Task tool to invoke the weather agent:
- subagent_type: weather-agent
- description: Fetch Dubai weather data
- prompt: Fetch the current temperature for Dubai, UAE in [unit requested by user]...
- model: haiku

## Step 3: Generate Visual Output

Use the Skill tool to invoke weather-svg-creator with the temperature value...

The command uses subagent_type to specify the agent and passes contextual data through the prompt parameter, maintaining clean interfaces between components.

Configuring the Agent with Pre-Loaded Skills

The .claude/agents/weather-agent.md file demonstrates agent-skill binding:

---
name: weather-agent
description: Use this agent PROACTIVELY when you need to fetch weather data for Dubai, UAE.
tools: WebFetch, Read, Write, Edit
model: sonnet
color: green
maxTurns: 5
permissionMode: acceptEdits
memory: project
skills:
  - weather-fetcher
---

# Weather Agent

You are a specialized agent for fetching weather data.

## Instructions

1. **Fetch**: Follow the `weather-fetcher` skill instructions to retrieve data from Open-Meteo
2. **Report**: Return the temperature value and unit to the caller without creating files

The skills: array automatically injects the weather-fetcher instructions into the agent's context, while memory: project allows the agent to persist data across turns if needed.

Creating the Fetcher Skill

The pre-loaded skill at .claude/skills/weather-fetcher/SKILL.md contains pure instructions:

## Instructions

1. **Fetch Weather Data**: Use the WebFetch tool to get current weather data for Dubai from the Open-Meteo API.
   - Celsius URL: https://api.open-meteo.com/v1/forecast?latitude=25.2048&longitude=55.2708&current=temperature_2m&temperature_unit=celsius
   - Fahrenheit URL: https://api.open-meteo.com/v1/forecast?latitude=25.2048&longitude=55.2708&current=temperature_2m&temperature_unit=fahrenheit

2. **Extract Temperature**: Parse the `current.temperature_2m` field from the JSON response.

3. **Return Result**: Format the output exactly as: `Current Dubai Temperature: [X]°[C/F]`.

This skill contains no executable code—only structured instructions that the agent executes using its available WebFetch tool.

Building the Output Skill

The direct-invocation skill at .claude/skills/weather-svg-creator/SKILL.md handles presentation:

## Instructions

You will receive the temperature value and unit from the calling context.

### 1. Create SVG Weather Card

Generate an SVG with embedded temperature display:
<svg width="400" height="200" xmlns="http://www.w3.org/2000/svg">
  <rect width="100%" height="100%" fill="#f0f0f0"/>
  <text x="50%" y="50%" font-family="Arial" font-size="24" text-anchor="middle">
    Dubai: [TEMPERATURE]°[UNIT]
  </text>
</svg>

### 2. Write SVG File

Read existing `orchestration-workflow/weather.svg` (if any), then write the new SVG using the Write tool.

### 3. Write Output Summary

Create `orchestration-workflow/output.md` containing the temperature, unit, location, and an embedded image reference to the SVG.

Why This Pattern Works

Separation of Concerns – Each component owns a single responsibility. Commands coordinate, agents fetch data, and skills generate outputs. This isolation makes testing and evolution straightforward.

Context Isolation – Agents run in fresh contexts with memory: project, preventing state leakage between unrelated workflows. A failure in the weather agent does not corrupt the calling command's context.

Skill Reusability – The weather-fetcher skill can attach to any agent requiring Dubai temperature data. New output formats (PDF, JSON, email) require only new skills; existing commands and agents remain unchanged.

Deterministic Orchestration – Explicit tool declarations (Task for agents, Skill for skills) eliminate ambiguous "run a bash command" anti-patterns. The system behaves predictably across executions.

Built-in Observability – Agent hooks (PreToolUse, PostToolUse) can wire to logging or voice-feedback systems without modifying core business logic, providing production-grade monitoring capabilities.

Summary

• Command → Agent → Skill orchestration workflows separate interaction, execution, and presentation into distinct, composable layers
• The shanraisshan/claude-code-best-practice repository provides a canonical weather example demonstrating this pattern end-to-end
• Agents use skills: arrays to load pre-loaded capabilities, while commands use the Skill tool for direct invocation
• The Task tool launches agents deterministically with isolated contexts (memory: project) and defined tool sets (WebFetch, Read, Write)
• Key files include .claude/commands/weather-orchestrator.md, .claude/agents/weather-agent.md, and the skill definitions in .claude/skills/
• This architecture enables extensible, testable, and observable AI workflows that scale across real-world projects

Frequently Asked Questions

What is the difference between pre-loaded skills and direct skills in Claude Code orchestration?

Pre-loaded skills attach to agents via the skills: array in the agent definition (e.g., weather-fetcher in .claude/agents/weather-agent.md), automatically injecting instructions into the agent's context at startup. Direct skills are invoked explicitly by commands using the Skill tool (e.g., weather-svg-creator), operating on data returned by agents rather than fetching it themselves.

How does the Task tool differ from shell commands in Claude Code workflows?

The Task tool creates a deterministic, sandboxed execution context with explicit parameters (subagent_type, description, prompt), whereas shell commands execute arbitrary bash in the main context. According to the repository's best practices, the Task tool eliminates ambiguous execution paths and provides built-in isolation through memory: project settings and maxTurns limits.

Can multiple agents share the same pre-loaded skill?

Yes. The weather-fetcher skill defined in .claude/skills/weather-fetcher/SKILL.md can be attached to any number of agents by listing it in their respective skills: arrays. This reusability ensures consistent API interaction logic across different workflow contexts without code duplication.

What configuration prevents agents from accidentally modifying project files?

The combination of permissionMode: acceptEdits and explicit tools declarations (e.g., tools: WebFetch, Read, Write, Edit) in the agent definition controls file system access. Additionally, the architectural pattern itself restricts file I/O to specific skills—the weather agent returns only text data, while the weather-svg-creator skill handles all file writes under orchestration-workflow/.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}