Agent Skill Design: N*N Toolchains to Smart Aggregation

Introduction: You Probably Already Know This

If you’re using Claude Code, you’ve likely written Skills like this:

---
name: research
description: Research expert
triggers:
  - "research"
  - "study"
tools:
  - WebSearch
  - WebFetch
---

This Skill helps you research any topic...

Simple, declarative, intuitive - this is the power of Claude Code Skills.

But here’s what you might not know:

This same “declarative Skill” concept can solve the N*N toolchain problem.

Part 1: The Problem You’ve Likely Faced

1.1 The Traditional Development Workflow

Collect Data → Manual Selection → Produce Output
    ↓              ↓              ↓
  Tool A      Judgment Step    Tool B

Problems:

❌ Manual intervention at each step
❌ Difficult tool connections
❌ N tools = N! possible combinations
❌ Hard to maintain and extend

Real Example:

// You have 3 tools: WebSearch, GitHub, Database

// Traditional approach: Write all combinations
async function workflow1() {
  const web = await WebSearch();
  const github = await GitHub();
  return process(web, github);
}

async function workflow2() {
  const web = await WebSearch();
  const db = await Database();
  return process(web, db);
}

async function workflow3() {
  const github = await GitHub();
  const db = await Database();
  return process(github, db);
}

// ... and more (3! = 6 combinations)

1.2 Enter Skills: The Solution

Intent → Skill Intelligent Aggregation → Result
           ↓
    [Tool A, Tool B, Tool C]
    Auto-select, execute, combine

What Changes:

✅ No manual tool selection
✅ Dynamic execution order
✅ N tools only need 1 Skill
✅ Flexible composition

Part 2: Starting with What You Know (Claude Code Skills)

2.1 A Simple Research Skill

---
name: tech-research
description: Research technology topics
triggers:
  - "research"
  - "study"
tools:
  - WebSearch
  - WebFetch
  - Read
  - Write
---

## Execution Steps

1. Search for [topic] on the web
2. Read top 5 results
3. Extract key information
4. Generate summary report
5. Save to file

This is already solving N*N! How?

// You don't write these:
async function searchOnly() { /* ... */ }
async function searchAndFetch() { /* ... */ }
async function searchFetchAndWrite() { /* ... */ }
// ... (many combinations)

// Skill handles ALL combinations dynamically:
// - Sometimes just search
// - Sometimes search + fetch
// - Sometimes search + fetch + write
// Based on what's needed!

2.2 Understanding the Three Core Roles

Role 1: Tool Aggregator

Skills combine existing tools, not reimplement them:

<!-- ✅ Good: Uses existing tools -->
tools:
  - WebSearch
  - GitHub
  - Database

<!-- ❌ Bad: Tries to reimplement -->
tools: []
# Then implements search logic from scratch

Role 2: Decision Engine

Replace human judgment with AI decisions:

Traditional:
[Data] → [Human decides: use WebSearch] → [Human decides: use GitHub] → [Result]

Skill:
[Data] → [AI decides: WebSearch + GitHub] → [Result]

Role 3: Execution Coordinator

Handle complex workflows automatically:

## Execution Steps

1. **Data Collection**
   - Search web (if needed)
   - Query GitHub (if needed)
   - Check database (if needed)

2. **Processing**
   - Extract relevant info
   - Cross-reference sources

3. **Output**
   - Generate report
   - Save to file

Part 3: The N*N Problem Explained

3.1 Combinatorial Explosion

3 tools: A, B, C

Possible execution orders:
A → B → C
A → C → B
B → A → C
B → C → A
C → A → B
C → B → A

Total: 3! = 6 combinations

With conditional execution (each step may/may not be needed):

Becomes: 2^3 × 3! = 48 combinations

3.2 Real-World Impact

// Real projects have 10+ tools
const tools = [
  'webSearch', 'github', 'database', 'api',
  'fileSystem', 'email', 'slack', 'jira',
  'analytics', 'monitor'
];

// Possible combinations: 10! ≈ 3,628,800
// Impossible to manually implement all!

Traditional Approach:

Development Time: Years (3.6M combinations)
Maintenance: Impossible

Skill Approach:

Development Time: Days (10 tools + 1 router)
Maintenance: Easy (declarative)
Coverage: All possible combinations

Part 4: Practical Skill Design

4.1 Single Responsibility Principle

Good Design:

