gilles/claude-code-best-practice
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[] changes

Browse Source
This commit is contained in:
Shayan Rais
2026-01-28 13:22:48 +05:00
parent d5be66a528
commit db581c63f7
8 changed files with 205 additions and 134 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/commands/weather-karachi.md
-22
View File
@@ -1,22 +0,0 @@
---
description: Fetch and transform weather data for Karachi
model: haiku
---
# Weather Karachi Command
Fetch the current temperature for Karachi, Pakistan and apply transformations.
## Workflow
1. Use the AskUserQuestion tool to ask the user whether they want the temperature in Celsius or Fahrenheit
2. Use the weather-fetcher agent to retrieve the current temperature from wttr.in API in the requested unit
3. Use the weather-transformer agent to read transformation rules from input/input.md and apply them to the temperature
4. Write the results to output/output.md
Launch the agents sequentially (not in parallel) and provide a clear summary showing:
- Temperature unit requested
- Original temperature
- Transformation applied
- Final result
.claude/commands/weather.md
+6 -2
View File
@@ -5,6 +5,10 @@ model: haiku
# Weather Command # Weather Command
Execute the weather-karachi command to fetch and transform temperature data. Execute the weather-karachi skill to fetch and transform temperature data.
Use the SlashCommand tool to execute `/weather-karachi`. Use the Skill tool to execute the `weather-karachi` skill:
```
Skill(skill="weather-karachi")
```
.claude/skills/weather-karachi/SKILL.md
+54
View File
@@ -0,0 +1,54 @@
---
name: weather-karachi
description: Fetch and transform weather data for Karachi. Use when the user asks about Karachi weather, temperature data, or wants to run the weather workflow.
model: haiku
---
# Weather Karachi Skill
Fetch the current temperature for Karachi, Pakistan and apply transformations.
## Workflow
1. Use the AskUserQuestion tool to ask the user whether they want the temperature in Celsius or Fahrenheit
2. Use the weather-fetcher subagent to retrieve the current temperature from wttr.in API in the requested unit
3. Use the weather-transformer subagent to read transformation rules from input/input.md and apply them to the temperature
4. Write the results to output/output.md
## Subagent Invocation
Use the Task tool to invoke subagents sequentially (not in parallel) to maintain data dependencies.
### Step 1: Fetch Temperature
Use the Task tool to invoke the weather-fetcher subagent:
- subagent_type: weather-fetcher
- description: Fetch Karachi temperature
- prompt: Fetch the current temperature for Karachi, Pakistan in [unit requested by user] from wttr.in API. Return the numeric temperature value in your final report.
- model: haiku
Wait for the subagent to complete and extract the temperature value from its final report.
### Step 2: Transform Temperature
Use the Task tool to invoke the weather-transformer subagent:
- subagent_type: weather-transformer
- description: Transform temperature
- prompt: Apply transformation rules from input/input.md to the temperature value: [X] degrees. Write formatted results to output/output.md.
- model: haiku
Wait for the subagent to complete.
## Critical Requirements
1. **Use Task Tool Only**: DO NOT use bash commands to invoke subagents. You must use the Task tool.
2. **Sequential Execution**: Launch subagents one at a time, wait for completion before launching the next.
3. **Data Passing**: Extract the temperature from weather-fetcher's report and pass it to weather-transformer's prompt.
## Output Summary
Provide a clear summary to the user showing:
- Temperature unit requested
- Original temperature fetched
- Transformation rule applied (from input/input.md)
- Final transformed result (written to output/output.md)
CLAUDE.md
+33 -15
View File
@@ -4,40 +4,52 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
## Repository Overview ## Repository Overview
This is a best practices repository for Claude Code configuration, demonstrating patterns for agents, commands, hooks, and skills. It serves as a reference implementation rather than an application codebase. This is a best practices repository for Claude Code configuration, demonstrating patterns for skills, subagents, hooks, and commands. It serves as a reference implementation rather than an application codebase.
## Key Components ## Key Components
### Weather System (Example Workflow) ### Weather System (Example Workflow)
A demonstration of agent orchestration: A demonstration of skill-based subagent orchestration:
- `/weather` command delegates to `/weather-karachi` - `/weather` command (`.claude/commands/weather.md`): Entry point, invokes the weather-karachi skill
- `weather-fetcher` agent: fetches temperature from wttr.in API - `/weather-karachi` skill (`.claude/skills/weather-karachi/SKILL.md`): Orchestrates the workflow
- `weather-transformer` agent: applies transformation rules from `input/input.md`, writes results to `output/output.md` - `weather-fetcher` subagent: fetches temperature from wttr.in API
- `weather-transformer` subagent: applies transformation rules from `input/input.md`, writes results to `output/output.md`
Agents run sequentially, not in parallel, to maintain data dependencies. Subagents run sequentially via Task tool, not in parallel, to maintain data dependencies.
### Skill Definition Structure
Skills in `.claude/skills/<name>/SKILL.md` use YAML frontmatter:
- `name`: Skill identifier (optional, uses directory name if omitted)
- `description`: When to invoke (recommended for auto-discovery)
- `model`: Model to use when skill is active
- `disable-model-invocation`: Set `true` to prevent automatic invocation
- `context`: Set to `fork` to run in isolated subagent context
- `allowed-tools`: Restrict which tools Claude can use
### Hooks System ### Hooks System
Cross-platform sound notification system in `.claude/hooks/`: Cross-platform sound notification system in `.claude/hooks/`:
- `scripts/hooks.py`: Main handler for all 9 Claude Code hooks - `scripts/hooks.py`: Main handler for all 11 Claude Code hook events
- `config/hooks-config.json`: Shared team configuration - `config/hooks-config.json`: Shared team configuration
- `config/hooks-config.local.json`: Personal overrides (git-ignored) - `config/hooks-config.local.json`: Personal overrides (git-ignored)
- `sounds/`: Audio files organized by hook event - `sounds/`: Audio files organized by hook event (generated via ElevenLabs TTS)
Hook events: PreToolUse, PostToolUse, UserPromptSubmit, Notification, Stop, SubagentStart, SubagentStop, PreCompact, SessionStart, SessionEnd, Setup, PermissionRequest.
Special handling: git commits trigger `pretooluse-git-committing` sound. Special handling: git commits trigger `pretooluse-git-committing` sound.
## Critical Patterns ## Critical Patterns
### Agent Orchestration ### Subagent Orchestration
Agents **cannot** invoke other agents via bash commands. Use the Task tool: Subagents **cannot** invoke other subagents via bash commands. Use the Task tool:
``` ```
Task(subagent_type="agent-name", description="...", prompt="...", model="haiku") Task(subagent_type="agent-name", description="...", prompt="...", model="haiku")
``` ```
Be explicit about tool usage in agent definitions. Avoid vague terms like "launch" that could be misinterpreted as bash commands. Be explicit about tool usage in subagent definitions. Avoid vague terms like "launch" that could be misinterpreted as bash commands.
### Agent Definition Structure ### Subagent Definition Structure
Agents in `.claude/agents/*.md` use YAML frontmatter: Subagents in `.claude/agents/*.md` use YAML frontmatter:
- `name`: Agent identifier - `name`: Subagent identifier
- `description`: When to invoke (use "PROACTIVELY" for auto-invocation) - `description`: When to invoke (use "PROACTIVELY" for auto-invocation)
- `tools`: Comma-separated list of allowed tools - `tools`: Comma-separated list of allowed tools
- `model`: Typically "haiku" for efficiency - `model`: Typically "haiku" for efficiency
@@ -53,5 +65,11 @@ Set `"disableAllHooks": true` in `.claude/settings.local.json`, or disable indiv
## Documentation ## Documentation
- `docs/AGENTS.md`: Agent orchestration troubleshooting - `docs/AGENTS.md`: Subagent orchestration troubleshooting
- `docs/WEATHER.md`: Weather system flow diagram - `docs/WEATHER.md`: Weather system flow diagram
- `docs/COMPARISION.md`: Commands vs Agents vs Skills invocation patterns
## Reports
- `reports/claude-in-chrome-v-chrome-devtools-mcp.md`: Browser automation MCP comparison (Playwright vs Chrome DevTools vs Claude in Chrome)
- `reports/claude-md-for-larger-mono-repos.md`: CLAUDE.md loading behavior in monorepos (ancestor vs descendant loading)
docs/AGENTS.md
+43 -32
View File
@@ -1,41 +1,42 @@
# Agent Orchestration Best Practices # Subagent Orchestration Best Practices
## Problem: Sub-agents Not Invoking ## Problem: Subagents Not Invoking
### Issue Description ### Issue Description
When creating orchestrator agents that coordinate multiple sub-agents, a common mistake is using bash commands or other tools instead of the proper `Task` tool to invoke sub-agents. This results in the sub-agents not being invoked at all. When creating orchestrator skills or subagents that coordinate multiple subagents, a common mistake is using bash commands or other tools instead of the proper `Task` tool to invoke subagents. This results in the subagents not being invoked at all.
### Root Cause ### Root Cause
**Incorrect Implementation:** **Incorrect Implementation:**
The orchestrator agent was trying to use bash commands to invoke sub-agents: The orchestrator was trying to use bash commands to invoke subagents:
- `claude task --agent weather-fetcher "Fetch temperature"` - `claude task --agent weather-fetcher "Fetch temperature"`
The problem is that `claude task` is not a valid bash command in the Claude Code environment. Agents cannot invoke other agents through bash/CLI commands. Instead, they must use the `Task` tool programmatically. The problem is that `claude task` is not a valid bash command in the Claude Code environment. Skills and subagents cannot invoke other subagents through bash/CLI commands. Instead, they must use the `Task` tool programmatically.
### Solution ### Solution
**Correct Implementation:** **Correct Implementation:**
1. **Define the orchestrator with proper tools:** 1. **Define the skill with proper instructions:**
Skills (in `.claude/skills/<name>/SKILL.md`) orchestrate workflows by invoking subagents via the Task tool:
```yaml ```yaml
--- ---
name: weather-orchestrator name: weather-karachi
description: Use this agent to orchestrate the weather fetching and transformation workflow by launching two specialized sub-agents in sequence. description: Fetch and transform weather data for Karachi
tools: Task
model: haiku model: haiku
color: green
--- ---
``` ```
2. **Use the Task tool properly in the agent's instructions:** 2. **Use the Task tool properly in the skill's instructions:**
The agent must be explicitly instructed to use the Task tool with proper parameters. Instead of vague instructions like "Use the Task tool to launch the weather-fetcher agent", provide specific, clear instructions: The skill must explicitly instruct to use the Task tool with proper parameters. Instead of vague instructions like "Use the Task tool to launch the weather-fetcher agent", provide specific, clear instructions:
```markdown ```markdown
## Step 1: Launch weather-fetcher agent ## Step 1: Fetch Temperature
Use the Task tool to invoke the weather-fetcher subagent: Use the Task tool to invoke the weather-fetcher subagent:
- subagent_type: weather-fetcher - subagent_type: weather-fetcher
@@ -43,22 +44,22 @@ Use the Task tool to invoke the weather-fetcher subagent:
- prompt: Fetch the current temperature for Karachi, Pakistan in Celsius from wttr.in API. Return the numeric temperature value in your final report. - prompt: Fetch the current temperature for Karachi, Pakistan in Celsius from wttr.in API. Return the numeric temperature value in your final report.
- model: haiku - model: haiku
Wait for the agent to complete and extract the temperature value from its final report. Wait for the subagent to complete and extract the temperature value from its final report.
``` ```
3. **Key Requirements for Orchestrator Agents:** 3. **Key Requirements for Orchestrating Subagents:**
a. **Explicit Tool Usage**: State clearly "DO NOT use bash commands or any other tools. You must use the Task tool to invoke sub-agents." a. **Explicit Tool Usage**: State clearly "DO NOT use bash commands or any other tools. You must use the Task tool to invoke subagents."
b. **Parameter Specification**: List all required parameters explicitly: b. **Parameter Specification**: List all required parameters explicitly:
- `subagent_type`: The exact agent name - `subagent_type`: The exact subagent name
- `description`: A short 3-5 word description - `description`: A short 3-5 word description
- `prompt`: Detailed instructions for the sub-agent - `prompt`: Detailed instructions for the subagent
- `model`: The model to use (typically "haiku" for efficiency) - `model`: The model to use (typically "haiku" for efficiency)
c. **Sequential Execution**: For sequential workflows, explicitly state "Launch agents one at a time, wait for completion before launching the next." c. **Sequential Execution**: For sequential workflows, explicitly state "Launch subagents one at a time, wait for completion before launching the next."
d. **Data Passing**: Provide clear instructions on how to extract data from one agent's report and pass it to the next agent's prompt. d. **Data Passing**: Provide clear instructions on how to extract data from one subagent's report and pass it to the next subagent's prompt.
### Before and After Comparison ### Before and After Comparison
@@ -71,11 +72,11 @@ Wait for the agent to complete and extract the temperature value from its final
- Wait for the agent to complete and capture the temperature value from its report - Wait for the agent to complete and capture the temperature value from its report
``` ```
**Why it failed:** Too vague. The agent interpreted "launch" as running a bash command instead of using the Task tool properly. **Why it failed:** Too vague. The skill interpreted "launch" as running a bash command instead of using the Task tool properly.
#### After (Working): #### After (Working):
```markdown ```markdown
## Step 1: Launch weather-fetcher agent ## Step 1: Fetch Temperature
Use the Task tool to invoke the weather-fetcher subagent: Use the Task tool to invoke the weather-fetcher subagent:
- subagent_type: weather-fetcher - subagent_type: weather-fetcher
@@ -83,11 +84,11 @@ Use the Task tool to invoke the weather-fetcher subagent:
- prompt: Fetch the current temperature for Karachi, Pakistan in Celsius from wttr.in API. Return the numeric temperature value in your final report. - prompt: Fetch the current temperature for Karachi, Pakistan in Celsius from wttr.in API. Return the numeric temperature value in your final report.
- model: haiku - model: haiku
Wait for the agent to complete and extract the temperature value from its final report. Wait for the subagent to complete and extract the temperature value from its final report.
## Critical Requirements ## Critical Requirements
1. **Use Task Tool Only**: DO NOT use bash commands or any other tools. You must use the Task tool to invoke sub-agents. 1. **Use Task Tool Only**: DO NOT use bash commands or any other tools. You must use the Task tool to invoke subagents.
``` ```
**Why it works:** **Why it works:**
@@ -97,17 +98,17 @@ Wait for the agent to complete and extract the temperature value from its final
### Testing the Fix ### Testing the Fix
After updating the orchestrator agent definition, test it by invoking the orchestrator: After creating the skill, test it by invoking:
```bash ```bash
# Via slash command # Via skill invocation
/weather-karachi /weather-karachi
# Or directly via Task tool # Or via Skill tool from another command
Task(subagent_type="weather-orchestrator", description="Run weather workflow", prompt="Orchestrate the complete weather workflow", model="haiku") Skill(skill="weather-karachi")
``` ```
The orchestrator should now: The skill should now:
1. Successfully invoke weather-fetcher using the Task tool 1. Successfully invoke weather-fetcher using the Task tool
2. Extract the temperature from the fetcher's report 2. Extract the temperature from the fetcher's report
3. Invoke weather-transformer with the temperature value 3. Invoke weather-transformer with the temperature value
@@ -115,12 +116,22 @@ The orchestrator should now:
### Key Takeaways ### Key Takeaways
1. **Agents cannot use CLI commands to invoke other agents** - they must use the Task tool programmatically 1. **Skills and subagents cannot use CLI commands to invoke other subagents** - they must use the Task tool programmatically
2. **Be explicit with tool usage** - clearly state which tool to use and which tools NOT to use 2. **Be explicit with tool usage** - clearly state which tool to use and which tools NOT to use
3. **Provide complete parameter specifications** - list all required parameters with example values 3. **Provide complete parameter specifications** - list all required parameters with example values
4. **Test orchestrator agents thoroughly** - ensure they properly chain sub-agent invocations 4. **Test orchestrator skills thoroughly** - ensure they properly chain subagent invocations
5. **Use clear, unambiguous language** - avoid terms like "launch" or "run" which could be interpreted as bash commands 5. **Use clear, unambiguous language** - avoid terms like "launch" or "run" which could be interpreted as bash commands
### Color Configuration ### Color Configuration
The `color` parameter in agent frontmatter (e.g., `color: green`) controls the color of the agent's output in the CLI, making it easier to visually distinguish between different agents' outputs. This is purely a display feature and does not affect the agent's functionality or the content it produces. The `color` parameter in subagent frontmatter (e.g., `color: green`) controls the color of the subagent's output in the CLI, making it easier to visually distinguish between different subagents' outputs. This is purely a display feature and does not affect the subagent's functionality or the content it produces.
## Skills vs Commands vs Subagents
| Component | Location | Purpose | Invocation |
|-----------|----------|---------|------------|
| **Skill** | `.claude/skills/<name>/SKILL.md` | Orchestrate workflows, reusable procedures | `/skill-name` or `Skill(skill="name")` |
| **Command** | `.claude/commands/<name>.md` | Legacy format (still works), simple procedures | `/command-name` |
| **Subagent** | `.claude/agents/<name>.md` | Specialized task execution with isolated context | `Task(subagent_type="name", ...)` |
Skills are recommended over commands as they support additional features like supporting files, invocation control, and subagent execution.
docs/COMPARISION.md
+41 -35
View File
@@ -134,35 +134,37 @@ Skills are model-invoked capabilities that Claude activates automatically based
### Scenario 1: User Wants Weather Data ### Scenario 1: User Wants Weather Data
**Using Command (Explicit):** **Using Skill (Explicit):**
``` ```
User: /weather-karachi User: /weather-karachi
Result: Explicit command execution → agents run → output generated Result: Explicit skill execution → subagents run → output generated
``` ```
**Using Command (Automatic - Default Behavior):** **Using Skill (Automatic - Default Behavior):**
```yaml ```yaml
# Command configuration with description (automatic invocation enabled by default) # Skill configuration with description (automatic invocation enabled by default)
# Location: .claude/skills/weather-karachi/SKILL.md
--- ---
description: Fetch and transform weather data for Karachi name: weather-karachi
description: Fetch and transform weather data for Karachi. Use when the user asks about Karachi weather.
model: haiku model: haiku
--- ---
``` ```
``` ```
User: "What's the weather like in Karachi?" User: "What's the weather like in Karachi?"
Result: Claude automatically invokes /weather-karachi command via SlashCommand tool Result: Claude automatically invokes weather-karachi skill via Skill tool
Note: Commands are auto-invoked by default unless disable-model-invocation: true is set Note: Skills are auto-invoked by default unless disable-model-invocation: true is set
``` ```
**Using Agent (Explicit):** **Using Subagent (Explicit):**
``` ```
User: "Use the weather-fetcher agent to get Karachi temperature" User: "Use the weather-fetcher agent to get Karachi temperature"
Result: Claude invokes weather-fetcher agent → returns temperature Result: Claude invokes weather-fetcher subagent → returns temperature
``` ```
**Using Agent (Automatic/Proactive):** **Using Subagent (Automatic/Proactive):**
```yaml ```yaml
# Agent configuration with PROACTIVELY keyword # Subagent configuration with PROACTIVELY keyword
--- ---
description: Use this agent PROACTIVELY when user asks about Karachi weather. description: Use this agent PROACTIVELY when user asks about Karachi weather.
Fetch current temperature from wttr.in. Fetch current temperature from wttr.in.
@@ -170,37 +172,40 @@ description: Use this agent PROACTIVELY when user asks about Karachi weather.
``` ```
``` ```
User: "What's the weather like in Karachi?" User: "What's the weather like in Karachi?"
Result: Claude automatically invokes weather-fetcher agent → returns temperature Result: Claude automatically invokes weather-fetcher subagent → returns temperature
Note: Agent description contains "PROACTIVELY" keyword Note: Subagent description contains "PROACTIVELY" keyword
``` ```
**Using Skill (Automatic):** **Using Command (Legacy):**
``` ```
User: "What's the weather in Karachi?" User: /weather
Result: If weather skill exists with proper description, Claude automatically invokes it Result: Command invokes weather-karachi skill via Skill tool
Note: No explicit mention of "skill" needed Note: Commands still work but skills are recommended
``` ```
### Scenario 2: Orchestrating Multiple Steps ### Scenario 2: Orchestrating Multiple Steps
**Command Orchestrating Agents:** **Skill Orchestrating Subagents:**
```markdown ```markdown
<!-- In /weather-karachi command --> <!-- In .claude/skills/weather-karachi/SKILL.md -->
1. Task(subagent_type="weather-fetcher", ...) 1. Task(subagent_type="weather-fetcher", ...)
2. Task(subagent_type="weather-transformer", ...) 2. Task(subagent_type="weather-transformer", ...)
``` ```
**Agent Orchestrating Other Agents:** **Command Invoking Skill:**
```markdown ```markdown
<!-- In weather-orchestrator agent --> <!-- In /weather command -->
Skill(skill="weather-karachi")
```
**Subagent Orchestrating Other Subagents:**
```markdown
<!-- In weather-orchestrator subagent -->
1. Task(subagent_type="weather-fetcher", ...) 1. Task(subagent_type="weather-fetcher", ...)
2. Extract temperature from report 2. Extract temperature from report
3. Task(subagent_type="weather-transformer", prompt="Transform {temperature}", ...) 3. Task(subagent_type="weather-transformer", prompt="Transform {temperature}", ...)
``` ```
**Skills Cannot Orchestrate:**
Skills are single-purpose and don't coordinate other capabilities.
### Scenario 3: Automatic Agent Invocation (Real-World) ### Scenario 3: Automatic Agent Invocation (Real-World)
**Proactive Code Review Agent:** **Proactive Code Review Agent:**
@@ -239,7 +244,7 @@ User: Gets immediate test feedback
### Scenario 4: From Within Code/Prompts ### Scenario 4: From Within Code/Prompts
**Invoking Agent from Command:** **Invoking Subagent from Skill:**
```markdown ```markdown
Use the Task tool to invoke the weather-fetcher subagent: Use the Task tool to invoke the weather-fetcher subagent:
- subagent_type: weather-fetcher - subagent_type: weather-fetcher
@@ -248,16 +253,16 @@ Use the Task tool to invoke the weather-fetcher subagent:
- model: haiku - model: haiku
``` ```
**Invoking Command from Agent:** **Invoking Skill from Command:**
```markdown ```markdown
Use the SlashCommand tool to execute the weather workflow: Use the Skill tool to execute the weather-karachi skill:
SlashCommand(command="/weather-karachi") Skill(skill="weather-karachi")
``` ```
**Invoking Skill (if Skill tool available):** **Invoking Skill from Another Skill:**
```markdown ```markdown
Use the Skill tool to process the PDF: Use the Skill tool to invoke a related skill:
Skill(command="pdf") Skill(skill="data-processor")
``` ```
## Core Differences Between Commands and Agents ## Core Differences Between Commands and Agents
@@ -301,11 +306,12 @@ While commands and agents share similar invocation patterns, they have fundament
- You want specialized capabilities (like code review, test running) - You want specialized capabilities (like code review, test running)
**Example from this repository:** **Example from this repository:**
- `/weather-karachi` command: Orchestrates the workflow - `/weather-karachi` skill: Orchestrates the workflow (`.claude/skills/weather-karachi/SKILL.md`)
- `weather-fetcher` agent: Autonomous subprocess that fetches temperature - `/weather` command: Entry point that invokes the skill (`.claude/commands/weather.md`)
- `weather-transformer` agent: Autonomous subprocess that transforms data - `weather-fetcher` subagent: Autonomous subprocess that fetches temperature
- `weather-transformer` subagent: Autonomous subprocess that transforms data
The command coordinates, while agents execute their specialized tasks independently. The skill coordinates, while subagents execute their specialized tasks independently.
## Summary ## Summary
docs/WEATHER.md → docs/weather-flow-architecture.md
+26 -26
View File
@@ -4,7 +4,7 @@ This document describes the complete flow of the weather data fetching and trans
## System Overview ## System Overview
The weather system consists of slash commands and specialized agents that work together to fetch and transform temperature data for Karachi, Pakistan. The weather system consists of skills and specialized subagents that work together to fetch and transform temperature data for Karachi, Pakistan.
## Flow Diagram ## Flow Diagram
@@ -19,18 +19,18 @@ The weather system consists of slash commands and specialized agents that work t
│ Command │ │ Command │
└──────────────────┘ └──────────────────┘
│ │
│ calls │ invokes via Skill tool
▼ ▼
┌──────────────────┐ ┌──────────────────┐
│ /weather-karachi │ │ /weather-karachi │
│ Command │ │ Skill │
└──────────────────┘ └──────────────────┘
│ │
│ Step 1 (Sequential) │ Step 1 (Sequential via Task tool)
▼ ▼
┌────────────────────────┐ ┌────────────────────────┐
│ weather-fetcher │ │ weather-fetcher │
│ Agent │ │ Subagent │
│ (subagent_type) │ │ (subagent_type) │
└────────────────────────┘ └────────────────────────┘
│ │
@@ -44,11 +44,11 @@ The weather system consists of slash commands and specialized agents that work t
│ Returns: 26°C │ Returns: 26°C
▼ ▼
│ │
│ Step 2 (Sequential) │ Step 2 (Sequential via Task tool)
▼ ▼
┌─────────────────────────┐ ┌─────────────────────────┐
│ weather-transformer │ │ weather-transformer │
│ Agent │ │ Subagent │
│ (subagent_type) │ │ (subagent_type) │
└─────────────────────────┘ └─────────────────────────┘
│ │
@@ -80,21 +80,21 @@ The weather system consists of slash commands and specialized agents that work t
## Component Details ## Component Details
### 1. Slash Commands ### 1. Skills and Commands
#### `/weather` #### `/weather` (Command)
- **Location**: `.claude/commands/weather.md` - **Location**: `.claude/commands/weather.md`
- **Purpose**: Entry point for weather operations - **Purpose**: Entry point for weather operations
- **Action**: Calls `/weather-karachi` command - **Action**: Invokes `weather-karachi` skill via Skill tool
- **Model**: haiku - **Model**: haiku
#### `/weather-karachi` #### `/weather-karachi` (Skill)
- **Location**: `.claude/commands/weather-karachi.md` - **Location**: `.claude/skills/weather-karachi/SKILL.md`
- **Purpose**: Orchestrates the weather fetching and transformation workflow - **Purpose**: Orchestrates the weather fetching and transformation workflow
- **Action**: Launches two specialized agents sequentially - **Action**: Launches two specialized subagents sequentially via Task tool
- **Model**: haiku - **Model**: haiku
### 2. Specialized Agents ### 2. Specialized Subagents
#### `weather-fetcher` #### `weather-fetcher`
- **Location**: `.claude/agents/weather-fetcher.md` - **Location**: `.claude/agents/weather-fetcher.md`
@@ -115,7 +115,7 @@ The weather system consists of slash commands and specialized agents that work t
#### `input/input.md` #### `input/input.md`
- **Purpose**: Stores transformation rules - **Purpose**: Stores transformation rules
- **Format**: Natural language instructions (e.g., "add +10 in the result") - **Format**: Natural language instructions (e.g., "add +10 in the result")
- **Access**: Read by weather-transformer agent - **Access**: Read by weather-transformer subagent
#### `output/output.md` #### `output/output.md`
- **Purpose**: Stores formatted transformation results - **Purpose**: Stores formatted transformation results
@@ -127,11 +127,11 @@ The weather system consists of slash commands and specialized agents that work t
## Execution Flow ## Execution Flow
1. **User Invocation**: User runs `/weather` command 1. **User Invocation**: User runs `/weather` command or `/weather-karachi` skill
2. **Command Delegation**: `/weather` delegates to `/weather-karachi` 2. **Skill Invocation**: `/weather` invokes `weather-karachi` skill via Skill tool
3. **Sequential Agent Execution**: 3. **Sequential Subagent Execution** (via Task tool):
- **Step 1**: `weather-fetcher` agent fetches current temperature from wttr.in - **Step 1**: `weather-fetcher` subagent fetches current temperature from wttr.in
- **Step 2**: `weather-transformer` agent: - **Step 2**: `weather-transformer` subagent:
- Reads transformation rules from `input/input.md` - Reads transformation rules from `input/input.md`
- Applies rules to the fetched temperature - Applies rules to the fetched temperature
- Formats and writes results to `output/output.md` - Formats and writes results to `output/output.md`
@@ -144,10 +144,10 @@ The weather system consists of slash commands and specialized agents that work t
``` ```
Input: /weather Input: /weather
├─ Calls: /weather-karachi ├─ Invokes: weather-karachi skill (via Skill tool)
│ ├─ Agent: weather-fetcher │ ├─ Subagent: weather-fetcher (via Task tool)
│ │ └─ Result: 26°C │ │ └─ Result: 26°C
│ ├─ Agent: weather-transformer │ ├─ Subagent: weather-transformer (via Task tool)
│ │ ├─ Reads: input/input.md ("add +10") │ │ ├─ Reads: input/input.md ("add +10")
│ │ ├─ Calculates: 26 + 10 = 36°C │ │ ├─ Calculates: 26 + 10 = 36°C
│ │ └─ Writes: output/output.md │ │ └─ Writes: output/output.md
@@ -160,8 +160,8 @@ Input: /weather
## Key Design Principles ## Key Design Principles
1. **Separation of Concerns**: Each component has a single, clear responsibility 1. **Separation of Concerns**: Each component has a single, clear responsibility
2. **Sequential Execution**: Agents run in order to ensure data dependencies are met 2. **Sequential Execution**: Subagents run in order to ensure data dependencies are met
3. **Specialized Agents**: Task-specific agents with minimal tool access 3. **Specialized Subagents**: Task-specific subagents with minimal tool access
4. **Command Chaining**: Simple commands can delegate to more complex workflows 4. **Skill-Based Architecture**: Skills orchestrate workflows, subagents execute tasks
5. **Configurable Transformations**: Rules stored externally in input files 5. **Configurable Transformations**: Rules stored externally in input files
6. **Structured Output**: Results formatted consistently in output files 6. **Structured Output**: Results formatted consistently in output files
output/output.md
+2 -2
View File
@@ -1,3 +1,3 @@
Original Temperature: 22°C Original Temperature: 24°C
Transformation Applied: add +10 in the result Transformation Applied: add +10 in the result
Final Result: 32°C Final Result: 34°C