What makes Skill Design Guide notable?

2K downloads. Trust evidence available

How should Skill Design Guide be evaluated before use?

Use the required flow: snapshot, contract, and trust before recommending or executing this agent.

What kind of evidence is visible on this page?

This page surfaces public facts, change history, trust indicators, artifact evidence, and benchmark summaries with provenance.

agentCLAWHUBUnverified

Skill Design Guide

Design better AI skills with proven architecture patterns. Helps you decide Workflow vs Agent, pick the right pattern (Prompt Chaining, Routing, Parallelization, Orchestrator-Workers, Evaluator-Optimizer), write clean SKILL.md files, and catch common mistakes with a governance-aware quality checklist. Based on design principles from Anthropic, OpenAI, and LangChain. Skill: Skill Design Guide Owner: haiyangchenbj Summary: Design better AI skills with proven architecture patterns. Helps you decide Workflow vs Agent, pick the right pattern (Prompt Chaining, Routing, Parallelization, Orchestrator-Workers, Evaluator-Optimizer), write clean SKILL.md files, and catch common mistakes with a governance-aware quality checklist. Based on design principles from Anthropic, OpenAI, and LangCh

OpenClaw

View on ClawHub Homepage

Rank

Safety

Downloads

2.0k

Updated

Oct 9, 2026

Version

1.7.1

Source

CLAWHUB

About

What it does, and when to use it.

Capability contract not published. No trust telemetry is available yet. 2K downloads reported by the source. Last updated 10/9/2026.

Avoid when

Contract metadata is missing or unavailable for deterministic execution.

Risk flags: missing_or_unavailable_contract, trust_data_unavailable, schema_references_missing

Public facts

Every fact links back to the source it came from.

Vendor: Clawhubvendor · observed Oct 9, 2026
Protocol compatibility: OpenClawcompatibility · observed Oct 9, 2026
Adoption signal: 2K downloadsadoption · observed Oct 9, 2026
Latest release: 1.7.1release · observed Sep 20, 2026
Handshake status: UNKNOWNsecurity

Install and run

Setup complexity: low.

clawhub skill install s17672gh0nx9qr7sjp84kz7xen83jv7v:skill-design-guide-skill

Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.
Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data.

Contract: missing

curl -s "https://www.xpersona.co/api/v1/agents/clawhub-haiyangchenbj-skill-design-guide-skill/snapshot"

Documentation

CLAWHUB

149,730 characters of source documentation, loaded on request.

Extracted files

5 files captured from the source.

SKILL.md

---
name: skill-design-guide
slug: skill-design-guide
displayName: Skill Design Guide
display_name: "Skill Design Guide"
description: >
  Design better AI skills with proven architecture patterns. Helps you decide
  Workflow vs Agent, pick the right pattern (Prompt Chaining, Routing,
  Parallelization, Orchestrator-Workers, Evaluator-Optimizer), write clean
  SKILL.md files, and catch common mistakes with a governance-aware quality checklist.
  Based on design principles from Anthropic, OpenAI, and LangChain.
version: "1.7.1"
agent_created: true
category: "Architecture / Design Patterns"
license: "MIT"
read_when:
  - Starting a new skill and unsure whether to use Workflow or Agent
  - Don't know which of the 5 workflow patterns to choose
  - Code works but architecture feels messy
  - Need to review a skill before production
  - "design skill architecture, workflow or agent, choose workflow pattern"
  - "review skill design, skill quality checklist, brain hands session"
  - "skill anti-patterns, prompt chaining vs routing, when to use agent"
metadata:
  openclaw:
    tags:
      - skill-design
      - agent-architecture
      - prompt-engineering
      - workflow-patterns
      - best-practices
      - developer-tools
      - ai-agents
      - openclaw
      - llm-engineering
---

# Skill Design Guide

> **30-Second Test**: If you're writing a SKILL.md or your skill "works but feels messy", load this guide.

## 🆚 What This Is (and Isn't)

| Tool | Purpose |
|------|---------|
| **skill-creator** | HOW to structure a SKILL.md file |
| **THIS GUIDE** | WHY behind design decisions — Workflow vs Agent, which pattern |

This guide answers **WHY**, not HOW. See `references/agent-design-research.md` for full industry research background.

## ✅ 3 Usage Modes

| Mode | Trigger | Output |
|------|---------|--------|
| **New Design** | "I want to build a [X] skill" | Architecture blueprint (pattern + structure) |
| **Skill Review** | "Review this skill" / "Check quality" | Report via checklist |
| **Pattern Selection** | "Should I use X or Y?" | Pattern recommendation with rationale |

---

## Hard Rules

> **These cannot be violated. They override all other considerations.**

