Skill Design Patterns

Agentic AI's lesson on skill design patterns identifies six recurring shapes—workflow, decision, validator, transformation, lookup, and feedback—that every skill falls into, and teaches engineers to match a problem to the correct pattern before writing SKILL.md. The lesson includes worked examples such as an invoice approval workflow and an expense routing decision skill, and warns that skills drifting toward multiple patterns often need rewriting.

· Agentic AI · 7 min read 📋 Prerequisites - From Prototype to Production previous lesson 🎯 What You'll Learn - Name and recognize six recurring skill design patterns - Match a new problem to the correct pattern before writing a line of SKILL.md - Explain how patterns combine, and when a skill is trying to be more than one at once You’ve Already Built These, Unnamed If you completed the free course’s capstone, you built five skills without being told what kind of skill each one was — a checklist skill, a validation skill, a transformation skill, a lookup skill, a feedback skill. That wasn’t an accident. Skills consistently fall into a small number of recurring shapes, and knowing the shape before you write the first line of SKILL.md is what separates a skill that’s well-scoped on the first attempt from one that gets rewritten three times because it was quietly trying to be two different things at once. This lesson names six patterns. Every skill you build for the rest of this course — and the enterprise packs in the project-based course after it — will be one of these, or a composition of more than one composition gets its own lesson: Skill Composition /courses/production-agent-skills-engineering/skill-composition . 1. Workflow Skill Shape: A fixed sequence of steps, done the same way every time, in order. step 1 → step 2 → step 3 → ... → done When to use it: The task doesn’t branch — every valid input goes through the same sequence. An invoice approval process, a release checklist, an onboarding runbook. Worked example — invoice approval: Process an invoice 1. Extract vendor, amount, and line items from the invoice. 2. Match the vendor against the approved-vendor list in references/vendors.md . 3. Check the amount against the requester's approval limit. 4. If everything matches, route to the requester's manager for sign-off. 5. Record the decision and amount in the ledger. Watch for: A workflow skill that starts accumulating if statements at every step is drifting toward the next pattern. 2. Decision Skill Shape: Branching logic — the path taken depends on the input. ┌─ condition A → outcome A input ──┤ └─ condition B → outcome B When to use it: The task’s correct next action genuinely depends on something about the input — not “always do X then Y,” but “do X if this, Y if that.” Worked example — expense approval routing: Route an expense report - If the amount is under $500 and matches a standard category, auto-approve. - If the amount is $500-$5,000, route to the direct manager. - If the amount exceeds $5,000, or the category is "other," route to finance for manual review. - If the expense lacks a receipt and exceeds $75, reject with an explanation regardless of amount. Watch for: A decision skill with more than four or five branches is a sign the branching logic itself might deserve its own reference file references/routing-rules.md , read on demand, rather than living entirely in the body. 3. Validator Skill Shape: Check input against rules; report exactly what’s wrong. input → validate → pass, or specific errors When to use it: The job is confirming correctness, not producing new output. A config file’s required fields, a commit message format, a schema check. Worked example — commit message validator: Validate a commit message Check against these rules, and report every rule that fails — not just the first one: 1. First line is 72 characters or fewer. 2. First line starts with a type: feat , fix , docs , refactor , test , or chore . 3. First line does not end with a period. 4. If the body is present, there's a blank line between it and the subject. Report failures as: "Rule N failed: <specific reason ." Do not simply say "invalid commit message." Watch for: A validator that says “this is invalid” without saying which rule failed and why is barely more useful than no validator at all — the whole value of the pattern is in the specificity of what comes back. 4. Transformation Skill Shape: Convert one format into another, faithfully. input format → transformation → output format When to use it: JSON to CSV, a log line into a structured summary, code comments into a changelog entry — anything defined primarily by “here’s what goes in, here’s what should come out.” Worked example — API log line to structured summary: Summarize an API log line Input: a raw log line like 2026-07-26T14:02:11Z POST /v1/orders 201 143ms user=42891 Output: a one-line structured summary: SUCCESS POST /v1/orders → 201 143ms — user 42891 For 4xx/5xx status codes, prefix with ERROR instead of SUCCESS , and include the response body if present in the log line. Watch for: Transformation skills live or die on examples, not descriptions of the rule. A worked input/output pair, like the one above, teaches the transformation far more reliably than a paragraph explaining it in the abstract. 5. Planner Skill Shape: Break a goal into an ordered set of tasks, and delegate. goal → plan → task 1, task 2, task 3, ... → delegate each When to use it: The request is a goal, not a procedure — “prepare a market analysis on Tesla” rather than “follow these five steps.” A planner skill’s job is to produce the steps, not necessarily to execute all of them itself. Worked example — research report planner: Plan a research report Given a research question, produce an ordered task list rather than answering directly: 1. Identify 3-5 sub-questions the report needs to answer. 2. For each sub-question, note what kind of source would answer it news, financial filings, academic, expert commentary . 3. Order sub-questions so foundational ones what does the company do come before analytical ones is it over- or under-valued . 4. Output the ordered task list. Do not attempt to research or write the report in this step — that is a separate task per sub-question. Watch for: A planner skill that also tries to execute every task itself is really a workflow skill wearing a planner’s name — the defining trait of this pattern is producing a plan for something else to carry out , which matters enormously once you reach Multi-Agent Skill Systems /courses/production-agent-skills-engineering/multi-agent-skill-systems , where a planner’s output becomes another agent’s input. 6. Reviewer Skill Shape: Assess completed work; score and give feedback. work → review against criteria → score + feedback When to use it: The task is judging something already produced, not producing it — a code review, a writing critique, feedback against a rubric. Worked example — code review skill: Review a pull request Check the diff against these criteria, in order, and comment on the first issue found in each category don't overwhelm with every minor nit : 1. Security: parameterized queries, no leaked secrets, auth checks present. 2. Correctness: obvious logic errors, unhandled edge cases in changed code. 3. Style: matches this repo's existing conventions in the surrounding file. For each finding, give: the specific line, what's wrong, and a concrete fix — not just "this could be better." Watch for: A reviewer skill that gives vague praise “looks good overall” without specific, actionable findings has the same failure mode as a validator that won’t say which rule failed — the value is entirely in the specificity. When a Skill Is Trying to Be Two Patterns at Once The most common design mistake at this stage isn’t picking the wrong pattern — it’s not noticing a skill has silently grown a second one inside it. A “process an invoice” workflow skill that’s accumulated five different approval-routing branches has grown a decision skill inside a workflow skill. That’s not automatically wrong, but it’s worth noticing deliberately: sometimes the right fix is composing two skills an next lesson’s topic /courses/production-agent-skills-engineering/skill-composition rather than one skill quietly doing two jobs. Summary | Pattern | Shape | Answers | |---|---|---| | Workflow | Fixed sequence | ”What are the steps, in order?” | | Decision | Branching logic | ”What should happen, given this specific input?” | | Validator | Check against rules | ”Is this correct, and if not, exactly why?” | | Transformation | Format A → Format B | ”What does this become?” | | Planner | Goal → ordered tasks | ”What needs to happen, and in what order, to reach this goal?” | | Reviewer | Assess completed work | ”How good is this, and what specifically should change?” | Naming a skill’s pattern before writing it forces a scoping decision early, rather than discovering mid-write that a “simple validator” has quietly grown branching logic it was never designed to hold. Next, you’ll learn to spot the opposite problem — skills that don’t just have the wrong shape, but are badly built regardless of shape, and the specific, named smells that give it away.