<!-- ✅ Each Skill focuses on one domain -->
skills/
├── research-skill/      # Data collection
├── writing-skill/       # Content generation
├── publishing-skill/    # Publishing management
└── analytics-skill/     # Data analysis

Bad Design:

<!-- ❌ One Skill does everything -->
skills/
└── everything-skill/    # Overloaded, hard to maintain

4.2 Composability Principle

The N*N Solution:

// Traditional: Implement all combinations
workflows/
├── research-to-writing/     # Research → Writing
├── research-to-publishing/  # Research → Publishing
├── writing-to-publishing/   # Writing → Publishing
└── ... (N! combinations)

// Skill: Intelligent routing
skills/
├── orchestrator-skill/  # Decides call order dynamically
└── atomic-skills/       # Individual skills
    ├── research/
    ├── writing/
    └── publishing/

4.3 Real Example: Tech Research Skill

Scenario: Research OpenClaw framework

Search for articles
Query GitHub data
Analyze community discussions
Generate comprehensive report

Traditional Implementation (pseudocode):

// You'd need to write all these:
async function researchOpenClaw() {
  const web = await webSearch("OpenClaw");
  const github = await githubQuery("openclaw/openclaw");
  return combine(web, github);
}

async function researchVue() {
  const web = await webSearch("Vue.js");
  const github = await githubQuery("vuejs/core");
  return combine(web, github);
}

// ... repeat for every technology

Skill Implementation:

---
name: tech-research
description: Research any technology topic
tools:
  - WebSearch
  - WebFetch
  - Grep
---

## Execution Steps

1. **Search**
   - Search "[topic] tutorial 2026"
   - Search "[topic] documentation"

2. **GitHub Analysis**
   - Query [topic]/[topic] repository
   - Extract stars, forks, languages

3. **Community**
   - Check recent discussions
   - Identify trending issues

4. **Report**
   - Combine all findings
   - Generate structured report

Usage:

# One Skill handles ANY technology
claude -p "Research OpenClaw"
claude -p "Research Vue.js"
claude -p "Research React Query"

Part 5: From Claude Code Skills to Agent SDK

5.1 The Concept Transfer

You already know how to write Claude Code Skills. Now apply that to Agent SDK:

Claude Code Skill (what you know):

---
name: github-analyzer
description: Analyze GitHub repos
tools: [WebSearch, WebFetch]
---

Agent SDK Skill (same concept, different platform):

from anthropic import Anthropic

skill = {
    "name": "github-analyzer",
    "description": "Analyze GitHub repos",
    "tools": ["web_search", "web_fetch"],
    "instructions": """
    You are a GitHub analyzer.
    Use web_search and web_fetch to analyze repos.
    """
}

agent = Anthropic()
result = agent.messages.create(
    model="claude-sonnet-4-20250514",
    system=skill["instructions"],
    tools=skill["tools"],
    messages=[{"role": "user", "content": "Analyze openclaw/openclaw"}]
)

Key Insight: The design logic is identical! Only the syntax changes.

5.2 Cross-Platform Skills

Write once, run anywhere:

---
name: repo-analyzer
description: Analyze code repositories
tools:
  - WebSearch    # Claude Code
  - web_search   # Agent SDK
  - web:search   # OpenClaw
---

## Universal Execution Flow

1. Detect repository platform (GitHub/GitLab/Bitbucket)
2. Fetch repository metadata
3. Analyze code structure
4. Generate report

Same logic, different platforms:

// Claude Code: Just create the file
.claude/skills/repo-analyzer/SKILL.md

// Agent SDK: Load with Python
loader = SkillLoader()
skill = loader.load(".claude/skills/repo-analyzer/SKILL.md")
agent = skill.to_agent_sdk()

// OpenClaw: Load with TypeScript
const skill = loader.load(".claude/skills/repo-analyzer/SKILL.md")
const openclawSkill = skill.to_openclaw()

Part 6: Best Practices

6.1 Design Checklist

## Skill Design Assessment

### Functionality
- [ ] Clear single responsibility
- [ ] Clear input/output definitions
- [ ] Testable logic
- [ ] Error handling mechanism

### Composability
- [ ] Standardized interface
- [ ] Independent tool dependencies
- [ ] Serializable state
- [ ] Version compatibility

### Observability
- [ ] Complete logging
- [ ] Performance metrics
- [ ] Error tracking
- [ ] Execution statistics

