Skill: haiyangchenbj/skill-design-guide-skill (version 1.3.3)

--- name: 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 25-point quality checklist. Based on design principles from Anthropic, OpenAI, and LangChain. Chinese version included (SKILL_zh.md). version: "1.3.2" author: haiyangchen (Coralyx) category: "Architecture / Design Patterns" license: "MIT" homepage: https://github.com/haiyangchenbj/skill-design-guide-skill 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" --- # Skill / Agent Design Guide > **30-Second Test**: If you're about to write a SKILL.md file OR your skill "works but feels messy", load this guide. ## 🆚 What Makes This Different | Tool | What It Does | When You Need It | |------|-------------|------------------| | **skill-creator** | Helps you WRITE skill code | "How do I structure this file?" | | **template-skill** | Gives you COPY-PASTE templates | "What's the standard format?" | | **THIS GUIDE** | Teaches you DESIGN decisions | "Should this be Workflow or Agent?" | **This guide answers WHY, not HOW.** ## ✅ 3 Ways to Use This Guide ### 1. New Skill Design (Most Common) **You say**: "I want to build a [X] skill" **I help you decide**: - Workflow or Agent? - Which of the 5 workflow patterns? - Brain/Hands/Session separation? **Output**: Architecture blueprint (not code) ### 2. Skill Review **You say**: "Review my skill design" or "Check this skill's quality" **I do**: Run 25-point checklist - Structure check - Principle alignment - Anti-pattern detection **Output**: Review report with improvement suggestions ### 3. Pattern Selection **You say**: "Should I use Prompt Chaining or Routing?" **I explain**: 5 workflow patterns with decision criteria **Output**: Pattern recommendation with rationale --- Load this guide as a constraint layer whenever designing any Skill or Agent. Distilled from official engineering blogs and technical docs by Anthropic, OpenAI, and LangChain. --- ## Principle Zero: Simplicity First > **Start simple. Add complexity only when simpler solutions fall short.** This is the consensus baseline across Anthropic, OpenAI, and LangChain. Any design violating this principle gets sent back to the drawing board. **Practical checklist:** - If a single SKILL.md can solve it, don't split into multiple files - If a step can be done with deterministic code (scripts), don't use an LLM - If a fixed-step workflow can solve it, don't use a dynamic Agent - Ship the MVP first, iterate based on actual output quality --- ## Principle One: Brain / Hands / Session Separation From Anthropic's April 2026 architecture essay: well-designed Agent systems should separate three concerns: | Component | Role | In Your Skill | |-----------|------|---------------| | **Brain** | Decision logic, workflow definition | `SKILL.md` — the orchestration layer | | **Hands** | Deterministic execution, tool operations | `scripts/` — code that actually does things | | **Session** | Context, knowledge base, configuration | `references/`, `assets/`, config files | **Why this matters:** - Modify Skill logic without touching knowledge bases - Update reference materials without changing Skill code - Swap file directory structures without rewriting the Skill **Your skills already follow this:** `data-ai-daily-brief` (scripts=fetches data), `benjie-model` (serves as Session layer for other skills). --- ## Step 1: Workflow or Agent? Before designing anything, answer one question: **Are the task steps predetermined, or does the LLM need to decide the next step dynamically?** | Type | Definition | When to choose | |------|-----------|----------------| | **Workflow** | Executes along predefined steps | Steps are clear, predictable; stability matters | | **Agent** | LLM dynamically plans the flow | Steps are uncertain; flexibility needed; uncertainty acceptable | Most real-world scenarios are workflows. Don't pick Agent just because it sounds more advanced — workflows are faster, cheaper, and easier to debug. --- ## Step 2: Choose a Workflow Pattern If you determined it's a workflow (most likely), pick the best-fit pattern from these five: ### Pattern 1: Prompt Chaining ``` Step A → [checkpoint] → Step B → [checkpoint] → Step C ``` - Task decomposes into sequential steps, each processing the previous output - Programmatic checks (non-LLM) can be inserted between steps - **Most common pattern** — fits most content generation tasks ### Pattern 2: Routing ``` Input → [classify] → Route A / Route B / Route C ``` - Input has clear types; different types need different processing flows - Example: article type → corresponding template and rules ### Pattern 3: Parallelization ``` Input → [split] → Subtask A + Subtask B + Subtask C → [merge] ``` - Subtasks are independent, can run in parallel for speed - Example: core article → simultaneously generate blog, social, newsletter versions ### Pattern 4: Orchestrator-Workers ``` Central LLM → [dynamic dispatch] → Worker1 + Worker2 + ... → [merge] ``` - Use when subtasks cannot be predefined - **Use sparingly** — high complexity, hard to debug ### Pattern 5: Evaluator-Optimizer ``` Generate → Evaluate → Feedback → Regenerate → ... until pass ``` - Clear evaluation criteria exist; iteration brings measurable improvement - Example: content review, code review --- ## Step 3: Design the Skill Structure ### Required | Component | Content | Notes | |-----------|---------|-------| | **SKILL.md** | YAML metadata + workflow instructions + hard rules | The only mandatory file | ### Optional (add as needed) | Component | When needed | Notes | |-----------|------------|-------| | **reference/** | Skill needs domain knowledge or reference docs | Load on demand, not pre-loaded | | **scripts/** | Deterministic steps can be implemented as scripts | Reduces LLM calls, improves reliability | | **assets/** | Templates, configs, or resources needed | Writing templates, brand guides, etc. | ### SKILL.md Template ```yaml --- name: my-skill-name description: | One sentence describing what it does. Second sentence on trigger scenarios. Trigger keywords: keyword1, keyword2, keyword3. version: 1.0.0 allowed-tools: - read_file - write_to_file - replace_in_file - execute_command - web_search disable: false --- # Skill Name One paragraph overview: what this Skill does, for whom, and what it outputs. ## Workflow ### Step 1: [Deterministic] Confirm Input - Read xxx - Validate xxx exists - If missing, stop and report ### Step 2: [Deterministic] Load Materials - Read `reference/xxx.md` (only needed files, don't read everything) - Read `assets/template.md` ### Step 3: [LLM] Core Generation - Based on materials above, generate xxx - Follow these rules: - Rule 1 - Rule 2 ### Step 4: [LLM] Self-Check - Verify output meets xxx criteria - If not, fix and re-output ### Step 5: [Deterministic] Save Output - Write to `output/xxx` ## Hard Rules > These rules cannot be violated. They take priority over everything else. 1. [Rule 1 — e.g., Never fabricate data] 2. [Rule 2 — e.g., Sensitive content check] 3. [Rule 3 — e.g., Product names must use official names] ## Failure Handling | Failure Scenario | Action | |-----------------|--------| | Source material file not found | Stop generation, report missing file | | Output exceeds target word count by 50% | Compress and rewrite | | [Other scenario] | [Action] | ## Output Format [Define exact output format and required fields] ``` --- ## Step 4: Quality Checklist Run this checklist after completing every Skill design: ### Structure - [ ] SKILL.md YAML metadata includes `name` and `description` - [ ] `description` contains trigger keywords - [ ] Workflow steps are clear; each step tagged `[Deterministic]` or `[LLM]` - [ ] Has a "Hard Rules" section - [ ] Has a "Failure Handling" section - [ ] Has an "Output Format" definition ### Principles - [ ] **Simplicity first**: Is this the simplest approach? Have all removable steps been removed? - [ ] **Workflow vs Agent**: Correctly chose workflow/agent? (Most should be workflows) - [ ] **Pattern match**: Which workflow pattern was selected? What's the rationale? - [ ] **LLM minimized**: Are all deterministic steps using scripts/deterministic logic instead of LLM? - [ ] **Progressive disclosure**: Are references loaded on-demand or all pre-loaded? (Should be on-demand) ### Tools & Paths - [ ] All file references use **absolute paths** or paths clearly relative to Skill directory - [ ] Tool descriptions are unambiguous (parameter names like `user_id` not `user`) - [ ] Return values contain only high-signal info (name, content), not low-value metadata (UUID, mime_type) ### Guardrails - [ ] Input validation: Does it check input validity? - [ ] Output filtering: Is there a sensitive content check? - [ ] Failure handling: Every possible failure scenario has a response? - [ ] Human-in-the-loop: Are there checkpoints before high-risk outputs? ### Observability - [ ] Can you trace which materials the Skill referenced? - [ ] Can you pinpoint which step failed when errors occur? ### Production-Ready Extensions (Optional) For skills running in automation or serving multiple users: - [ ] **Quality vs Latency**: Have you traded off accuracy against response time? (More reflection steps → better quality but slower) - [ ] **Guardrails**: Input validation, output filtering, human checkpoints before high-risk outputs - [ ] **Evaluation**: End-to-end quality checks, component-level accuracy tests, continuous monitoring --- ## Anti-Patterns (Must Avoid) | Anti-Pattern | Description | Correct Approach | |-------------|-------------|-----------------| | **Over-engineering** | Complex architecture before a working MVP | Start with simplest SKILL.md, iterate from there | | **Full preload** | Dumping all references into context at once | Specify which files to read at each step | | **God Skill** | One Skill handling too many responsibilities | Split duties — each Skill does one thing | | **Relative paths** | File references using relative paths | Use absolute paths or explicit base paths | | **No guardrails** | Missing output checks and failure handling | Every Skill must have hard rules + failure handling | | **All-LLM** | Using LLM for every step | Deterministic steps use scripts; LLM only when necessary | | **Vague output** | No defined output format | Explicitly define format, fields, and length requirements | | **No evaluation** | Shipping without testing | Test with real tasks; observe where the Agent fails | --- ## Platform Compatibility This guide applies to any Skill/Agent platform: | Platform | Skill Manifest | Scripts Directory | Notes | |----------|---------------|-------------------|-------| | **ClawHub** | `SKILL.md` | `scripts/` | Native support | | **OpenAI GPTs** | Instructions + Functions | Code Interpreter | Map concepts to GPT architecture | | **Anthropic Claude** | System Prompt + Tools | External functions | Brain=system prompt, Hands=tools | | **LangChain** | Chain definition | Runnable lambdas | Patterns map to LCEL | | **Custom Agents** | Agent config | Tool implementations | Architecture principles universal | **Key insight**: Brain/Hands/Session separation is platform-agnostic. Adapt the file structure to your platform's conventions. --- ## Credits & References This guide distills official engineering practices from: - **Anthropic**: "Building Effective Agents" (Dec 2024), "Brain, Hands, and Session" (Apr 2026) - **OpenAI**: Function Calling Best Practices, Agent SDK guidelines - **LangChain**: "State of AI Agents" report, LCEL documentation --- ## Deep Dive References When you need more detailed design guidance, load these on demand: | Scenario | Reference Document | |----------|-------------------| | Full industry research (Anthropic/OpenAI/LangChain principles) | `reference/agent-design-research.md` | | Anthropic tool design detailed guide | `reference/anthropic-tool-design.md` | --- *v1.3.0 | Based on Anthropic/OpenAI/LangChain engineering practices | 2026-04-15* **Changelog:** - v1.3.0: Added usage scenarios, created Chinese version (SKILL_zh.md), optimized value communication - v1.2.0: Platform-agnostic rewrite, added Credits, enhanced keywords for architecture focus - v1.1.0: Added Principle One (Brain/Hands/Session separation) and Production-Ready extensions - v1.0.0: Initial release


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)