diff --git a/!/tags/best-practice.svg b/!/tags/best-practice.svg
new file mode 100644
index 0000000..d72cdea
--- /dev/null
+++ b/!/tags/best-practice.svg
@@ -0,0 +1,17 @@
+
\ No newline at end of file
diff --git a/!/tags/implemented-hd.svg b/!/tags/implemented-hd.svg
new file mode 100644
index 0000000..8be43d6
--- /dev/null
+++ b/!/tags/implemented-hd.svg
@@ -0,0 +1,32 @@
+
\ No newline at end of file
diff --git a/!/tags/implemented.svg b/!/tags/implemented.svg
new file mode 100644
index 0000000..a9c7856
--- /dev/null
+++ b/!/tags/implemented.svg
@@ -0,0 +1,17 @@
+
\ No newline at end of file
diff --git a/!/tags/orchestration-workflow-hd.svg b/!/tags/orchestration-workflow-hd.svg
new file mode 100644
index 0000000..a98d97d
--- /dev/null
+++ b/!/tags/orchestration-workflow-hd.svg
@@ -0,0 +1,32 @@
+
\ No newline at end of file
diff --git a/!/tags/orchestration-workflow.svg b/!/tags/orchestration-workflow.svg
new file mode 100644
index 0000000..22696e3
--- /dev/null
+++ b/!/tags/orchestration-workflow.svg
@@ -0,0 +1,17 @@
+
\ No newline at end of file
diff --git a/README.md b/README.md
index e364cc4..c519be5 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,10 @@
# claude-code-best-practice
practice makes claude perfect
-
-[](https://github.com/shanraisshan/claude-code-best-practice#my-experience) *Click on this badge to show the latest best practice*
-[](https://github.com/shanraisshan/claude-code-best-practice/tree/main/.claude/hooks) *Click on this badge to show implementation in this repo*
+
+[](https://github.com/shanraisshan/claude-code-best-practice#my-experience) *Click on this badge to show the latest best practice*
+[](https://github.com/shanraisshan/claude-code-best-practice/tree/main/.claude/hooks) *Click on this badge to show implementation in this repo*
+[](https://github.com/shanraisshan/claude-code-best-practice#orchestration-workflow) *Click on this badge to see the Command → Agent → Skills orchestration workflow*
@@ -23,7 +24,7 @@ practice makes claude perfect
|---------|----------|-------------|
| [**Skills**](https://code.claude.com/docs/en/skills) | `.claude/skills//SKILL.md` | Reusable knowledge, workflows, and slash commands — load on-demand or invoke with `/skill-name` |
| [**Commands**](https://code.claude.com/docs/en/skills) | `.claude/commands/.md` | Entry-point prompts for workflows — invoke with `/command-name` |
-| [**Sub-Agents**](https://code.claude.com/docs/en/sub-agents) | `.claude/agents/.md` | [](best-practice/claude-subagents.md) Custom agents with their own name, color, tools, permissions, and model — usable as main agent or isolated subagents via the Task tool |
+| [**Sub-Agents**](https://code.claude.com/docs/en/sub-agents) | `.claude/agents/.md` | [](best-practice/claude-subagents.md) [](implementation/claude-subagents-implementation.md) Custom agents with their own name, color, tools, permissions, and model — usable as main agent or isolated subagents via the Task tool |
| [**Memory**](https://code.claude.com/docs/en/memory) | `CLAUDE.md` | Persistent context via CLAUDE.md files and `@path` imports that Claude sees every session |
| [**Rules**](https://code.claude.com/docs/en/memory#modular-rules-with-clauderules) | `.claude/rules/*.md` | Modular topic-specific instructions with optional path-scoping via frontmatter |
| [**Hooks**](https://code.claude.com/docs/en/hooks) | `.claude/hooks/` | Deterministic scripts that run outside the agentic loop on specific events |
@@ -108,7 +109,11 @@ practice makes claude perfect
- [Claude Code Tasks - inspired by beats](https://www.reddit.com/r/ClaudeAI/comments/1qkjznp/anthropic_replaced_claude_codes_old_todos_with/) [Inspiration](https://github.com/steveyegge/beads)
- [Ralph Plugin](https://x.com/GeoffreyHuntley/status/2015031262692753449)
-## COMMAND + SKILL + SUBAGENT ARCHITECTURE
+
+
+##
+
+Multi-step workflows using the **Command → Agent → Skills** architecture pattern.
diff --git a/best-practice/claude-subagents.md b/best-practice/claude-subagents.md
index 73a70bb..19ddd49 100644
--- a/best-practice/claude-subagents.md
+++ b/best-practice/claude-subagents.md
@@ -1,6 +1,7 @@
-# Claude Code: Subagents Reference
+# Sub-agents Best Practice
-
+
+[](../implementation/claude-subagents-implementation.md)
Complete reference for Claude Code subagents — built-in agent types, custom agent definitions, and frontmatter fields.
diff --git a/implementation/claude-subagents-implementation.md b/implementation/claude-subagents-implementation.md
new file mode 100644
index 0000000..5d2a193
--- /dev/null
+++ b/implementation/claude-subagents-implementation.md
@@ -0,0 +1,87 @@
+# Sub-agents Implementation
+
+
+
+
+
+---
+
+
+
+The weather agent is implemented in this repo as an example of the **Command → Agent → Skills** architecture pattern.
+
+---
+
+## Weather Agent
+
+**File**: [`.claude/agents/weather.md`](../.claude/agents/weather.md)
+
+```yaml
+---
+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
+ weather-orchestration/input.md, writing results to
+ weather-orchestration/output.md.
+tools: WebFetch, Read, Write
+model: sonnet
+color: green
+memory: project
+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
+3. **Finally**: Update your agent memory with the reading details for
+ historical tracking
+
+...
+```
+
+The agent has two skills preloaded (`weather-fetcher` and `weather-transformer`) that provide step-by-step instructions for fetching from the wttr.in API and applying transformation rules.
+
+---
+
+## How to Use
+
+```bash
+$ claude
+> What is the weather in Karachi?
+```
+
+---
+
+
+
+The weather agent is the **Agent** in the Command → Agent → Skills orchestration pattern. It receives the workflow from the `/weather-orchestrator` command and executes it using two preloaded skills (`weather-fetcher`, `weather-transformer`) within a single execution context.
+
+
+
+
+
+| Component | Role | This Repo |
+|-----------|------|-----------|
+| **Command** | Entry point, user interaction | `/weather-orchestrator` |
+| **Agent** | Orchestrates workflow with preloaded skills | `weather` agent |
+| **Skills** | Domain knowledge injected at startup | `weather-fetcher`, `weather-transformer` |
+
@@ -23,7 +24,7 @@ practice makes claude perfect
|---------|----------|-------------|
| [**Skills**](https://code.claude.com/docs/en/skills) | `.claude/skills/
+
+Multi-step workflows using the **Command → Agent → Skills** architecture pattern.
diff --git a/best-practice/claude-subagents.md b/best-practice/claude-subagents.md
index 73a70bb..19ddd49 100644
--- a/best-practice/claude-subagents.md
+++ b/best-practice/claude-subagents.md
@@ -1,6 +1,7 @@
-# Claude Code: Subagents Reference
+# Sub-agents Best Practice
-
+
+
+The weather agent is implemented in this repo as an example of the **Command → Agent → Skills** architecture pattern.
+
+---
+
+## Weather Agent
+
+**File**: [`.claude/agents/weather.md`](../.claude/agents/weather.md)
+
+```yaml
+---
+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
+ weather-orchestration/input.md, writing results to
+ weather-orchestration/output.md.
+tools: WebFetch, Read, Write
+model: sonnet
+color: green
+memory: project
+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
+3. **Finally**: Update your agent memory with the reading details for
+ historical tracking
+
+...
+```
+
+The agent has two skills preloaded (`weather-fetcher` and `weather-transformer`) that provide step-by-step instructions for fetching from the wttr.in API and applying transformation rules.
+
+---
+
+## How to Use
+
+```bash
+$ claude
+> What is the weather in Karachi?
+```
+
+---
+
+
+
+The weather agent is the **Agent** in the Command → Agent → Skills orchestration pattern. It receives the workflow from the `/weather-orchestrator` command and executes it using two preloaded skills (`weather-fetcher`, `weather-transformer`) within a single execution context.
+
+
+