From 7dba1d44e80a1edb256762a1ad44cd1bc6d59ddb Mon Sep 17 00:00:00 2001 From: Shayan Rais Date: Wed, 28 Jan 2026 15:23:42 +0500 Subject: [PATCH] [] architecture changes --- .claude/agents/weather-fetcher.md | 42 --- .claude/agents/weather-transformer.md | 50 --- .claude/agents/weather.md | 52 +++ .claude/commands/weather-orchestrator.md | 43 +++ .claude/commands/weather.md | 14 - .claude/skills/weather-fetcher/SKILL.md | 36 +++ .claude/skills/weather-karachi/SKILL.md | 54 ---- .claude/skills/weather-transformer/SKILL.md | 54 ++++ CLAUDE.md | 12 +- docs/AGENTS.md | 137 -------- docs/COMPARISION.md | 337 -------------------- docs/weather-flow-architecture.md | 225 +++++++------ input/input.md | 2 +- output/output.md | 16 +- 14 files changed, 329 insertions(+), 745 deletions(-) delete mode 100644 .claude/agents/weather-fetcher.md delete mode 100644 .claude/agents/weather-transformer.md create mode 100644 .claude/agents/weather.md create mode 100644 .claude/commands/weather-orchestrator.md delete mode 100644 .claude/commands/weather.md create mode 100644 .claude/skills/weather-fetcher/SKILL.md delete mode 100644 .claude/skills/weather-karachi/SKILL.md create mode 100644 .claude/skills/weather-transformer/SKILL.md delete mode 100644 docs/AGENTS.md delete mode 100644 docs/COMPARISION.md diff --git a/.claude/agents/weather-fetcher.md b/.claude/agents/weather-fetcher.md deleted file mode 100644 index c780be5..0000000 --- a/.claude/agents/weather-fetcher.md +++ /dev/null @@ -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 diff --git a/.claude/agents/weather-transformer.md b/.claude/agents/weather-transformer.md deleted file mode 100644 index 067fd31..0000000 --- a/.claude/agents/weather-transformer.md +++ /dev/null @@ -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 diff --git a/.claude/agents/weather.md b/.claude/agents/weather.md new file mode 100644 index 0000000..d9d3cf5 --- /dev/null +++ b/.claude/agents/weather.md @@ -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 diff --git a/.claude/commands/weather-orchestrator.md b/.claude/commands/weather-orchestrator.md new file mode 100644 index 0000000..c94ff03 --- /dev/null +++ b/.claude/commands/weather-orchestrator.md @@ -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) diff --git a/.claude/commands/weather.md b/.claude/commands/weather.md deleted file mode 100644 index acb5b34..0000000 --- a/.claude/commands/weather.md +++ /dev/null @@ -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") -``` diff --git a/.claude/skills/weather-fetcher/SKILL.md b/.claude/skills/weather-fetcher/SKILL.md new file mode 100644 index 0000000..aea4558 --- /dev/null +++ b/.claude/skills/weather-fetcher/SKILL.md @@ -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 diff --git a/.claude/skills/weather-karachi/SKILL.md b/.claude/skills/weather-karachi/SKILL.md deleted file mode 100644 index b8e1465..0000000 --- a/.claude/skills/weather-karachi/SKILL.md +++ /dev/null @@ -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) diff --git a/.claude/skills/weather-transformer/SKILL.md b/.claude/skills/weather-transformer/SKILL.md new file mode 100644 index 0000000..1ca35d7 --- /dev/null +++ b/.claude/skills/weather-transformer/SKILL.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 diff --git a/CLAUDE.md b/CLAUDE.md index b2fd8e8..6e5b27a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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//SKILL.md` use YAML frontmatter: diff --git a/docs/AGENTS.md b/docs/AGENTS.md deleted file mode 100644 index 0611a11..0000000 --- a/docs/AGENTS.md +++ /dev/null @@ -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//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//SKILL.md` | Orchestrate workflows, reusable procedures | `/skill-name` or `Skill(skill="name")` | -| **Command** | `.claude/commands/.md` | Legacy format (still works), simple procedures | `/command-name` | -| **Subagent** | `.claude/agents/.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. diff --git a/docs/COMPARISION.md b/docs/COMPARISION.md deleted file mode 100644 index ae5b178..0000000 --- a/docs/COMPARISION.md +++ /dev/null @@ -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"
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"
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"
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?"
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 - -1. Task(subagent_type="weather-fetcher", ...) -2. Task(subagent_type="weather-transformer", ...) -``` - -**Command Invoking Skill:** -```markdown - -Skill(skill="weather-karachi") -``` - -**Subagent Orchestrating Other Subagents:** -```markdown - -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 - diff --git a/docs/weather-flow-architecture.md b/docs/weather-flow-architecture.md index 73ce340..a0c28a2 100644 --- a/docs/weather-flow-architecture.md +++ b/docs/weather-flow-architecture.md @@ -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 diff --git a/input/input.md b/input/input.md index f3c93b8..09bb87a 100644 --- a/input/input.md +++ b/input/input.md @@ -1 +1 @@ -add +10 in the result. \ No newline at end of file +add +20 in the result. \ No newline at end of file diff --git a/output/output.md b/output/output.md index 73d4a28..bd67070 100644 --- a/output/output.md +++ b/output/output.md @@ -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