[] changes
This commit is contained in:
Shayan Rais
@@ -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
|
||||
@@ -5,6 +5,10 @@ model: haiku
|
||||
|
||||
# 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")
|
||||
```
|
||||
|
||||
@@ -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)
|
||||
@@ -4,40 +4,52 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
|
||||
|
||||
## 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
|
||||
|
||||
### Weather System (Example Workflow)
|
||||
A demonstration of agent orchestration:
|
||||
- `/weather` command delegates to `/weather-karachi`
|
||||
- `weather-fetcher` agent: fetches temperature from wttr.in API
|
||||
- `weather-transformer` agent: applies transformation rules from `input/input.md`, writes results to `output/output.md`
|
||||
A demonstration of skill-based subagent orchestration:
|
||||
- `/weather` command (`.claude/commands/weather.md`): Entry point, invokes the weather-karachi skill
|
||||
- `/weather-karachi` skill (`.claude/skills/weather-karachi/SKILL.md`): Orchestrates the workflow
|
||||
- `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
|
||||
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.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.
|
||||
|
||||
## Critical Patterns
|
||||
|
||||
### Agent Orchestration
|
||||
Agents **cannot** invoke other agents via bash commands. Use the Task tool:
|
||||
### Subagent Orchestration
|
||||
Subagents **cannot** invoke other subagents via bash commands. Use the Task tool:
|
||||
```
|
||||
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
|
||||
Agents in `.claude/agents/*.md` use YAML frontmatter:
|
||||
- `name`: Agent identifier
|
||||
### Subagent Definition Structure
|
||||
Subagents in `.claude/agents/*.md` use YAML frontmatter:
|
||||
- `name`: Subagent identifier
|
||||
- `description`: When to invoke (use "PROACTIVELY" for auto-invocation)
|
||||
- `tools`: Comma-separated list of allowed tools
|
||||
- `model`: Typically "haiku" for efficiency
|
||||
@@ -53,5 +65,11 @@ Set `"disableAllHooks": true` in `.claude/settings.local.json`, or disable indiv
|
||||
|
||||
## Documentation
|
||||
|
||||
- `docs/AGENTS.md`: Agent orchestration troubleshooting
|
||||
- `docs/AGENTS.md`: Subagent orchestration troubleshooting
|
||||
- `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)
|
||||
|
||||
+43
-32
@@ -1,41 +1,42 @@
|
||||
# Agent Orchestration Best Practices
|
||||
# Subagent Orchestration Best Practices
|
||||
|
||||
## Problem: Sub-agents Not Invoking
|
||||
## Problem: Subagents Not Invoking
|
||||
|
||||
### 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
|
||||
|
||||
**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"`
|
||||
|
||||
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
|
||||
|
||||
**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
|
||||
---
|
||||
name: weather-orchestrator
|
||||
description: Use this agent to orchestrate the weather fetching and transformation workflow by launching two specialized sub-agents in sequence.
|
||||
tools: Task
|
||||
name: weather-karachi
|
||||
description: Fetch and transform weather data for Karachi
|
||||
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
|
||||
## Step 1: Launch weather-fetcher agent
|
||||
## Step 1: Fetch Temperature
|
||||
|
||||
Use the Task tool to invoke the weather-fetcher subagent:
|
||||
- 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.
|
||||
- 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:
|
||||
- `subagent_type`: The exact agent name
|
||||
- `subagent_type`: The exact subagent name
|
||||
- `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)
|
||||
|
||||
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
|
||||
|
||||
@@ -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
|
||||
```
|
||||
|
||||
**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):
|
||||
```markdown
|
||||
## Step 1: Launch weather-fetcher agent
|
||||
## Step 1: Fetch Temperature
|
||||
|
||||
Use the Task tool to invoke the weather-fetcher subagent:
|
||||
- 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.
|
||||
- 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
|
||||
|
||||
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:**
|
||||
@@ -97,17 +98,17 @@ Wait for the agent to complete and extract the temperature value from its final
|
||||
|
||||
### Testing the Fix
|
||||
|
||||
After updating the orchestrator agent definition, test it by invoking the orchestrator:
|
||||
After creating the skill, test it by invoking:
|
||||
|
||||
```bash
|
||||
# Via slash command
|
||||
# Via skill invocation
|
||||
/weather-karachi
|
||||
|
||||
# Or directly via Task tool
|
||||
Task(subagent_type="weather-orchestrator", description="Run weather workflow", prompt="Orchestrate the complete weather workflow", model="haiku")
|
||||
# Or via Skill tool from another command
|
||||
Skill(skill="weather-karachi")
|
||||
```
|
||||
|
||||
The orchestrator should now:
|
||||
The skill should now:
|
||||
1. Successfully invoke weather-fetcher using the Task tool
|
||||
2. Extract the temperature from the fetcher's report
|
||||
3. Invoke weather-transformer with the temperature value
|
||||
@@ -115,12 +116,22 @@ The orchestrator should now:
|
||||
|
||||
### 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
|
||||
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
|
||||
|
||||
### 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.
|
||||
|
||||
+41
-35
@@ -134,35 +134,37 @@ Skills are model-invoked capabilities that Claude activates automatically based
|
||||
|
||||
### Scenario 1: User Wants Weather Data
|
||||
|
||||
**Using Command (Explicit):**
|
||||
**Using Skill (Explicit):**
|
||||
```
|
||||
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
|
||||
# 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
|
||||
---
|
||||
```
|
||||
```
|
||||
User: "What's the weather like in Karachi?"
|
||||
Result: Claude automatically invokes /weather-karachi command via SlashCommand tool
|
||||
Note: Commands are auto-invoked by default unless disable-model-invocation: true is set
|
||||
Result: Claude automatically invokes weather-karachi skill via Skill tool
|
||||
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"
|
||||
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
|
||||
# Agent configuration with PROACTIVELY keyword
|
||||
# Subagent configuration with PROACTIVELY keyword
|
||||
---
|
||||
description: Use this agent PROACTIVELY when user asks about Karachi weather.
|
||||
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?"
|
||||
Result: Claude automatically invokes weather-fetcher agent → returns temperature
|
||||
Note: Agent description contains "PROACTIVELY" keyword
|
||||
Result: Claude automatically invokes weather-fetcher subagent → returns temperature
|
||||
Note: Subagent description contains "PROACTIVELY" keyword
|
||||
```
|
||||
|
||||
**Using Skill (Automatic):**
|
||||
**Using Command (Legacy):**
|
||||
```
|
||||
User: "What's the weather in Karachi?"
|
||||
Result: If weather skill exists with proper description, Claude automatically invokes it
|
||||
Note: No explicit mention of "skill" needed
|
||||
User: /weather
|
||||
Result: Command invokes weather-karachi skill via Skill tool
|
||||
Note: Commands still work but skills are recommended
|
||||
```
|
||||
|
||||
### Scenario 2: Orchestrating Multiple Steps
|
||||
|
||||
**Command Orchestrating Agents:**
|
||||
**Skill Orchestrating Subagents:**
|
||||
```markdown
|
||||
<!-- In /weather-karachi command -->
|
||||
<!-- In .claude/skills/weather-karachi/SKILL.md -->
|
||||
1. Task(subagent_type="weather-fetcher", ...)
|
||||
2. Task(subagent_type="weather-transformer", ...)
|
||||
```
|
||||
|
||||
**Agent Orchestrating Other Agents:**
|
||||
**Command Invoking Skill:**
|
||||
```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", ...)
|
||||
2. Extract temperature from report
|
||||
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)
|
||||
|
||||
**Proactive Code Review Agent:**
|
||||
@@ -239,7 +244,7 @@ User: Gets immediate test feedback
|
||||
|
||||
### Scenario 4: From Within Code/Prompts
|
||||
|
||||
**Invoking Agent from Command:**
|
||||
**Invoking Subagent from Skill:**
|
||||
```markdown
|
||||
Use the Task tool to invoke the weather-fetcher subagent:
|
||||
- subagent_type: weather-fetcher
|
||||
@@ -248,16 +253,16 @@ Use the Task tool to invoke the weather-fetcher subagent:
|
||||
- model: haiku
|
||||
```
|
||||
|
||||
**Invoking Command from Agent:**
|
||||
**Invoking Skill from Command:**
|
||||
```markdown
|
||||
Use the SlashCommand tool to execute the weather workflow:
|
||||
SlashCommand(command="/weather-karachi")
|
||||
Use the Skill tool to execute the weather-karachi skill:
|
||||
Skill(skill="weather-karachi")
|
||||
```
|
||||
|
||||
**Invoking Skill (if Skill tool available):**
|
||||
**Invoking Skill from Another Skill:**
|
||||
```markdown
|
||||
Use the Skill tool to process the PDF:
|
||||
Skill(command="pdf")
|
||||
Use the Skill tool to invoke a related skill:
|
||||
Skill(skill="data-processor")
|
||||
```
|
||||
|
||||
## 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)
|
||||
|
||||
**Example from this repository:**
|
||||
- `/weather-karachi` command: Orchestrates the workflow
|
||||
- `weather-fetcher` agent: Autonomous subprocess that fetches temperature
|
||||
- `weather-transformer` agent: Autonomous subprocess that transforms data
|
||||
- `/weather-karachi` skill: Orchestrates the workflow (`.claude/skills/weather-karachi/SKILL.md`)
|
||||
- `/weather` command: Entry point that invokes the skill (`.claude/commands/weather.md`)
|
||||
- `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
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ This document describes the complete flow of the weather data fetching and trans
|
||||
|
||||
## 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
|
||||
|
||||
@@ -19,18 +19,18 @@ The weather system consists of slash commands and specialized agents that work t
|
||||
│ Command │
|
||||
└──────────────────┘
|
||||
│
|
||||
│ calls
|
||||
│ invokes via Skill tool
|
||||
▼
|
||||
┌──────────────────┐
|
||||
│ /weather-karachi │
|
||||
│ Command │
|
||||
│ Skill │
|
||||
└──────────────────┘
|
||||
│
|
||||
│ Step 1 (Sequential)
|
||||
│ Step 1 (Sequential via Task tool)
|
||||
▼
|
||||
┌────────────────────────┐
|
||||
│ weather-fetcher │
|
||||
│ Agent │
|
||||
│ Subagent │
|
||||
│ (subagent_type) │
|
||||
└────────────────────────┘
|
||||
│
|
||||
@@ -44,11 +44,11 @@ The weather system consists of slash commands and specialized agents that work t
|
||||
│ Returns: 26°C
|
||||
▼
|
||||
│
|
||||
│ Step 2 (Sequential)
|
||||
│ Step 2 (Sequential via Task tool)
|
||||
▼
|
||||
┌─────────────────────────┐
|
||||
│ weather-transformer │
|
||||
│ Agent │
|
||||
│ Subagent │
|
||||
│ (subagent_type) │
|
||||
└─────────────────────────┘
|
||||
│
|
||||
@@ -80,21 +80,21 @@ The weather system consists of slash commands and specialized agents that work t
|
||||
|
||||
## Component Details
|
||||
|
||||
### 1. Slash Commands
|
||||
### 1. Skills and Commands
|
||||
|
||||
#### `/weather`
|
||||
#### `/weather` (Command)
|
||||
- **Location**: `.claude/commands/weather.md`
|
||||
- **Purpose**: Entry point for weather operations
|
||||
- **Action**: Calls `/weather-karachi` command
|
||||
- **Action**: Invokes `weather-karachi` skill via Skill tool
|
||||
- **Model**: haiku
|
||||
|
||||
#### `/weather-karachi`
|
||||
- **Location**: `.claude/commands/weather-karachi.md`
|
||||
#### `/weather-karachi` (Skill)
|
||||
- **Location**: `.claude/skills/weather-karachi/SKILL.md`
|
||||
- **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
|
||||
|
||||
### 2. Specialized Agents
|
||||
### 2. Specialized Subagents
|
||||
|
||||
#### `weather-fetcher`
|
||||
- **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`
|
||||
- **Purpose**: Stores transformation rules
|
||||
- **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`
|
||||
- **Purpose**: Stores formatted transformation results
|
||||
@@ -127,11 +127,11 @@ The weather system consists of slash commands and specialized agents that work t
|
||||
|
||||
## Execution Flow
|
||||
|
||||
1. **User Invocation**: User runs `/weather` command
|
||||
2. **Command Delegation**: `/weather` delegates to `/weather-karachi`
|
||||
3. **Sequential Agent Execution**:
|
||||
- **Step 1**: `weather-fetcher` agent fetches current temperature from wttr.in
|
||||
- **Step 2**: `weather-transformer` agent:
|
||||
1. **User Invocation**: User runs `/weather` command or `/weather-karachi` skill
|
||||
2. **Skill Invocation**: `/weather` invokes `weather-karachi` skill via Skill tool
|
||||
3. **Sequential Subagent Execution** (via Task tool):
|
||||
- **Step 1**: `weather-fetcher` subagent fetches current temperature from wttr.in
|
||||
- **Step 2**: `weather-transformer` subagent:
|
||||
- Reads transformation rules from `input/input.md`
|
||||
- Applies rules to the fetched temperature
|
||||
- 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
|
||||
├─ Calls: /weather-karachi
|
||||
│ ├─ Agent: weather-fetcher
|
||||
├─ Invokes: weather-karachi skill (via Skill tool)
|
||||
│ ├─ Subagent: weather-fetcher (via Task tool)
|
||||
│ │ └─ Result: 26°C
|
||||
│ ├─ Agent: weather-transformer
|
||||
│ ├─ Subagent: weather-transformer (via Task tool)
|
||||
│ │ ├─ Reads: input/input.md ("add +10")
|
||||
│ │ ├─ Calculates: 26 + 10 = 36°C
|
||||
│ │ └─ Writes: output/output.md
|
||||
@@ -160,8 +160,8 @@ Input: /weather
|
||||
## Key Design Principles
|
||||
|
||||
1. **Separation of Concerns**: Each component has a single, clear responsibility
|
||||
2. **Sequential Execution**: Agents run in order to ensure data dependencies are met
|
||||
3. **Specialized Agents**: Task-specific agents with minimal tool access
|
||||
4. **Command Chaining**: Simple commands can delegate to more complex workflows
|
||||
2. **Sequential Execution**: Subagents run in order to ensure data dependencies are met
|
||||
3. **Specialized Subagents**: Task-specific subagents with minimal tool access
|
||||
4. **Skill-Based Architecture**: Skills orchestrate workflows, subagents execute tasks
|
||||
5. **Configurable Transformations**: Rules stored externally in input files
|
||||
6. **Structured Output**: Results formatted consistently in output files
|
||||
+2
-2
@@ -1,3 +1,3 @@
|
||||
Original Temperature: 22°C
|
||||
Original Temperature: 24°C
|
||||
Transformation Applied: add +10 in the result
|
||||
Final Result: 32°C
|
||||
Final Result: 34°C
|
||||
|
||||
Reference in New Issue
Block a user