### Maintainability
- [ ] Clear documentation
- [ ] Code comments
- [ ] Test coverage
- [ ] Example code

6.2 Performance Optimization

Parallel Execution:

// ❌ Serial (slow)
for (const tool of tools) {
  await tool.execute();
}

// ✅ Parallel (fast)
await Promise.all(
  tools.map(tool => tool.execute())
);

Caching Strategy:

class CachedSkill {
  private cache = new LRUCache<string, any>({
    max: 100,
    ttl: 1000 * 60 * 5  // 5 minutes
  });

  async execute(input: any): Promise<any> {
    const key = this.generateKey(input);

    const cached = this.cache.get(key);
    if (cached) return cached;

    const result = await this.doExecute(input);
    this.cache.set(key, result);

    return result;
  }
}

Part 7: Real-World Examples

Example 1: Document Processor Skill

Use Case: Process various document types

---
name: document-processor
description: Process PDFs, Word docs, Markdown files
tools:
  - Read
  - Bash
  - WebFetch
---

## Execution Steps

1. **Detect Format**
   - Check file extension
   - Verify MIME type

2. **Extract Content**
   - PDF: Use pdf-parser
   - Word: Use pandoc
   - Markdown: Read directly

3. **Process**
   - Extract text
   - Identify structure
   - Parse metadata

4. **Output**
   - Generate summary
   - Save to JSON/database

Handles N Formats × M Operations = N×M combinations

// Traditional: Write each combination
async function pdfToJson() { /* ... */ }
async function pdfToSummary() { /* ... */ }
async function wordToJson() { /* ... */ }
async function wordToSummary() { /* ... */ }
// ... (N×M implementations)

// Skill: One definition handles all

Example 2: Customer Support Skill

Use Case: Intelligent customer support aggregation

---
name: customer-support
description: Aggregate multiple knowledge sources
tools:
  - knowledge-base
  - faq-search
  - github-issues
  - slack-history
---

## Execution Flow

1. **Classify Query**
   - Technical → knowledge-base + github-issues
   - Billing → faq-search + crm
   - Account → slack-history + user-db

2. **Select Tools**
   - Dynamically choose based on classification

3. **Retrieve & Synthesize**
   - Query selected sources
   - Combine results
   - Generate answer

4. **Response**
   - Format answer
   - Include source citations

Solves: 4 sources × 3 query types × 2 response formats = 24 combinations

Traditional: 24 separate workflows Skill: 1 declarative definition

Part 8: Advanced Patterns

8.1 Orchestrator Pattern

---
name: workflow-orchestrator
description: Coordinate multiple Skills
tools:
  - research-skill
  - writing-skill
  - publishing-skill
---

## Dynamic Workflow

1. **Parse Intent**
   - User wants to publish article
   → Need: research + writing + publishing

   - User wants to research only
   → Need: research

2. **Execute Selected Skills**
   - Run in dependency order
   - Pass context between skills

3. **Aggregate Results**
   - Combine outputs
   - Return final result

8.2 Fallback Pattern

---
name: resilient-fetcher
description: Fetch with multiple fallbacks
tools:
  - WebFetch
  - WebSearch
  - Read
---

## Execution Strategy

1. **Primary**: Try WebFetch first
2. **Fallback 1**: Use WebSearch if fails
3. **Fallback 2**: Check local cache with Read
4. **Error**: All methods failed

Summary: Key Takeaways

Core Concepts

Start with Claude Code Skills
- You already know this
- Simple, declarative, effective
Understand the N*N Problem
- Traditional: N! combinations
- Skills: N tools + 1 router
- Savings: Exponential cost reduction
Three Roles of AI Skills
- Tool Aggregator (combine existing capabilities)
- Decision Engine (replace human judgment)
- Execution Coordinator (optimize workflows)
Cross-Platform Application
- Same design logic
- Different syntax
- Write once, run anywhere

Action Items

For Beginners:

Write your first Claude Code Skill
Identify repetitive tasks
Design intelligent routing
Test and iterate

For Advanced Developers:

Apply Skills to Agent SDK
Build orchestrator Skills
Implement caching & optimization
Share with community

Benefits

✅ Reduced Development Time: Days instead of years ✅ Lower Maintenance: Declarative over procedural ✅ Flexibility: Handle any combination dynamically ✅ Scalability: Easy to add new tools