[] architecture changes
This commit is contained in:
Shayan Rais
@@ -1,42 +0,0 @@
|
||||
---
|
||||
name: weather-fetcher
|
||||
description: Use this agent PROACTIVELY when you need to fetch current weather temperature data for Karachi, Pakistan. This agent specializes in retrieving real-time temperature from wttr.in API and returning the Celsius value. Invoke automatically when weather data retrieval is requested.
|
||||
tools: WebFetch
|
||||
model: haiku
|
||||
color: red
|
||||
---
|
||||
|
||||
# Weather Fetcher Agent
|
||||
|
||||
You are a specialized weather fetching agent that retrieves current weather data for Karachi, Pakistan.
|
||||
|
||||
## Your Task
|
||||
|
||||
Fetch the current temperature for Karachi, Pakistan in degrees Celsius (Centigrade) and return it in your final report.
|
||||
|
||||
## Instructions
|
||||
|
||||
1. **Fetch Weather Data**: Use the WebFetch tool to get current weather data for Karachi from wttr.in API:
|
||||
- URL: `https://wttr.in/Karachi?format=j1`
|
||||
- This returns JSON format weather data
|
||||
|
||||
2. **Extract Temperature**: From the JSON response, extract the current temperature in Celsius from the `current_condition` section.
|
||||
|
||||
3. **Return Result**: In your final report, provide:
|
||||
- The current temperature value in Celsius
|
||||
- A brief status message
|
||||
- The raw data for reference
|
||||
|
||||
## Expected Output Format
|
||||
|
||||
Your final report should include:
|
||||
```
|
||||
Current Karachi Temperature: [X]°C
|
||||
Status: Successfully fetched weather data
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- Only fetch the temperature, do not perform any transformations
|
||||
- Use wttr.in as it provides reliable, free weather data
|
||||
- Return just the numeric temperature value clearly
|
||||
@@ -1,50 +0,0 @@
|
||||
---
|
||||
name: weather-transformer
|
||||
description: Use this agent PROACTIVELY when you need to apply mathematical transformations to temperature data. This agent reads transformation rules from input/input.md, applies them to the provided temperature, and writes formatted results to output/output.md. Invoke automatically when temperature transformation or modification is needed.
|
||||
tools: Read, Write
|
||||
model: haiku
|
||||
color: blue
|
||||
---
|
||||
|
||||
# Weather Transformer Agent
|
||||
|
||||
You are a specialized weather transformation agent that applies mathematical transformations to weather data.
|
||||
|
||||
## Your Task
|
||||
|
||||
You will receive a temperature value and must:
|
||||
1. Read transformation instructions from `input/input.md`
|
||||
2. Apply the transformation to the temperature
|
||||
3. Write the final result to `output/output.md`
|
||||
|
||||
## Instructions
|
||||
|
||||
1. **Read Transformation Rules**: Use the Read tool to read `input/input.md` which contains the transformation instructions.
|
||||
|
||||
2. **Apply Transformation**: Apply the transformation rule to the temperature value provided to you.
|
||||
- Example: If instruction says "add +10", add 10 to the temperature
|
||||
- Example: If instruction says "multiply by 2", multiply temperature by 2
|
||||
|
||||
3. **Write Output**: Use the Write tool to save the transformed result to `output/output.md` with proper formatting.
|
||||
|
||||
## Expected Input
|
||||
|
||||
You will receive the temperature value from the weather-fetcher agent in the format:
|
||||
```
|
||||
Temperature: [X]°C
|
||||
```
|
||||
|
||||
## Expected Output
|
||||
|
||||
Write to `output/output.md` with format:
|
||||
```
|
||||
Original Temperature: [X]°C
|
||||
Transformation Applied: [description]
|
||||
Final Result: [Y]°C
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- Read the exact transformation from input/input.md - don't assume
|
||||
- Show your work: include original value, transformation, and result
|
||||
- Ensure output/output.md is properly formatted and readable
|
||||
@@ -0,0 +1,52 @@
|
||||
---
|
||||
name: weather
|
||||
description: Use this agent PROACTIVELY when you need to fetch and transform weather data for Karachi, Pakistan. This agent fetches real-time temperature from wttr.in API and applies transformation rules from input/input.md, writing results to output/output.md.
|
||||
tools: WebFetch, Read, Write
|
||||
model: haiku
|
||||
color: green
|
||||
skills:
|
||||
- weather-fetcher
|
||||
- weather-transformer
|
||||
---
|
||||
|
||||
# Weather Agent
|
||||
|
||||
You are a specialized weather agent that fetches and transforms weather data for Karachi, Pakistan.
|
||||
|
||||
## Your Task
|
||||
|
||||
Execute the weather workflow by following the instructions from your preloaded skills sequentially:
|
||||
|
||||
1. **First**: Follow the `weather-fetcher` skill instructions to fetch the current temperature
|
||||
2. **Then**: Follow the `weather-transformer` skill instructions to apply transformations and write results
|
||||
|
||||
## Workflow
|
||||
|
||||
### Step 1: Fetch Temperature (weather-fetcher skill)
|
||||
|
||||
Follow the weather-fetcher skill instructions to:
|
||||
- Fetch current temperature from wttr.in API for Karachi
|
||||
- Extract the temperature value in Celsius
|
||||
- Keep this value for the transformation step
|
||||
|
||||
### Step 2: Transform Temperature (weather-transformer skill)
|
||||
|
||||
Follow the weather-transformer skill instructions to:
|
||||
- Read transformation rules from `input/input.md`
|
||||
- Apply the transformation to the fetched temperature
|
||||
- Write formatted results to `output/output.md`
|
||||
|
||||
## Final Report
|
||||
|
||||
After completing both steps, provide a summary:
|
||||
- Temperature unit: Celsius
|
||||
- Original temperature fetched
|
||||
- Transformation rule applied
|
||||
- Final transformed result
|
||||
- Confirmation that output was written to `output/output.md`
|
||||
|
||||
## Critical Requirements
|
||||
|
||||
1. **Sequential Execution**: Complete the fetcher step before starting the transformer step
|
||||
2. **Use Your Skills**: The skill content is preloaded - follow those instructions
|
||||
3. **Data Flow**: Pass the temperature from step 1 to step 2
|
||||
@@ -0,0 +1,43 @@
|
||||
---
|
||||
description: Fetch and transform weather data for Karachi
|
||||
model: haiku
|
||||
---
|
||||
|
||||
# Weather Orchestrator 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 agent to fetch and transform the temperature data
|
||||
|
||||
## Agent Invocation
|
||||
|
||||
Use the Task tool to invoke the weather agent. This agent has two skills preloaded:
|
||||
- `weather-fetcher`: Fetches current temperature from wttr.in API
|
||||
- `weather-transformer`: Applies transformation rules and writes results
|
||||
|
||||
### Invoke Weather Agent
|
||||
|
||||
Use the Task tool to invoke the weather agent:
|
||||
- subagent_type: weather
|
||||
- description: Fetch and transform Karachi weather
|
||||
- prompt: Fetch the current temperature for Karachi, Pakistan in [unit requested by user]. Then apply the transformation rules from input/input.md and write the results to output/output.md. The agent has preloaded skills (weather-fetcher and weather-transformer) that provide the detailed instructions.
|
||||
- model: haiku
|
||||
|
||||
Wait for the agent to complete its workflow.
|
||||
|
||||
## Critical Requirements
|
||||
|
||||
1. **Use Task Tool Only**: DO NOT use bash commands to invoke agents. You must use the Task tool.
|
||||
2. **Single Agent**: The weather agent handles both fetching and transformation using its preloaded skills.
|
||||
3. **Pass User Preference**: Include the user's temperature unit preference in the 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)
|
||||
@@ -1,14 +0,0 @@
|
||||
---
|
||||
description: Fetch and transform weather data for Karachi
|
||||
model: haiku
|
||||
---
|
||||
|
||||
# Weather Command
|
||||
|
||||
Execute the weather-karachi skill to fetch and transform temperature data.
|
||||
|
||||
Use the Skill tool to execute the `weather-karachi` skill:
|
||||
|
||||
```
|
||||
Skill(skill="weather-karachi")
|
||||
```
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
name: weather-fetcher
|
||||
description: Instructions for fetching current weather temperature data for Karachi, Pakistan from wttr.in API
|
||||
---
|
||||
|
||||
# Weather Fetcher Skill
|
||||
|
||||
This skill provides instructions for fetching current weather data.
|
||||
|
||||
## Task
|
||||
|
||||
Fetch the current temperature for Karachi, Pakistan in degrees Celsius (Centigrade).
|
||||
|
||||
## Instructions
|
||||
|
||||
1. **Fetch Weather Data**: Use the WebFetch tool to get current weather data for Karachi from wttr.in API:
|
||||
- URL: `https://wttr.in/Karachi?format=j1`
|
||||
- This returns JSON format weather data
|
||||
|
||||
2. **Extract Temperature**: From the JSON response, extract the current temperature in Celsius from the `current_condition` section.
|
||||
|
||||
3. **Store Result**: Keep the temperature value for the next step (transformation).
|
||||
|
||||
## Expected Output
|
||||
|
||||
After completing this skill's instructions:
|
||||
```
|
||||
Current Karachi Temperature: [X]°C
|
||||
Status: Successfully fetched weather data
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- Only fetch the temperature, do not perform any transformations yet
|
||||
- Use wttr.in as it provides reliable, free weather data
|
||||
- Return just the numeric temperature value clearly
|
||||
@@ -1,54 +0,0 @@
|
||||
---
|
||||
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)
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
name: weather-transformer
|
||||
description: Instructions for applying mathematical transformations to temperature data based on rules in input/input.md
|
||||
---
|
||||
|
||||
# Weather Transformer Skill
|
||||
|
||||
This skill provides instructions for transforming temperature data.
|
||||
|
||||
## Task
|
||||
|
||||
Apply mathematical transformations to a temperature value and write results to output file.
|
||||
|
||||
## Instructions
|
||||
|
||||
1. **Read Transformation Rules**: Use the Read tool to read `input/input.md` which contains the transformation instructions.
|
||||
|
||||
2. **Apply Transformation**: Apply the transformation rule to the temperature value.
|
||||
- Example: If instruction says "add +10", add 10 to the temperature
|
||||
- Example: If instruction says "multiply by 2", multiply temperature by 2
|
||||
|
||||
3. **Write Output**: Use the Write tool to save the transformed result to `output/output.md` with proper formatting.
|
||||
|
||||
## Expected Input
|
||||
|
||||
The temperature value from the weather-fetcher skill:
|
||||
```
|
||||
Temperature: [X]°C
|
||||
```
|
||||
|
||||
## Expected Output
|
||||
|
||||
Write to `output/output.md` with format:
|
||||
```markdown
|
||||
# Weather Transformation Result
|
||||
|
||||
## Original Temperature
|
||||
[X]°C
|
||||
|
||||
## Transformation Applied
|
||||
[description from input/input.md]
|
||||
|
||||
## Final Result
|
||||
[Y]°C
|
||||
|
||||
## Calculation Details
|
||||
[X]°C [operation] = [Y]°C
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- Read the exact transformation from input/input.md - don't assume
|
||||
- Show your work: include original value, transformation, and result
|
||||
- Ensure output/output.md is properly formatted and readable
|
||||
@@ -9,13 +9,13 @@ This is a best practices repository for Claude Code configuration, demonstrating
|
||||
## Key Components
|
||||
|
||||
### Weather System (Example Workflow)
|
||||
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`
|
||||
A demonstration of the **Command → Agent → Skills** architecture pattern:
|
||||
- `/weather-orchestrator` command (`.claude/commands/weather-orchestrator.md`): Entry point that invokes the weather agent
|
||||
- `weather` agent (`.claude/agents/weather.md`): Executes workflow using preloaded skills
|
||||
- `weather-fetcher` skill (`.claude/skills/weather-fetcher/SKILL.md`): Instructions for fetching temperature from wttr.in API
|
||||
- `weather-transformer` skill (`.claude/skills/weather-transformer/SKILL.md`): Instructions for applying transformation rules from `input/input.md`, writes results to `output/output.md`
|
||||
|
||||
Subagents run sequentially via Task tool, not in parallel, to maintain data dependencies.
|
||||
The agent has skills preloaded via the `skills` field, providing domain knowledge for sequential execution.
|
||||
|
||||
### Skill Definition Structure
|
||||
Skills in `.claude/skills/<name>/SKILL.md` use YAML frontmatter:
|
||||
|
||||
-137
@@ -1,137 +0,0 @@
|
||||
# Subagent Orchestration Best Practices
|
||||
|
||||
## Problem: Subagents Not Invoking
|
||||
|
||||
### Issue Description
|
||||
|
||||
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 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. 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 skill with proper instructions:**
|
||||
|
||||
Skills (in `.claude/skills/<name>/SKILL.md`) orchestrate workflows by invoking subagents via the Task tool:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: weather-karachi
|
||||
description: Fetch and transform weather data for Karachi
|
||||
model: haiku
|
||||
---
|
||||
```
|
||||
|
||||
2. **Use the Task tool properly in the skill's 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: 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 Celsius 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.
|
||||
```
|
||||
|
||||
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 subagents."
|
||||
|
||||
b. **Parameter Specification**: List all required parameters explicitly:
|
||||
- `subagent_type`: The exact subagent name
|
||||
- `description`: A short 3-5 word description
|
||||
- `prompt`: Detailed instructions for the subagent
|
||||
- `model`: The model to use (typically "haiku" for efficiency)
|
||||
|
||||
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 subagent's report and pass it to the next subagent's prompt.
|
||||
|
||||
### Before and After Comparison
|
||||
|
||||
#### Before (Broken):
|
||||
```markdown
|
||||
## Your Task
|
||||
|
||||
1. **Launch weather-fetcher agent**: Use the Task tool to launch the weather-fetcher agent
|
||||
- This agent will fetch the current temperature for Karachi, Pakistan in Celsius
|
||||
- Wait for the agent to complete and capture the temperature value from its report
|
||||
```
|
||||
|
||||
**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: 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 Celsius 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.
|
||||
|
||||
## Critical Requirements
|
||||
|
||||
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:**
|
||||
- Explicitly lists all Task tool parameters
|
||||
- Clearly states NOT to use bash commands
|
||||
- Provides specific parameter values
|
||||
|
||||
### Testing the Fix
|
||||
|
||||
After creating the skill, test it by invoking:
|
||||
|
||||
```bash
|
||||
# Via skill invocation
|
||||
/weather-karachi
|
||||
|
||||
# Or via Skill tool from another command
|
||||
Skill(skill="weather-karachi")
|
||||
```
|
||||
|
||||
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
|
||||
4. Report the complete workflow results
|
||||
|
||||
### Key Takeaways
|
||||
|
||||
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 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 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.
|
||||
@@ -1,337 +0,0 @@
|
||||
# COMPARISION
|
||||
commands, agents, skill
|
||||
|
||||
# Invocation Patterns Reference
|
||||
|
||||
This document provides a comprehensive reference for invoking Agents, Commands, and Skills across different contexts.
|
||||
|
||||
## Agent Invocation
|
||||
|
||||
Agents are specialized subprocesses that handle complex, multi-step tasks. They support both **automatic delegation** (proactive) and **explicit invocation**.
|
||||
|
||||
### Invocation Methods
|
||||
|
||||
| From | How | Example | Notes |
|
||||
|----------------------|------------------------|-------------------------------------|-------|
|
||||
| Claude CLI | **Automatic (proactive)** | User: "I just modified the auth code"<br/>Claude auto-invokes code-review agent | Requires "PROACTIVELY" keyword in agent description |
|
||||
| Claude CLI | Explicit natural language | "use weather transformer agent to transform 50 degree" | Direct request by name |
|
||||
| /commands/Commands.md| Task tool | `Task(subagent_type="weather-transformer", description="Transform temperature", prompt="Apply transformation to 50°C", model="haiku")` | Programmatic invocation from commands |
|
||||
| Another subagent | Task tool | `Task(subagent_type="weather-fetcher", description="Fetch temperature", prompt="Get Karachi temperature", model="haiku")` | Agent-to-agent orchestration |
|
||||
|
||||
### Automatic Delegation (Proactive Agents)
|
||||
|
||||
Agents can be configured for **automatic invocation** by Claude based on context. Claude analyzes:
|
||||
- Your task description and request
|
||||
- Each agent's `description` field
|
||||
- Current context and available tools
|
||||
|
||||
**To enable automatic delegation**, include directive keywords in the agent's `description` field:
|
||||
- `"use PROACTIVELY"`
|
||||
- `"MUST BE USED"`
|
||||
- `"Invoke automatically"`
|
||||
|
||||
**Example: Proactive Code Review Agent**
|
||||
```yaml
|
||||
---
|
||||
name: code-reviewer
|
||||
description: Use this agent PROACTIVELY after any code modifications. Expert code reviewer that analyzes quality, security, and maintainability. Invoke automatically when code is written or modified.
|
||||
tools: Read, Grep, Bash
|
||||
model: haiku
|
||||
---
|
||||
```
|
||||
|
||||
**Result**: When you modify code, Claude automatically invokes `code-reviewer` without explicit request.
|
||||
|
||||
**Example: Proactive Test Agent**
|
||||
```yaml
|
||||
---
|
||||
name: test-runner
|
||||
description: MUST BE USED when tests fail or new code is added. Automatically runs tests and fixes failures.
|
||||
tools: Bash, Read, Edit
|
||||
model: haiku
|
||||
---
|
||||
```
|
||||
|
||||
**Result**: Claude proactively runs tests after code changes.
|
||||
|
||||
## Command Invocation
|
||||
|
||||
Commands (slash commands) are user-defined operations that extend Claude Code with reusable prompts. They support both **automatic invocation** (by default) and **explicit activation**.
|
||||
|
||||
### Invocation Methods
|
||||
|
||||
| From | How | Example | Notes |
|
||||
|----------------------|------------------------|-------------------------------------|-------|
|
||||
| Claude CLI | **Automatic (default)** | User: "I need to write unit tests"<br/>Claude auto-invokes `/write-unit-test` if description matches | Requires `description` field; can disable with `disable-model-invocation: true` |
|
||||
| Claude CLI | Natural language prompt | "use the weather command to fetch the weather" | Claude interprets and expands command |
|
||||
| Claude CLI | Explicit slash command | `/weather-karachi` | Direct command execution |
|
||||
| /agents/Agents.md | SlashCommand tool | `SlashCommand(command="/weather-karachi")` | Commands invoked from agents |
|
||||
| Another /command | SlashCommand tool | `SlashCommand(command="/weather-karachi")` | Command chaining |
|
||||
|
||||
### Automatic Command Invocation
|
||||
|
||||
By default, Claude can **automatically invoke slash commands** through the SlashCommand tool when contextually appropriate. This works similarly to proactive agents.
|
||||
|
||||
**How it works:**
|
||||
- Commands with a `description` field are included in Claude's context
|
||||
- Claude analyzes your request and matches it against available command descriptions
|
||||
- If a match is found, Claude automatically invokes the command via SlashCommand tool
|
||||
|
||||
**To enable automatic invocation**, ensure your command has a clear `description`:
|
||||
```yaml
|
||||
---
|
||||
description: Writes comprehensive unit tests for the specified function or module
|
||||
model: haiku
|
||||
---
|
||||
```
|
||||
|
||||
**To disable automatic invocation** for a specific command:
|
||||
```yaml
|
||||
---
|
||||
description: Administrative command for system configuration
|
||||
disable-model-invocation: true
|
||||
model: haiku
|
||||
---
|
||||
```
|
||||
|
||||
**Example: Auto-invoked Test Command**
|
||||
```yaml
|
||||
---
|
||||
description: Generates and runs unit tests for new code. Use when user adds new functions or asks about testing.
|
||||
model: haiku
|
||||
---
|
||||
```
|
||||
|
||||
**Result**: When you say "I added a new login function", Claude may automatically invoke this command.
|
||||
|
||||
**Global Control**: Use `/permissions` to disable the SlashCommand tool entirely, preventing all automatic command execution.
|
||||
|
||||
## Skill Invocation
|
||||
|
||||
Skills are model-invoked capabilities that Claude activates automatically based on context. Unlike agents and commands, skills cannot be explicitly invoked.
|
||||
|
||||
| From | How | Example | Notes |
|
||||
|----------------------|------------------------|-------------------------------------|-------|
|
||||
| Claude CLI | Automatic (model-driven) | User: "Extract text from this PDF"<br/>Claude autonomously activates PDF skill | No explicit invocation - Claude decides based on Skill description |
|
||||
| Claude CLI | Natural language prompt | "Can you help me analyze this Excel file?"<br/>Claude may invoke Excel skill if available | Context-dependent activation |
|
||||
| /agents/Agents.md | Skill tool | `Skill(command="pdf")` | **Only if agent has Skill tool access** |
|
||||
| Another /command | Skill tool | `Skill(command="xlsx")` | **Only if command prompt includes Skill tool access** |
|
||||
| Another skill | N/A | Skills cannot invoke other skills | Skills are single-purpose and don't orchestrate |
|
||||
|
||||
### Key Differences: Skills vs Agents vs Commands
|
||||
|
||||
| Feature | Agent | Command | Skill |
|
||||
|----------------------|------------------------|------------------------|------------------------|
|
||||
| **Invocation** | **Both**: Automatic (with PROACTIVELY keyword) OR Explicit (Task tool/prompt) | **Both**: Automatic (default, via SlashCommand tool) OR Explicit (slash syntax) | Automatic only (model-driven) |
|
||||
| **User Activation** | Contextual (if proactive) OR "Use X agent" | Contextual (default) OR `/command-name` | Contextual request only |
|
||||
| **Discoverability** | Automatic via description (if proactive) OR user must know name | Automatic via description (default) | Automatic via description |
|
||||
| **Orchestration** | Can invoke other agents/commands | Can invoke agents/commands | Single-purpose, no orchestration |
|
||||
| **Configuration** | Use `PROACTIVELY` keyword in description for auto-invocation | `disable-model-invocation: true` to prevent auto-invocation | Description determines when to activate |
|
||||
| **Opt-Out** | Don't use PROACTIVELY keyword | Set `disable-model-invocation: true` | No opt-out mechanism |
|
||||
| **Best For** | Multi-step workflows | Reusable procedures | Ambient capabilities |
|
||||
|
||||
## Invocation Examples by Scenario
|
||||
|
||||
### Scenario 1: User Wants Weather Data
|
||||
|
||||
**Using Skill (Explicit):**
|
||||
```
|
||||
User: /weather-karachi
|
||||
Result: Explicit skill execution → subagents run → output generated
|
||||
```
|
||||
|
||||
**Using Skill (Automatic - Default Behavior):**
|
||||
```yaml
|
||||
# Skill configuration with description (automatic invocation enabled by default)
|
||||
# Location: .claude/skills/weather-karachi/SKILL.md
|
||||
---
|
||||
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 skill via Skill tool
|
||||
Note: Skills are auto-invoked by default unless disable-model-invocation: true is set
|
||||
```
|
||||
|
||||
**Using Subagent (Explicit):**
|
||||
```
|
||||
User: "Use the weather-fetcher agent to get Karachi temperature"
|
||||
Result: Claude invokes weather-fetcher subagent → returns temperature
|
||||
```
|
||||
|
||||
**Using Subagent (Automatic/Proactive):**
|
||||
```yaml
|
||||
# Subagent configuration with PROACTIVELY keyword
|
||||
---
|
||||
description: Use this agent PROACTIVELY when user asks about Karachi weather.
|
||||
Fetch current temperature from wttr.in.
|
||||
---
|
||||
```
|
||||
```
|
||||
User: "What's the weather like in Karachi?"
|
||||
Result: Claude automatically invokes weather-fetcher subagent → returns temperature
|
||||
Note: Subagent description contains "PROACTIVELY" keyword
|
||||
```
|
||||
|
||||
**Using Command (Legacy):**
|
||||
```
|
||||
User: /weather
|
||||
Result: Command invokes weather-karachi skill via Skill tool
|
||||
Note: Commands still work but skills are recommended
|
||||
```
|
||||
|
||||
### Scenario 2: Orchestrating Multiple Steps
|
||||
|
||||
**Skill Orchestrating Subagents:**
|
||||
```markdown
|
||||
<!-- In .claude/skills/weather-karachi/SKILL.md -->
|
||||
1. Task(subagent_type="weather-fetcher", ...)
|
||||
2. Task(subagent_type="weather-transformer", ...)
|
||||
```
|
||||
|
||||
**Command Invoking Skill:**
|
||||
```markdown
|
||||
<!-- 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}", ...)
|
||||
```
|
||||
|
||||
### Scenario 3: Automatic Agent Invocation (Real-World)
|
||||
|
||||
**Proactive Code Review Agent:**
|
||||
```yaml
|
||||
---
|
||||
name: code-reviewer
|
||||
description: Use this agent PROACTIVELY after any code modifications. Reviews for quality, security, and best practices.
|
||||
tools: Read, Grep, Bash
|
||||
---
|
||||
```
|
||||
|
||||
**User Workflow:**
|
||||
```
|
||||
User: "I've updated the authentication logic in auth.ts"
|
||||
Claude: Automatically invokes code-reviewer agent
|
||||
Agent: Reads auth.ts, analyzes changes, reports findings
|
||||
User: Gets automatic code review without asking for it
|
||||
```
|
||||
|
||||
**Proactive Test Runner Agent:**
|
||||
```yaml
|
||||
---
|
||||
name: test-runner
|
||||
description: MUST BE USED when code is modified or tests fail. Automatically runs tests and reports results.
|
||||
tools: Bash, Read
|
||||
---
|
||||
```
|
||||
|
||||
**User Workflow:**
|
||||
```
|
||||
User: "I fixed the login bug"
|
||||
Claude: Automatically invokes test-runner agent
|
||||
Agent: Runs test suite, reports pass/fail status
|
||||
User: Gets immediate test feedback
|
||||
```
|
||||
|
||||
### Scenario 4: From Within Code/Prompts
|
||||
|
||||
**Invoking Subagent from Skill:**
|
||||
```markdown
|
||||
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 Celsius
|
||||
- model: haiku
|
||||
```
|
||||
|
||||
**Invoking Skill from Command:**
|
||||
```markdown
|
||||
Use the Skill tool to execute the weather-karachi skill:
|
||||
Skill(skill="weather-karachi")
|
||||
```
|
||||
|
||||
**Invoking Skill from Another Skill:**
|
||||
```markdown
|
||||
Use the Skill tool to invoke a related skill:
|
||||
Skill(skill="data-processor")
|
||||
```
|
||||
|
||||
## Core Differences Between Commands and Agents
|
||||
|
||||
While commands and agents share similar invocation patterns, they have fundamental architectural differences:
|
||||
|
||||
### Key Architectural Differences
|
||||
|
||||
**1. Purpose & Complexity**
|
||||
- **Commands**: Reusable prompt templates that expand into instructions. Best for **procedural workflows** with predefined steps.
|
||||
- **Agents**: Autonomous subprocesses with their own tool access. Best for **complex, multi-step tasks** requiring independent decision-making.
|
||||
|
||||
**2. Execution Model**
|
||||
- **Commands**: Expand into prompts that Claude executes in the main conversation context
|
||||
- **Agents**: Run as separate subprocesses with isolated execution environments
|
||||
|
||||
**3. Tool Access**
|
||||
- **Commands**: Execute within the main Claude context and inherit available tools
|
||||
- **Agents**: Have explicitly defined tool subsets specified in their configuration (e.g., `tools: Read, Grep, Bash`)
|
||||
|
||||
**4. Autonomy Level**
|
||||
- **Commands**: Provide instructions for Claude to follow. Can interact with users via AskUserQuestion tool to gather preferences or clarify requirements.
|
||||
- **Agents**: Act autonomously to complete tasks and return final reports. **Should NOT ask questions** - they run independently and must work with the information provided in their prompt.
|
||||
|
||||
**5. Model Selection**
|
||||
- **Commands**: Can specify which model to use for executing the command
|
||||
- **Agents**: Can specify which model runs the agent subprocess (e.g., `model: haiku` for cost efficiency)
|
||||
|
||||
### When to Choose Each
|
||||
|
||||
**Choose Commands when:**
|
||||
- You have a reusable prompt/workflow
|
||||
- Steps are mostly predefined
|
||||
- You want users to trigger via `/slash` syntax
|
||||
- You need a simple procedural template
|
||||
|
||||
**Choose Agents when:**
|
||||
- Task requires autonomous multi-step problem solving
|
||||
- You need isolated tool access for security/organization
|
||||
- Task should run as independent subprocess
|
||||
- You want specialized capabilities (like code review, test running)
|
||||
|
||||
**Example from this repository:**
|
||||
- `/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 skill coordinates, while subagents execute their specialized tasks independently.
|
||||
|
||||
## Summary
|
||||
|
||||
- **Agents**: **Both automatic and explicit invocation**
|
||||
- Automatic: Use `PROACTIVELY` or `MUST BE USED` keywords in description field
|
||||
- Explicit: Via Task tool or natural language prompt
|
||||
|
||||
- **Commands**: **Both automatic (default) and explicit invocation**
|
||||
- Automatic: Enabled by default when `description` field is present
|
||||
- Explicit: Via slash syntax (`/command`) or SlashCommand tool
|
||||
- Opt-out: Set `disable-model-invocation: true` to prevent automatic invocation
|
||||
|
||||
- **Skills**: **Automatic invocation only** - Claude decides based on context and description
|
||||
- No explicit invocation mechanism
|
||||
- No opt-out available
|
||||
|
||||
- **Key Design Choices**:
|
||||
- Use **proactive agents** for complex multi-step workflows that should trigger automatically
|
||||
- Use **commands (with auto-invocation)** for reusable procedures that should activate contextually
|
||||
- Use **commands (with disable-model-invocation)** for workflows requiring strict explicit control
|
||||
- Use **skills** for ambient, always-available single-purpose capabilities
|
||||
- **Orchestration difference**: Agents and commands can orchestrate other agents/commands; skills are single-purpose
|
||||
|
||||
+124
-101
@@ -4,7 +4,10 @@ This document describes the complete flow of the weather data fetching and trans
|
||||
|
||||
## System Overview
|
||||
|
||||
The weather system consists of skills and specialized subagents that work together to fetch and transform temperature data for Karachi, Pakistan.
|
||||
The weather system demonstrates the **Command → Agent → Skills** architecture pattern, where:
|
||||
- A command orchestrates the workflow
|
||||
- An agent executes tasks using preloaded skills
|
||||
- Skills provide domain-specific knowledge and instructions
|
||||
|
||||
## Flow Diagram
|
||||
|
||||
@@ -14,108 +17,100 @@ The weather system consists of skills and specialized subagents that work togeth
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────┐
|
||||
│ /weather │
|
||||
│ Command │
|
||||
└──────────────────┘
|
||||
┌──────────────────────┐
|
||||
│ /weather-orchestrator│
|
||||
│ Command │
|
||||
│ (Entry point) │
|
||||
└──────────────────────┘
|
||||
│
|
||||
│ invokes via Skill tool
|
||||
│ Task tool invocation
|
||||
▼
|
||||
┌──────────────────┐
|
||||
│ /weather-karachi │
|
||||
│ Skill │
|
||||
└──────────────────┘
|
||||
┌──────────────────────┐
|
||||
│ weather │
|
||||
│ Agent │
|
||||
│ (Orchestrates flow) │
|
||||
│ │
|
||||
│ skills: │
|
||||
│ - weather-fetcher │
|
||||
│ - weather-transformer│
|
||||
└──────────────────────┘
|
||||
│
|
||||
│ Step 1 (Sequential via Task tool)
|
||||
▼
|
||||
┌────────────────────────┐
|
||||
│ weather-fetcher │
|
||||
│ Subagent │
|
||||
│ (subagent_type) │
|
||||
└────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌────────────────────────┐
|
||||
│ wttr.in API │
|
||||
│ Fetch Temperature │
|
||||
│ for Karachi │
|
||||
└────────────────────────┘
|
||||
│
|
||||
│ Returns: 26°C
|
||||
▼
|
||||
│
|
||||
│ Step 2 (Sequential via Task tool)
|
||||
▼
|
||||
┌─────────────────────────┐
|
||||
│ weather-transformer │
|
||||
│ Subagent │
|
||||
│ (subagent_type) │
|
||||
└─────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────┐
|
||||
│ input/input.md │
|
||||
│ Read Transform Rules │
|
||||
└─────────────────────────┘
|
||||
│
|
||||
│ Reads: "add +10"
|
||||
▼
|
||||
┌────────────────────────┐
|
||||
│ Apply Transform │
|
||||
│ 26 + 10 = 36°C │
|
||||
└────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌────────────────────────┐
|
||||
│ output/output.md │
|
||||
│ Write Results │
|
||||
└────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌────────────────────────┐
|
||||
│ Display Summary │
|
||||
│ to User │
|
||||
└────────────────────────┘
|
||||
┌───────────────┴───────────────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────────────────────┐ ┌─────────────────────────┐
|
||||
│ weather-fetcher │ │ weather-transformer │
|
||||
│ Skill │ │ Skill │
|
||||
│ (Preloaded knowledge) │ │ (Preloaded knowledge) │
|
||||
└─────────────────────────┘ └─────────────────────────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────────────────────┐ ┌─────────────────────────┐
|
||||
│ wttr.in API │ │ input/input.md │
|
||||
│ Fetch Temperature │ │ Read Transform Rules │
|
||||
│ for Karachi │ └─────────────────────────┘
|
||||
└─────────────────────────┘ │
|
||||
│ ▼
|
||||
│ Returns: 26°C ┌─────────────────────────┐
|
||||
│ │ Apply Transform │
|
||||
└─────────────────────│ 26 + 10 = 36°C │
|
||||
└─────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────┐
|
||||
│ output/output.md │
|
||||
│ Write Results │
|
||||
└─────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────┐
|
||||
│ Display Summary │
|
||||
│ to User │
|
||||
└─────────────────────────┘
|
||||
```
|
||||
|
||||
## Component Details
|
||||
|
||||
### 1. Skills and Commands
|
||||
### 1. Command
|
||||
|
||||
#### `/weather` (Command)
|
||||
- **Location**: `.claude/commands/weather.md`
|
||||
#### `/weather-orchestrator` (Command)
|
||||
- **Location**: `.claude/commands/weather-orchestrator.md`
|
||||
- **Purpose**: Entry point for weather operations
|
||||
- **Action**: Invokes `weather-karachi` skill via Skill tool
|
||||
- **Action**: Invokes the weather agent via Task tool
|
||||
- **Model**: haiku
|
||||
|
||||
#### `/weather-karachi` (Skill)
|
||||
- **Location**: `.claude/skills/weather-karachi/SKILL.md`
|
||||
- **Purpose**: Orchestrates the weather fetching and transformation workflow
|
||||
- **Action**: Launches two specialized subagents sequentially via Task tool
|
||||
### 2. Agent with Skills
|
||||
|
||||
#### `weather` (Agent)
|
||||
- **Location**: `.claude/agents/weather.md`
|
||||
- **Purpose**: Execute the weather workflow using preloaded skills
|
||||
- **Skills**: `weather-fetcher`, `weather-transformer`
|
||||
- **Tools Available**: WebFetch, Read, Write
|
||||
- **Model**: haiku
|
||||
- **Color**: green
|
||||
|
||||
### 2. Specialized Subagents
|
||||
The agent has skills preloaded into its context at startup. It follows the instructions from each skill sequentially.
|
||||
|
||||
#### `weather-fetcher`
|
||||
- **Location**: `.claude/agents/weather-fetcher.md`
|
||||
- **Purpose**: Fetch real-time temperature data
|
||||
### 3. Skills
|
||||
|
||||
#### `weather-fetcher` (Skill)
|
||||
- **Location**: `.claude/skills/weather-fetcher/SKILL.md`
|
||||
- **Purpose**: Instructions for fetching real-time temperature data
|
||||
- **Data Source**: wttr.in API for Karachi, Pakistan
|
||||
- **Output**: Temperature in Celsius (numeric value)
|
||||
- **Tools Available**: WebFetch
|
||||
|
||||
#### `weather-transformer`
|
||||
- **Location**: `.claude/agents/weather-transformer.md`
|
||||
- **Purpose**: Apply mathematical transformations to temperature data
|
||||
#### `weather-transformer` (Skill)
|
||||
- **Location**: `.claude/skills/weather-transformer/SKILL.md`
|
||||
- **Purpose**: Instructions for applying mathematical transformations
|
||||
- **Input Source**: `input/input.md` (transformation rules)
|
||||
- **Output Destination**: `output/output.md` (formatted results)
|
||||
- **Tools Available**: Read, Write
|
||||
|
||||
### 3. Data Files
|
||||
### 4. Data Files
|
||||
|
||||
#### `input/input.md`
|
||||
- **Purpose**: Stores transformation rules
|
||||
- **Format**: Natural language instructions (e.g., "add +10 in the result")
|
||||
- **Access**: Read by weather-transformer subagent
|
||||
- **Access**: Read by weather agent following weather-transformer skill
|
||||
|
||||
#### `output/output.md`
|
||||
- **Purpose**: Stores formatted transformation results
|
||||
@@ -127,15 +122,17 @@ The weather system consists of skills and specialized subagents that work togeth
|
||||
|
||||
## Execution Flow
|
||||
|
||||
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`
|
||||
4. **Result Display**: Summary shown to user with:
|
||||
1. **User Invocation**: User runs `/weather-orchestrator` command
|
||||
2. **User Prompt**: Command asks user for preferred temperature unit (Celsius/Fahrenheit)
|
||||
3. **Agent Invocation**: Command invokes weather agent via Task tool
|
||||
4. **Skill Execution** (within agent context):
|
||||
- **Step 1**: Agent follows `weather-fetcher` skill instructions to fetch temperature from wttr.in
|
||||
- **Step 2**: Agent follows `weather-transformer` skill instructions to:
|
||||
- Read transformation rules from `input/input.md`
|
||||
- Apply rules to the fetched temperature
|
||||
- Write formatted results to `output/output.md`
|
||||
5. **Result Display**: Summary shown to user with:
|
||||
- Temperature unit requested
|
||||
- Original temperature
|
||||
- Transformation rule applied
|
||||
- Final transformed result
|
||||
@@ -143,25 +140,51 @@ The weather system consists of skills and specialized subagents that work togeth
|
||||
## Example Execution
|
||||
|
||||
```
|
||||
Input: /weather
|
||||
├─ Invokes: weather-karachi skill (via Skill tool)
|
||||
│ ├─ Subagent: weather-fetcher (via Task tool)
|
||||
│ │ └─ Result: 26°C
|
||||
│ ├─ Subagent: weather-transformer (via Task tool)
|
||||
Input: /weather-orchestrator
|
||||
├─ Asks: Celsius or Fahrenheit?
|
||||
├─ User: Celsius
|
||||
├─ Task: weather agent (via Task tool)
|
||||
│ ├─ Skills Preloaded:
|
||||
│ │ ├─ weather-fetcher (knowledge)
|
||||
│ │ └─ weather-transformer (knowledge)
|
||||
│ ├─ Step 1 (weather-fetcher skill):
|
||||
│ │ └─ Fetches from wttr.in → 26°C
|
||||
│ ├─ Step 2 (weather-transformer skill):
|
||||
│ │ ├─ Reads: input/input.md ("add +10")
|
||||
│ │ ├─ Calculates: 26 + 10 = 36°C
|
||||
│ │ └─ Writes: output/output.md
|
||||
│ └─ Output:
|
||||
│ ├─ Original: 26°C
|
||||
│ ├─ Transform: Add +10
|
||||
│ └─ Result: 36°C
|
||||
│ └─ Returns: Complete report
|
||||
└─ Output:
|
||||
├─ Unit: Celsius
|
||||
├─ Original: 26°C
|
||||
├─ Transform: Add +10
|
||||
└─ Result: 36°C
|
||||
```
|
||||
|
||||
## Key Design Principles
|
||||
|
||||
1. **Separation of Concerns**: Each component has a single, clear responsibility
|
||||
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
|
||||
1. **Command → Agent → Skills**: Three-tier architecture for clean separation
|
||||
2. **Skills as Knowledge**: Skills provide domain knowledge preloaded into agent context
|
||||
3. **Single Agent**: One agent handles multiple related tasks using its skills
|
||||
4. **Sequential Execution**: Agent follows skill instructions in order
|
||||
5. **Configurable Transformations**: Rules stored externally in input files
|
||||
6. **Structured Output**: Results formatted consistently in output files
|
||||
|
||||
## Architecture Pattern: Agent-Skills
|
||||
|
||||
This system demonstrates the **agent-skills pattern** where:
|
||||
|
||||
```yaml
|
||||
# In agent definition (.claude/agents/weather.md)
|
||||
---
|
||||
name: weather
|
||||
skills:
|
||||
- weather-fetcher
|
||||
- weather-transformer
|
||||
---
|
||||
```
|
||||
|
||||
- **Skills are preloaded**: Full skill content is injected into agent's context at startup
|
||||
- **Agent uses skill knowledge**: Agent follows instructions from preloaded skills
|
||||
- **No dynamic invocation**: Skills are not invoked separately; they're reference material
|
||||
- **Single execution context**: All work happens within one agent's context
|
||||
|
||||
+1
-1
@@ -1 +1 @@
|
||||
add +10 in the result.
|
||||
add +20 in the result.
|
||||
+13
-3
@@ -1,3 +1,13 @@
|
||||
Original Temperature: 24°C
|
||||
Transformation Applied: add +10 in the result
|
||||
Final Result: 34°C
|
||||
# Weather Transformation Result
|
||||
|
||||
## Original Temperature
|
||||
24°C
|
||||
|
||||
## Transformation Applied
|
||||
Add +20 to the temperature value
|
||||
|
||||
## Final Result
|
||||
44°C
|
||||
|
||||
## Calculation Details
|
||||
24°C + 20 = 44°C
|
||||
|
||||
Reference in New Issue
Block a user