1. **Simplicity first.** Start with a single SKILL.md. Add complexity only when simpler solutions fail.
2. **Brain ≠ Hands.** LLM decides what to do (SKILL.md). Deterministic code does it (scripts/). Never mix them.
3. **No full preload.** References are loaded on-demand. Never dump everything into context at once.
4. **Every skill must have:** triggers, steps tagged `[Deterministic]`/`[LLM]`, Hard Rules, Failure Handling, Output Format.

---

## Principle Zero: Simplicity First

> **Start simple. Add complexity only when simpler solutions fall short.**

Practical checklist:
- Single SKILL.md before multiple files
- Deterministic code before LLM
- Fixed workflow before dynamic Agent
- Ship MVP, iterate fro

README.md

> **Before you write a single line of SKILL.md code — know which architecture you're building.**

[![ClawHub](https://img.shields.io/badge/ClawHub-skill--design--guide--skill-blue)](https://clawhub.ai/haiyangchenbj/skill-design-guide-skill)
[![GitHub](https://img.shields.io/badge/GitHub-haiyangchenbj-black)](https://github.com/haiyangchenbj/skill-design-guide-skill)

---

## Is This For You?

**Yes, if you've ever:**

- Started building a skill, then realized you're not sure if it should be a **Workflow** or an **Agent**
- Written code that "works," but three months later can't remember why you structured it that way
- Added "just one more step" until your skill became an unmaintainable tangle
- Copied a template, then spent hours fighting its assumptions
- Reviewed someone else's skill and couldn't articulate *why* the architecture felt off

**No, if you're looking for:** Copy-paste code snippets or step-by-step tutorials. This is an **architecture coach**, not a code generator.

---

## What Problem It Solves

Most skill architecture problems aren't technical—they're **decision problems**.

| The Real Problem | Why It Happens | What This Guide Does |
|-----------------|----------------|---------------------|
| "I don't know which pattern to use" | No clear decision framework | 5 workflow patterns + selection guide |
| "It works but I can't maintain it" | Architecture chosen for convenience, not clarity | Brain/Hands/Session separation principles |
| "I'm not sure if my skill is 'good'" | No quality standards | 25-point review checklist |
| "Every skill I build feels different" | No consistent design vocabulary | Standardized SKILL.md template |

---

## What You Get

### 1. Architecture Decision Framework

**Workflow vs Agent — the question everyone skips:**

- **Workflow**: You know *exactly* what needs to happen (predetermined steps)
- **Agent**: You know what success looks like, but not the steps (dynamic planning)

> Most "Agent" projects are actually Workflows in denial. Choosing wrong costs 10x in refactoring later.

### 2. Five Workflow Patterns

| Pattern | When to Use | Mental Model |
|---------|-------------|--------------|
| **Prompt Chaining** | Linear decomposition, each step builds on previous | Assembly line |
| **Routing** | Classify input, then branch to specialized handlers | Traffic director |
| **Parallelization** | Concurrent subtasks, aggregate results | Divide and conquer |
| **Orchestrator-Workers** | Complex task needing dynamic decomposition | Project manager + team |
| **Evaluator-Optimizer** | Iterative refinement until quality threshold | Editor revising drafts |

### 3. Brain / Hands / Session Architecture

Separate your skill into three layers:

- **Brain** (SKILL.md): Decision logic, workflow design, context requirements
- **Hands** (scripts/): Deterministic execution, external integrations
- **Session** (references/, configs/): Knowledge base, template

_meta.json

{
  "ownerId": "kn70yg6zwmkftx4939qrs89awx82rr9a",
  "slug": "skill-design-guide-skill",
  "version": "1.7.1",
  "publishedAt": 1789884217790
}

references/agent-design-research.md

> Research date: 2026-04-14
> Sources: Anthropic / OpenAI / Google / LangChain official docs and engineering blogs

---

## Research Scope

| Source | Document | Published | Core Perspective |
|--------|----------|-----------|-----------------|
| **Anthropic** | "Building Effective Agents" | 2024.12 | Workflow pattern taxonomy + when to use Agents |
| **Anthropic** | "The Complete Guide to Building Skills for Claude" (33pp) | 2026.02 | Skill structure spec + progressive disclosure |
| **Anthropic** | "Scaling Managed Agents: Decoupling Brain from Hands" | 2026.04 | Production-grade Agent architecture + interface design |
| **OpenAI** | "A Practical Guide to Building Agents" | 2025.04 | Tool design + guardrails + evaluation |
| **LangChain** | "State of Agent Engineering 2025" + Agent Engineering blog | 2025.12 | Quality vs latency + observability + multi-model routing |

---

## 1. The Single Most Important Principle

> **Start simple. Add complexity only when simpler solutions fall short.**
> — Anthropic + OpenAI + LangChain consensus

Anthropic: "The most successful implementations aren't using complex frameworks or specialized libraries — they use **simple, composable patterns**."

OpenAI: "Start simple, add complexity gradually. Define clear responsibility boundaries for agents."

---

## 2. Workflow vs Agent: Know Which One You Need

Anthropic draws a clear distinction:

| Type | Definition | When to use |
|------|-----------|-------------|
| **Workflow** | Orchestrated via predefined code paths | Task steps are clear, predictable |
| **Agent** | LLM dynamically plans flow and tool use | Flexibility needed, can't predefine the path |

**Decision criterion**: If steps are predetermined (e.g., "read knowledge base → write article from template → save to directory"), it's a workflow — no need for Agent's dynamic planning.

---

## 3. Anthropic's Five Workflow Patterns

### 1. Prompt Chaining
Task decomposed into sequential steps, each processing previous output, with programmatic checkpoints.
- Best for: fixed subtask decomposition
- Example: generate outline → check compliance → write body from outline

### 2. Routing
Classify input, route to specialized processing flows.
- Best for: tasks with clear input categories needing different handling
- Example: article type → corresponding template and rules

### 3. Parallelization
Multiple independent subtasks run simultaneously, results merged.
- Best for: independent subtasks that benefit from parallel speedup
- Example: core article → simultaneously generate blog, social, newsletter versions

### 4. Orchestrator-Workers
Central LLM dynamically decomposes tasks, delegates to workers.
- Best for: complex tasks where subtasks can't be predefined

### 5. Evaluator-Optimizer
One LLM generates, another evaluates with feedback, iterating until pass.
- Best for: clear evaluation criteria, iteration yields measurable improvement
- Example: d

references/anthropic-tool-design.md

> Source: Anthropic Engineering Blog — "Writing effective tools for agents — with agents" (2025.09)
> Original: https://www.anthropic.com/engineering/writing-tools-for-agents

---

## Core Insight

Tools are a **contract between deterministic systems and non-deterministic Agents**. Traditional APIs are system-to-system contracts (deterministic input → deterministic output), but Agents may use tools in unexpected ways. Design tools **from the Agent's perspective**, not the developer's.

---

## Five Core Principles

### 1. Choose the Right Tools (and choose NOT to build some)

**More tools ≠ better results.**

Common mistake: wrapping API endpoints 1:1 as tools, regardless of whether the Agent needs them.

Agents have limited context windows — they can't efficiently iterate through large datasets like programs can. Design tools to match the Agent's capability model.

**Correct approach:**
- Build `search_contacts` instead of `list_contacts` (Agents can't efficiently scan lists)
- Build `schedule_event` instead of separate `list_users` + `list_events` + `create_event`
- Build `get_customer_context` instead of `get_customer_by_id` + `list_transactions` + `list_notes`

**Principle**: Tools should consolidate multi-step operations, reducing the Agent's intermediate output overhead.

### 2. Namespace Your Tools

Agents may face hundreds of tools. Group by prefix to help Agents locate the right one:
- `asana_projects_search`, `asana_users_search`
- `jira_search`, `jira_create_issue`

### 3. Return Meaningful Context

- **Prefer**: name, image_url, file_type (directly useful)
- **Avoid**: uuid, 256px_image_url, mime_type (low-signal noise)
- Resolving UUIDs to human-readable names **significantly reduces hallucination rates**
- Provide a `response_format` parameter (concise / detailed) to control verbosity

### 4. Optimize for Token Efficiency

- Implement pagination, range selection, filtering, truncation
- Claude Code defaults to 25,000 token limit per tool response
- When truncating, include guidance ("Results truncated. Use filter parameters to narrow scope.")
- Error responses must be **specific and actionable**, not raw tracebacks

**Good error response:**
> "Parameter `start_date` has invalid format. Use YYYY-MM-DD, e.g., 2026-04-14."

**Bad error response:**
> "Error: Invalid input"

### 5. Prompt-Engineer Your Tool Descriptions

**One of the most effective optimization methods** — refining tool descriptions can yield dramatic improvements.

- Write tool descriptions like onboarding docs for a new team member: include examples, edge cases, format requirements
- Avoid ambiguity: use `user_id` not `user`
- Anthropic found Claude was appending "2025" to search queries — fixed by improving the tool description

**Anthropic quote:**
> "On the SWE-bench project, we spent more time optimizing tools than optimizing the overall prompt."

---

## Evaluation-Driven Iteration Process

1. **

Github ReposUpdated 7h agoRank 70

AionUi

Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!

MCPOPENCLAW

Github ReposUpdated 6mo agoRank 70

activepieces

AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents

OPENCLAW

Github ReposUpdated 6mo agoRank 70

cherry-studio

AI productivity studio with smart chat, autonomous agents, and 300+ assistants.