# Building Command → Agent → Skill Orchestration Workflows with Claude Code > Learn to build command agent skill orchestration workflows with real-world examples using the claude-code-best-practice repository. Master reusable AI patterns. - Repository: [Shayan Rais/claude-code-best-practice](https://github.com/shanraisshan/claude-code-best-practice) - Tags: how-to-guide - Published: 2026-03-12 --- **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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/skills/weather-fetcher/SKILL.md) and [`.claude/skills/weather-svg-creator/SKILL.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/commands/weather-orchestrator.md) establishes the workflow entry point: ```markdown --- 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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/agents/weather-agent.md) file demonstrates agent-skill binding: ```yaml --- 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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/skills/weather-fetcher/SKILL.md) contains pure instructions: ```markdown ## 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¤t=temperature_2m&temperature_unit=celsius - Fahrenheit URL: https://api.open-meteo.com/v1/forecast?latitude=25.2048&longitude=55.2708¤t=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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/skills/weather-svg-creator/SKILL.md) handles presentation: ```markdown ## 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: Dubai: [TEMPERATURE]°[UNIT] ### 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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/commands/weather-orchestrator.md), [`.claude/agents/weather-agent.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.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/`.