# Wondel.ai Skills > 51 frameworks from bestselling business and engineering books — StoryBrand, Jobs to Be Done, $100M Offers, Clean Code and 47 more — packaged as free, MIT-licensed AI agent skills, plus 14 guided journeys that run them end to end. An agent skill is a folder of instructions your AI coding agent loads on demand. These follow the open https://agentskills.io standard, so they work in Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw, Hermes Agent and any other compatible agent. - Install everything: `npx skills add wondelai/skills --all --global` - Install one skill: `npx skills add wondelai/skills/ --global` - Source: https://github.com/wondelai/skills (MIT) - Built by Wondel.ai. Founder: Michał Jaskólski (https://www.linkedin.com/in/mjaskolski/). - Who we are and how a book becomes a skill: https://skills.wondel.ai/about/ ## Learn Plain explanations of what agent skills are, how they differ from MCP and subagents, and how to install them. Also available as HTML at https://skills.wondel.ai/learn//. - [What Is an AI Agent Skill?](https://skills.wondel.ai/learn/what-is-an-ai-agent-skill.md): A skill is a folder of instructions your AI agent loads on demand — a SKILL.md plus any scripts it needs. What goes in the folder, how the agent decides to load it, and why that beats pasting the same prompt every session. - [Claude Skills vs MCP: Which One Do You Actually Need?](https://skills.wondel.ai/learn/claude-skills-vs-mcp.md): A skill teaches an agent how to do something; MCP gives it a live connection to a system. Where each one wins, when MCP is genuinely the right answer, what they cost in context, and how to compose them. - [Skills vs Subagents vs Slash Commands vs CLAUDE.md: What Goes Where](https://skills.wondel.ai/learn/skills-vs-subagents-vs-prompts.md): Four ways to give a coding agent instructions, and one question that decides between them: what can you afford to have in context on every single turn? A practical map, with the context-window arithmetic. - [How to Install Claude Code Skills](https://skills.wondel.ai/learn/how-to-install-claude-code-skills.md): The practical install walkthrough: the one-line npx command, what --global really changes, where skills live in Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw and Hermes Agent, how to install by hand, and why a skill sometimes never triggers. - [SKILL.md, Explained](https://skills.wondel.ai/learn/skill-md-explained.md): The anatomy of the one required file in an agent skill: every frontmatter field, why description decides whether your skill ever loads, how long the body should be — annotated with a real, shipping SKILL.md. - [The Agent Skills Standard: One Format, Many Agents](https://skills.wondel.ai/learn/agent-skills-standard.md): What agentskills.io is, what a shared skill format solves that per-vendor prompt files never could, what the specification actually defines, and how to tell whether an agent supports it — including what's still unsettled. - [How to Write an Agent Skill](https://skills.wondel.ai/learn/how-to-write-an-agent-skill.md): A practical guide to authoring a skill that actually fires: choosing a triggerable scope, writing the description as a trigger rather than a summary, keeping the body short with the depth in reference files, and testing whether it changed the output. - [Claude Code Skills Libraries: An Honest Roundup](https://skills.wondel.ai/learn/claude-code-skills-libraries.md): A fair comparison of the main open skills libraries for Claude Code and other agents — Superpowers, Corey Haines' marketing skills, Anthropic's official repo, book-derived collections, and ours — with straight guidance on which to install for which job. - [Clean Code vs Clean Architecture: Same Author, Different Altitude](https://skills.wondel.ai/learn/clean-code-vs-clean-architecture.md): Clean Code governs what happens inside a function; Clean Architecture governs which way dependencies point between modules. What each one actually rules on, why neither rescues the other, and which to reach for given a specific symptom. - [Domain-Driven Design vs Clean Architecture: What Is the Boundary Drawn Around?](https://skills.wondel.ai/learn/domain-driven-design-vs-clean-architecture.md): DDD draws boundaries around meaning — bounded contexts, ubiquitous language, aggregates. Clean Architecture draws them around dependency direction. How they compose, what each one does that the other cannot, and when DDD is genuinely overkill. - [Lean Startup vs Design Sprint: Which One Should You Run?](https://skills.wondel.ai/learn/lean-startup-vs-design-sprint.md): One is a loop with no end date; the other is five days with a fixed agenda. What each actually produces, when a sprint is the cheaper way to buy the answer, when it is theatre, and how the two compose. - [Positioning vs Messaging: Which One Is Actually Broken?](https://skills.wondel.ai/learn/positioning-vs-messaging.md): Positioning is the context you choose; messaging is the words that follow from it. Why homepage rewrites so often change nothing, a symptom test that tells you which one is broken, and the order Obviously Awesome and StoryBrand run in. ## Guides Long-form playbooks that sequence the skills into a job. Each is also available as HTML at https://skills.wondel.ai/guides//. - [How to Create a New Business with AI Skills](https://skills.wondel.ai/guides/create-a-new-business-with-ai-skills.md): A step-by-step playbook for going from idea to validated, positioned, monetizable business — using AI agent skills drawn from Lean Startup, The Mom Test, JTBD, and more. - [How to Create a New Website with AI Skills](https://skills.wondel.ai/guides/create-a-new-website-with-ai-skills.md): Build a high-converting website from scratch — message, design, typography, and conversion — with AI agent skills from StoryBrand, Refactoring UI, Making Websites Win, and more. - [How to Create a New App with AI Skills](https://skills.wondel.ai/guides/create-a-new-app-with-ai-skills.md): Go from concept to a well-architected, well-built app — validation, architecture, domain modeling, and clean code — with AI agent skills from Lean Startup, Clean Architecture, DDD, and more. - [How to Improve an Existing Business with AI Skills](https://skills.wondel.ai/guides/improve-an-existing-business-with-ai-skills.md): Sharpen strategy, operations, pricing, and team output in a business that already runs — with AI agent skills from Good Strategy Bad Strategy, Traction, High Output Management, and more. - [How to Improve an Existing Website with AI Skills](https://skills.wondel.ai/guides/improve-an-existing-website-with-ai-skills.md): Diagnose and fix an underperforming website — conversion, usability, messaging, speed, and polish — with AI agent skills from Making Websites Win, Don't Make Me Think, Refactoring UI, and more. - [How to Improve an Existing App with AI Skills](https://skills.wondel.ai/guides/improve-an-existing-app-with-ai-skills.md): Fix how a shipped app feels — product fit, UX friction, visual hierarchy, microinteractions, in-app copy, and honest persuasion — with AI agent skills from Competing Against Luck, Don't Make Me Think, Refactoring UI, Influence, and more. - [How to Grow an Existing Business with AI Skills](https://skills.wondel.ai/guides/grow-an-existing-business-with-ai-skills.md): Build a repeatable growth engine — marketing system, outbound sales, word-of-mouth, and pricing — with AI agent skills from The 1-Page Marketing Plan, Predictable Revenue, Contagious, and more. - [How to Grow an Existing Website with AI Skills](https://skills.wondel.ai/guides/grow-an-existing-website-with-ai-skills.md): Turn more of your existing traffic into leads and customers — testing, lead capture, persuasion, and shareability — with AI agent skills from Making Websites Win, Scorecard Marketing, Contagious, and more. - [How to Grow an Existing App with AI Skills](https://skills.wondel.ai/guides/grow-an-existing-app-with-ai-skills.md): Drive activation, retention, and engagement in an app that already has users — habit loops, retention behavior design, discovery, and metrics — with AI agent skills from Hooked, Tiny Habits, Continuous Discovery, and more. - [From Vibe-Coded Prototype to Production-Ready Product](https://skills.wondel.ai/guides/vibe-coded-prototype-to-production.md): A hands-on engineering playbook for turning an AI-generated prototype into something you can ship and operate — tests, structure, resilience, and scale — using AI agent skills from Clean Code, Refactoring, Release It!, and more. - [How to Refactor a Codebase Buried in Technical Debt](https://skills.wondel.ai/guides/refactor-a-codebase-buried-in-technical-debt.md): A safe, incremental plan for taming a legacy codebase — characterization tests, seams, named refactorings, and boundaries — using AI agent skills from Working Effectively with Legacy Code, Refactoring, Clean Architecture, and more. - [How to Design the Best Possible Architecture for a New App](https://skills.wondel.ai/guides/design-the-best-architecture-for-a-new-app.md): Make the high-leverage architecture decisions right the first time — boundaries, domain model, data, and resilience — using AI agent skills from Clean Architecture, Domain-Driven Design, Designing Data-Intensive Applications, and more. - [Fix a Conversion Flow That Leaks](https://skills.wondel.ai/guides/fix-a-conversion-flow-that-leaks.md): A step-by-step playbook for one flow that loses people — landing page, signup, checkout, or in-app onboarding — using AI agent skills from Lean Analytics, Making Websites Win, StoryBrand, $100M Offers, Influence, and The Design of Everyday Things. - [Make a Slow App Measurably Faster](https://skills.wondel.ai/guides/make-a-slow-app-measurably-faster.md): An engineering playbook for a codebase that ships and earns but has grown slow and tangled — baseline, boundaries, hot paths, the real bottleneck, and the query layer — using AI agent skills from Working Effectively with Legacy Code, Clean Architecture, A Philosophy of Software Design, Refactoring, Release It!, and Designing Data-Intensive Applications. ## Skills (51) Directory: https://skills.wondel.ai/skills/ ### Design & UX Domain hub, with a guide to choosing between them: https://skills.wondel.ai/skills/design/ - [Refactoring UI](https://skills.wondel.ai/skills/refactoring-ui.md): Practical UI design system — based on *Refactoring UI* by Adam Wathan & Steve Schoger - [iOS HIG Design](https://skills.wondel.ai/skills/ios-hig-design.md): Native iOS app design guidelines — based on *Human Interface Guidelines* by Apple - [UX Heuristics](https://skills.wondel.ai/skills/ux-heuristics.md): Usability evaluation and principles — based on *Don’t Make Me Think* by Steve Krug & Jakob Nielsen - [Web Typography](https://skills.wondel.ai/skills/web-typography.md): Web typography principles and implementation — based on *On Web Typography* by Jason Santa Maria - [Design of Everyday Things](https://skills.wondel.ai/skills/design-everyday-things.md): Foundational design principles: affordances, signifiers, feedback — based on *The Design of Everyday Things* by Don Norman - [Top Design](https://skills.wondel.ai/skills/top-design.md): Award-winning 10/10 web design — based on *Elite Agency Techniques* by Locomotive, Studio Freight, AREA 17 - [Lean UX](https://skills.wondel.ai/skills/lean-ux.md): Collaborative, experiment-driven UX design — based on *Lean UX* by Jeff Gothelf & Josh Seiden - [Microinteractions](https://skills.wondel.ai/skills/microinteractions.md): Designing details that delight users — based on *Microinteractions* by Dan Saffer - [Steve Jobs Design Review](https://skills.wondel.ai/skills/steve-jobs-design-review.md): Jobs-style reviews: ruthless simplicity, focus, binary verdicts — based on *Steve Jobs* by Walter Isaacson ### Marketing & Messaging Domain hub, with a guide to choosing between them: https://skills.wondel.ai/skills/marketing/ - [StoryBrand Messaging](https://skills.wondel.ai/skills/storybrand-messaging.md): Clear brand messaging using story structure — based on *Building a StoryBrand* by Donald Miller - [Made to Stick](https://skills.wondel.ai/skills/made-to-stick.md): SUCCESs framework for memorable messaging — based on *Made to Stick* by Chip & Dan Heath - [Contagious](https://skills.wondel.ai/skills/contagious.md): Word-of-mouth and virality using STEPPS — based on *Contagious* by Jonah Berger - [1-Page Marketing Plan](https://skills.wondel.ai/skills/one-page-marketing.md): End-to-end marketing plan: prospect to raving fan — based on *The 1-Page Marketing Plan* by Allan Dib - [Scorecard Marketing](https://skills.wondel.ai/skills/scorecard-marketing.md): Quiz/assessment funnel lead generation — based on *Scorecard Marketing* by Daniel Priestley - [Obviously Awesome](https://skills.wondel.ai/skills/obviously-awesome.md): Product positioning: unique value, target customers — based on *Obviously Awesome* by April Dunford ### Sales & Persuasion Domain hub, with a guide to choosing between them: https://skills.wondel.ai/skills/sales/ - [$100M Offers](https://skills.wondel.ai/skills/hundred-million-offers.md): Grand Slam Offer creation: Value Equation, pricing, guarantees — based on *$100M Offers* by Alex Hormozi - [Negotiation](https://skills.wondel.ai/skills/negotiation.md): Tactical negotiation for high-stakes conversations — based on *Never Split the Difference* by Chris Voss - [Influence Psychology](https://skills.wondel.ai/skills/influence-psychology.md): Persuasion science and ethical influence — based on *Influence: The Psychology of Persuasion* by Robert Cialdini - [Predictable Revenue](https://skills.wondel.ai/skills/predictable-revenue.md): Outbound sales process and Cold Calling 2.0 — based on *Predictable Revenue* by Aaron Ross - [CRO Methodology](https://skills.wondel.ai/skills/cro-methodology.md): Conversion rate optimization methodology — based on *Making Websites Win* by Karl Blanks & Ben Jesson - [Monetizing Innovation](https://skills.wondel.ai/skills/monetizing-innovation.md): Design the product around validated willingness to pay — based on *Monetizing Innovation* by Madhavan Ramanujam & Georg Tacke ### Product & Innovation Domain hub, with a guide to choosing between them: https://skills.wondel.ai/skills/product/ - [Jobs to Be Done](https://skills.wondel.ai/skills/jobs-to-be-done.md): JTBD framework for product innovation — based on *Competing Against Luck* by Clayton Christensen - [Hooked UX](https://skills.wondel.ai/skills/hooked-ux.md): Habit-forming product design — based on *Hooked* by Nir Eyal - [Improve Retention](https://skills.wondel.ai/skills/improve-retention.md): Behavior design for user retention using B=MAP — based on *Tiny Habits* by BJ Fogg - [Lean Startup](https://skills.wondel.ai/skills/lean-startup.md): Build-Measure-Learn methodology — based on *The Lean Startup* by Eric Ries - [Design Sprint](https://skills.wondel.ai/skills/design-sprint.md): 5-day process for validating ideas through prototyping — based on *Sprint* by Jake Knapp - [Continuous Discovery](https://skills.wondel.ai/skills/continuous-discovery.md): Habits for continuous product discovery — based on *Continuous Discovery Habits* by Teresa Torres - [Inspired](https://skills.wondel.ai/skills/inspired-product.md): Building products customers love — based on *Inspired* by Marty Cagan - [The Mom Test](https://skills.wondel.ai/skills/mom-test.md): Customer conversations that reveal the truth — based on *The Mom Test* by Rob Fitzpatrick - [The 37signals Way](https://skills.wondel.ai/skills/37signals-way.md): Lean, opinionated product development from Getting Real to Shape Up — based on *Shape Up* by Jason Fried & DHH - [Lean Analytics](https://skills.wondel.ai/skills/lean-analytics.md): Startup metrics and the One Metric That Matters — based on *Lean Analytics* by Alistair Croll & Benjamin Yoskovitz ### Strategy & Growth Domain hub, with a guide to choosing between them: https://skills.wondel.ai/skills/strategy/ - [Crossing the Chasm](https://skills.wondel.ai/skills/crossing-the-chasm.md): Technology adoption lifecycle and go-to-market — based on *Crossing the Chasm* by Geoffrey Moore - [Blue Ocean Strategy](https://skills.wondel.ai/skills/blue-ocean-strategy.md): Create uncontested market space with value innovation — based on *Blue Ocean Strategy* by W. Chan Kim & Renée Mauborgne - [Cold Start Problem](https://skills.wondel.ai/skills/cold-start-problem.md): Network effects: launch and scale networked products — based on *The Cold Start Problem* by Andrew Chen - [Good Strategy Bad Strategy](https://skills.wondel.ai/skills/good-strategy-bad-strategy.md): Strategy kernel: diagnosis, guiding policy, coherent action — based on *Good Strategy Bad Strategy* by Richard Rumelt ### Team & Operations Domain hub, with a guide to choosing between them: https://skills.wondel.ai/skills/team/ - [Traction EOS](https://skills.wondel.ai/skills/traction-eos.md): Entrepreneurial Operating System for running a business — based on *Traction* by Gino Wickman - [Drive Motivation](https://skills.wondel.ai/skills/drive-motivation.md): Intrinsic motivation: Autonomy, Mastery, Purpose — based on *Drive* by Daniel Pink - [High Output Management](https://skills.wondel.ai/skills/high-output-management.md): Managerial leverage, 1:1s, OKRs, task-relevant maturity — based on *High Output Management* by Andrew S. Grove - [Team Topologies](https://skills.wondel.ai/skills/team-topologies.md): Org design for fast flow: four team types, three interaction modes — based on *Team Topologies* by Matthew Skelton & Manuel Pais ### Code Quality Domain hub, with a guide to choosing between them: https://skills.wondel.ai/skills/code/ - [Clean Code](https://skills.wondel.ai/skills/clean-code.md): Writing readable, maintainable code — based on *Clean Code* by Robert C. Martin - [Pragmatic Programmer](https://skills.wondel.ai/skills/pragmatic-programmer.md): Practical software craftsmanship — based on *The Pragmatic Programmer* by Andrew Hunt & David Thomas - [Refactoring](https://skills.wondel.ai/skills/refactoring-patterns.md): Improving code design through systematic refactoring — based on *Refactoring* by Martin Fowler - [Software Design](https://skills.wondel.ai/skills/software-design-philosophy.md): Reducing complexity through thoughtful software design — based on *A Philosophy of Software Design* by John Ousterhout - [Legacy Code](https://skills.wondel.ai/skills/working-with-legacy-code.md): Safely change untested code: seams and characterization tests — based on *Working Effectively with Legacy Code* by Michael C. Feathers - [Technical Documentation](https://skills.wondel.ai/skills/technical-documentation.md): Audit and write developer docs: reader fit, procedures, API reference — based on *Developer Documentation Style Guide* by Google ### Architecture & Systems Domain hub, with a guide to choosing between them: https://skills.wondel.ai/skills/architecture/ - [Clean Architecture](https://skills.wondel.ai/skills/clean-architecture.md): Building maintainable, testable software architectures — based on *Clean Architecture* by Robert C. Martin - [Domain-Driven Design](https://skills.wondel.ai/skills/domain-driven-design.md): Modeling complex business domains in software — based on *Domain-Driven Design* by Eric Evans - [Data-Intensive Apps](https://skills.wondel.ai/skills/ddia-systems.md): Designing reliable, scalable data systems — based on *Designing Data-Intensive Applications* by Martin Kleppmann - [System Design](https://skills.wondel.ai/skills/system-design.md): Scalable system design patterns and trade-offs — based on *System Design Interview* by Alex Xu - [Release It!](https://skills.wondel.ai/skills/release-it.md): Production-ready software patterns for stability and resilience — based on *Release It!* by Michael T. Nygard - [High Perf Browser](https://skills.wondel.ai/skills/high-perf-browser.md): Browser networking performance optimization — based on *High Performance Browser Networking* by Ilya Grigorik ## Guided journeys (14) Multi-phase metaskills that run a whole job end to end, one decision at a time. - [Create a Business](https://skills.wondel.ai/skills/create-business.md): Raw idea → validated, positioned, priced business — 10 phases - [Create a Website](https://skills.wondel.ai/skills/create-website.md): Blank page → high-converting website — 10 phases - [Create an App](https://skills.wondel.ai/skills/create-app.md): Idea → validated, well-architected app — 10 phases - [Improve a Business](https://skills.wondel.ai/skills/improve-business.md): Diagnose and fix a plateaued business — 8 phases - [Improve a Website](https://skills.wondel.ai/skills/improve-website.md): Diagnose, fix, and prove website improvements — 8 phases - [Improve an App](https://skills.wondel.ai/skills/improve-app.md): Product, UX, copy, and in-app persuasion — fix what users feel — 9 phases - [Grow a Business](https://skills.wondel.ai/skills/grow-business.md): Build a repeatable growth engine — 9 phases - [Grow a Website](https://skills.wondel.ai/skills/grow-website.md): Convert, capture, and compound website traffic — 8 phases - [Grow an App](https://skills.wondel.ai/skills/grow-app.md): Retention-first app growth — 8 phases - [Improve Code Quality](https://skills.wondel.ai/skills/improve-code-quality.md): Vibe-coded prototype → production-ready code — 9 phases - [Remove Technical Debt](https://skills.wondel.ai/skills/remove-technical-debt.md): Pay down debt in place without stopping shipping — 8 phases - [Design Code Architecture](https://skills.wondel.ai/skills/design-code-architecture.md): Deliberate architecture for a new system — 8 phases - [Conversion Optimization](https://skills.wondel.ai/skills/conversion-optimization.md): Leaking flow → measured, tested funnel — 7 phases - [Architecture Optimization](https://skills.wondel.ai/skills/architecture-optimization.md): Slow, tangled codebase → fast and cleanly bounded — 8 phases ## Services - [Work with us](https://skills.wondel.ai/work-with-us/): custom Claude skills, subagents and MCP integrations, shipped to production. Three formats — Skill / Agent Sprint, Custom Build, Skills-Library-as-a-Service. Fixed-price engagements, quoted after a 15-minute call. - [Engagements & pricing](https://skills.wondel.ai/pricing.md): the formats, timelines and scope in markdown, and how to get a quote. ## Optional - [Full content](https://skills.wondel.ai/llms-full.txt): every guide and explainer as plain markdown in one file. - [MCP server](https://skills.wondel.ai/mcp/): open, read-only endpoint at https://skills.wondel.ai/mcp — routes a task to the right skill and serves its instructions without installing anything. - [Agent map](https://skills.wondel.ai/AGENTS.md): every machine-readable surface on this site. - [RSS feed](https://skills.wondel.ai/rss.xml): new and updated guides. --- --- --- --- --- # What Is an AI Agent Skill? > A skill is a folder of instructions your AI agent loads on demand — a SKILL.md plus any scripts it needs. What goes in the folder, how the agent decides to load it, and why that beats pasting the same prompt every session. By Michał Jaskólski · Published 2026-08-17 · Updated 2026-08-17 · 10 min read Canonical: https://skills.wondel.ai/learn/what-is-an-ai-agent-skill/ Skills used: clean-code, lean-startup, domain-driven-design, cro-methodology **TL;DR:** An AI agent skill is a folder containing a SKILL.md file — YAML metadata plus written instructions — that an agent loads only when a task matches the skill's description. The folder can bundle scripts, reference documents and templates. Skills follow an open standard, so the same folder works across Claude Code, Codex, Cursor and dozens of other agents. - A skill is a folder, not a plugin: a required SKILL.md, plus optional scripts, references and assets. - The description field is the trigger — it is the only part of most skills an agent reads before deciding whether the rest is relevant. - Progressive disclosure is the whole point: many skills can sit on disk while costing almost nothing in context until one is needed. - Skills are an open format, so a skill you write once is portable across agents rather than locked to a single vendor. - Skills complement MCP and subagents rather than replacing them — MCP adds capabilities, a skill adds judgment about how to use them. Every team that starts using coding agents seriously hits the same wall within about a month. You work out the right way to ask for something — the exact framing that gets a pull request reviewed properly, or an MVP scoped the way you actually scope MVPs — and then you paste it. Again. Into tomorrow's session, into a teammate's session, into a different agent on a different machine. The knowledge is real and hard-won. The delivery mechanism is a text file you keep reopening. An AI agent skill is the fix for that. It is a folder of instructions — a `SKILL.md` file plus whatever scripts, reference documents and templates it needs — that your agent loads on demand, at the moment a task calls for it. You write it once. It lives on disk, or in a git repo, or in a shared team directory. The agent decides when it is relevant and pulls it into context by itself. That is the entire idea, and its unglamorousness is the feature. No runtime, no API, no server to keep alive — a directory with a markdown file in it. Which is precisely why the format spread across two dozen agent products in months. ## What is an agent skill, precisely? The [Agent Skills](https://agentskills.io) standard defines it plainly: a skill is a directory containing, at minimum, a `SKILL.md` file. That file holds YAML frontmatter with metadata — a `name` and a `description` are required — followed by markdown instructions telling the agent how to do something. ``` clean-code/ ├── SKILL.md # required: metadata + instructions ├── scripts/ # optional: executable code ├── references/ # optional: deeper documentation └── assets/ # optional: templates, data files ``` The instructions are written for a machine that reads English, so they look like a well-organised internal wiki page rather than code: principles, procedures, tables of before-and-after examples, edge cases, a diagnostic checklist. The important word here is *folder*. Not a prompt, not a config setting, not a service. Something you can read, diff, review in a pull request, and copy to another machine with `cp -r`. Every property that makes skills useful in a team follows from that. ## What's actually inside the folder? Four things, only the first of which is mandatory. **`SKILL.md`** is the required file, and the only one many skills have. Its frontmatter carries the metadata; its body carries the instructions. The standard caps `name` at 64 characters (lowercase, hyphenated, matching the parent directory) and `description` at 1024, and recommends keeping the body under 500 lines. We cover the anatomy field by field in [SKILL.md, explained](https://skills.wondel.ai/learn/skill-md-explained/). **`scripts/`** holds executable code the agent runs rather than reimprovises — a Python file that converts a document, a shell script that queries a deployment. Deterministic work belongs here; the agent should decide *when* to run it, not regenerate it each time. **`references/`** holds material that would bloat `SKILL.md` if inlined: API references, per-language conventions, worked examples. The agent reads these only when a task needs them, so keeping each one focused is the trick. **`assets/`** holds static resources: document templates, configuration boilerplate, lookup tables, diagrams. Beyond that, the standard permits any files you like. The three folder names are conventions rather than requirements — useful because agents and humans both benefit from a predictable layout. ## How does an agent decide to load a skill? This is where skills earn their keep, and it is the part most explanations skip. The mechanism is **progressive disclosure**, and the standard describes it in three stages. Discovery: the agent loads only the `name` and `description` of each available skill — roughly a hundred tokens each — so it knows what exists and when each might matter. Activation: when a task matches a description, the agent reads that skill's full `SKILL.md` into context. Execution: it follows the instructions, loading referenced files or running bundled scripts only if the work requires them. So you can have fifty skills installed and pay almost nothing for the forty-nine irrelevant to what you are doing right now. A library that would be unusable if pasted wholesale becomes practical because the agent only ever reads the slice it needs. > Fifty skills on disk cost about as much context as one paragraph — until one of them is the right skill, and then you get all of it. It also explains why the `description` field carries disproportionate weight. That single line is, for most of a session, the *only* thing the agent knows about your skill. "Helps with code quality" will never trigger, because nobody's request looks like that. Name the situations — "use when the user mentions code smells, this function is too long, or reviewing a pull request for readability" — and it fires when it should. One honest caveat: exactly *when* an agent reads those descriptions, how it matches them, and whether you can force a load are implementation details that differ between products. The standard describes discovery as happening at startup, and that is the model to design against — but some agents re-scan, and some expose skills as a tool the model calls explicitly. If a skill you expected to fire stays quiet, naming it directly is the reliable fallback. Anthropic's [Agent Skills documentation](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) covers the Claude side; the [specification](https://agentskills.io/specification) covers what conforming agents agree on. ## Why not just paste the instructions into the prompt? You can. For a one-off, you should. The case for a skill is what happens on the second, twentieth and two-hundredth use. **Context economy.** A pasted instruction block occupies context from the moment you send it until the conversation ends, whether or not the task needs it. A skill occupies roughly one line until it is relevant. Multiply that across a dozen practices and pasting stops being viable. **Reuse without decay.** Prompts kept in a scratch file get edited, half-remembered, and re-derived. A skill is a single artifact with one canonical version. When you learn a step was missing, you fix it in the file, and every future session — yours and everyone else's — gets the fix. **Consistency across sessions and people.** This is the quiet one. If the way your agent reviews code depends on which teammate is prompting it, you do not have a code review standard; you have a distribution of moods. A shared skill makes the *method* the artifact instead of the phrasing, and new joiners inherit the team's accumulated judgment on day one. **It is code, so treat it like code.** A skill lives in git — review a change to it, blame a line, roll it back, tag a version. And because reference files load on demand, it can carry far more depth than you would type into a chat box. > **Prompt** — Use the `clean-code` skill to review the pull request on my current branch — flag any function doing more than one thing, every name that does not reveal intent, and any swallowed exceptions, then give me the top five fixes in priority order > (https://skills.wondel.ai/skills/clean-code/) ## Does a skill work in more than one agent? Yes, and this is the part that changed the calculus for most teams. The format was originally developed by [Anthropic](https://www.anthropic.com/) and released as an open standard, now maintained in the open at [agentskills.io](https://agentskills.io). Adoption has been broad and fast: Claude and [Claude Code](https://code.claude.com/docs/en/skills), OpenAI's Codex, Cursor, GitHub Copilot and VS Code, Gemini CLI, OpenCode, Goose, Amp, OpenClaw and a long tail of others all read the same `SKILL.md` layout. So the folder you write is not a bet on a vendor — move to a different agent and your skills come with you unchanged. Support is not perfectly uniform, though. Every conforming agent handles the required core — the directory layout, `name`, `description`, the markdown body — while optional fields such as `allowed-tools` are explicitly marked experimental and installation paths differ between products. If portability matters, stay on the core. We go deeper in [the agent skills standard, explained](https://skills.wondel.ai/learn/agent-skills-standard/), and on per-agent mechanics in [how to install skills](https://skills.wondel.ai/learn/how-to-install-claude-code-skills/). ## How do skills relate to MCP, subagents and slash commands? They are not competitors. They solve different halves of the same problem, and picking the wrong one wastes real time. **MCP** — the Model Context Protocol — gives an agent *capabilities*: a live connection to your database, your issue tracker, your monitoring stack. A skill gives an agent *judgment*: what to do, in what order, and what "good" looks like. They compose — MCP hands the agent the ability to query production, a skill tells it how to investigate an incident with that access. Need fresh data or a side effect in an external system? MCP. Need a method applied consistently? A skill. The full comparison lives in [Claude skills vs MCP](https://skills.wondel.ai/learn/claude-skills-vs-mcp/). **Subagents** are about *isolation and parallelism* — spawning a separate context to do a chunk of work and report back, so a long investigation does not flood your main conversation. A subagent is a worker; a skill is the instruction sheet that worker reads. They stack. See [skills vs subagents vs prompts](https://skills.wondel.ai/learn/skills-vs-subagents-vs-prompts/) for how to choose. **Slash commands** are *explicit invocation* — you type the name, the thing runs, every time. Skills are implicit: the agent decides. Use a command when you never want the behaviour firing on its own, a skill when you want the agent to notice the situation for you. In several agents you can have both, with a command that simply forces the skill to load. ## When is a skill the wrong tool? Skills are not a universal wrapper, and treating them as one produces a library nobody trusts. Skip the skill when the instruction is **genuinely one-off**. The cost of a skill is not writing it — it is maintaining it, and every skill you keep is a description competing for the agent's attention. Skip it when what you need is **data, not method**. "What are our current error rates?" is a query, and it wants MCP or a script. Skills carry procedural knowledge, not facts that go stale. Skip it when the behaviour should be **unconditional**. If something must apply to every interaction — a house style rule, a hard security constraint — put it in your agent's always-loaded instructions file (`CLAUDE.md`, `AGENTS.md`, or the equivalent). Skills are conditional by design; that is the wrong property for a rule with no exceptions. Skip it when the work is **deterministic**. If the steps never vary and the output is mechanical, write the script and call it — though a skill that says *when* to run it may still earn its place. And be suspicious of the **skill that is really a summary**. The most common failure we see is a `SKILL.md` that describes a topic rather than directing an agent through it — an encyclopedia entry that changes nothing about the agent's behaviour. If your instructions would work equally well as a blog post, they are not yet a skill. [How to write an agent skill](https://skills.wondel.ai/learn/how-to-write-an-agent-skill/) goes through the rewrite. > A skill is not what your agent knows. It is what your agent does, and when it decides to do it. ## What does this look like in practice? Each of our 51 skills packages a canonical framework — [Lean Startup](https://skills.wondel.ai/skills/lean-startup/) for validating an idea, [Domain-Driven Design](https://skills.wondel.ai/skills/domain-driven-design/) for modelling a business, [Clean Code](https://skills.wondel.ai/skills/clean-code/) for readable functions, [CRO Methodology](https://skills.wondel.ai/skills/cro-methodology/) for a landing page that will not convert — so the agent applies the real method rather than a generic-sounding version of it. That is the practical value of the format. You are rarely short of an opinion about how work should be done. You are short of a way to make the agent hold it consistently, for everyone on the team, without you in the room. > **Prompt** — Use the `lean-startup` skill to map the leap-of-faith assumptions behind the feature I just described, rank them by which failure would be fatal, and design the smallest experiment that tests the riskiest one > (https://skills.wondel.ai/skills/lean-startup/) ## Frequently asked questions ### Is an AI agent skill the same as a prompt? No, though a skill contains prompt-like instructions. A prompt is something you send once, in one session, occupying context from the moment you send it. A skill is a file on disk that an agent loads only when a task matches its description, and that the same agent — or a teammate's — can load again tomorrow without you retyping anything. The difference that matters is conditionality and reuse: a prompt is a message, a skill is an artifact you can version, review, and share. ### Do I need to install anything to use skills? You need an agent that supports the format, which most now do. Beyond that, a skill is just a folder placed where your agent looks for skills, so installing one can be as simple as copying a directory. Package managers make it easier — our library installs with a single npx command. Per-agent details differ enough that we split them into a dedicated installation guide. ### How many skills is too many? There is no hard ceiling, because progressive disclosure means unused skills cost roughly a line of context each rather than their full contents. The real constraint is description quality, not count. Fifty skills with sharp, situation-naming descriptions work fine; ten with vague overlapping ones produce an agent that loads the wrong skill. If skills are misfiring, tighten descriptions rather than deleting them. ### Can a skill run code, or is it just text? Both. The markdown instructions are the core, but a skill folder can bundle executable scripts the agent runs directly, plus reference documents and templates it reads on demand. That is the recommended pattern for anything deterministic: put the mechanical step in a script so the agent executes it rather than regenerating it, and reserve the markdown for the judgment about when to run it. ### Who writes agent skills — vendors or users? Anyone. The format is open and the barrier is a text file, so skills come from vendors shipping them alongside products, open-source libraries like ours, and — most commonly — teams writing their own. The highest-value skills are usually internal ones: your deployment procedure, your review standards, the three gotchas in your legacy billing module. Nobody else can write those. ### Do skills work with agents other than Claude? Yes. The format was created by Anthropic but released as an open standard, and adopted well beyond Claude — Codex, Cursor, Copilot and VS Code, Gemini CLI, OpenCode, Amp, Goose, OpenClaw and others read the same layout. Stick to the required core of the specification and a skill written for one agent works in the rest. Optional and experimental fields are where support varies, so treat those as a bonus rather than a foundation. ## Where to go next For the file-level detail — every frontmatter field, and why `description` decides whether your skill ever loads — read [SKILL.md, explained](https://skills.wondel.ai/learn/skill-md-explained/). To choose between a skill, an MCP server and a subagent for a specific job, [Claude skills vs MCP](https://skills.wondel.ai/learn/claude-skills-vs-mcp/) and [skills vs subagents vs prompts](https://skills.wondel.ai/learn/skills-vs-subagents-vs-prompts/) make the call concrete. Or skip the theory and install a few. Our [library of 51 skills](https://skills.wondel.ai/skills/) is free and MIT-licensed: ``` npx skills add wondelai/skills --all --global ``` Then ask your agent to do something one of them covers, and watch it reach for the right method without being told how. --- # Claude Skills vs MCP: Which One Do You Actually Need? > A skill teaches an agent how to do something; MCP gives it a live connection to a system. Where each one wins, when MCP is genuinely the right answer, what they cost in context, and how to compose them. By Michał Jaskólski · Published 2026-08-17 · Updated 2026-08-17 · 12 min read Canonical: https://skills.wondel.ai/learn/claude-skills-vs-mcp/ Skills used: release-it, clean-architecture **TL;DR:** A skill is instruction — knowledge about how to do a job, pulled into the model's context when it becomes relevant. MCP is connection — a protocol that hands the model a live, authenticated channel into an external system. If your agent already has a path to the data, write a skill. If it has no path at all, you need MCP. Serious setups usually end up with both. - Instruction versus connection is the entire distinction: MCP moves data and actions across a boundary; a skill tells the model what to do with them. - If the agent can already reach the system — a CLI it can run, a repo it can read, a key in its environment — an MCP server often adds a service to operate without adding any new access. - MCP genuinely wins for live data behind authentication, for writes you want schema-validated and approvable, and for one integration you want to reuse across several different agents. - The strongest setups compose: the MCP server supplies the capability, and a skill supplies the judgement about how to use it well. - Both cost context, but differently — a skill's description sits in context at rest, while modern clients defer MCP tool schemas until a task needs them. The question gets asked as if one replaces the other, and it doesn't. A skill and an MCP server only look adjacent because they both arrive as "things you add to your agent." One is a document; the other is a network protocol. Confusing them produces two expensive mistakes: standing up an MCP server to wrap a command-line tool the agent could already run, and writing an ever more elaborate skill describing an API the agent has no credentials to reach. The load-bearing distinction is **instruction versus connection**. A skill is knowledge about *how* to do something — a folder with a `SKILL.md` in it, loaded into the model's context when the task matches. MCP is a protocol that gives a model *access* to a system it otherwise cannot touch. A skill changes what the model knows; MCP changes what the model can reach. We maintain a library of open-source [agent skills](https://skills.wondel.ai/skills/) and also get paid to build private MCP servers against other people's systems, so to be explicit: there are plenty of jobs where the honest answer is "you need MCP, and a skill won't help." Those are marked below. This piece assumes you roughly know what a `SKILL.md` is; if not, start with [what an AI agent skill is](https://skills.wondel.ai/learn/what-is-an-ai-agent-skill/). ## What is MCP actually for? The [Model Context Protocol](https://modelcontextprotocol.io/) is an open standard for connecting AI applications to external systems. It is a wire protocol — JSON-RPC 2.0 messages between an **MCP host** (the AI application), an **MCP client** (one per connection, created by the host), and an **MCP server** (a program that exposes some system). The protocol defines three things a server can expose: - **Tools** — executable functions the model can invoke: run a query, file a ticket, send a message. - **Resources** — data the client can read into context: a file, a schema, a record. - **Prompts** — reusable templates the host can surface to the user. In Claude Code these appear as `/mcp__servername__promptname`. It also defines what a client can offer back: as of protocol revision `2026-07-28`, **elicitation** — a server asking the user for information or a confirmation — is the live client primitive, with sampling and logging [deprecated](https://modelcontextprotocol.io/docs/learn/architecture). Two transports are specified, stdio for a local process and Streamable HTTP for a remote one. Authentication lives in the HTTP transport, which supports standard HTTP auth with OAuth recommended for obtaining tokens. The most useful sentence in the whole MCP documentation is this one, from the architecture overview: *"MCP focuses solely on the protocol for context exchange — it does not dictate how AI applications use LLMs or manage the provided context."* Read that as a boundary marker. MCP is deliberately, correctly silent on how the model should behave. It hands your agent a `query` tool with a JSON Schema and a one-paragraph description. It will not tell the agent which of your forty tables matter, that `orders.status` has three legacy values nobody documented, that a full scan on `events` will time out, or that a refund over a certain size should stop and ask a human. That is the gap a skill fills. > MCP gets the agent into the room. It has nothing to say about what the agent should do once it is standing there. ## What does a skill do that MCP doesn't? A skill is a folder containing a `SKILL.md` file: frontmatter with a `name` and a `description`, then markdown instructions, plus any scripts or references you bundle alongside. The format was developed at Anthropic, released as an open standard, and is now implemented across a long list of agents under the umbrella of [agentskills.io](https://agentskills.io/). We cover it in [SKILL.md explained](https://skills.wondel.ai/learn/skill-md-explained/) and [the agent skills standard](https://skills.wondel.ai/learn/agent-skills-standard/). What matters here is the loading model. Agents load skills through **progressive disclosure**: at startup only each skill's name and description enter context; the body loads when the task matches; bundled files and scripts load only when the instructions reach for them. Anthropic's documentation puts the resting cost at roughly 100 tokens per skill and budgets the body at under 5,000 tokens — which is why you can have dozens installed and pay for almost none of them until one becomes relevant. So a skill is the natural home for *procedure and judgement*: conventions, sequences, the thing your senior engineer knows that was never written down. None of it is a capability; all of it is knowledge. ## Skills vs MCP: the capability table | | Agent skill | MCP server | |---|---|---| | What it is | A folder of instructions (plus optional scripts and references) | A running program speaking a JSON-RPC protocol | | What it adds | Knowledge, procedure, judgement | Access: tools, resources, prompts | | Where it lives | In a repo or a config directory, as files | A local process or a remote HTTP endpoint | | Loaded when | Description at startup; body when the task matches | Client-dependent; increasingly deferred until needed | | Handles authentication | No — it can only use credentials the agent already has | Yes — that is a core job of the HTTP transport | | Returns live data | Only if the agent can fetch it some other way | Yes, that is the point | | Enforceable | No. It is context; the model can ignore it | Partly. The host can gate, log and deny individual tool calls | | Operational burden | A file to review in a pull request | A service to deploy, authenticate, version and keep up | | Works offline | Yes | Only for local stdio servers | | Portable | Yes — the same folder works across agentskills.io-compatible agents | Yes — the same server works across MCP-compatible hosts | | Best at | Telling the agent *how* | Telling the agent *what it can touch* | Note that portability is not a differentiator; both are open formats with broad adoption. What differs is what you are portable *with*: a skill travels as text you can read in a diff, an MCP server travels as a deployment. ## When is a skill enough — and an MCP server pure overhead? One question resolves most of these arguments: **does the agent already have a path to this system?** If it does, an MCP server frequently adds a service to operate without adding any new capability. The clearest case is wrapping a CLI. Your coding agent can run bash, and `gh`, `aws`, `kubectl`, `psql` and the rest are already installed, already authenticated on your machine, already documented. Putting a server in front of them buys schema validation and a tidier tool list; it costs a process, a config entry, a dependency to patch, and a permanent translation layer between the model and a tool whose real documentation it can read. What the agent is missing there is not access — it is *which* commands, in what order, with which flags, and what to do with the output. That is a skill, and a much smaller thing to build. The same applies to anything already in the working tree. A skill saying "the canonical schema is at `db/schema.sql`; read it before writing a query; never hand-write a migration, run `npm run db:generate`" beats a server that re-serves the same file over JSON-RPC. Two more cases where a skill is the right shape: - **The knowledge is stable and the access is trivial.** Coding conventions, review checklists, incident runbooks. Nothing to connect to. - **You want determinism.** Bundle a script in the skill folder. The agent runs it and only the *output* enters context — the source never does. Usually cheaper and more reliable than having the model regenerate equivalent code each time. There is a governance argument too: a skill is markdown in your repository, so it goes through code review and shows up in `git blame`. An MCP server is infrastructure, and infrastructure accrues owners, secrets and on-call. ## When do you genuinely need MCP? Often. This is the part skill vendors tend to skip, so let's be specific about where a skill cannot help you at all. **Live data behind authentication.** Jira issues, Sentry events, Salesforce records, a production Postgres replica, a Notion workspace. If the agent has no credentialed route to the system, no amount of instruction manufactures one. MCP exists precisely for this and is very good at it. **Writes you want validated and approvable.** A tool call has a name, a JSON Schema, and a discrete invocation the host can intercept — so it can be gated behind an approval prompt, logged, rate-limited, or denied by policy. A skill gets none of that: it is context, and context shapes behaviour rather than enforcing it. When the operation is "issue a refund," you want the enforcement surface, and MCP is where it lives. **Authentication you don't want the model near.** The Streamable HTTP transport handles bearer tokens, API keys, custom headers and OAuth at the transport layer, so the credential never has to appear in a prompt, a skill body or the transcript. Any design where a skill tells the model to read a secret and paste it somewhere is worse on every axis. **Capabilities that change underneath you.** MCP servers can advertise that their tool list changed and notify subscribed clients, so what an agent can do may shift at runtime as permissions change or a feature flips on. A static markdown file cannot express that. **One integration, many agents.** If four agents across your company need the same internal system, a single MCP server is the honest architecture. Build once, integrate everywhere is the real promise of the protocol, and it holds up. **Sandboxes without a network.** Under-appreciated, and documented: skills running on the Claude API execute in a sandboxed container with no network access and no runtime package installation. A skill that "just shells out to curl" is fine in Claude Code — where skills have the same network access as any other program on your machine — and impossible through the API. If the choice is between building an MCP server and not solving the problem, build the server. ## Can they work together? Yes, and this is the configuration that actually performs in production: **an MCP server that provides the capability, and a skill that provides the judgement about how to use it.** The MCP server for your data warehouse exposes `run_query`. The skill next to it says: these six tables matter and here is what each column means; always filter by `tenant_id`; never `SELECT *` on the events table; if the result exceeds ten thousand rows, aggregate in SQL rather than pulling it into context; for revenue questions the source of truth is the finance mart, not raw events. None of that fits in a tool description, and none of it belongs in one. The two layers are visibly converging. Claude Code's MCP documentation tells server authors that the server-instructions field helps Claude understand when to search for their tools, "**similar to how skills work**." Meanwhile a Claude Code skill can pre-approve specific tools for the turn that invokes it, and a subagent definition can name the MCP servers it may use. The mechanisms are designed to nest. A useful frame, borrowed from [Clean Architecture](https://skills.wondel.ai/skills/clean-architecture/): the MCP server is an adapter at the edge, and the skill is the use case that knows what to do with it. Keeping the vendor at the boundary and the judgement in your own layer is the same instinct that stops a database dictating your business logic. It also implies the operational point people skip — an MCP server is an integration point, so it fails like one, and a server that hangs is worse than one that errors: it burns the turn and produces nothing. > **Prompt** — Use the `release-it` skill to design the failure handling for the MCP servers my agent depends on — timeouts on every outbound tool call, a circuit breaker on the third-party one, and a fallback that degrades the session gracefully instead of hanging when a server stops responding > (https://skills.wondel.ai/skills/release-it/) ## What does each one cost you in context? Context is the scarce resource, so the accounting matters. **Skills** cost their name and description at rest, for every installed skill, every session — roughly 100 tokens each, per Anthropic's documentation. The body arrives only when the skill is triggered, but note that in Claude Code a loaded skill *stays in the conversation for the rest of the session*, with auto-compaction re-attaching recent invocations within a bounded budget. Near-zero until used, then persistent. Write short bodies. **MCP** used to be much worse, because every connected server's full tool definitions loaded upfront and a few chatty servers could eat a serious slice of the window before you typed anything. That has changed. Claude Code now defers MCP tool definitions by default: only tool names and server instructions load at session start, and the model searches for the definitions it needs. Descriptions and server instructions are truncated at 2 KB each. Two caveats, because this is the most version-dependent thing in the article. Deferral is a *client* behaviour, not a protocol guarantee — the MCP documentation describes progressive tool discovery as a best practice for clients federating many servers, so other hosts may still load everything eagerly. And Claude Code's own defaults and thresholds have moved more than once; check [the current docs](https://code.claude.com/docs/en/mcp) rather than any number from a blog post, this one included. The guidance survives the churn: **skills scale cheaply in number, MCP servers scale cheaply only if your client defers their schemas.** Connect the servers you need, not the ones you might. ## So which one do you actually need? Work down this list and stop at the first line that matches. 1. **The agent has no credentialed route to the system.** You need MCP. Nothing else will do. 2. **The operation writes to something you'd want a human to approve, or a log of.** MCP, so the host has a discrete call to gate. 3. **Several different agents need the same integration.** MCP, once, rather than four half-baked wrappers. 4. **The agent can already reach it (a CLI, the repo, a key in the environment) but keeps doing it wrong.** A skill. You have a knowledge problem, not an access problem. 5. **You already have the MCP server and the results are mediocre.** A skill on top of it. This is the most common under-diagnosed case: the connection works and the judgement is missing. 6. **The rule must hold no matter what the model decides.** Neither. Use your client's enforcement layer — permissions, deny rules, hooks. A skill is context and can be ignored; a tool call can at least be blocked. Most teams we work with land on 4 or 5, which is unsurprising: MCP has had far more attention than the instruction layer, so the connections are usually already there and the guidance usually isn't. ## Frequently asked questions ### Is MCP being replaced by Agent Skills? No. They operate at different layers and the tooling is converging on using both together. MCP is a transport-and-capability protocol; skills are an instruction format. Anthropic ships and documents both, Claude Code supports both at once, and the MCP docs point server authors at skill-style guidance for their server instructions. The "skills killed MCP" framing comes from a real observation — many early MCP servers were thin CLI wrappers a skill would have handled better — but generalising that into a replacement is wrong. ### Can a skill call an MCP tool? Yes, and it is a good pattern. A skill's instructions can name which MCP tool to use for a step, in what order, and what to do with the result. In Claude Code a skill can also pre-approve specific tools so the agent doesn't stop for permission mid-turn, and a subagent definition can restrict which MCP servers are visible to it at all. The skill supplies the procedure; the server supplies the capability it calls. ### Does an MCP server bloat my context window? Less than it used to, and it depends entirely on your client. The historical problem was that every connected server's full tool schemas loaded at session start. Claude Code now defers MCP tool definitions by default, loading only tool names and server instructions upfront; other hosts may still load everything eagerly. The general advice is unchanged: connect servers you actually use, keep tool descriptions tight, and audit what is loaded if a session feels heavy from the first turn. ### When is writing an MCP server a mistake? When it wraps something the agent could already do. If your server's tools shell out to a CLI that is installed and authenticated on the machine the agent runs on, you have built a translation layer rather than an integration — a process, a config entry and a schema surface to maintain, in exchange for capability the agent already had. Document the CLI in a skill instead. The exception is a sandboxed environment with no network or no shell, where the wrapper genuinely is the only route. ### Do skills work outside Claude? Yes — the `SKILL.md` format is an open standard, and [agentskills.io](https://agentskills.io/) catalogues the agents implementing it. MCP has comparably broad client support. Neither locks you to a vendor, but loading behaviour and context accounting differ between implementations, so check your own agent's docs rather than assuming Claude Code's behaviour is universal. ### Which should I build first? Whichever removes the current bottleneck. If the agent produces confidently wrong work because it doesn't know your conventions, build the skill: an afternoon, reviewable, reversible. If it can't see the system at all, build the MCP server, because no instruction fixes a missing connection. Standing up a new internal agent, the honest sequence is usually to connect the one or two systems it genuinely cannot live without, then spend the rest of your effort on the instruction layer — that is where the quality gap almost always turns out to be. ## Where to go next If the answer is a skill, [how to write an agent skill](https://skills.wondel.ai/learn/how-to-write-an-agent-skill/) covers the format and the failure modes, and [installing skills in Claude Code](https://skills.wondel.ai/learn/how-to-install-claude-code-skills/) covers getting one running. If you now need to work out where instructions should live across skills, subagents, slash commands and `CLAUDE.md`, that is [the next comparison](https://skills.wondel.ai/learn/skills-vs-subagents-vs-prompts/). Our own library packages canonical engineering and business books as agent skills — free, MIT-licensed, one command: ``` npx skills add wondelai/skills --all --global ``` And if the answer turned out to be "the MCP server *and* the skill layer on top of it, in production, against systems we can't hand to a stranger" — that is the work we do. [Talk to us](https://skills.wondel.ai/work-with-us/). --- # Skills vs Subagents vs Slash Commands vs CLAUDE.md: What Goes Where > Four ways to give a coding agent instructions, and one question that decides between them: what can you afford to have in context on every single turn? A practical map, with the context-window arithmetic. By Michał Jaskólski · Published 2026-08-17 · Updated 2026-08-17 · 13 min read Canonical: https://skills.wondel.ai/learn/skills-vs-subagents-vs-prompts/ Skills used: software-design-philosophy **TL;DR:** Four mechanisms, one axis. Project instructions like CLAUDE.md are always-on context, loaded in full at the start of every session. A skill is on-demand context — its description sits in the window, its body loads when the task matches. A slash command is a skill you trigger yourself. A subagent is a separate context window doing delegated work and reporting back a summary. Choose by what you can afford to pay for on every turn. - The crux is context-window economics: always-on instructions are a tax you pay every turn, on-demand instructions are a bet that the description is good enough to win the trigger. - In Claude Code, slash commands and skills are now the same mechanism — a custom slash command is what a skill looks like when you turn off model invocation. - A subagent is the only one of the four that gives you a second context window, and its real value is the output you never have to read. - Project instructions should hold short, always-true facts; anything that is a multi-step procedure, or only matters for part of the codebase, belongs in a skill or a path-scoped rule. - None of the four is enforcement — if a rule must hold regardless of what the model decides, you want a hook or a permission rule, not more prose. After a few weeks with a coding agent you hit the same problem everyone else does: a dozen things the agent should do differently, and four plausible places to write each of them down. Does the deploy checklist go in `CLAUDE.md`? Is it a slash command? Should test-failure triage run in a subagent? When does a section of project instructions become a skill? These get treated as four unrelated features because they arrived at different times and live on different documentation pages. They aren't. They are four points on one axis — **how much of the context window this costs you, and when** — and once you see the axis, the choice is usually obvious. - **Project instructions** (`CLAUDE.md` and its `.claude/rules/` cousin) are always-on: loaded in full, every session, before you type anything. - **A skill** is on-demand: its description sits in context so the model knows it exists, and the body arrives when the task matches. - **A slash command** is a skill you fire yourself instead of letting the model decide. - **A subagent** is a second context window — delegated work somewhere you can't see, returning a summary. If you want the *other* comparison — instructions versus connections — see [Claude skills vs MCP](https://skills.wondel.ai/learn/claude-skills-vs-mcp/); if you haven't met the skill format at all, start with [what an AI agent skill is](https://skills.wondel.ai/learn/what-is-an-ai-agent-skill/). One scoping note. The `SKILL.md` format is an open standard implemented across [many agents](https://agentskills.io/). Subagents, slash commands and `CLAUDE.md` are, in the forms described here, Claude Code features; other agents have analogues (`AGENTS.md` being the obvious one) with different loading rules. Details specific to Claude Code, or likely to move between versions, are flagged. ## What is the actual difference between them? | | Project instructions | Skill | Slash command | Subagent | |---|---|---|---|---| | What it is | Standing facts and rules | Packaged procedure or reference | A skill you trigger by name | Delegated work in its own context | | Lives in | `CLAUDE.md`, `.claude/rules/` | `.claude/skills//SKILL.md` | The same file, with model invocation off | `.claude/agents/.md` | | Who triggers it | Nobody — it's just there | The model when relevant (or you, by name) | You, by typing `/name` | The model, by delegating | | Context window | Yours | Yours | Yours | Its own, fresh | | Cost at rest | Full text, every session | Name and description only | Nothing | Nothing | | Cost when used | — | Body enters context and stays | Body enters context and stays | Only the returned summary | | Sees your conversation | n/a | Yes | Yes | No, unless it forks it | | Portable beyond Claude Code | Partly (`AGENTS.md`) | Yes, open standard | Varies by agent | Varies by agent | | Best at | Short, always-true facts | Procedures worth finding automatically | Actions with side effects you want to time | Work whose output you'll never re-read | Read the "cost at rest" row twice. That is the row that decides most arguments. > Always-on context is a tax you pay on every turn. On-demand context is a bet that your description is good enough to win the trigger. ## Skills vs CLAUDE.md: what belongs in each? `CLAUDE.md` files load into the context window at the start of every session. Claude Code walks up the directory tree from where you launched it, collects every `CLAUDE.md` and `CLAUDE.local.md` it finds, and concatenates them — root first, closest to your working directory last. Files in *sub*directories are the exception: those load on demand, when the agent reads a file there. The consequence is a hard budget. Anthropic's guidance is to target under 200 lines per file, and the stated reason is worth quoting precisely: longer files "consume more context and reduce adherence." Not just cost — *adherence*. A 900-line `CLAUDE.md` is not a more thoroughly instructed agent, it is a diluted one. The `@path` import syntax helps you organise a large file into several, but it does not help you pay for it: imported files load at launch alongside the file referencing them. So the division is about frequency of relevance, not importance. **Belongs in `CLAUDE.md`:** the build command. The test command. The package manager you use and the one you don't. Where handlers live. The two or three conventions that differ from tool defaults and that the agent would otherwise get wrong every time. **Belongs in a skill:** the release procedure. The incident runbook. The review checklist. Anything that is a *sequence* rather than a fact, and anything long enough to blow the 200-line budget alone. Claude Code's documentation makes the trigger explicit: create a skill when "a section of CLAUDE.md has grown into a procedure rather than a fact." There is a middle option most people miss: `.claude/rules/` files accept a `paths:` frontmatter field of glob patterns, and a rule scoped that way loads only when the agent works with matching files — your React conventions arrive when it touches `src/**/*.tsx` and cost nothing otherwise. If your `CLAUDE.md` is bloated because half of it applies to one directory, that is the fix, not a skill. Nearby sits **auto memory** — notes the agent writes itself, whose index also loads at the start of every conversation up to a documented limit (the first 200 lines or 25 KB). It is on the always-on side of the axis, and worth auditing for that reason. ## Skills vs slash commands: are they still separate things? This is the question with the most out-of-date answers on the internet, so here is the documented current state: **in Claude Code, custom slash commands have been merged into skills.** A file at `.claude/commands/deploy.md` and a skill at `.claude/skills/deploy/SKILL.md` both create `/deploy` and work the same way. Existing command files keep working; if both exist under one name, the skill wins. What used to be the difference — "a skill is something the model picks up, a command is something you type" — is now a frontmatter field rather than a separate mechanism: - `disable-model-invocation: true` — only you can invoke it. This is the pure slash-command shape, and it has a property worth noticing: **the description is not loaded into context at all.** The model doesn't know it exists until you run it. Resting cost: zero. - `user-invocable: false` — only the model can invoke it. For background knowledge that isn't a meaningful action for a human to take. "Explain how the legacy billing system works" is not a command anyone types. - Neither field, the default — both of you can. Description in context, body on invocation. That first bullet is the real reason to still think in terms of commands. It is what you choose when the thing has side effects and you want to control the timing: you do not want the agent deciding, unprompted, that the code looks ready and it will now deploy. `/deploy`, `/commit`, `/release` — turn model invocation off and you get a zero-context-cost action that fires exactly when you say so. The command ergonomics survived the merge. Arguments arrive as `$ARGUMENTS`, or positionally as `$1`, `$2`, and shell output can be injected into the prompt before it is sent — so a `/pr-summary` skill arrives with the actual diff in it rather than instructions to fetch one. The caveat: this merge is a Claude Code behaviour and a recent one. Other agents implement `SKILL.md` but structure their command layer differently. For a mixed team, keep the *content* in the skill body — the portable part — and treat invocation frontmatter as per-agent configuration. ## Skills vs subagents: when do you need a separate context window? Everything above shares one context window: yours. A subagent is the one mechanism that doesn't. It runs "in its own context window with a custom system prompt, specific tool access, and independent permissions," and returns a result to your conversation. The decision is not about complexity or specialisation. It is about **output volume versus follow-up need**. Reach for a subagent when the work produces a lot of text you will never look at again: a full test run, a codebase-wide grep for every call site, twelve files read to answer one question. The verbose output stays in the subagent's context and only the conclusion comes back — worth a great deal, because a single unlucky `grep` can cost more of your window than the entire conversation preceding it. Stay in the main conversation when the task needs iteration. Claude Code's guidance is direct: use the main conversation when "the task needs frequent back-and-forth or iterative refinement," when "multiple phases share significant context," when the change is quick and targeted, or when latency matters — subagents start fresh and need time to gather context your session already has. There is a design lens here that is more useful than it sounds. In [A Philosophy of Software Design](https://skills.wondel.ai/skills/software-design-philosophy/), a *deep* module hides significant implementation behind a simple interface; a *shallow* one wraps very little behind an interface costing more to learn than it saves. A subagent is a module whose interface is its description going in and its summary coming out. One that reads forty files and returns six lines is deep. One that reads a single file and returns its contents is shallow — you paid startup latency and a fresh context to move a `Read` call somewhere else. > **Prompt** — Use the `software-design-philosophy` skill to review my agent configuration against deep-versus-shallow module principles — treat each skill and subagent as a module whose interface is its description going in and its summary coming out, and tell me which ones hide real complexity and which are shallow pass-throughs I should collapse back into the main conversation > (https://skills.wondel.ai/skills/software-design-philosophy/) ## What actually reaches a subagent? This is where most subagent disappointment comes from, so precision helps. A subagent does **not** inherit your conversation. The documentation is blunt: non-fork subagents "start with a fresh, isolated context window" and "don't see your conversation history, the skills you've already invoked, or the files Claude has already read." What it *does* start with, per the docs: its own system prompt, the task message, `CLAUDE.md` files, git status, any skills preloaded through its `skills` frontmatter field, and a roster of its sibling agents. Output style, the main conversation's auto memory and the context window size are named as things that never reach it. Three consequences: 1. **The task message is the whole briefing.** File paths, constraints, what "done" looks like. Half-instructed subagents produce confidently irrelevant work, and you don't find out until the summary arrives. 2. **What isn't in the summary is gone.** The reasoning, the files read, the dead ends ruled out: discarded when it finishes. 3. **Project instructions travel; loaded skills don't.** That is what the `skills` frontmatter field is for — and note it behaves differently from a normal session, injecting the full skill content at startup rather than only the description. The other configuration worth knowing is `context: fork`, which flips the relationship. Instead of a subagent that pulls in a skill, you write a skill that *runs as* a subagent: its body becomes the prompt driving a fresh context. Neat when a procedure is both well-specified and noisy — a research sweep, a broad audit — because you get isolation without a separate agent definition to maintain. There are limits. Claude Code caps nesting depth (three layers below the main conversation by default) and concurrency (20 running subagents). Both defaults have moved before; check the current docs rather than designing around a number from an article. ## How much context does each one really cost? Rough shape, in the order you should worry about them: **Project instructions: full price, every session, forever.** Every line of every `CLAUDE.md` in your path is in the window before your first message. This is the only one of the four with no on-demand story at all, which is why the 200-line target exists and why path-scoped rules are worth the setup. **Skills: near-zero at rest, then persistent.** Description only until triggered — but once a skill's content loads in Claude Code it stays in the conversation for the rest of the session rather than unloading when the task moves on. Compaction handles this with a budget: recent invocations are re-attached after a summary, truncated per skill, under a shared cap, filled from the most recent backwards, so in a long session the older ones quietly stop coming back. Either way: keep bodies short, and put long reference material in separate files the agent reads only when it needs them. **Slash commands with model invocation disabled: free until used.** Nothing at rest, not even the description. Twenty operational procedures that only a human should ever start can all sit there for zero tokens. **Subagents: nothing at rest, and the whole point is what they *don't* charge you.** The cost is elsewhere — latency, because they start cold, and tokens spent rediscovering context your main conversation already had. One correction to a common intuition: none of this is really about token *price*. It is about attention. A window stuffed with instructions that don't apply to the current task makes the model worse at that task, independently of cost — which is the real argument for on-demand loading, and why the 200-line guidance talks about adherence rather than dollars. ## How do they combine? The good setups all look roughly the same: **`CLAUDE.md` names the map, skills hold the territory.** A short line — "release procedure: use the `/release` skill" — costs a few tokens every session and buys reliable discovery of a 300-line procedure that costs nothing until the day you release. **Skills carry the knowledge, subagents carry the noise.** A `code-review` subagent whose `skills` field preloads your review conventions beats either alone: the conventions live in one reviewable file your main conversation can also use, and the review's file-reading happens where you never see it. **And none of them is enforcement.** This is the most important sentence here. `CLAUDE.md` content is delivered as a message the model reads, not a hard constraint — the docs say plainly that there is "no guarantee of strict compliance." Skills are the same: context, which shapes behaviour rather than binding it. If a rule must hold no matter what the model decides, the answer is a [hook](https://code.claude.com/docs/en/hooks-guide) or a permission deny rule, which run as client-side machinery regardless of what the model concludes. Writing it in bolder capitals is not a substitute, and the failure mode is that it works nine times out of ten — exactly often enough to lull you. ## Which one should I reach for? Stop at the first line that matches: 1. **It must hold regardless of what the model decides.** Not one of these four. Use a hook or a permission rule. 2. **It's a one-line fact that's true in every session** — the build command, the package manager, a naming convention. `CLAUDE.md`. 3. **It's a fact that's only true for part of the codebase.** A `.claude/rules/` file with `paths:` frontmatter. 4. **It's a multi-step procedure you want the agent to find on its own.** A skill. Spend your effort on the description — that is the entire discovery mechanism. 5. **It's a procedure with side effects, and you want to choose the moment.** A skill with `disable-model-invocation: true`. Free until you type it. 6. **It generates output you'll read once and never again.** A subagent, or a skill with `context: fork`. 7. **You'd need to iterate on the result three times.** None of them — just do it in the main conversation. The most common mistake we see is rule 2 swallowing rule 4: a `CLAUDE.md` that grew to 600 lines because every procedure got appended to it. The tell is that adherence gets *worse* as the file gets longer — which feels like the model ignoring you, and is actually you having diluted the instructions that mattered. Move the procedures out; the file gets shorter and the agent gets better at the same time. ## Frequently asked questions ### Are slash commands deprecated in favour of skills? In Claude Code they have been merged rather than deprecated. A file in `.claude/commands/` still works and still produces a slash command; a skill directory produces the same command plus a folder for supporting files, frontmatter controlling who can invoke it, and automatic loading when the model judges it relevant. If a command and a skill share a name, the skill wins. Existing command files need no migrating, but new work belongs in a skill directory. ### Does a subagent see my CLAUDE.md? Yes. Project instructions are part of what a subagent starts with, alongside its own system prompt, the task message, git status, any preloaded skills, and a roster of its sibling agents. What it does not get is your conversation history, the skills you already invoked, or the main conversation's auto memory. Two built-in Claude Code agent types, Explore and Plan, deliberately skip project instructions and git status to keep their startup context small — so a research subagent may know less about your project than you assume. ### Is a skill just a longer CLAUDE.md? No, and the difference is when it loads. Project instructions are read in full at the start of every session whether or not they are relevant, which is why the guidance is to keep them under about 200 lines. A skill's body loads only when the task matches its description, so a 400-line procedure costs almost nothing on the days you are not running it. Claude Code's rule of thumb: facts that hold every session go in project instructions, anything that has become a multi-step procedure moves to a skill. ### When is a subagent the wrong choice? When you will iterate on the result. A subagent starts with a fresh context, paying latency and tokens to rediscover things your main conversation already knows, and everything it learned that is not in its summary is discarded. If your next message is "no, do it differently," you have thrown away the state that would have made that cheap. Subagents pay off when the work is self-contained, verbose, and finished when it returns. ### Do these concepts exist outside Claude Code? Skills do, as an open standard implemented by a long list of agents. The other three are shakier. Most agents have some notion of always-on project instructions, often `AGENTS.md` — Claude Code reads `CLAUDE.md` instead, and the documented workaround is a `CLAUDE.md` importing the other file so both tools read the same content. Sub-agent delegation and user-triggered prompt templates exist elsewhere under different names, with materially different loading and isolation rules. Treat the skill body as the portable asset and everything else as per-agent configuration. ### How do I know if my setup is too heavy? Look at what is in the window before you type anything. If project instructions plus rules plus the memory index take a meaningful slice of context before the conversation starts, that is a slice you cannot spend on the task — and adherence drops as the pile grows. The usual fixes, in order: move procedures into skills, scope directory-specific rules with `paths:` frontmatter, turn off model invocation on skills only a human should start, and delegate anything producing output you will not re-read. ## Where to go next If the answer is "write a skill," [how to write an agent skill](https://skills.wondel.ai/learn/how-to-write-an-agent-skill/) covers the format and the ways descriptions fail to trigger, and [installing skills in Claude Code](https://skills.wondel.ai/learn/how-to-install-claude-code-skills/) covers getting one loaded. If the missing piece might be a connection to an external system rather than instruction, that's [skills vs MCP](https://skills.wondel.ai/learn/claude-skills-vs-mcp/). And [our library](https://skills.wondel.ai/skills/) packages canonical engineering and business books as skills: ``` npx skills add wondelai/skills --all --global ``` Primary sources for the specifics above: [Claude Code skills](https://code.claude.com/docs/en/skills), [subagents](https://code.claude.com/docs/en/sub-agents), [memory and project instructions](https://code.claude.com/docs/en/memory), and the [Agent Skills specification](https://agentskills.io/specification). Loading behaviour, defaults and limits change between versions; where this article and the docs disagree, the docs are right. --- # How to Install Claude Code Skills > The practical install walkthrough: the one-line npx command, what --global really changes, where skills live in Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw and Hermes Agent, how to install by hand, and why a skill sometimes never triggers. By Michał Jaskólski · Published 2026-08-17 · Updated 2026-08-17 · 8 min read Canonical: https://skills.wondel.ai/learn/how-to-install-claude-code-skills/ Skills used: clean-code, obviously-awesome, cro-methodology **TL;DR:** Run npx skills add wondelai/skills --all --global to install the whole library in about 30 seconds, with no account. The --global flag installs at user level, so the skills load in every project; drop it to install into the current repo only. The CLI links skills into the compatible agents it finds on your machine, and each agent then loads one on its own when a task matches its description. - npx skills add wondelai/skills --all --global is shorthand for every skill, every detected agent, no prompts; the per-skill form is npx skills add wondelai/skills/ --global. - --global installs at user level so a skill follows you across every project; a project install lives in the repo and is the one you commit for teammates and CI. - Every agent reads skills from its own directory — ~/.claude/skills for Claude Code, ~/.agents/skills for Codex, ~/.hermes/skills for Hermes Agent — so 'where did it install' has a different answer per agent. - Claude and Claude Cowork are the exception: they load the skills enabled on your Claude account, not files sitting on your disk. - When a skill never fires, the cause is almost always that its description doesn't match how you phrased the request — name the skill, or invoke it directly. Installing an agent skill is genuinely a one-line job, over in about thirty seconds, with no account and nothing to configure. What trips people up is everything around that line: global or project, which directory your particular agent reads, what to do if you'd rather not run `npx`, and — the question that brings most people here — why the skill you just installed sits there quietly instead of firing when you need it. If you're still deciding whether skills are the right tool, [what a skill is](https://skills.wondel.ai/learn/what-is-an-ai-agent-skill/) and [how skills compare to MCP](https://skills.wondel.ai/learn/claude-skills-vs-mcp/) are better starting points. This is the page for getting one onto your machine and confirming it works. ## What does `npx skills add wondelai/skills --all --global` actually do? This is the command behind every install button on this site: ``` npx skills add wondelai/skills --all --global ``` `add wondelai/skills` points the [skills.sh](https://skills.sh) CLI at the public GitHub repo `wondelai/skills`. `--all` is documented shorthand for `--skill '*' --agent '*' -y`: every skill in the repo, into every compatible agent the CLI detects on your machine, without stopping to ask. `--global` installs at user level rather than into the current directory. Two details matter before you run it. The CLI links skills into your agent directories rather than duplicating files — pass `--copy` for independent copies, which some sandboxes, container images and Windows setups need. And because `--all` skips the confirmation prompt, run `npx skills add wondelai/skills --list` first if you want to see what's coming. ## How do I install just one skill instead of all of them? Append the skill's slug to the repo path. Every skill page on this site shows its own version of this line: ``` npx skills add wondelai/skills/obviously-awesome --global ``` For a handful rather than one, `-s` (`--skill`) takes several names at once and `-a` (`--agent`) narrows the targets — the CLI's own examples use `claude-code` and `cursor` as agent identifiers: ``` npx skills add wondelai/skills --skill clean-code refactoring-patterns --global ``` There's no penalty for installing everything. Agents load only each skill's name and description at startup — roughly a hundred tokens apiece — and pull the full instructions into context only when a task matches, which is why "install the lot and forget about it" is a sensible default rather than a context-budget problem. ## What does `--global` change, compared with a project install? `--global` (short form `-g`) means *user level*: installed once into your home directory, available in every project you open. Leave the flag off and the skill installs into the project you're currently in. The choice is about who else needs it. **Global** suits the frameworks you personally reach for everywhere: nobody else on your team gets them and none of your repos change. **Project** suits skills that *are* part of the project — a house style, a deployment procedure, a domain glossary. Because it lives inside the repo you commit it, so teammates get it on their next pull and cloud or CI sessions that clone the repo pick it up too. A skill that exists only in your home directory is invisible to all of those. Most people end up doing both. If the same name exists at both levels, check your agent's precedence rules — Claude Code resolves a clash in favour of the personal skill over the project one, the opposite of what most people assume. ## Where do skills live in each agent? These skills work in Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw, Hermes Agent, and other [agentskills.io](https://agentskills.io)-compatible agents. The installer handles placement for you, but knowing where each agent looks turns "it didn't work" into a five-second fix. The paths below come from each agent's own documentation. ### Claude Code Personal skills live at `~/.claude/skills//SKILL.md` and apply to all your projects; project skills live at `.claude/skills//SKILL.md`. Claude picks one up automatically when a task matches, and you can invoke it directly as `/`. Claude Code watches those directories, so a skill added mid-session works without a restart — unless the skills directory itself didn't exist when the session started. Claude Code can also install these skills as plugins, published as ten themed collections: ``` /plugin marketplace add wondelai/skills /plugin install code-craftsmanship@wondelai-skills ``` Plugin skills are namespaced as `plugin-name:skill-name`, so they never collide with anything in your personal or project directories. ### Claude The claude.ai apps don't read your filesystem, so `npx` can't reach them. Anthropic documents custom skills as zip uploads through Claude's settings, on the paid plans with file creation and code execution enabled. Uploaded skills are per-user rather than org-wide, and they don't sync between Claude's surfaces. Check [Claude's Agent Skills documentation](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) for the current steps and plan requirements. ### Claude Cowork Cowork surprises people most: Cowork sessions do not read `~/.claude/skills/` from your machine. They load the skills enabled on your Claude account, synced when the session starts, managed from the Customize area in the Claude desktop app sidebar or in your skills settings on claude.ai. The route into Cowork is "enable it on your account", not "install it locally". ### Codex Codex reads user-level skills from `$HOME/.agents/skills` and project skills from `.agents/skills` in your working directory and at the repository root, scanning upward from where you are. Invoke one explicitly with `$skill-name`, or let Codex match your prompt against the description. The repo also ships a Codex plugin marketplace, so in a clone Codex discovers the same ten collections and you manage them from the `/plugins` menu in the TUI. ### Cursor Cursor looks in `.cursor/skills/` and `.agents/skills/` for project skills, and `~/.cursor/skills/` and `~/.agents/skills/` for user-level ones. It also reads `.claude/skills/` and `~/.claude/skills/` for backwards compatibility, which is why skills installed for Claude Code often just appear in Cursor. Skills surface automatically, or type `/` in the Agent chat and pick one by name. ### OpenClaw OpenClaw searches several roots in priority order — the workspace's own `skills` directory, then `/.agents/skills`, then `~/.agents/skills`, then its managed state directory and bundled skills — and the highest source wins on a name clash. Invoke as `/skill-name`, reference inline as `$skill-name`, or let the model choose. OpenClaw also has its own installer (`openclaw skills install`). ### Hermes Agent Hermes treats `~/.hermes/skills/` as its primary directory and source of truth, and also picks up project-local skills from `/.hermes/skills/` or `/.agents/skills/`, plus extra directories listed under `skills.external_dirs` in `~/.hermes/config.yaml`. Skills are invoked as slash commands, and Hermes will chain several in one command. For any agent not listed here, its own docs are the authority — the shared standard specifies the skill *format*, not where each client stores it. The [agentskills.io client showcase](https://agentskills.io/clients) links to the skills documentation for every compatible agent. ## How do I install a skill by hand, without npx? A skill is just a folder. If you'd rather not run an installer, clone the repo and copy the one you want into the right directory: ``` git clone https://github.com/wondelai/skills.git cp -r skills/clean-code ~/.claude/skills/ ``` Copy the whole directory, not only `SKILL.md` — most skills bundle a `references/` folder the instructions point at, and a skill missing its references will load and then fail halfway through a task. Substitute the target path for your agent from the section above. The trade-off is updates: the CLI refreshes what it installed with `npx skills update --global`, while a hand-copied folder is yours to re-copy. ## How do I check that it worked? Two checks, and you want both — one that the files landed, one that the agent can see them. ``` npx skills list --global npx skills list --global --agent claude-code ``` Add `--json` for machine-readable output, or just look: `ls ~/.claude/skills` should show one directory per skill, each containing a `SKILL.md`. The second check is the one that matters, because a file on disk is not a skill in context. Start a fresh session, give the agent a task the skill is supposed to own, and ask it to name what it used: > **Prompt** — Use the `clean-code` skill to review this file for naming, function length, and error handling, and start your answer by naming the skill you are applying so I can confirm it loaded > (https://skills.wondel.ai/skills/clean-code/) If the answer names the skill and reads like the framework rather than generic advice, the install is real. In Claude Code and Cursor you can also invoke it directly — `/clean-code` — which bypasses matching entirely and proves the file is being read. > A skill that never triggers usually isn't installed wrong. It's described wrong — or you phrased the request in words its description never anticipated. ## Why isn't my skill triggering? This is the most common problem after a successful install, and the honest answer is rarely the exciting one. Agents don't read your skills at startup — they read each skill's **name and description**, and nothing more, until something you say matches. So the skill isn't broken and the install isn't corrupt: the description simply doesn't overlap the words you used. Ask for "help with our landing page" and a skill whose description talks about conversion rate optimization, funnels and objection handling may never surface. Fixes, in the order worth trying: 1. **Name the skill in your prompt.** "Use the `cro-methodology` skill to audit this page." This works in every compatible agent and instantly separates a matching problem from an installation problem. 2. **Invoke it directly.** `/skill-name` in Claude Code, Cursor, OpenClaw and Hermes Agent; `$skill-name` in Codex. If that works and automatic matching doesn't, the file is fine. 3. **Check the scope.** A project install only applies inside that project, and a global install won't reach a Cowork or cloud session that never sees your disk. 4. **Restart the session.** Most agents load skill metadata at startup. Claude Code watches its directories, but not one created after the session began. 5. **Look for a name collision.** A skill sharing a name with a bundled command may be shadowed; use the namespaced plugin form instead. 6. **Re-install with `--copy`** if your environment doesn't resolve symlinks — a broken link looks exactly like a missing skill. The mechanism is worth internalising if you write your own skills: the description is not documentation, it's the trigger. [What goes in SKILL.md](https://skills.wondel.ai/learn/skill-md-explained/) covers how to write one that fires. > **Prompt** — Use the `obviously-awesome` skill to position our product against the alternatives our buyers actually consider, and tell me which parts of your instructions you are drawing on as you go > (https://skills.wondel.ai/skills/obviously-awesome/) ## How do I update or remove skills? ``` npx skills update --global npx skills remove --global ``` `update` refreshes installed skills to their latest versions (`-g` limits it to global, `-p` to project). `remove` runs interactively or takes names directly, with the same `--global` and `--agent` flags as `add`, and only removes the link or copy from the agent directory. ## Frequently asked questions ### Do I need an account or an API key to install these skills? No. They are MIT-licensed files in a public GitHub repository, and the installer places them in a directory your agent already reads. Nothing to sign up for, no key to paste, no service in the loop at runtime — once the folder is on disk the skill works inside the agent you already use, on the model you already pay for. ### Will installing the whole library slow down my agent or fill my context window? No, by design. Agents load only the name and description of each installed skill at startup, on the order of 100 tokens each. Full instructions enter context when a task matches, and bundled reference files load only if the instructions call for them. That progressive disclosure model is why installing the whole library is a sensible default rather than a trade-off. ### Can I install these skills in an agent that isn't on the compatible list? Usually yes. The seven agents named here are the ones we call out, but the format is an open standard and any agent that reads a folder containing a SKILL.md file can use these skills. Copy the folder into whichever directory that agent documents as its skills location — check its own docs, or the client showcase on agentskills.io, which links to the skills documentation for each compatible client. ### Does a skill installed in Claude Code also work in Claude on the web? Not automatically. Custom skills don't sync between Claude's surfaces: a filesystem skill in Claude Code is separate from one uploaded to claude.ai, which is separate again from one uploaded through the API. This also explains the Cowork behaviour — Cowork sessions load the skills enabled on your Claude account rather than the files in your home directory. ## Install it and try one thing Run the one-liner, then pick a task you were going to do anyway and name a skill in the prompt: ``` npx skills add wondelai/skills --all --global ``` The verification that counts isn't a directory listing — it's an answer that sounds like the framework instead of generic advice. Browse [all the skills](https://skills.wondel.ai/skills/) to find the one closest to what you're working on today. --- # SKILL.md, Explained > The anatomy of the one required file in an agent skill: every frontmatter field, why description decides whether your skill ever loads, how long the body should be — annotated with a real, shipping SKILL.md. By Michał Jaskólski · Published 2026-08-17 · Updated 2026-08-17 · 8 min read Canonical: https://skills.wondel.ai/learn/skill-md-explained/ Skills used: clean-code, refactoring-patterns, clean-architecture **TL;DR:** A SKILL.md is a markdown file with YAML frontmatter. Two fields are required — name and description — and the description is the load-bearing one, because it is the only part most agents read before deciding whether to open the rest. The body holds the instructions; anything long belongs in referenced files that load on demand. - Two frontmatter fields are required: name (max 64 chars, matching the directory) and description (max 1024 chars). - The description is the trigger — write what the skill does and the exact situations that should activate it, in that order. - Progressive disclosure means the body is a budget: keep SKILL.md under about 500 lines and push detail into references/. - Write directions, not a summary — if the file reads like an article about the topic, it will not change what your agent does. Every agent skill is a folder, and every skill folder has exactly one required file: `SKILL.md`. Everything else — scripts, reference documents, templates — is optional. If you understand one thing about the format, understand this file. It is markdown with YAML frontmatter at the top. That is the whole specification. The subtlety is not in the syntax; it is in knowing which parts the agent reads, when it reads them, and what that means for where you put your words. Get that wrong and you end up with a technically valid skill that never fires — or one that fires constantly and floods the context with detail nobody needed. This page walks the file top to bottom, annotated with one of our own shipping skills. For the higher-level framing first, see [what is an AI agent skill](https://skills.wondel.ai/learn/what-is-an-ai-agent-skill/). ## What's actually inside a SKILL.md file? Two parts, in order. A YAML frontmatter block delimited by `---`, and a markdown body. Here is the top of [Clean Code](https://skills.wondel.ai/skills/clean-code/), one of the 51 skills in our library, unedited: ```yaml --- name: clean-code description: 'Write readable, maintainable code through disciplined naming, small functions, and clean error handling. Use when the user mentions "clean up this code", "this function is too long", "code smells", "naming conventions", "boy scout rule", "single responsibility", or "unit test quality". Also trigger when reviewing a pull request for readability, untangling a messy function, debating comment styles, or improving error-handling patterns. Covers SRP, comment discipline, formatting, and unit testing. For refactoring techniques, see refactoring-patterns. For architecture and dependency rules, see clean-architecture.' license: MIT metadata: author: wondelai version: "1.4.0" --- ``` Four fields, of which two are required. Then the body opens with an H1 and a one-paragraph statement of when to apply the skill: ```markdown # Clean Code Framework A disciplined approach to writing code that communicates intent, minimizes surprises, and welcomes change. Apply these principles when writing new code, reviewing pull requests, refactoring legacy systems, or advising on code quality. ## Core Principle **Code is read far more often than it is written — optimize for the reader.** ``` Note what that opening does. It is not introducing a topic; it restates the activation conditions in the agent's working context, then hands it one principle to reason from. Every paragraph in a good `SKILL.md` is trying to change a decision the agent is about to make. ## What does each frontmatter field do? The [specification](https://agentskills.io/specification) defines six fields. Most skills use two or three. **`name`** (required). Maximum 64 characters, lowercase letters, numbers and hyphens only, no leading, trailing or consecutive hyphens — and it must match the parent directory name. `clean-code` lives in `clean-code/`. This is what users type to invoke the skill explicitly, so make it the obvious noun phrase rather than something clever. **`description`** (required). Maximum 1024 characters, non-empty. It should describe both what the skill does and when to use it. This is the field that decides whether your skill is ever loaded, and it gets its own section below. **`license`** (optional). A license name, or a pointer to a bundled license file. Ours say `MIT`. Worth setting on anything you publish. **`compatibility`** (optional, max 500 characters). Environment requirements: an intended product, required system packages, network access. The spec is blunt that most skills do not need it — use it when your skill genuinely will not work without `docker` and `jq` on the path. **`metadata`** (optional). An arbitrary map of string keys to string values, for anything the spec does not define. We use it for `author` and `version`, which is what makes a library reviewable — you can see whether a teammate is running the version that fixed the bad advice. **`allowed-tools`** (optional, experimental). A space-separated list of pre-approved tools the skill may use, like `Bash(git:*) Read`. The specification marks it experimental and warns support varies between agents — treat it as a convenience where it works, not a security boundary you rely on. That is the complete list. If you find yourself wanting a seventh field, it belongs in `metadata`. ## Why is `description` the single most important line? Because for most of a session it is the only part of your skill the agent has seen. Agents load skills through progressive disclosure. At discovery, the agent reads just the `name` and `description` of every installed skill — around a hundred tokens each — and only opens the full `SKILL.md` when a task matches. Your instructions can be immaculate; if the description does not match the way a real request is phrased, none of them will ever be read. > Everything else in the file is an argument for what to do. The description is the argument for whether the agent bothers to look. So write it as two halves, in this order: **what the skill does**, then **when to use it**. The second half is where most descriptions fail, because it requires predicting the user's words rather than describing your own topic. Three habits make the difference: - **Name the symptoms, not the subject.** People do not ask for "code quality". They say a function is too long. Put the phrasing they actually use into the description — note that Clean Code's trigger half is almost entirely quoted user speech. - **Include the situations, not just the words.** Keyword matching is fragile alone; a clause like "also trigger when reviewing a pull request for readability" gives the agent a scenario to recognise when the vocabulary differs. - **Disambiguate against your neighbours.** The last two sentences of the Clean Code description exist purely to route: "For refactoring techniques, see refactoring-patterns. For architecture and dependency rules, see clean-architecture." In a library of 51 skills, the failure mode is not that nothing loads — it is that the *adjacent* skill loads. You have 1024 characters. Using 200 of them is usually a mistake; using all 1024 on prose that never names a trigger is worse. ## What belongs in the body — and what doesn't? The body is where the agent gets its directions, and the operative constraint is that it loads **all at once** — the moment the skill activates, the entire file enters context. That makes the body a budget, not a canvas. The specification recommends keeping the instruction layer under roughly 5,000 tokens and the main `SKILL.md` under 500 lines, with detailed material moved into separate files. Our Clean Code skill lands at 222 lines, with six reference files beside it — `naming-conventions.md`, `functions-and-methods.md`, `error-handling.md`, `code-smells.md`, `comments-formatting.md`, `testing-principles.md`. The way it hands off is worth copying. Inside the section on naming, after the principles and a compact table of patterns, sits a single line: ```markdown See [references/naming-conventions.md](references/naming-conventions.md) when renaming or reviewing names — per-language conventions, pronounceable/searchable tables, and before/after examples. ``` Two things make that pointer work. It uses a relative path from the skill root, as the spec calls for. And it says *when* to open the file and *what is in it*, so the agent can decide without reading it. A bare link with no conditions is one the agent either always follows or never does. What stays in the body: principles to reason from, the procedure, decision criteria, compact tables. What moves out: exhaustive enumerations, per-language variations, long worked examples — anything that is reference material rather than instruction. Keep reference chains one level deep. ## When should a skill bundle scripts? When the work is deterministic and you would rather it not be re-derived every time. The convention is a `scripts/` directory holding executable code the agent runs — Python, Bash and JavaScript are common, though what actually runs depends on the agent. The rule of thumb: if the steps never vary and correctness matters more than judgment, write the script and have `SKILL.md` say when to run it and how to read the output. That beats asking the model to regenerate the same logic every invocation, because generated code varies and a committed script does not. Scripts should be self-contained or document their dependencies, fail with messages an agent can act on, and handle the obvious edge cases. An `assets/` directory covers the rest — templates, schemas, lookup tables, anything static the skill hands over rather than describes. Many good skills have neither. Clean Code has none: it is pure judgment, and judgment does not compile. ## What are the most common SKILL.md mistakes? Four, in descending order of how often we see them. **A vague description.** "Helps with code quality." "Assists with documentation." These are topics, not triggers, and skills carrying them sit unloaded forever while their authors conclude the format does not work. The spec's own example of a poor description is `Helps with PDFs.` If you fix one thing here, fix this. **Dumping the whole book into the body.** A 2,000-line `SKILL.md` defeats progressive disclosure: every activation now costs a large fraction of the context window, most of it irrelevant. The fix is not to delete material — move it into `references/` and add a conditional pointer. **Writing a summary instead of directions.** The subtle one. A file that explains a methodology reads well to a human and changes nothing about the agent's behaviour. Directions are imperative and testable: *flag any function over twenty lines*, *extract handlers rather than inlining try-catch*. Our test — if the text would work unchanged as a blog post, it is not yet a skill. **No boundary against neighbouring skills.** Two skills whose descriptions both plausibly match "improve this code" will fight, and the winner is arbitrary. Name the adjacent skills and state which owns which case. > **Prompt** — Use the `clean-code` skill to review my most important service class and flag any function over twenty lines or doing more than one thing, every name that does not reveal intent, and any swallowed exceptions — then give it a score out of ten and the top five fixes in priority order > (https://skills.wondel.ai/skills/clean-code/) ## Frequently asked questions ### What are the required fields in a SKILL.md? Exactly two: name and description. The name must be 1 to 64 characters, lowercase letters, numbers and hyphens only, with no leading, trailing or consecutive hyphens, and it must match the folder the file sits in. The description must be non-empty and at most 1024 characters. Everything else is optional. ### How long should a SKILL.md be? Short enough that loading it is cheap, since the whole body enters context the moment the skill activates. The specification recommends keeping the instruction layer under about 5,000 tokens and the main file under 500 lines. Our Clean Code skill sits at 222 lines with six reference files beside it — principles and procedure in the main file, exhaustive detail one level away and loaded only when a task needs it. ### Why isn't my skill loading? Almost always the description. Agents match against it before reading anything else, so a description naming your topic rather than the user's symptoms will never fire. Rewrite it with the phrases people actually type and the situations that should trigger it, and check it does not overlap ambiguously with a neighbouring skill. As a diagnostic, name the skill explicitly in your prompt — if it works when invoked by name but never fires on its own, the description is the problem. ### Can I use any markdown in the body? Yes. The spec places no format restrictions on the body — headings, tables, code blocks, checklists, whatever communicates the procedure most compactly. Tables earn their space because they encode a lot of decision criteria in few tokens. What matters is not the markup but the mode: write directions the agent can act on, not exposition it can only agree with. ### Where do I put files the skill needs? By convention, executable code goes in scripts/, deeper documentation in references/, and static resources like templates and lookup tables in assets/. None are required, but the conventional names help agents and humans navigate an unfamiliar skill. Reference them with relative paths from the skill root, one level deep rather than nesting pointers inside pointers. ### Does the version field do anything? Not to the agent — version lives inside metadata, which the specification defines as an arbitrary map clients may use for their own purposes. Its value is to your team. A version plus an author makes a library reviewable: you can tell which revision a colleague is running, roll back advice that turned out wrong, and treat a change to a skill the way you treat a change to code. ## Where to go next About to write your first one? [How to write an agent skill](https://skills.wondel.ai/learn/how-to-write-an-agent-skill/) turns this anatomy into a procedure. Still deciding whether a skill is the right container at all — as opposed to an MCP server or a subagent — start with [what is an AI agent skill](https://skills.wondel.ai/learn/what-is-an-ai-agent-skill/). The fastest way to internalise the shape is to read a few real ones. All 50 of ours are MIT-licensed: ``` npx skills add wondelai/skills --all --global ``` Open any `SKILL.md` in the folder it installs to, and you will see the same anatomy: a description built out of the user's own words, a body that fits in one screen of scrolling, and the depth kept one level away until something asks for it. --- # The Agent Skills Standard: One Format, Many Agents > What agentskills.io is, what a shared skill format solves that per-vendor prompt files never could, what the specification actually defines, and how to tell whether an agent supports it — including what's still unsettled. By Michał Jaskólski · Published 2026-08-17 · Updated 2026-08-17 · 6 min read Canonical: https://skills.wondel.ai/learn/agent-skills-standard/ Skills used: jobs-to-be-done, clean-code **TL;DR:** agentskills.io publishes Agent Skills: an open format where a skill is a folder containing a SKILL.md file with name and description in YAML frontmatter, plus optional scripts, references, and assets. Anthropic developed it and released it as an open standard, and dozens of agent products now read it — so one skill folder runs in Claude Code, Codex, Cursor and the rest without being rewritten per vendor. - A skill is a directory with a SKILL.md file; name and description are the only required frontmatter fields, and everything else is optional. - The specification covers the file format, not distribution or installation — each client still picks its own skills directory and its own invocation syntax. - Portability is the reason to invest: a skill written once is an asset that survives switching agents, rather than config locked to whichever tool you use this year. - Check support the empirical way — find the agent in the client showcase on agentskills.io, then read the skills page in its own docs for the directory it reads. - It is a young standard: the format is stable and widely adopted, but allowed-tools is marked experimental and packaging conventions are still diverging. For about two years, teaching an AI coding tool how you work meant writing the same instructions three or four times over. A `.cursorrules` file for one editor, a rules directory for another, a differently-named markdown file for a third. Same content, four formats — and none of it travelled when you switched tools, which in this ecosystem happened roughly every quarter. Agent Skills is the format that ended that. It is deliberately unambitious: a skill is a folder, the folder has a `SKILL.md` file, the file has two required fields. The interesting part isn't the design — it's that a large slice of the agent ecosystem agreed to read the same thing, which is what turns a file format into leverage. ## What is agentskills.io? [agentskills.io](https://agentskills.io) is the home of the Agent Skills specification: the documentation, a reference validator, and a showcase of the clients that support it. The format was originally developed by [Anthropic](https://www.anthropic.com/), released as an open standard, and has since been adopted by a growing list of agent products. Development happens in the open — there's a public [GitHub repository](https://github.com/agentskills/agentskills) and a Discord, and the standard describes itself as open to contributions from the broader ecosystem. Its own framing: a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows, where a skill is a folder containing a `SKILL.md` file with metadata and instructions, optionally bundled with scripts, reference material and templates. If you want the concept before the specification, [what an AI agent skill is](https://skills.wondel.ai/learn/what-is-an-ai-agent-skill/) covers that ground. ## What problem does a shared skill format solve? "Write once, run anywhere" is the short answer, but the alternative wasn't nothing — it was per-vendor prompt files, and they failed in three ways. **They didn't travel.** Instructions written for one tool were dead weight the moment you tried another. Every switch meant a translation pass, and translation passes don't happen; knowledge just gets left behind. **They didn't compose.** A flat rules file competes with itself — everything loads all the time, so your tenth procedure degrades the first nine. Skills load on demand, so the tenth costs almost nothing until you need it. **They had no distribution story.** You can't share a `.cursorrules` file with someone on a different editor. A skill folder is portable by construction, which is what makes public libraries possible at all: [a library of skills](https://skills.wondel.ai/skills/) is only useful because it isn't addressed to one vendor's customers. > The value of a standard isn't the format. It's that the thing you wrote last year still runs in the tool you picked this morning. ## What does the format actually specify? Three things: a directory layout, a small frontmatter schema, and a loading model. **The directory.** A skill is a directory containing, at minimum, a `SKILL.md` file. The spec names three optional conventions — `scripts/` for executable code the agent can run, `references/` for documentation it reads on demand, `assets/` for templates and static resources — and allows any other files you like. **The frontmatter.** Only two fields are required: `name` (lowercase, hyphenated, matching the parent directory name) and `description` (saying both what the skill does and when to use it). Optional fields cover `license`, a `compatibility` string for environment requirements, a free-form `metadata` map, and `allowed-tools`, which the spec explicitly marks as experimental with support varying between implementations. Everything after the frontmatter is plain Markdown with no format restrictions. [What goes in SKILL.md](https://skills.wondel.ai/learn/skill-md-explained/) walks through the anatomy and the exact limits. **The loading model.** Agents load skills through *progressive disclosure*, in three stages. At startup, only each skill's name and description load — roughly 100 tokens apiece — just enough for the agent to know a skill might be relevant. When a task matches the description, the full `SKILL.md` body loads. Bundled files load only when the instructions reach for them. That explains the two practical rules the spec gives authors: keep `SKILL.md` under 500 lines, and treat the `description` as a trigger rather than as documentation. Notice what isn't in it: no install command, no registry, no directory path an agent must use, no runtime API. The spec covers the artifact, not the plumbing. ## Why portability matters when you're choosing what to invest in Writing a good skill is real work — encoding a review checklist, a positioning framework or a deployment procedure well enough that an agent applies it consistently takes an afternoon at minimum. That effort is only worth spending if the result outlives the tool you wrote it in, and under the standard it does. The same folder is read by Claude Code from `~/.claude/skills/`, by Codex from `~/.agents/skills/`, by Cursor from `~/.cursor/skills/`, by OpenClaw and Hermes Agent from their own roots — and by whatever replaces them, provided it reads the format. The skill is a versionable text asset in your repository, not configuration held inside a vendor's product. There's a team dimension too. Most engineering organisations are not standardised on one agent and won't be: one person is in Claude Code, another in Cursor, a third has moved to Codex, and CI runs something else again. A skill committed to the repository is the only form of shared agent knowledge that reaches all of them at once — a governance argument as much as a convenience one. Your review standards, a [clean-code](https://skills.wondel.ai/skills/clean-code/) skill say, live in one reviewable file rather than four people's private settings. > **Prompt** — Use the `jobs-to-be-done` skill to analyse why our customers actually hire our product, working from the interviews in this folder > (https://skills.wondel.ai/skills/jobs-to-be-done/) That skill is one directory containing one `SKILL.md`, and it runs identically in every compatible agent. ## How do I check whether an agent supports it? Three checks, in increasing order of confidence. **Look it up in the client showcase.** agentskills.io maintains a [list of compatible clients](https://agentskills.io/clients) — currently including Claude, Claude Code, Codex and ChatGPT, Cursor, GitHub Copilot, VS Code, Gemini CLI, OpenCode, Goose, Amp, OpenHands, Kiro, Factory, OpenClaw and Hermes Agent, among dozens of others. Each entry links to that client's own skills documentation. **Read the agent's own skills page.** This is where you find the thing the standard deliberately doesn't specify: which directory that agent reads. Claude Code documents `~/.claude/skills/` and `.claude/skills/`; Codex documents `$HOME/.agents/skills` and `.agents/skills`; Cursor documents `.cursor/skills/` and `.agents/skills/` plus fallbacks. If an agent's docs name a skills directory and a `SKILL.md` file, it supports the format in the way that matters to you. **Test it.** Drop a folder with a trivial `SKILL.md` into the documented path, start a session, and ask the agent to use it by name. Two minutes, and it settles the question — including for agents that support the format without appearing in any list. Our [installation guide](https://skills.wondel.ai/learn/how-to-install-claude-code-skills/) covers the per-agent paths in detail. To validate a skill you wrote, agentskills.io publishes a reference library, `skills-ref`, with a `validate` command that checks frontmatter and naming conventions against the spec. ## What's settled, and what isn't Being straight about this matters more than boosterism, because the standard is young. **Settled:** the core file format. A folder, a `SKILL.md`, `name` and `description` required, Markdown body, progressive disclosure as the loading model. That much is stable, documented, and read by a large and still-growing set of clients. A skill written to that shape today will be read tomorrow. **Not settled:** almost everything around distribution. Because the spec covers the artifact rather than how it reaches a machine, the ecosystem has several parallel answers — the [skills.sh](https://skills.sh) CLI, Claude Code's plugin marketplaces, the separate [Agent Plugins](https://agent-plugins.org/) packaging spec, and each agent's own installer. They coexist rather than compete, but expect to meet more than one. **Also not settled:** the edges of the frontmatter. `allowed-tools` is labelled experimental in the spec itself, and individual clients recognise extra fields the spec doesn't define. Sticking to the documented fields is what keeps a skill portable. Invocation syntax is out of scope entirely — slash commands in some agents, a `$skill-name` prefix in others. The honest summary: the format is the settled part and the packaging is the moving part, which is the right way round, since the format is what your writing effort is stored in. ## Frequently asked questions ### Who owns or governs the Agent Skills standard? The format was originally developed by Anthropic and released as an open standard. Development now happens publicly, with a GitHub repository and a Discord for discussion, and the standard describes itself as open to contributions from the broader ecosystem. Beyond that, no formal foundation or steering body is published on agentskills.io — so it is best understood as an open, publicly developed specification with an originating vendor, rather than a standard under independent governance. ### What version of the specification should I target? The specification page doesn't publish a version number; it is maintained as a living document describing the current format. In practice you target the documented fields as they stand: name and description required, license, compatibility, metadata and allowed-tools optional, with allowed-tools flagged experimental. For a machine check, the skills-ref library published alongside the spec has a validate command that checks a skill directory against the current rules. ### Is a skill written for Claude Code portable to other agents? Usually, and the exception is instructive. A skill that sticks to the specified frontmatter fields and plain Markdown instructions works anywhere the format is read. What doesn't travel is client-specific extras: frontmatter keys only one agent recognises, and body features only one product implements. Spec-conformant frontmatter plus ordinary Markdown is portable; anything beyond it is a local enhancement, not part of the skill. ### Does adopting the standard lock me into a particular agent or vendor? No, and that's the point of it. Because the skill is a plain directory of Markdown files kept in your own repository or home directory, moving to a different agent means pointing that agent at the same folder rather than rewriting anything. That is the reverse of the situation the format replaced, where instructions lived in vendor-specific configuration and every tool switch meant a translation pass that in practice never happened. ## Where to go from here To use skills rather than write them, the fastest path is [installing an existing library](https://skills.wondel.ai/learn/how-to-install-claude-code-skills/) and pointing your agent at a task you were doing anyway. To write one, [how to write an agent skill](https://skills.wondel.ai/learn/how-to-write-an-agent-skill/) covers the authoring craft and [what goes in SKILL.md](https://skills.wondel.ai/learn/skill-md-explained/) covers the file itself. If you're weighing the format against a runtime integration, [skills compared with MCP](https://skills.wondel.ai/learn/claude-skills-vs-mcp/) draws that line. Either way, the standard's practical promise is worth restating: what you write is a folder, the folder is yours, and it keeps working when you change tools. --- # How to Write an Agent Skill > A practical guide to authoring a skill that actually fires: choosing a triggerable scope, writing the description as a trigger rather than a summary, keeping the body short with the depth in reference files, and testing whether it changed the output. By Michał Jaskólski · Published 2026-08-17 · Updated 2026-08-17 · 9 min read Canonical: https://skills.wondel.ai/learn/how-to-write-an-agent-skill/ Skills used: clean-code, clean-architecture, refactoring-patterns **TL;DR:** Write the description first and write it as a trigger, not a summary — name the moment, quote the phrases a user would really type, and say where the skill does not apply. Then keep SKILL.md short and push depth into reference files the agent loads on demand. Finally, test twice: once to see whether it fires, once to see whether it changed the output. - The description is the only part of your skill the agent reads before deciding whether to load it — the highest-leverage line in the file, and the one most authors get wrong. - Scope a skill to one recognisable moment with a repeatable procedure; a skill about "good engineering" fires for everything and therefore for nothing. - A skill tells the agent what to do differently — decision rules, an order of operations, things to flag — not what a topic is about. - Keep SKILL.md to a couple of thousand words and move the depth into reference files, with each pointer placed at its point of need. - Test firing and effect separately: a skill that loads but changes nothing is as broken as one that never loads. Anyone who works with a coding agent for a month notices the same thing: it is competent at everything and disciplined at nothing. Ask it to review a pull request and you get plausible remarks; ask it to price a product and you get a reasonable-sounding range. Nothing is wrong, exactly — but a practitioner can tell no method was applied, because none was. A skill fixes that: a folder with a `SKILL.md` the agent loads when it recognises the situation, telling it what to do. Writing one is easy. Writing one that *fires* when it should, and changes the output when it does, comes down to the handful of decisions below. For the anatomy of the file read [what goes in a SKILL.md](https://skills.wondel.ai/learn/skill-md-explained/); for portability, [the agent skills standard](https://skills.wondel.ai/learn/agent-skills-standard/); to run someone else's skills, [how to install Claude Code skills](https://skills.wondel.ai/learn/how-to-install-claude-code-skills/). ## What makes a skill narrow enough to actually fire? Start with a moment, not a topic. An agent picks skills by matching the situation it is in, so the first question is not "what do I know worth writing down" but "what moment do I want to change behaviour in, and would I recognise it in a transcript?" Topics fail this test. A skill called "software engineering best practices" competes with every request that touches code; it will either lose to more specific skills or win constantly and drown out the ones that should have fired. Moments pass it: *I'm reviewing a pull request for readability*. *We need to decide whether business logic can import the ORM*. That is why our library has three code-quality skills where a lazier design would have one. [Clean Code](https://skills.wondel.ai/skills/clean-code/) fires at the level of names, function size and error handling; [Refactoring](https://skills.wondel.ai/skills/refactoring-patterns/) when you have a named smell and need a named transformation; [Clean Architecture](https://skills.wondel.ai/skills/clean-architecture/) when the question is which way a dependency points. Merged, they would be one skill worse at all three jobs. The cheap test, worth running before you write a word of the body: three sentences a real user might type that *should* load your skill, in their words, and three that plausibly might but *should not*. If you cannot fill either list the scope is wrong. Keep both; they become your test suite. Then check there is something to apply — the [rule we use when turning a book into a skill](https://skills.wondel.ai/about/) is that the source must contain a procedure someone else could follow. ## How do you write a skill description that actually triggers? Here is the mechanic that determines everything: when the agent decides which skills are relevant, it sees the name and description of each installed skill and nothing else. The body becomes visible only after the description has won. So the description is not documentation — it is the matching surface, and where most skills quietly fail. The failure looks like this: > Clean Code principles for writing better, more maintainable software. A fine sentence that matches almost nothing, because it describes the skill's subject instead of the user's situation. Nobody types "I would like clean code principles." They type "this function is too long." Compare the description that actually ships with our `clean-code` skill: > Write readable, maintainable code through disciplined naming, small functions, and clean error handling. Use when the user mentions "clean up this code", "this function is too long", "code smells", "naming conventions", "boy scout rule", "single responsibility", or "unit test quality". Also trigger when reviewing a pull request for readability, untangling a messy function, debating comment styles, or improving error-handling patterns. Covers SRP, comment discipline, formatting, and unit testing. For refactoring techniques, see refactoring-patterns. For architecture and dependency rules, see clean-architecture. Five parts, each doing a job. A **capability**, stated as an action. **Quoted trigger phrases in the user's register** — the words a person actually types, informal ones included, not conference-talk vocabulary. **Situations without vocabulary**: "reviewing a pull request for readability" catches someone who describes a task and uses none of your keywords. A **scope claim**. And **routing** — hand-offs to neighbours, which stops three overlapping skills firing on one request. > The description is not a summary of your skill. It is the only thing the agent reads before deciding whether your skill exists. Write it before the body, because naming the trigger moments forces the scope decision you may still be avoiding. Keep it third-person and inside the format's 1024-character limit — a description that hits the ceiling is usually one skill pretending to be two. ## What should a skill say — instructions, not a summary The second most common failure is a body that summarises. A summary tells the agent what a topic is about — and the model has read more about clean code than you have. So interrogate every paragraph with one question: *what will the agent do differently having read this?* If the honest answer is "be slightly better informed," cut it. What survives looks like this: - **Decision rules with a threshold.** "A function that takes a boolean flag is really two functions — split it" is actionable. "Functions should be focused" is not. - **An order of operations.** Our legacy-code skill fixes a sequence: find the change points, find the test points, break dependencies, write characterization tests, *then* change the code. The value is in the ordering, which a summary flattens. - **A rubric that forces a verdict.** Every book skill in our library scores the work 0–10 against a diagnostic table, turning "here are some thoughts" into a number, the failed rows, and a fix for each. - **A mistakes table** — the mistake, why it fails, the fix. The highest-density format we know for behaviour change, because it pre-empts the wrong thing the model would do. What goes: history, biography, case studies, throat-clearing. That is the book's job. > **Prompt** — Use the `clean-code` skill to score our user-management module 0-10, flagging every name that hides intent, every function doing more than one thing, and every function that both mutates state and returns a value, then list the top ten fixes in priority order > (https://skills.wondel.ai/skills/clean-code/) ## How long should a SKILL.md be, and where does the rest go? Short. Every word of a loaded skill competes with the user's actual problem in the context window, and a skill that costs more attention than it returns is a net loss even when its advice is good. A useful target is a couple of hundred lines — our `clean-code` skill is about 220 — with the depth in reference files the agent reads only when it needs them. That skill has six of them, each 1,500 to 3,000 words. Most sessions load none. The part people get wrong is the pointer. A list of reference files at the bottom is a table of contents, and the agent treats it accordingly: it ignores the list or reads everything. What works is an inline pointer at the point of need with a *when* clause — "See `references/error-handling.md` when the code swallows exceptions in bare catch blocks or returns null on failure." That is an instruction with a condition attached, and it fires the same way the skill does. The folder is allowed to be large; the file loaded every time is not. ## What do examples and counter-examples do that rules cannot? Rules are unambiguous in the middle and vague at the edges, which is exactly where the agent operates. Examples fix the edges: a before-and-after pair, or a two-column table — *instead of this, write this*. Two lines of real code settle an argument that three paragraphs of principle leave open. The counter-example is the half most authors skip, and the more important one. The failure you are writing against is never gibberish; it is the plausible, competent-looking output the model produces by default. "Do not write vague code review comments" is unenforceable, because the model does not believe its comments are vague. Showing the exact comment you do not want, beside the one you do, is enforceable. Then ship example prompts. They double as the test cases in the next section. ## Where should a skill say it does not apply? In three places. **In the description, as routing** — the "for X, see Y" clauses are not politeness, they are how a library stays coherent instead of becoming a bidding war where every skill claims every request. **In the body, as an explicit boundary**: a sentence naming the adjacent situation and handing it off saves the agent from applying a framework to a problem it was not built for. And **wherever the method is genuinely contested.** Clean Code and *A Philosophy of Software Design* disagree, in print, about how small a function should be. A skill that flattens that into house doctrine makes the agent confidently wrong in front of someone who knows the literature. Naming the disagreement and when each side applies costs nothing, and is the difference between a framework and a sales pitch. ## How do you test whether a skill is working? Two questions, and conflating them is why authors end up tinkering with a description that was never the problem. **Does it fire?** Open a fresh session and type the sentence a real user would type — not "use the pricing skill," which proves only that it is installed. Your agent will usually name the skill it picked; for certainty, drop a tracer into it ("begin your reply with the word ANCHOR"). Run the three positive sentences, then the three negatives — a skill that fires on everything is a worse neighbour than one that never fires, and only the negatives reveal it. **Did it change the output?** Run the same task twice — once with the skill renamed so it cannot load, once with it installed — and diff. If the answers say substantially the same thing, the skill is decoration, and the fix is in the body rather than the description: you wrote a summary. Use a fresh subagent for each run; a context that has already seen your skill is not a control. The Superpowers project publishes a good write-up of [testing skills with subagents](https://github.com/obra/superpowers/tree/main/skills/writing-skills) worth reading whichever library you write for. Then keep testing after you ship: every time your agent does the wrong thing in a real session, the rule that would have prevented it is the next line of your skill. ## Frequently asked questions ### How long should a skill description be? Two to four sentences: the capability, the quoted phrases, the situations that carry no keywords, and the hand-offs. The format allows 1024 characters and a good one rarely needs them all — pressed against the ceiling usually means you are describing two skills. ### Can one skill reference or invoke another? It can point at one, and it should: a routing clause in the description plus a hand-off in the body. What a plain skill does not do is orchestrate several others — for that, write a skill whose entire content is the sequence, which is what our fourteen guided journeys are. If you need isolated context or separate tool permissions, you are describing a subagent; see [skills vs subagents vs prompts](https://skills.wondel.ai/learn/skills-vs-subagents-vs-prompts/). ### Should I write a skill, or just a better prompt? Write the prompt first. If a paragraph pasted into a conversation gets the output you want, a skill is premature. The case begins when you have pasted it a fourth time, when you want it applied without remembering to invoke it, or when teammates need the behaviour without knowing the incantation. A one-off instruction is a prompt; a rule that applies whenever a recognisable situation appears is a skill. ### Two of my skills keep firing on the same request. How do I fix it? Almost always a description problem with a scope problem underneath. Write out the request that triggered both, decide which skill you wanted, then add the distinguishing situation to that one's description and a hand-off in both. If you cannot decide, the two cover one moment and should be merged. Overlap in subject matter is fine; overlap in trigger situation is not. ### My skill never fires. What is wrong? Check the description first, against real sentences rather than your intentions. The usual causes: it summarises the topic instead of naming the situation, it uses your vocabulary rather than the user's, or the scope is so broad a specific skill wins every time. Also confirm the frontmatter parses — a malformed `name` or `description` silently excludes the skill. If it loads when you name it explicitly but never on its own, the body is fine and the description is not. ## Start with the description Take the order, if nothing else: name the moment, write the description as a trigger, write a body that changes behaviour, move the depth out of the way, then test whether it fires and whether it mattered. Authors who work that way ship something that works on the first or second attempt; authors who write the body first produce a very good document no agent ever loads. Everything in [our library](https://skills.wondel.ai/skills/) is readable on GitHub, so the fastest calibration is to open a skill whose subject you know well and ask whether its description would have caught your last three requests about it. And if your team would rather have this built than build it, [that is what we do](https://skills.wondel.ai/work-with-us/). --- # Claude Code Skills Libraries: An Honest Roundup > A fair comparison of the main open skills libraries for Claude Code and other agents — Superpowers, Corey Haines' marketing skills, Anthropic's official repo, book-derived collections, and ours — with straight guidance on which to install for which job. By Michał Jaskólski · Published 2026-08-17 · Updated 2026-08-17 · 8 min read Canonical: https://skills.wondel.ai/learn/claude-code-skills-libraries/ Skills used: **TL;DR:** The main open skills libraries solve different problems, so the useful question is which job you have. Superpowers changes how your agent builds software; Corey Haines' marketing skills execute go-to-market channels; Anthropic's repo carries the file-format skills and the spec; book-derived libraries, ours included, supply named frameworks. Most people should install two of them, not one. - These libraries are not substitutes — they compose along different axes: process, channel execution, file formats, and domain frameworks. - Install Superpowers if you want your coding agent to plan, test, and review differently; it has nothing to say about pricing or positioning, and does not pretend to. - If your work is marketing execution, Corey Haines' collection is the better fit than any book-framework library, ours included. - If the method you need comes from one specific book nobody has packaged, book-to-skill lets you convert it yourself rather than waiting for a catalogue to cover it. - Star counts move fast and measure attention rather than fit — read three descriptions and one full SKILL.md before installing anything. There are now enough open skills libraries that "which one should I install" is a real question, and the honest answer is that most of them are not competing. They occupy different axes: one changes how your agent writes software, another gives it channel-level marketing playbooks, another ships the file-format handlers, another supplies named frameworks from books. Install the wrong one for your job and you conclude that skills do not work; install two covering different axes and the idea clicks. We maintain one of the libraries below, which is a reason to be suspicious of this page and also the reason it is worth writing. Where another is the better answer, it says so — a roundup that concludes "install ours" is not a comparison. One note: **all star counts here were checked on 17 August 2026 and are approximate.** They move quickly and measure attention rather than fit. If you have not installed a skill yet, [how to install Claude Code skills](https://skills.wondel.ai/learn/how-to-install-claude-code-skills/) covers the mechanics; this page is about choosing. ## Which Claude Code skills library should I install first? The short version, before the detail: - Your **coding agent should work differently** — plan before it codes, test properly, review its own work: [Superpowers](https://github.com/obra/superpowers). - You are doing **marketing execution** yourself: [Corey Haines' marketing skills](https://github.com/coreyhaines31/marketingskills). - You need Claude to **handle documents** — Word, Excel, PowerPoint, PDF — or you are **authoring skills**: [Anthropic's own repo](https://github.com/anthropics/skills). - You want **named frameworks from books** applied to your decisions: a book-derived library, [ours](https://github.com/wondelai/skills) among them. - Your method lives in **one specific book nobody has packaged**: [book-to-skill](https://github.com/virgiliojr94/book-to-skill), and do it yourself. ## Superpowers: a development methodology, not a grab bag [obra/superpowers](https://github.com/obra/superpowers) (roughly 273,000 stars, MIT) is the most-used skills project in the ecosystem and the most opinionated. It is not a catalogue of independent skills; it is a software development methodology assembled from about fourteen composable ones plus the instructions that make the agent actually use them. The pieces are the lifecycle: brainstorming a spec out of a vague request, writing plans, executing plans, subagent-driven development, TDD, systematic debugging, code review, git worktrees, verification before completion, finishing a branch. The bet is different from everything else here. Most libraries wait to be relevant; Superpowers front-loads a behaviour change — the agent stops jumping straight to code, extracts a spec, produces a plan, then works through it with subagents while checking its own output. Long autonomous stretches that stay on plan are the product, not the individual skills. **Install this if** your complaint is about *how* your agent builds software: dives in too fast, skips tests, declares victory early. **Do not install it expecting** domain knowledge — it has nothing to say about pricing, positioning or conversion, and it asserts a strong process, so an existing workflow you like will meet friction. Worth flagging whichever library you choose: its `writing-skills` skill, particularly the [notes on testing skills with subagents](https://github.com/obra/superpowers/tree/main/skills/writing-skills), is one of the better public resources on authoring, and we link it from [our own guide to writing a skill](https://skills.wondel.ai/learn/how-to-write-an-agent-skill/). ## Corey Haines' marketing skills: channel-level execution [coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills) (roughly 44,600 stars, MIT, built by marketer Corey Haines) is about fifty skills covering the surface a founder actually has to operate: SEO audits, programmatic SEO, schema, CRO, signup and onboarding, popups, paywalls, copywriting, cold email, email sequences, social, video, ads, A/B testing, analytics, pricing, launches, PR, referrals, competitor profiling, ASO. The structural idea is a shared foundation: a `product-marketing` skill holds your product, audience and positioning, and the others read it first, so the copywriting skill knows who it is writing to. That is why the collection behaves like a system rather than fifty disconnected prompts. > If the sentence you are about to type is "write the launch email sequence," this is the library that answers it. A framework library will hand you a framework instead — which is not what you asked for. **Install this if** you are a founder or technical marketer doing go-to-market work yourself and want operational playbooks per channel. Its skills are execution-shaped: they produce the artefact. **That is a real difference from ours** — our marketing skills are framework-shaped, applying StoryBrand or the Value Equation to what you already have and arguing with your positioning. For "write me the paywall copy," theirs is the better fit. ## Anthropic's official skills repo: the reference implementation [anthropics/skills](https://github.com/anthropics/skills) (roughly 170,000 stars) plays three roles at once. It carries the document skills that make Claude useful on real files — `docx`, `xlsx`, `pptx`, `pdf` — plus a set covering frontend design, brand guidelines, artifact building and webapp testing. It carries `skill-creator` and `mcp-builder`, the official on-ramps for authoring a skill or an MCP server. And it carries the [Agent Skills specification](https://github.com/anthropics/skills/blob/main/spec/agent-skills-spec.md) and a template, which makes it the reference for the format rather than merely a collection in it. **Install this if** you need the file-format skills — that alone justifies it for most people — or you are writing skills and want the canonical template. **Do not expect** a curated methodology; it is a deliberately broad first-party toolkit, not a point of view about how you work. For what is genuinely specified versus one vendor's convention, see [the agent skills standard](https://skills.wondel.ai/learn/agent-skills-standard/). ## Book-derived skills: the closest peers to what we do This is the category we are in, so treat it with appropriate suspicion and go read the repos. **[virgiliojr94/book-to-skill](https://github.com/virgiliojr94/book-to-skill)** (roughly 22,500 stars, MIT) is not a library at all — it is a tool that turns a technical book you own, in PDF, EPUB, DOCX, Markdown or other formats, into an agent skill, working with Claude Code, GitHub Copilot CLI and Amp. This is the honest answer to the commonest gap in any curated catalogue: your method comes from one specific book and nobody has packaged it. Waiting for someone to cover your book is a worse plan than spending twenty minutes converting it, and it is also the right tool for internal material no public library will contain. The trade-off: generated output is a starting point, not an edited skill, so expect to trim it and rewrite the description. **[DamiMartinez/book-skills](https://github.com/DamiMartinez/book-skills)** (MIT, very small and new — a handful of skills, single-digit stars at the time of writing) is a hand-written one-skill-per-book collection with a design goal we endorse: each skill triggers on the book's *concepts*, not its title, so "how do I validate this before building it" pulls in Build-Measure-Learn without you naming *The Lean Startup*. Its selection leans toward computer-science textbooks nobody else has covered — Russell and Norvig's *Artificial Intelligence: A Modern Approach*, Mitchell's *Machine Learning*, Kernighan and Ritchie's *The C Programming Language*. The size is a reason to read it rather than skip it: eight skills you can audit in an afternoon beats fifty you never will. **[wondelai/skills](https://github.com/wondelai/skills)** is ours (roughly 1,900 stars, MIT — comfortably the smallest audience on this page). It is 51 book frameworks spanning both halves of the problem: engineering (Clean Code, Refactoring, Clean Architecture, Domain-Driven Design) and business, marketing, product and UX (Influence, $100M Offers, StoryBrand, The Mom Test), plus 14 guided journeys that sequence them end to end. Pick it over the other two for coverage across both domains plus the sequencing; pick one of them when your book is one we do not have. Our method is on [the about page](https://skills.wondel.ai/about/), the catalogue on [the skills index](https://skills.wondel.ai/skills/). ## Can I install more than one skills library at the same time? Yes, and most people should. Skills are folders; two libraries do not conflict at the file level unless two skills share a name, and the real interaction is trigger overlap — two descriptions competing for one request. Since these libraries mostly occupy different axes, that overlap is smaller than you would guess: Superpowers plus a book-framework library is a comfortable pairing. The failure mode is quantity. Selection degrades as the number of installed descriptions grows, because the agent chooses from a longer list of near-neighbours. Install globally only what you want everywhere, and scope the rest to the projects that need them. ## How do I judge a skills library before installing it? Four checks, and none of them is the star count. **Read three descriptions.** The `description` field is the part that actually runs; it decides whether a skill ever loads. Descriptions that name situations and quote the phrases a user would type signal a maintained library. Descriptions that summarise a topic signal that nothing will ever fire. **Read one SKILL.md end to end.** Pick the skill whose subject you know best and ask whether it would change what your agent does. Instructions, thresholds and mistake tables change behaviour; a well-written summary of something the model already knows does not. **Check the licence and the last commit.** Most libraries here carry an explicit MIT licence, which matters if you plan to fork or vendor skills into a company repo — but it is not universal, so look before you copy. **Ignore the star count.** It measures how many people heard about a repo, not whether it fits your work. The most-starred project here is useless to a marketer, and the smallest is the only one packaging a couple of classic CS textbooks. ## Frequently asked questions ### If I only install one, which should it be? Pick by what you do most days. Shipping code: Superpowers, the biggest single delta available. Running marketing: Corey Haines' collection. Struggling to get Claude to open a spreadsheet: Anthropic's document skills. Framework libraries like ours are usually the second install, because they change the quality of decisions rather than the mechanics of work — a subtler improvement to notice on day one. ### Do I need a book-framework library if I already run Superpowers? Depends which complaint you still have. Superpowers governs *how* your agent works — planning, testing, reviewing, finishing. A framework library governs *what method it applies* to a decision inside that work. If your agent now plans well and tests properly but still produces pricing with no theory behind it and code reviews with no named smells, that is the gap a framework library fills. If the process is what is still broken, frameworks will not fix it. They compose cleanly, so running both is normal. ### Are these libraries Claude Code only, despite the name? Mostly not. The `SKILL.md` convention is shared across agents, and Superpowers, Corey Haines' collection, book-to-skill and ours all document use with Codex, Cursor and others alongside Claude Code — the differences are in where each agent looks for skills, not in the file. Anthropic's repo is naturally Claude-shaped and some of its skills lean on Claude-specific surfaces. ### Does a bigger catalogue mean a better library? No, and past a point it is a liability. Every installed skill adds a description to the list the agent chooses from, so two hundred skills with mediocre descriptions select worse than twenty with sharp ones. The more useful number is how many of a library's skills you can imagine firing this month. ### Where can I see all of these listed in one place? There is no complete registry, which is part of why this page exists. [agentskills.io](https://agentskills.io) documents the open format these libraries build on, and each repo's README lists its catalogue. If you know a library that belongs here and is not, open an issue on [our repo](https://github.com/wondelai/skills) — we would rather this page be accurate than flattering. ## The useful conclusion There is no best skills library, and any page telling you otherwise is selling something — including, potentially, this one. There is a best library *for the complaint you have right now*: process, channel execution, file handling, or domain method. Name the complaint and the choice makes itself; usually the answer is two libraries covering two axes rather than one covering everything badly. If your complaint is that your agent produces confident work with no method behind it, that is the gap we built [our 51 skills and 14 guided journeys](https://skills.wondel.ai/skills/) to close. If it is one of the other complaints, install the library above that matches — we would rather you solve the problem than use our thing. --- # Clean Code vs Clean Architecture: Same Author, Different Altitude > Clean Code governs what happens inside a function; Clean Architecture governs which way dependencies point between modules. What each one actually rules on, why neither rescues the other, and which to reach for given a specific symptom. By Michał Jaskólski · Published 2026-08-18 · Updated 2026-08-18 · 8 min read Canonical: https://skills.wondel.ai/learn/clean-code-vs-clean-architecture/ Skills used: clean-code, clean-architecture, software-design-philosophy, refactoring-patterns, working-with-legacy-code **TL;DR:** Clean Code rules on what happens inside a function — names, size, error handling, the readability of one file. Clean Architecture rules on which way dependencies point between modules — frameworks and databases at the edge, business rules in the centre. Same author, two altitudes, almost no overlap in what they decide. Most codebases need both, and neither one rescues the other. - The axis is altitude, not quality: Clean Code is about the sentences, Clean Architecture is about the floor plan. - The Dependency Rule is the whole of Clean Architecture's position — source code dependencies may point only inward, and an inner circle must not name anything declared in an outer one. - Readable code inside a badly drawn boundary still rots; it just rots slowly enough to delay the diagnosis. - Pick by symptom: a function nobody can follow is a Clean Code problem, a one-line requirement change that touches nine files is a Clean Architecture problem. - Martin's strongest function-length position is genuinely contested — Ousterhout argues the opposite in print — so treat it as an informed opinion rather than a lint rule. Two books, one author, half a shared title. That is most of the reason people install one expecting the other, then wonder why their agent is renaming variables when they asked where the repository interface belongs. The distinction is **altitude**. [Clean Code](https://skills.wondel.ai/skills/clean-code/) (2008) operates inside a file: naming, function size, how errors are signalled, whether the next reader can follow a method without decoding it. [Clean Architecture](https://skills.wondel.ai/skills/clean-architecture/) (2017) operates between modules: which component may know about which, where the framework sits, whether a business rule can run without a database. One is craft, the other structure, and the failure modes they prevent are unrelated. We publish both as free agent skills and see them installed together constantly, so to be clear: this is not a which-is-better piece. If the format is new to you, start with [what an AI agent skill is](https://skills.wondel.ai/learn/what-is-an-ai-agent-skill/). ## What does Clean Code actually govern? The unit is whatever you can hold in your head at once: a name, a function, a class, a file. The rules are correspondingly local — intention-revealing names, functions that do one thing at one level of abstraction, exceptions rather than return codes, a comment treated as a small failure to express intent in the code itself. It reaches a rung higher in places — the chapter on classes argues for cohesion and the Single Responsibility Principle, the chapter on boundaries for wrapping third-party APIs so their shape does not spread. But the frame never changes: a person reading this file, trying to understand it. The yardstick is comprehension per line. It is therefore the highest-frequency skill in a coding-agent stack: it applies to every diff, and its output is a rename or an extraction — nothing that commits you to a project shape. ## What does Clean Architecture actually govern? The unit is the component, and there is essentially one rule. **The Dependency Rule: source code dependencies may point only inward, toward higher-level policy.** An inner circle must not name anything declared in an outer one — not a class, not a function, not a variable, and especially not a data format the outer layer defines. Entities sit innermost, use cases wrap them, interface adapters wrap those, frameworks and drivers sit at the edge. The half people drop is what happens when control flows *outward* at runtime, which it constantly does — a use case genuinely needs to save a record. Dependency Inversion resolves that without an exception to the rule: the use case declares the interface it needs, an outer layer implements it, and the source dependency still points inward while the call goes out. That move is what turns "the database is a detail" from a slogan into a claim about code. Around it sits the rest: SOLID at class level, component cohesion and coupling principles, boundaries only at points of real volatility, and a rule about what a crossing may carry — plain data, never a framework type or an ORM entity. Note what it says nothing about: your names or your function length. ## Clean Code vs Clean Architecture: the altitude table | | Clean Code | Clean Architecture | |---|---|---| | Unit of concern | Name, function, class, file | Component, layer, boundary | | The core rule | Express intent so the next reader needs no explanation | Source code dependencies point only inward | | What it decides | How something is written | Where it lives and what it may know about | | Reviewed by | Reading a diff | Reading an import graph | | Failure symptom | "I can't tell what this does without reading all of it" | "One requirement change touched nine files" | | Cost of getting it wrong | Slow comprehension, bugs from misread code | Rewrites, untestable core, framework lock-in | | Cost to fix later | Low — local, mechanical, reversible | High — moves code across module lines | | Blast radius of a violation | The file | Everything downstream of the boundary | The "reviewed by" row is why these are separate jobs: a Clean Code violation is caught by anyone reading the diff, while a Dependency Rule violation shows up only in an import graph — which is why it survives review and compounds. > Clean Code is about the sentences. Clean Architecture is about the floor plan. A beautifully written sentence in the wrong room is still in the wrong room. ## Why does clean code inside a bad boundary still rot? Because readability is local and coupling is global, and only one of them determines what a change costs. Take a pricing rule living in an HTTP controller: perfect names, six-line functions, textbook error handling. Now a nightly batch job and an admin tool need the same rule. There is nothing to reuse — it is entangled with a request object — so it gets copied twice and the three copies drift. No naming discipline prevents that, because the problem was never in the prose. It was in an import. That is change amplification, a property of where code sits rather than how it reads, and good craft *hides* it: the code stays pleasant while the cost per change climbs, so the diagnosis arrives late — usually as "we can't test anything without spinning up the whole stack." > **Prompt** — Use the `clean-architecture` skill to find the Dependency Rule violations in this codebase — business rules importing a framework type, an ORM entity or an HTTP request object — and for each one show the interface the inner layer should declare and which outer module should implement it > (https://skills.wondel.ai/skills/clean-architecture/) ## Is a clean architecture full of unreadable functions any better? No, and in one way it is worse. Layering multiplies the files you read per change: one feature now runs through a controller, a request model, a use case, a repository interface, an implementation and a mapper. That trade only pays if each stop is quick to understand. When every layer is a 200-line method with `tmp`, `flag2` and four nested conditionals, you have bought the navigation cost of structure without the comprehension it was meant to fund. The Dependency Rule also offers no protection against a use case that quietly does five unrelated things — it is satisfied by *where* code sits. Whether the thing sitting there is coherent is Clean Code's question, and [Refactoring](https://skills.wondel.ai/skills/refactoring-patterns/) is how you fix it with the tests green. ## Which one should I reach for? Match the symptom Stop at the first line that matches what you are actually seeing. 1. **A function is impossible to follow without reading all of it.** Clean Code — local problem, local fix. 2. **You cannot run a business rule in a test without a web server and a database.** Clean Architecture: your dependencies point the wrong way. 3. **Swapping the ORM, the queue or the payment provider would touch files everywhere.** Clean Architecture. There is no boundary where you assumed one. 4. **The code reads well and a one-line change still touches nine files.** Clean Architecture. Craft is not your bottleneck. 5. **The structure is wrong and the fix must stay reviewable.** [Refactoring](https://skills.wondel.ai/skills/refactoring-patterns/) — named transformations, small steps, tests green in between. 6. **There are no tests and you daren't touch it.** [Legacy Code](https://skills.wondel.ai/skills/working-with-legacy-code/) first; the others assume you can tell when you broke something. One caveat, plainly: four concentric circles, an interface per gateway and a DTO at every crossing can cost more than they save on a CRUD app with one datastore. What survives at any size is the direction rule plus a real boundary at your points of genuine volatility. The folder count is negotiable. ## Do they contradict each other anywhere? Barely — and where they seem to, it is usually Clean Code against a third position rather than against Clean Architecture. The live disagreement is function length. Martin's stance — functions should be small, then smaller — is the most contested claim in either book. John Ousterhout argues the opposite in *A Philosophy of Software Design*: splitting a function purely to shorten it can produce shallow modules, push complexity into the interfaces between the fragments, and leave the reader chasing behaviour across more places than before. Install [Clean Code](https://skills.wondel.ai/skills/clean-code/) and [Software Design](https://skills.wondel.ai/skills/software-design-philosophy/) together and they will disagree about one long, cohesive function — usefully, because you get the argument instead of a silent rule. Clean Code is an opinionated style to push back on, not a linter. Clean Architecture sits out that fight entirely. > **Prompt** — Use the `clean-code` skill to review this module for readability only — intention-revealing names, functions at one level of abstraction, error handling that does not obscure the happy path — and leave the module boundaries and dependency direction untouched > (https://skills.wondel.ai/skills/clean-code/) ## Frequently asked questions ### Are Clean Code and Clean Architecture by the same author? Yes — Robert C. Martin wrote both, Clean Code in 2008 and Clean Architecture in 2017. The shared branding is why they get confused, but they were written nine years apart about different levels of a system, and reading one tells you little about the other's content. ### Which one should I install first? Clean Code, usually, because it applies to every diff your agent produces. Add Clean Architecture when a structural symptom appears — an untestable core, a framework you cannot upgrade — or at the start of a new system, where the direction rule is nearly free and retrofitting it is not cheap. ### Will the two skills conflict if I install both? No — they rule on different decisions, so an agent applying both checks naming and function shape while also checking which module may import which. The conflict people report is Clean Code against Software Design over function length. If your team has settled on other conventions, say so in the prompt. ### Does Clean Architecture include SOLID? Yes — as the class-level principles feeding the component-level ones, with Dependency Inversion doing the heavy lifting for the Dependency Rule itself. Clean Code touches the Single Responsibility Principle in its chapter on classes but does not work through the rest. ### Can code be clean without being well architected? Routinely — it is the most common state of a healthy-looking codebase in trouble. Every file reads well and the pricing logic still lives in a controller, so it cannot be tested without HTTP and gets copied the first time a second caller needs it. Readability makes bad structure survivable, which is precisely what hides it. ## Where to go next If the real question is where a boundary belongs rather than which way it points, that is [Domain-Driven Design vs Clean Architecture](https://skills.wondel.ai/learn/domain-driven-design-vs-clean-architecture/). To apply all of it from a blank page, see [how to design the best possible architecture for a new app](https://skills.wondel.ai/guides/design-the-best-architecture-for-a-new-app/). Both skills are free and MIT-licensed, alongside the rest of the [Code Quality](https://skills.wondel.ai/skills/code/) and [Architecture & Systems](https://skills.wondel.ai/skills/architecture/) collections: ``` npx skills add wondelai/skills --all --global ``` --- # Domain-Driven Design vs Clean Architecture: What Is the Boundary Drawn Around? > DDD draws boundaries around meaning — bounded contexts, ubiquitous language, aggregates. Clean Architecture draws them around dependency direction. How they compose, what each one does that the other cannot, and when DDD is genuinely overkill. By Michał Jaskólski · Published 2026-08-18 · Updated 2026-08-18 · 9 min read Canonical: https://skills.wondel.ai/learn/domain-driven-design-vs-clean-architecture/ Skills used: domain-driven-design, clean-architecture, software-design-philosophy, ddia-systems, 37signals-way **TL;DR:** Both draw boundaries, around different things. Domain-Driven Design decides where a boundary belongs and what the words inside it mean — bounded contexts, ubiquitous language, aggregates. Clean Architecture decides which way dependencies cross it. They compose: DDD's domain layer is what sits in Clean Architecture's core. The recurring mistake is treating a bounded context as a layer. - DDD answers where a boundary goes and what it means; Clean Architecture answers which way dependencies cross it. Neither answers the other's question. - A bounded context is a vertical slice with its own full stack; a layer is horizontal. Conflating them gives you one shared model with four layers painted on it. - The repository is where the two lock together: DDD names it in domain terms, Clean Architecture puts the interface inside the boundary and the implementation outside. - Strategic DDD — contexts, ubiquitous language, core versus generic subdomains — is cheap and pays early. Tactical DDD is where the cost lands, and where small systems should usually stop. - Hexagonal, Onion and Clean Architecture are a family sharing one instinct, not the same architecture — and none of them is DDD. Both are boundary disciplines, and the conflation is expensive because the question each answers is different. Clean Architecture asks **which way dependencies may cross a boundary**. Domain-Driven Design asks **where the boundary belongs and what the words inside it mean**. You can satisfy one perfectly and have nothing to show for the other. The tell is a team that says "bounded context" when it means "layer" — a mistake that yields one shared, overgrown model with a tidy stack of folders around it. We publish both as free agent skills and they are among the most-installed pair in the library, so this is a composition question, not a contest. If the format is new to you, start with [what an AI agent skill is](https://skills.wondel.ai/learn/what-is-an-ai-agent-skill/). ## What does Clean Architecture draw its boundary around? Dependency direction, and almost nothing else. [Clean Architecture](https://skills.wondel.ai/skills/clean-architecture/) turns on the Dependency Rule: source code dependencies may point only inward, toward higher-level policy, and an inner circle must not name anything declared in an outer one — no class, no function, no data format the outer layer owns. Entities innermost, use cases around them, adapters outside, frameworks at the edge. When control flows outward at runtime, you invert it with an interface declared on the inside. That is a rule about *arrows*, and it is deliberately content-free: it has no opinion on whether the central object is an `Order` or a `TransactionRecord`, or whether billing and support share one customer model. Point every arrow correctly at a single overgrown model and you have a textbook-compliant architecture wrapped around the exact structure DDD exists to prevent. ## What does DDD draw its boundary around? Meaning. [Domain-Driven Design](https://skills.wondel.ai/skills/domain-driven-design/) starts from the claim that the hard part is understanding the business, and that the code should say what the business says. Three ideas carry the weight. **Ubiquitous language.** One vocabulary, used identically in conversation, in the model and in the code. When the words match, a whole class of translation bugs stops existing, and a domain expert can read a method name and tell you it is wrong. **Bounded contexts.** A boundary inside which one word has exactly one meaning. `Customer` in billing carries a tax ID and a payment method; `Customer` in support carries a ticket history and a satisfaction score. Fusing them into one omniscient class is the failure the pattern exists to prevent. Where contexts meet you translate, often through an anti-corruption layer. **Aggregates.** A cluster governed by a root that enforces the invariants, making it a transactional consistency boundary as well as a modelling one. Evans defined the root and the rule that outside objects reference only it; the familiar heuristics about small aggregates and referencing others by identity are later tightenings, most associated with Vaughn Vernon rather than the 2003 book. Notice what DDD does not decide: whether the domain layer may import the ORM. Evans isolates the domain; the mechanism that *enforces* that isolation is Clean Architecture's contribution. ## DDD vs Clean Architecture: the boundary table | | Domain-Driven Design | Clean Architecture | |---|---|---| | The question it answers | Where does the boundary belong, and what do the words mean inside it? | Which way may dependencies cross it? | | Boundary shape | Vertical — a bounded context is a full slice of the system | Horizontal — layers within one deployable | | Silent on | Which way dependencies point | What anything means or where to cut | | Between systems | Context mapping: anti-corruption layer, conformist, shared kernel | An adapter, with no view on the relationship | | Who must be in the room | Domain experts — it is a conversation before it is code | Developers — a decision you can make alone | | Verified by | A domain expert reading the code and disagreeing | An import graph | | Cheapest useful subset | The ubiquitous language | The direction rule at one volatile boundary | | Cost when overapplied | Aggregates and mappers around a domain with no invariants | Circles, DTOs and interfaces around a CRUD app | > Clean Architecture tells you which way the arrows point. Domain-Driven Design tells you what the boxes are called and why they exist. ## How do they compose in one codebase? Cleanly, because DDD's domain layer is what Clean Architecture leaves empty at the centre. Martin's inner circle is a *slot*: it holds enterprise-wide business rules and says nothing about their shape, so a transaction script sitting there satisfies the Dependency Rule perfectly. DDD is the richest way to fill it — entities, value objects and aggregates that own their invariants. The repository is where the two lock together. Evans's Repository already declares itself in domain language and hides the persistence technology; Martin's rule puts the interface inside the boundary and its Postgres implementation outside. Same object, two justifications. The anti-corruption layer works the same way: Clean Architecture calls it an adapter and stops, while DDD tells you what the translation is *for*. The failure worth naming is confusing the two boundary shapes. A bounded context is vertical — its own model, its own language, its own full stack, potentially its own database. A layer is horizontal and lives *inside* a context. One `Customer` model with a controller, a service and a repository around it is layers, not contexts, and a fifth folder will not produce any. > **Prompt** — Use the `domain-driven-design` skill to map the bounded contexts in my system — find the words that mean different things to different teams, draw the context map with the relationship type for each pair, and mark where an anti-corruption layer is needed so another team's model does not leak into mine > (https://skills.wondel.ai/skills/domain-driven-design/) ## Is hexagonal architecture the same as Clean Architecture — and is either one DDD? Related, not identical, and no. Ports and Adapters (Alistair Cockburn, 2005), Onion Architecture (Jeffrey Palermo, 2008) and Clean Architecture (Robert C. Martin, 2012 as a post, 2017 as a book) are a family; Martin presents his as a synthesis and names the others as inputs. They share one instinct: the application core defines the interfaces, infrastructure implements them, and the source dependency points inward. They differ in what else they prescribe. Hexagonal is deliberately symmetric — driving ports on one side, driven ports on the other — and says nothing about layering inside the hexagon. Onion adds concentric rings with a domain model at the centre. Clean Architecture adds the entity-versus-use-case split and a rule about what may cross a boundary. None of them is DDD. The association is historical — Vaughn Vernon's *Implementing Domain-Driven Design* uses ports and adapters as its default architecture — but that is a pairing convention, not an identity. You can build a hexagon around a domain model nobody in the business would recognise. ## When is DDD overkill? More often than its reputation suggests. The tactical half — aggregate roots, repositories, factories, value objects, an application layer, mapping between domain and persistence models — multiplies files and indirection, fights most ORMs, and needs a team fluent in the vocabulary. Against a domain with real invariants that is an excellent trade; against a form saved to a table it is ceremony, and an aggregate that enforces nothing is a class with a list inside it. The guard is DDD's own strategic layer, which is the half people skip. Separate the core domain — the part that is actually your advantage — from the generic subdomains anyone could buy, model the core deeply, and buy authentication, email and payments rather than hand-crafting a commodity. If nothing qualifies as core, that is your answer about the tactical patterns. Strategic DDD is a different bargain: naming things the way the business names them costs nothing, and noticing that `Customer` means two things is worth doing on day one, when the split is a rename rather than a migration. It is the aggregate machinery that has to justify itself — [The 37signals Way](https://skills.wondel.ai/skills/37signals-way/) is the counterweight when it cannot. > **Prompt** — Use the `clean-architecture` skill to take the domain model I already have and place it under the Dependency Rule — say which types are entities and which are use cases, where each repository interface should be declared versus implemented, and exactly what is allowed to cross each boundary > (https://skills.wondel.ai/skills/clean-architecture/) ## Which one do you need first? Stop at the first line that matches. 1. **Two teams use the same word for different things and the translation keeps producing bugs.** DDD, strategic half. 2. **You cannot run a business rule in a test without the database and the web framework.** Clean Architecture. Your model is not the problem yet. 3. **One class has forty fields because three departments each needed six.** DDD — a missing context boundary, not a missing layer. 4. **You are about to split into services.** DDD first to find the seams, Clean Architecture second for the inside of each one. Splitting before you know the seams is the expensive order. 5. **The domain is genuinely CRUD and every word means one thing.** Keep the direction rule and the ubiquitous language; skip the tactical patterns. If the modules are multiplying anyway, that is a complexity question for [Software Design](https://skills.wondel.ai/skills/software-design-philosophy/). ## Frequently asked questions ### Is a bounded context the same as a layer? No, and it is the most consequential confusion of the two. A bounded context is a vertical slice — its own model, its own language, its own stack of layers, potentially its own database. A layer is horizontal and sits inside a context. Layers separate technical responsibilities within one model; contexts separate models from each other. ### Do I need DDD to use Clean Architecture? No. Clean Architecture works over any core, including procedural transaction scripts — the Dependency Rule is satisfied by placement alone. What you lose is a principled answer to where the boundaries go, which is why systems with a clean layer diagram and one enormous shared model are so common. ### Are aggregates, domain events and CQRS all part of DDD? Aggregates are, from the 2003 book. Domain events entered the pattern language later, and CQRS and event sourcing grew up alongside DDD rather than inside it — commonly paired, not required. Treat the tactical catalogue as a menu you order from once strategic design says the domain is worth it. ### Which should I learn first? Clean Architecture, for the faster payback: one rule, verifiable in an import graph, useful on the smallest project. DDD earns its keep when people already argue about what things mean — and if that is happening now, invert the order, because no amount of correct dependency direction settles an argument about what `Customer` is. ## Where to go next If your question is craft rather than boundaries, the neighbouring comparison is [Clean Code vs Clean Architecture](https://skills.wondel.ai/learn/clean-code-vs-clean-architecture/). Applied from scratch, in sequence: [how to design the best possible architecture for a new app](https://skills.wondel.ai/guides/design-the-best-architecture-for-a-new-app/). Both skills are free and MIT-licensed, alongside the rest of the [Architecture & Systems skills](https://skills.wondel.ai/skills/architecture/): ``` npx skills add wondelai/skills --all --global ``` --- # Lean Startup vs Design Sprint: Which One Should You Run? > One is a loop with no end date; the other is five days with a fixed agenda. What each actually produces, when a sprint is the cheaper way to buy the answer, when it is theatre, and how the two compose. By Michał Jaskólski · Published 2026-08-18 · Updated 2026-08-18 · 8 min read Canonical: https://skills.wondel.ai/learn/lean-startup-vs-design-sprint/ Skills used: lean-startup, design-sprint, mom-test, continuous-discovery **TL;DR:** A Design Sprint is one five-day event that answers a design question — will people understand this, choose it, get through it — with a prototype and five customer interviews. Lean Startup is a permanent Build-Measure-Learn loop that answers whether the business works, using experiments, cohorts and a pivot threshold set in advance. The sprint buys a decision; the loop buys a direction. - The axis is cadence and commitment: a sprint is a time-boxed week with a fixed agenda, while Build-Measure-Learn is a discipline that never finishes. - A sprint is the cheaper answer when the risk is comprehension, choice or flow — something a person can react to on a screen in front of you. - A sprint is theatre when the risk is demand: a facade prototype cannot be bought, abandoned or renewed, so Friday cannot tell you whether anyone will pay or come back. - They compose cleanly — a sprint works as one deliberate turn of the loop, provided you wrote down beforehand what result would change the plan. - The Mom Test governs the quality of what customers tell you in either process; Continuous Discovery is the weekly rhythm that keeps evidence arriving between them. Both methods are sold with the same sentence — validate before you build — and both usually get chosen on temperament rather than on risk. A deadline makes a sprint feel decisive; enough startup reading makes a loop feel rigorous. Neither choice was made against the thing that could actually kill the project. The load-bearing distinction is **cadence and commitment**. Eric Ries's Build-Measure-Learn is a discipline with no end date: name the leap-of-faith assumption, build the smallest thing that could disprove it, measure a number chosen in advance, decide to pivot or persevere, repeat. Jake Knapp's Design Sprint is a single event with a fixed agenda: Monday to Friday, one room, a prototype by Thursday evening, five customers on Friday, an answer before the weekend. One is a loop. The other is a box. Both sit in our [product skills](https://skills.wondel.ai/skills/product/) library, and an agent asked to "help us validate this" will produce either while rarely asking which risk you are carrying. New to the format? [What an AI agent skill is](https://skills.wondel.ai/learn/what-is-an-ai-agent-skill/) covers it; this piece is about the methods. ## What does each one actually produce? A [Design Sprint](https://skills.wondel.ai/skills/design-sprint/) produces a decision and a list of specific confusions. The prototype is disposable; the durable output is the write-up — what all five testers understood, where each of them hesitated, which direction survived contact. Even when the concept dies on Friday, that list is worth the week. [Lean Startup](https://skills.wondel.ai/skills/lean-startup/) produces validated learning and a pivot-or-persevere call: a hypothesis with a threshold attached, an MVP that is frequently not software, and instrumented behaviour over time — cohorts, one actionable metric nominated before the experiment ran, and innovation accounting that shows progress while revenue is roughly zero. The epistemic gap matters more than either artefact. A sprint gathers five people reacting to a facade, once, in a room where they know they are watched. The loop gathers behaviour: what people did unmoderated, across a cohort, over weeks. Reactions are excellent evidence about comprehension and terrible evidence about demand. ## Lean Startup vs Design Sprint: the comparison table | | Design Sprint | Lean Startup | |---|---|---| | Shape | One five-day event, hour-by-hour agenda | A loop with no end date | | Costs | Seven or fewer people for a week, plus recruiting five customers | Whatever the experiment costs — often a page and a week of traffic | | Answers | Will people understand this, choose it, get through it? | Will people keep doing it, pay for it, come back? | | Evidence | Five moderated interviews against a facade prototype | Instrumented behaviour, cohorts, one actionable metric | | Risk it attacks | Desirability at first glance, and usability | Sustained desirability, and viability | | Typical failure | The question was not worth a week, or Friday gets dropped | No threshold was written, so every result reads as encouraging | | Ends | Friday | It does not | Neither column is the rigorous one. A sprint with a leading interview script produces confident nonsense faster than any method available to you; a loop with no stated threshold produces a permanent state of promising early signals. ## When is a Design Sprint the cheaper way to get the answer? Twenty-five person-days is a real cost, and small next to a quarter spent building the wrong screen. Four conditions make the trade obvious: - **The risk has a visible surface** — comprehension, choice between options, getting through a flow. If a person could react to it on a screen, the machinery fits. - **Two or more plausible directions, and an argument that has stopped producing new information.** Wednesday hands the tie-break to one named person on purpose — the part a debate cannot do for itself. - **Five of the right customers are reachable this month.** Recruiting is the underestimated constraint, and the one you can start before Monday. - **Someone in the room can act on Friday's answer.** Output that gets re-litigated by a committee has saved nobody anything. The underrated benefit is front-loading: Monday forces you to write down what you are trying to learn, specifically enough that Friday can contradict it. ## When is a Design Sprint theatre? When the real risk is demand rather than design. Five people react to a facade in a session where they were recruited, scheduled and thanked. They are being asked for an opinion, not for money. A prototype cannot charge a card, fail to be renewed, be found by a stranger through a search box, or be quietly abandoned in week three. If your open question is whether anyone pays, returns after the novelty, or arrives through an affordable channel, Friday hands you five articulate, unrepresentative reactions and a deck with the word *validated* on it. > A facade prototype can be misunderstood. It cannot be bought, renewed or abandoned — which is exactly why it settles design questions and cannot settle demand. Three other tells: the decision was already made and the week exists to manufacture consent; nobody owns what happens after Friday; or the sprint is the only discovery the team does all year. The guard is cheap — before Monday, write down the result that would stop the build. If no outcome would change what you do next, spend the week talking to customers instead. ## Can you run a Design Sprint inside Build-Measure-Learn? Yes, and this is the honest relationship between them. A sprint is one turn of the loop with a fixed agenda and an unusually rich Measure step. Ries's loop is deliberately silent about *how you decide what to build* — build the smallest thing that could disprove the assumption, it says, but not which smallest thing. Monday through Wednesday fills that gap. Three compositions work: use the sprint to **choose** which experiment is worth instrumenting; run the **loop after** a sprint, because Friday's patterns are hypotheses about behaviour rather than measurements of it; or drop a sprint **into a stalled loop**, when three iterations have moved nothing and the problem is the concept rather than the increments. Two do not. A sprint followed by nothing — a decision with no way of finding out whether it was right. And a loop with no design step, which produces thin ships that each fail for a reason nobody can name afterwards. > **Prompt** — Use the `lean-startup` skill to turn our sprint findings into a build-measure-learn plan — name the leap-of-faith assumption the prototype did not test, the smallest experiment that could disprove it, the single actionable metric, and the pivot-or-persevere threshold, all written down before we ship anything > (https://skills.wondel.ai/skills/lean-startup/) ## Where do The Mom Test and Continuous Discovery fit? All four get confused because all four say "talk to customers." They govern different things. [The Mom Test](https://skills.wondel.ai/skills/mom-test/) governs **question quality**, and it is not a process at all — it is a filter applied to sentences. It belongs to Friday's interview script exactly as much as to a problem interview before the loop starts. Neither method has any defence against a leading question; a badly written script just gets you to the wrong conclusion by Friday evening rather than next quarter. [Continuous Discovery](https://skills.wondel.ai/skills/continuous-discovery/) governs **cadence**. A sprint is an event and Build-Measure-Learn has no schedule attached; Torres supplies the rhythm that stops the year after a successful sprint from being evidence-free. So: The Mom Test is the instrument, Design Sprint and Lean Startup are two schedules for using it, and Continuous Discovery keeps a schedule from lapsing when the quarter gets busy. ## So which one should you run? Work down the list and stop at the first line that matches. 1. **Your interview notes are full of compliments.** Neither, yet — both will convert a leading question into a confident wrong answer. 2. **Nobody outside the building has reacted to the concept, and a large build starts soon.** Design Sprint. 3. **Three plausible directions and an argument that has stopped moving.** Design Sprint, for the Decider more than the prototype. 4. **The question is whether people pay, retain, or come back.** Lean Startup. No prototype answers it. 5. **You launched, the chart goes up, and nobody can say whether the business works.** Lean Startup — cohorts and one actionable metric instead of a growing total. 6. **You need an answer like this most weeks.** Continuous Discovery; a repeated sprint is an expensive habit. 7. **You cannot say what result would change your mind.** Neither. Write the threshold down first. ## Frequently asked questions ### Are Lean Startup and Design Sprint compatible, or do you have to pick one? Compatible, at different grain. The sprint is a five-day container for one design question; Build-Measure-Learn decides whether the business underneath it works. Run the sprint as one turn of the loop — use it to choose what to build, then instrument the thin version and watch real behaviour. What fails is treating the sprint as a substitute, because a Friday verdict from five people is not a measurement of demand. ### Can a Design Sprint replace an MVP? No, though both involve something fake that customers see. A facade prototype exists to be reacted to in a moderated session; an MVP exists to be used, unsupervised, by people who chose it. The prototype can show that four of five testers never found the pricing. Only the MVP shows that nobody renewed. ### Is five customer interviews really enough? For the narrow claim, largely yes: a handful of moderated sessions surfaces most of the comprehension and usability problems in an interface, and Friday finds patterns across five rather than producing a statistic. Generalising it to demand is the mistake — five recruited people tell you nothing reliable about conversion, willingness to pay or retention, and any percentage derived from them is decorative. ### What if we cannot get five days of everyone's calendar? Shortened variants circulate widely, and compressing the sketching and decision days is survivable. What does not compress is Monday's framing — a sprint aimed at the wrong target answers the wrong question faster — and Friday. If you can only secure two days, you have a workshop, and three well-asked customer conversations would teach you more. ### What does an AI agent actually add to either method? Preparation, arithmetic, and one discipline that is hard to impose on yourself: pre-registration. Ask for the sprint questions, the target map, the prototype brief and the interview script; ask for the hypothesis, the metric definition and the pattern write-up. Then make it state the threshold before the experiment runs and hold you to it after, because the commonest failure in both methods is a result reinterpreted as encouraging once it arrives. ## Where to go next If the answer is the week, [Design Sprint](https://skills.wondel.ai/skills/design-sprint/) carries the schedule and writes the materials. If it is the loop, [Lean Startup](https://skills.wondel.ai/skills/lean-startup/) carries the MVP types, innovation accounting and the pivot taxonomy. If the honest answer was "our evidence is bad," start with [The Mom Test](https://skills.wondel.ai/skills/mom-test/); if it was "we only do this once a year," [Continuous Discovery](https://skills.wondel.ai/skills/continuous-discovery/). Our library packages canonical engineering and business books as agent skills — free, MIT-licensed, one command: ``` npx skills add wondelai/skills --all --global ``` And if you would rather have the discovery loop and the agent that runs it built for your team, [that is the work we do](https://skills.wondel.ai/work-with-us/). --- # Positioning vs Messaging: Which One Is Actually Broken? > Positioning is the context you choose; messaging is the words that follow from it. Why homepage rewrites so often change nothing, a symptom test that tells you which one is broken, and the order Obviously Awesome and StoryBrand run in. By Michał Jaskólski · Published 2026-08-18 · Updated 2026-08-18 · 8 min read Canonical: https://skills.wondel.ai/learn/positioning-vs-messaging/ Skills used: obviously-awesome, storybrand-messaging, made-to-stick **TL;DR:** Positioning is the context you put the product in — the category, the alternatives a buyer weighs you against, the customer who cares most. Messaging is the language that follows from that choice. The two get confused because bad positioning has only one visible symptom, and it looks exactly like bad copy. Settle the context first, then write. - Positioning is a decision about context; messaging is an artefact made of words — and customers only ever see the artefact, which is why the wrong one keeps getting fixed. - The buyer's first question is always compared to what, and if you do not answer it they pick a frame themselves, usually one you lose in. - Symptom test: confusion about what it is means positioning; understood-but-unmoved means messaging; forgotten by Thursday means memorability. - Run them in order — Obviously Awesome, then StoryBrand Messaging, then Made to Stick as an editing pass — because each inherits the answer above it. - A positioning change that leaves the site unchanged never shipped, and a copy rewrite that swaps the category noun repositioned you without a meeting. The most expensive week in early-stage marketing is the one spent rewriting the homepage when the real problem is that nobody can tell what the product is. It feels like progress, and three months later conversion sits where it was, so the team schedules another rewrite. Two or three rewrites a year with nothing moving is not a copywriting problem. It is a diagnosis problem. The distinction is **what you are** versus **how you say it**. Positioning is the context you place the product in: the category, the alternatives a buyer weighs you against, the segment that cares disproportionately. Messaging is the language that follows — headline, one-liner, deck, emails. Positioning decides which words could possibly be right; messaging picks them. This is the most common confusion in our [marketing skills](https://skills.wondel.ai/skills/marketing/) library, and it has a structural cause: positioning is invisible. No customer ever reads your canvas. A positioning failure can only reach you through copy that does not land — so it arrives disguised as a copy problem and gets a copy fix. ## What is positioning, and what is messaging? Nobody evaluates anything in a vacuum. People understand new things by reference to things they already know, so the first question in a buyer's head is not what does this do but *compared to what*. That frame is settled before a word gets written. Positioning is where you settle it deliberately. The alternative is not "no positioning" — it is positioning assigned by someone else. If you do not supply the frame, the visitor builds one from your pricing page's shape, from the first competitor they have heard of, from the category your job postings imply. Default positioning is still positioning; it just belongs to whoever guessed. Messaging assumes that question is answered and gets on with the next two: why should I care, and what do I do now. It is the only layer customers see, which is why it absorbs all the attention and why it makes such a poor diagnostic. ## Positioning vs messaging: the comparison table | | Positioning | Messaging | |---|---|---| | What it settles | The category, who you are for, what you are weighed against | What a visitor reads, in what order, with what next step | | The buyer's question | What is this, compared to what? | Why should I care, and what do I do now? | | Where it lives | A company decision — a canvas, a statement, a sales narrative | Homepage, deck, one-liner, emails, ads | | Who has to agree | Founders, sales and product | Marketing can ship it on a Tuesday | | Built from | What customers switched from, win/loss reasons | The positioning above it, plus the customer's problem and stakes | | How you test it | The team fills the canvas independently and compares | Comprehension first, then conversion | | Cost to change | High — pricing, packaging and sales narrative move with it | Low — a page and an afternoon | | The skill | [Obviously Awesome](https://skills.wondel.ai/skills/obviously-awesome/) | [StoryBrand Messaging](https://skills.wondel.ai/skills/storybrand-messaging/) | Read the cost row twice, because it explains the loop teams get stuck in. Messaging is cheap to change and expensive to evaluate — you need traffic and weeks. Positioning is expensive to change and cheap to evaluate. So the cheap diagnostic gets skipped and the expensive one runs in circles. ## Why does rewriting the homepage rarely fix anything? Because the copy is downstream, and better writing against the wrong frame is worse than mediocre writing against the right one — you have made the wrong comparison easier to make. If a visitor has decided you are a cheaper version of the category leader, crisper prose gets them there faster. - **You get scored on someone else's checklist.** In the wrong category you are measured against features you deliberately do not have, and what you are genuinely better at never appears on the sheet. - **Your differentiators read as noise.** An attribute is unique only relative to a named set of alternatives. Without that set, a real capability lands as one more feature claim among ten. - **The rewrite is unfalsifiable.** Conversion does not move, nobody can say whether the words or the frame was at fault, so the next fix is another rewrite. > Bad positioning has exactly one symptom, and it looks exactly like bad copy. That is why it keeps getting the wrong treatment. ## Is my problem positioning or messaging? A test that costs an afternoon. Take the last ten conversations with people who did not buy — sales calls, demo no-shows, replies to outbound, a stranger reading your homepage aloud — and sort what they actually said. **Positioning, if you hear:** - "So what would we be replacing?" — asked *after* a complete demo, by someone who followed all of it. - The prospect compares you to something irrelevant, and half the call goes on correcting the frame. - You win when a named competitor is in the deal and lose when nobody is — beaten by a spreadsheet, or by carrying on as they are. - Two colleagues describe the product to a stranger and produce two different products. **Messaging, if you hear:** - People restate what you do accurately, and still do nothing. - "I got it, I just could not see why it mattered for us." - Visitors read to the bottom and there was never one obvious thing to do next. - The copy is entirely accurate and made of abstractions. **Neither, if you hear:** someone who had a genuinely good call last week cannot repeat one specific thing about you. Compressed to a line: a failure of *what* is positioning, a failure of *so what* is messaging, and a failure of *what were they called again* is memorability. One caveat, because the test is cleaner than reality: a positioning problem usually has a messaging problem sitting on top of it, since copy written against an unresolved frame tends to be structurally bad too. Fix the frame first anyway — twice in the right order costs less than four times in the wrong one. ## What do Obviously Awesome and StoryBrand actually do? [Obviously Awesome](https://skills.wondel.ai/skills/obviously-awesome/) carries April Dunford's method, which works from the outside in rather than from your feature list. It starts with **competitive alternatives** — what your best customers would genuinely do if you vanished, very often a spreadsheet or nothing — isolates the **attributes** only you have relative to that set, translates those into the **value** they unlock, identifies the **customers** who care disproportionately about it, and chooses the **market category** that makes all of it obvious instead of requiring explanation. Relevant trends sit alongside as an optional extra, with a warning attached: a trend bolted onto positioning you have not done makes buyers more confused, not less. The book also separates a few positioning styles — win the category you are in, dominate a subsegment of it, or create a new one — and is clear the third is the expensive option, because you pay to teach a market that the problem exists before you can sell the cure. > **Prompt** — Use the `obviously-awesome` skill to pressure-test our positioning before we touch any copy — list the competitive alternatives our best customers would use if we vanished, mark which of our attributes are genuinely unique against that set rather than against a competitor we picked, and flag every answer that is a guess needing customer interviews > (https://skills.wondel.ai/skills/obviously-awesome/) [StoryBrand Messaging](https://skills.wondel.ai/skills/storybrand-messaging/) carries Donald Miller's SB7 framework, and assumes the frame is settled. It organises the words as a story: a character wants something, has a problem, and meets a guide who shows empathy and authority; the guide gives them a plan and calls them to action, and the story makes plain what failure costs and what success looks like. The parts that do the most work are the internal problem — how the situation makes the buyer feel, not just what it breaks — and the single direct call to action. The thing to hold onto is that SB7 takes positioning as an input it does not produce: hand it the wrong category and it will build a beautifully structured page around it. ## Where does Made to Stick fit? A third thing, orthogonal to both. [Made to Stick](https://skills.wondel.ai/skills/made-to-stick/) asks whether one idea survives a single hearing and gets repeated accurately by someone with no incentive to remember it — the Heaths' six traits are Simple, Unexpected, Concrete, Credible, Emotional and Stories. You can be correctly positioned, clearly messaged and completely forgettable. That is expensive in any deal with more than one person in it, because your champion has to retell your pitch from memory to a room you were never in. The usual diagnosis is the curse of knowledge: once you know something you cannot imagine not knowing it, so you speak in abstractions that felt concrete to you years ago. Run it as a pass over finished copy — it is a scoring instrument, and it needs something to score. So: positioning decides the comparison, messaging decides the sentence, and Made to Stick decides whether the sentence survives the week. ## What order do you run them in? Positioning, then messaging, then memorability. Each inherits the answer above it, and inverting any pair wastes the work below. > **Prompt** — Use the `storybrand-messaging` skill to write the BrandScript and homepage from the positioning I am pasting below — keep the category and the competitive alternative exactly as stated rather than inventing better-sounding ones, name the internal problem as well as the external one, and give me one direct call to action instead of four soft ones > (https://skills.wondel.ai/skills/storybrand-messaging/) Two things break the order, and both are quiet. **Positioning that never ships:** a finished canvas is not a change, and if the homepage, the deck and the first sixty seconds of the demo still say what they said last quarter, you ran a workshop rather than a repositioning. **Messaging that quietly repositions:** a writer who swaps the category noun in your headline has made a positioning decision without the meeting, and sales will find out on a call. The corollary is a budgeting one. When positioning genuinely changes, every downstream asset is invalidated at once. That cost belongs in the decision, not in the surprise three weeks later. ## Frequently asked questions ### Can you have good messaging and bad positioning at the same time? Yes, and it is the most expensive combination available. Clear copy against the wrong frame converts — it just converts the wrong people. They arrive expecting the category you implied, judge you on that category's criteria, and either bounce at the demo or churn in month four. Rising signups with falling retention, and a sales team that keeps re-explaining what the product is, is a positioning signature. ### Do I need customers before I can do positioning? You can position pre-launch, but know what you are trading. The strongest input is what your happy customers actually switched from, and before launch there is no such set — so the alternatives, the segment and the category are hypotheses, and everything downstream inherits the guess. Name the alternatives as they exist today, including doing nothing, mark each answer as evidence or assumption, and revisit after the first fifteen or twenty real conversations. ### How often should positioning change? Rarely, and only when evidence forces it. Three legitimate triggers: you keep winning in a segment you never targeted, the reasons in your win/loss notes stop matching your canvas, or the category you chose gets redefined by somebody else's marketing budget. A new quarter, a new head of marketing and a competitor's launch are not triggers. Every change invalidates the assets built on it, so the real cost is the rewrite rather than the decision. ### Our product does several things for several audiences. How do we position that? Pick the segment where you win most decisively and position for it, rather than describing the union of everything you do. A page written for three audiences is read carefully by none, because each reader must first work out which third applies to them. If the segments genuinely need different alternatives, categories and buying criteria, the answer is separate narratives and separate pages. A blended page usually means the company has not chosen, and choosing is what positioning is. ### How do I know whether a messaging rewrite worked? Test comprehension before conversion, because it is faster and more informative. Show the page to someone outside your market for five seconds and ask what you offer, how it would make their life better, and what they are meant to do next — Miller's grunt test. If they cannot answer all three, the copy has not shipped yet. If they can and conversion still has not moved, your problem is elsewhere: the frame above it, or the offer underneath it. ### Can an AI agent do positioning and messaging in one pass? It will, and that is precisely the failure mode. Ask for a homepage and you get one, complete with a confident category noun nobody chose and competitive alternatives inferred from your own description. Make the positioning a separate, reviewed artefact first — with guesses marked as guesses — then hand it to the messaging pass as an explicit input, and tell it not to improve the category on your behalf. ## Where to go next If the diagnosis was positioning, [Obviously Awesome](https://skills.wondel.ai/skills/obviously-awesome/) runs the canvas and tells you which answers need customer interviews first. If it was messaging, [StoryBrand Messaging](https://skills.wondel.ai/skills/storybrand-messaging/) writes from the frame you give it. If it was recall, [Made to Stick](https://skills.wondel.ai/skills/made-to-stick/) scores the six traits and fixes the two dragging the message down. All three live in [marketing skills](https://skills.wondel.ai/skills/marketing/). Our library packages canonical business and engineering books as agent skills — free, MIT-licensed, one command: ``` npx skills add wondelai/skills --all --global ``` And if the positioning work needs someone in the room with your sales calls and your win/loss data rather than a prompt, [that is the work we do](https://skills.wondel.ai/work-with-us/). --- # How to Create a New Business with AI Skills > A step-by-step playbook for going from idea to validated, positioned, monetizable business — using AI agent skills drawn from Lean Startup, The Mom Test, JTBD, and more. By Michał Jaskólski · Published 2026-06-25 · Updated 2026-08-08 · 18 min read Canonical: https://skills.wondel.ai/guides/create-a-new-business-with-ai-skills/ Skills used: lean-startup, mom-test, jobs-to-be-done, design-sprint, good-strategy-bad-strategy, blue-ocean-strategy, obviously-awesome, hundred-million-offers, monetizing-innovation, crossing-the-chasm **TL;DR:** You create a new business with AI skills by earning evidence before spending runway: find the customer's real job with Jobs to Be Done, validate it through Mom Test interviews, test the riskiest assumption in a five-day Design Sprint, then sharpen strategy, positioning, offer, and price — ten skills, one deliberate order, from idea to beachhead. - The expensive mistakes happen before the first line of code — validate demand, positioning, and price before you build anything. - Order matters: discovery (Jobs to Be Done, The Mom Test) precedes validation (Design Sprint, Lean Startup), and both precede strategy, positioning, and pricing. - Never pick a price by copying a competitor — test willingness to pay while the product is still a concept, as Monetizing Innovation prescribes. - Install the full stack with npx skills add wondelai/skills --all --global, then run one skill per phase and loop back when the evidence says so. Most new businesses do not fail because the founder could not build the thing. They fail because the founder built the wrong thing, for nobody in particular, priced on a guess, and explained in a way prospects never understood. The code worked. The business did not. The expensive mistakes were all made *before* the first line of code — in the months when nobody was watching and everything felt like progress. This guide is for the founder standing at exactly that moment: a raw idea, some conviction, and a finite amount of runway and energy. The temptation is to start building immediately, because building feels productive and talking to strangers feels slow. Resist it. The single highest-leverage thing you can do right now is to compress the cycle between *I think this is true* and *I have evidence it is true* — and to do that compression across demand, strategy, positioning, and price, not just product. That is what this stack of ten AI agent skills does. Each one packages a battle-tested business book into something your coding agent can actually run. Used together, they form one continuous workflow: discover the real job customers are trying to get done, talk to them without poisoning the data, prototype and test the riskiest assumption in a week, then — only once demand is real — sharpen your strategy, find uncontested space, nail your positioning, build an offer people feel stupid refusing, price it against validated willingness to pay, and pick the beachhead you will dominate first. The order matters. Demand before building, strategy before scale, price before product. You will not use all ten in a single afternoon. You will move through them roughly in sequence, looping back as evidence accumulates. By the end you should have something most first-time founders never get: a business you can defend on every axis — *who it is for, what job it does, why it is different, why it wins, what it costs, and why anyone would pay.* Let's build it. > You can be wrong about your product in a week, or wrong about your business in a year. Pick the week. ## Phase 1 — Find the real job before you fall for your solution The first mistake is starting with the solution. You have an idea — "an app that does X" — and every subsequent decision quietly bends toward justifying it. The fix is to start one level deeper, with the [Jobs to Be Done](https://skills.wondel.ai/skills/jobs-to-be-done/) skill, which is built on a single uncomfortable truth from [*Competing Against Luck*](https://www.christenseninstitute.org/theory/jobs-to-be-done/): customers do not buy products, they hire them to make progress in a specific circumstance. Your job is to find that progress before you fall in love with your way of delivering it. A "job" is not a goal ("be healthy") and not a task ("click the button"). It is progress in context: *When I'm commuting alone, I want something to occupy me and blunt my hunger, so I'm not starving by lunch.* Notice that statement never mentions a milkshake — or your product. That is the point. A well-formed job statement (`When [circumstances], I want to [progress], so I can [outcome]`) is solution-agnostic, which means it survives even when your first idea dies. And every job has three inseparable dimensions: functional (what they need to do), emotional (how they want to feel), and social (how they want to be seen). Miss the emotional and social ones and you will build something that works on a spec sheet and dies in the market. The other thing JTBD forces you to confront early is your *real* competition. It is almost never the other apps in your category. It is the spreadsheet, the sticky note, the intern doing it by hand, and — most often — non-consumption, the customer simply doing nothing. If you cannot beat "doing nothing," no feature will save you. Have your agent map the full competitive set around the job, including the workarounds people have hacked together, because those workarounds are a map of unmet needs. > **Prompt** — Use the `jobs-to-be-done` skill to analyze my business idea; reconstruct the likely Job to Be Done, write it as a When/I-want-to/so-I-can statement, and lay out all three dimensions — functional, emotional, and social > (https://skills.wondel.ai/skills/jobs-to-be-done/) > **Prompt** — Use the `jobs-to-be-done` skill to map every alternative my customer could hire for this job — including spreadsheets, manual workarounds, hiring someone, and doing nothing — and tell me which competing hire I actually have to beat to win the Big Hire > (https://skills.wondel.ai/skills/jobs-to-be-done/) Do not skip the emotional and social dimensions thinking they are soft. A founder building invoice software discovers the functional job is "get paid faster" — but the emotional job is "stop feeling like a nag," and the social job is "look professional to clients." Those last two are where the differentiated product lives. ## Phase 2 — Talk to customers without poisoning the well Now you need evidence the job is real and painful. This is where almost everyone fails, because almost everyone runs customer conversations that generate cheerful, useless lies. The [The Mom Test](https://skills.wondel.ai/skills/mom-test/) skill — from [Rob Fitzpatrick's book of the same name](https://www.momtestbook.com/) — exists to fix this. Its core premise: everyone is lying to you, not maliciously, but because you are asking questions so bad that the only polite answer is a compliment. The three rules are deceptively simple. Talk about their life, not your idea — never mention your solution until the very end, if at all. Ask about specifics in the past, not hypotheticals about the future ("Tell me about the last time this happened" beats "Would you use a tool that..."). And talk less; aim for them speaking eighty percent of the time. The deepest insight: a question passes the Mom Test only if the answer could *destroy* your imagined business. "Do you think this is a good idea?" always gets a yes and teaches you nothing. "How are you handling this today, and what does it cost you?" reveals actual behavior and budget. The currency of these conversations is not enthusiasm — it is commitment. "I'd definitely buy that" costs nothing. An intro, a deposit, a scheduled pilot, a letter of intent: those cost something real, and only those tell you the truth. The worst outcome is not a "no." It is the polite zombie lead who loves your idea and will never, ever buy. Have your agent build you an interview guide that obeys the rules, then — crucially — review your *actual* transcripts for where you led the witness. > **Prompt** — Use the `mom-test` skill to write me a 12-question customer discovery interview guide for my target customers that obeys the three Mom Test rules — every question must be about their past behavior and current workarounds, never about my idea, and none can be answerable with a meaningless yes > (https://skills.wondel.ai/skills/mom-test/) > **Prompt** — Use the `mom-test` skill to score my recent customer interview notes against the Mom Test principles, flag every leading question and every compliment I accepted as data, and tell me which 'commitments' were real versus zombie-lead politeness > (https://skills.wondel.ai/skills/mom-test/) If you walk out of a meeting feeling great but holding no concrete facts and no commitment, you ran a pitch, not a discovery conversation. Run it again, and this time do not mention what you are building. ## Phase 3 — Test the riskiest assumption in five days You now have a hypothesis grounded in real conversations. Before you commit months to building, prove the riskiest part of it in a single week. The [Design Sprint](https://skills.wondel.ai/skills/design-sprint/) skill packages the Google Ventures five-day process — Map, Sketch, Decide, Prototype, Test — and it does one thing supremely well: it replaces months of debate with a real decision backed by five real customer reactions. The structure is fixed for a reason. Monday you map the problem and pick one target moment in the customer journey — the riskiest, highest-stakes step. Tuesday everyone sketches solutions alone (no group brainstorms; they produce mush). Wednesday you decide, with a single Decider breaking ties so you do not design by committee. Thursday you build a *facade* — not working code, just something that looks real enough to provoke an honest reaction. Friday you put it in front of five target customers and watch them struggle. Five is the magic number: patterns emerge by the third or fourth interview, and returns flatten after five. The hardest discipline on Friday is to shut up and let them struggle. The moment you explain the prototype, you have invalidated the test — because customers will not have you sitting beside them when they use the real thing. Watch where they get confused. That confusion is your roadmap. > **Prompt** — Use the `design-sprint` skill to plan a five-day design sprint to test the riskiest moment of trust in my product concept; give me the Monday map with sprint questions, a target moment on the customer journey, and a Friday five-act interview script that does not explain the prototype to the user > (https://skills.wondel.ai/skills/design-sprint/) A design sprint will not tell you the whole business works. It will tell you, cheaply and fast, whether the core concept survives contact with five real humans — and whether you should build it, fix it, or walk away. Walking away after one week is a win; you just saved yourself a year. ## Phase 4 — Run the loop and pick the smallest possible MVP Discovery and a sprint give you a strong start. Building a real business means turning that into a repeatable engine of validated learning — and that is the [Lean Startup](https://skills.wondel.ai/skills/lean-startup/) skill, drawn from [Eric Ries's book](https://theleanstartup.com/). Its central machine is the Build-Measure-Learn loop, and its central instruction is to plan that loop *backward*: first decide what you need to learn, then what metric proves it, then build the absolute minimum that produces that metric. That minimum is the MVP, and it is almost always smaller and more embarrassing than you think. The skill catalogs the types: a smoke test (a landing page and a signup button, no product — how Dropbox validated demand with a video); a concierge MVP (you deliver the service manually, pretending it is automated); a Wizard of Oz (a polished front end with a human frantically working the back end). Each tests a different leap-of-faith assumption — the assumptions that, if wrong, kill the business. You test the riskiest one first, never the easiest. And you measure with actionable metrics, not vanity ones. Total signups always goes up and tells you nothing; the signup-to-active conversion rate tells you whether anyone cares. Cohort retention tells you whether the product is actually improving. Set your pivot-or-persevere criteria *before* you run the experiment, so that week-one panic does not get to rewrite your strategy. > **Prompt** — Use the `lean-startup` skill to read my feature wish list for the product, identify my single riskiest leap-of-faith assumption, then design the smallest MVP that tests it — pick a type (smoke test, concierge, or Wizard of Oz) and write a Build-Measure-Learn experiment card with the hypothesis, the one actionable metric, and the success threshold > (https://skills.wondel.ai/skills/lean-startup/) > **Prompt** — Use the `lean-startup` skill to define the pivot-or-persevere criteria for this experiment before we run it — what cohort retention and activation numbers at day 30 would mean persevere, what would mean pivot, and which type of pivot would be on the table if the value hypothesis fails > (https://skills.wondel.ai/skills/lean-startup/) Pick one engine of growth — sticky, viral, or paid — and optimize that one. Running all three at once dilutes your focus and muddies your learning. Most businesses at this stage should obsess over the sticky engine: get retention above churn before you spend a dollar acquiring anyone. ## Phase 5 — Turn ambition into an actual strategy By now you have evidence demand is real. The danger shifts: you have a working idea but no real strategy, just a list of goals dressed up as one. The [Good Strategy Bad Strategy](https://skills.wondel.ai/skills/good-strategy-bad-strategy/) skill, from [Richard Rumelt's book](https://profilebooks.com/work/good-strategy-bad-strategy/), is the antidote. Its core claim is sharp: "grow 40 percent, expand to Europe, become the category leader" is not a strategy. It is a wish list. A goal names an ambition; a strategy explains how you will achieve it given the actual obstacles in your way. Real strategy has a kernel of three parts. A **diagnosis** that names the single critical challenge and simplifies a messy reality into one thing that matters. A **guiding policy** — the overall approach you have chosen — that is a genuine choice with losers; if your nearest competitor could paste it into their deck unchanged, it is a platitude, not a policy. And **coherent actions**: coordinated, resourced steps that each reinforce the others, every one with an owner and a date. Most failed strategies skip the diagnosis entirely and leap from ambition straight to a laundry list of disconnected initiatives. The skill is just as good at *detecting* bad strategy as writing it. Run your plan through the four hallmarks — fluff (buzzwords that collapse to nothing when restated plainly), failure to face the real challenge, goals masquerading as strategy, and dog's-dinner objective lists — and you will see exactly where it is hollow. The source of power that matters most for a new business is concentration: pick one pivot point and pour everything past the threshold where results become visible, instead of spreading thin effort across five fronts and winning none. > **Prompt** — Use the `good-strategy-bad-strategy` skill to audit my one-page business plan against the four hallmarks of bad strategy, then rewrite it as a proper kernel — a one-paragraph diagnosis of my single critical challenge, a guiding policy that rules whole classes of action out, and three coherent actions with owners — plus an explicit list of what I am choosing NOT to do > (https://skills.wondel.ai/skills/good-strategy-bad-strategy/) The hardest part is choosing, because every real choice creates losers. But that is the work. A strategy that pleases every stakeholder concentrates nothing and wins nowhere. ## Phase 6 — Find the uncontested space instead of fighting for scraps Strategy tells you how to win. The next question is *where* to win — and the most common error is to compete head-on in a bloody, crowded market on the same factors as everyone else. The [Blue Ocean Strategy](https://skills.wondel.ai/skills/blue-ocean-strategy/) skill, from Kim and Mauborgne's book, offers the alternative: stop fighting for share of an existing market (a "red ocean") and create uncontested space (a "blue ocean") where competition is, for a while, irrelevant. The engine is *value innovation* — the pursuit of differentiation and low cost simultaneously, which competitors assume is impossible. You achieve it with the Four Actions Framework, the ERRC grid: which factors the industry takes for granted can you **Eliminate**? What can you **Reduce** well below the standard? What should you **Raise** well above it? And what can you **Create** that the industry has never offered? Eliminating and reducing over-served factors cuts your costs at the same time raising and creating lifts buyer value — so value rises more than cost, breaking the trade-off. Plot it on a strategy canvas and a genuinely different offering shows up as a curve that diverges from everyone else's instead of tracing the same shape. Crucially, blue oceans are built by converting *non-customers*, not by stealing rivals' customers. Map the three tiers — the soon-to-be (on the edge of your market, ready to jump), the refusing (who looked and consciously said no), and the unexplored (who never considered your category at all) — and find the common barrier whose removal would unlock a wave of new demand. > **Prompt** — Use the `blue-ocean-strategy` skill to build a strategy canvas for my market — the tools my customers use today and the factors everyone competes on — then apply the ERRC grid to design a value-innovation move I can make with limited resources — what to eliminate and reduce to cut cost while I raise and create on the factors that actually matter to my buyer > (https://skills.wondel.ai/skills/blue-ocean-strategy/) Do not eliminate factors customers genuinely value — especially anything touching trust, security, or accuracy in a finance product. Test your assumptions about what is over-served before you cut it. ## Phase 7 — Position so prospects instantly get it You can have a great product in great market space and still lose, because prospects do not understand what you are in thirty seconds. The [Obviously Awesome](https://skills.wondel.ai/skills/obviously-awesome/) skill, from April Dunford's book, fixes that — and its central reframe is the one most founders miss: *positioning is not messaging, positioning is context.* It is the frame of reference you put customers in so your strengths look obvious. Customers always evaluate you relative to alternatives; there is no absolute perception of "expensive" or "powerful," only relative to what they are comparing you against. Choose that comparison deliberately. The process is five steps, and it is the same one whether you have a research budget or not. First, identify your true **competitive alternatives** — what customers would actually use if you vanished (usually a spreadsheet or "doing nothing," not a named competitor). Second, list your **unique attributes** — what you have that those alternatives do not, things that survive the "only we" test. Third, map each attribute to the **value** it delivers by asking "so what?" until you reach something the customer genuinely cares about. Fourth, define your **best-fit customers** — the tightest possible description of who cares most, identifiable by job title and company traits, never "everyone." Fifth, choose the **market category** that makes your value obvious: compete in an existing one, carve a subcategory, or — rarely, only with traction to spare — create a new one and pay the education tax of teaching the market what it is. > **Prompt** — Use the `obviously-awesome` skill to walk me through the full Obviously Awesome positioning exercise for my product — list the real competitive alternatives (including spreadsheets and doing nothing), identify my unique attributes, run the so-what test to map them to value themes, define my best-fit customer precisely, and recommend whether to position in an existing category or a subcategory > (https://skills.wondel.ai/skills/obviously-awesome/) > **Prompt** — Use the `obviously-awesome` skill to fill out the positioning canvas for me and write a one-line internal positioning statement in the form 'For [best-fit customer], we are the [category] that [key value]' that my whole team can repeat identically > (https://skills.wondel.ai/skills/obviously-awesome/) Test the result the cheap way: say your category and one-liner to someone outside the business and watch their face. If they get it in the first thirty seconds, the category is right. If they squint, no amount of clever copy will rescue you — fix the positioning, not the words. ## Phase 8 — Build an offer people feel stupid refusing Positioning makes prospects understand you. An offer makes them buy. The [$100M Offers](https://skills.wondel.ai/skills/hundred-million-offers/) skill, from [Alex Hormozi's book](https://www.acquisition.com/books), is built on a claim worth internalizing: the offer is the number one lever in the business. A great offer sells despite mediocre marketing; the best marketing in the world cannot save a weak one. So before you optimize a funnel or run an ad, fix the offer. The heart of it is the Value Equation: value equals dream outcome times perceived likelihood of achievement, divided by time delay times effort and sacrifice. Maximize the top, minimize the bottom. People buy outcomes, weighed against how confident they are of getting them and how long and hard the path looks. A guarantee raises perceived likelihood and lowers risk at the same time. Faster results and less effort command premium prices. From there you assemble a Grand Slam Offer — a complete package of core offer, named bonuses (each killing a specific objection, each with a defensible dollar value), a risk-reversing guarantee, and ethical scarcity — so that no competitor offers the same combination and price comparison becomes impossible. And you name it with the MAGIC formula: a magnetic reason, the avatar, the goal, a time frame, and a container word. > Fix the offer before you fix the funnel. A category-of-one offer with crude marketing beats a commodity with a beautiful one. > **Prompt** — Use the `hundred-million-offers` skill to turn my product into a Grand Slam Offer for my best-fit segment using the Value Equation — maximize the dream outcome and slash time-delay and effort, then stack three named bonuses that each kill a specific objection, design a risk-reversing guarantee, add ethical scarcity, and name the whole offer with the MAGIC formula > (https://skills.wondel.ai/skills/hundred-million-offers/) Keep every dollar value honest and every guarantee genuinely honorable — a bonus priced at what nobody would actually pay, or a guarantee buried in fine print, destroys trust the moment it is discovered. The goal is to be a category of one, not to inflate a fake value-price gap. ## Phase 9 — Price against validated willingness to pay Here is where most founders quietly torch their economics: they build the whole product, then pick a price at launch by copying a competitor or marking up their costs. The [Monetizing Innovation](https://skills.wondel.ai/skills/monetizing-innovation/) skill, from [Ramanujam and Tacke of Simon-Kucher](https://www.wiley.com/en-us/Monetizing+Innovation%3A+How+Smart+Companies+Design+the+Product+to+Capture+Value-p-9781119240860), inverts that. Its core instruction — *design the product around the price* — means you have the willingness-to-pay conversation while the product is still a concept, because the price customers will accept is the earliest, clearest signal of whether the thing is worth building at all. Seventy-two percent of new products miss their revenue targets, and treating price as an afterthought is the common root cause. You cannot ask customers to name a perfect price, but they reliably reveal a *range*. Ask what feels acceptable, what feels expensive, and what is prohibitively expensive. Ask purchase probability on a one-to-five scale and trust only the top box. Then watch for the four monetization failures: **feature shock** (cramming so much in that value drowns in complexity), **minivation** (a 10x product priced ten percent above what it replaces — a win rate near 100 percent with no price pushback is its telltale sign), the **hidden gem** (a valuable byproduct nobody monetizes), and the **undead** (a product nobody wants, kept alive on sunk cost). Segment customers by what they value and will pay — never by demographics — and package with the leader / filler / killer model: classify every feature, build good-better-best tiers around the leaders that drive purchase, design the middle tier first because most buyers land there, and pull "killer" features (the ones that *reduce* willingness to pay for a segment forced to fund them) out into add-ons. > **Prompt** — Use the `monetizing-innovation` skill to design our monetization before we finish building — write a willingness-to-pay interview script for my next ten customer calls using the acceptable / expensive / prohibitive price questions, then classify my planned features into leaders, fillers, and killers and draft a good-better-best tier structure with the middle tier designed to be the one most buyers choose > (https://skills.wondel.ai/skills/monetizing-innovation/) > **Prompt** — Use the `monetizing-innovation` skill to tell me which of the four monetization failures my current pricing is drifting toward given that my win rate is near 100 percent and no prospect ever pushes back on price, and recommend the specific countermeasure > (https://skills.wondel.ai/skills/monetizing-innovation/) Pick your price metric — per seat, per invoice checked, per error caught — before you pick the price level, because the metric decides whether revenue grows automatically as customers get more value. A metric that tracks delivered value is the difference between a business that compounds and one that caps out at renewal. ## Phase 10 — Pick the beachhead you will dominate first You have a validated, positioned, priced offer. The final question is go-to-market, and the [Crossing the Chasm](https://skills.wondel.ai/skills/crossing-the-chasm/) skill, from Geoffrey Moore's book, names the trap that kills technology businesses with early traction: the chasm between the visionary early adopters who love new things and the pragmatist early majority who just want something that works. The two groups want opposite things — what wins the visionary actively *repels* the pragmatist — so the strategy and the whole product both have to change to cross. The way across is not to be everything to everyone; that is how you stall in the chasm. It is to pick a single, narrow beachhead segment — "solo bookkeeping firms that bill more than fifty invoices a month," not "finance teams" — and utterly dominate it. A good beachhead has an urgent, expensive pain, is reachable through known channels, has customers who talk to each other (so references spread), and is small enough to own yet big enough to matter. Then you assemble the *whole product* for that one segment: not just your core technology, but the integrations, onboarding, support, and partner pieces a pragmatist needs before they will buy. References are the currency here — pragmatists will not move without proof from peers — and your positioning shifts from "revolutionary" (which terrifies them) to "proven solution for your specific problem." Win the beachhead, then knock down adjacent segments one at a time, bowling-pin style. > **Prompt** — Use the `crossing-the-chasm` skill to help me choose a single beachhead segment for my product — score three candidate niches against pain, reachability, word-of-mouth, and whether I can dominate them, then map the whole-product requirements (integrations, onboarding, references) a pragmatist in that segment needs before they will buy > (https://skills.wondel.ai/skills/crossing-the-chasm/) Resist the urge to keep your options open by chasing several segments at once. Concentration is the whole game: own one segment completely, get your lighthouse references, and let that dominance pull you into the next. ## Your checklist - [ ] Write the Job to Be Done as a `When [circumstances], I want to [progress], so I can [outcome]` statement — with no mention of your product - [ ] Map the full competitive set around the job, including workarounds and non-consumption, and name the hire you must beat - [ ] Run at least ten Mom Test conversations about past behavior, and review your transcripts for leading questions - [ ] Collect a real commitment (time, reputation, or money) from each promising conversation — no zombie leads - [ ] Run a five-day design sprint on the riskiest part of the concept; test with five target customers - [ ] Identify your single riskiest leap-of-faith assumption and pick the smallest MVP that tests it - [ ] Define actionable metrics and pivot-or-persevere criteria *before* running the experiment - [ ] Write a strategy kernel: diagnosis, guiding policy, coherent actions — plus an explicit no-list - [ ] Build a strategy canvas and an ERRC grid to find an uncontested value-innovation move - [ ] Complete the five-step positioning exercise and test your one-liner on an outsider in 30 seconds - [ ] Assemble a Grand Slam Offer: core, named bonuses, risk-reversing guarantee, ethical scarcity, MAGIC name - [ ] Run willingness-to-pay interviews; classify features as leader / filler / killer; design good-better-best tiers - [ ] Choose your price metric before your price level - [ ] Select one beachhead segment and define its whole product ## Common mistakes **Building before validating.** The fatal one. You will be tempted to skip Phases 1 through 4 because building feels like progress and talking to strangers feels slow. But every hour of building before you have evidence is an hour bet on an unvalidated guess. Use the smallest possible MVP — a smoke test or a concierge service — to buy that evidence before you write real code. **Pitching during discovery.** If you mention your idea in a customer interview, you have ended the discovery and started a sales pitch — and the data goes from honest to flattering and worthless. Keep the conversation entirely about their life and past behavior. Save your idea for the very end, if you mention it at all. **Mistaking compliments and signups for validation.** "That's a great idea!" and a free email signup both feel like progress and both contain almost zero information about whether anyone will pay. Chase commitment instead: a deposit, a pre-order, a scheduled pilot, an active paying user. Watch what people *do*, not what they *say*. **Confusing goals for strategy.** "Grow 40 percent and become the leader" is a wish, not a plan. If your document never names the one critical challenge you face, you have no strategy to evaluate or improve. Write the diagnosis first, always. **Positioning for everyone.** A product "for everyone" is compelling to no one. The broadest possible target dilutes your differentiation until prospects feel it was built for someone else. Tighten your best-fit definition until it is almost uncomfortably narrow, then go narrower. **Pricing on cost or competitors.** Both anchor on the wrong thing — your costs measure your business, a competitor's price measures their strategy; neither measures what *your* customer values. Price from validated willingness-to-pay ranges, and decide your price metric before your price level. **Trying to cross the chasm on multiple fronts.** Early traction tempts you to chase every interested segment. Spreading thin means you dominate nothing and accumulate no references — and pragmatists buy on references. Pick one beachhead and own it completely before expanding. ## Frequently asked questions ### In what order should I actually use these skills? Roughly the order above, but it is a loop, not a straight line. Start with [Jobs to Be Done](https://skills.wondel.ai/skills/jobs-to-be-done/) and [The Mom Test](https://skills.wondel.ai/skills/mom-test/) to find and validate the real problem. Use [Design Sprint](https://skills.wondel.ai/skills/design-sprint/) and [Lean Startup](https://skills.wondel.ai/skills/lean-startup/) to test the riskiest assumption cheaply. Once demand is real, sharpen the business with [Good Strategy Bad Strategy](https://skills.wondel.ai/skills/good-strategy-bad-strategy/) and [Blue Ocean Strategy](https://skills.wondel.ai/skills/blue-ocean-strategy/), then make the market understand and want you with [Obviously Awesome](https://skills.wondel.ai/skills/obviously-awesome/), [$100M Offers](https://skills.wondel.ai/skills/hundred-million-offers/), and [Monetizing Innovation](https://skills.wondel.ai/skills/monetizing-innovation/). Finish with [Crossing the Chasm](https://skills.wondel.ai/skills/crossing-the-chasm/) to plan go-to-market. Expect to loop back — a Mom Test conversation in Phase 2 may send you back to rewrite the job statement from Phase 1, and that is the process working. ### Do I really need all ten, or can I just pick a few? You can start a business with two or three, but the failures cluster predictably around the ones founders skip. Skip discovery and you build the wrong thing. Skip pricing work and you torch your margins. Skip positioning and prospects never grasp what you are. The minimum honest stack is discovery (jobs-to-be-done plus mom-test), one validation skill (lean-startup or design-sprint), one positioning skill (obviously-awesome), and one pricing skill (monetizing-innovation or hundred-million-offers). The rest sharpen the edges and become essential the moment you start to scale. ### How do I install and invoke a skill? Install any skill from your terminal with `npx skills add wondelai/skills/ --global` — for example, `npx skills add wondelai/skills/mom-test --global`. Then you invoke it by writing a prompt that tells your agent to use it, exactly like the prompt blocks throughout this guide: paste in your real artifacts (your interview notes, your feature list, your pricing page) and ask the skill to do its work on them. The more concrete your inputs, the better the output. ### Can my AI agent talk to customers for me? No, and you should not want it to. The skills design your interview guides, score your transcripts for bias, structure your experiments, and analyze the results — but the actual conversations and the real commitments have to come from you. The Mom Test only works on genuine human behavior; an agent role-playing a customer will cheerfully confirm whatever you hope is true. Use the agent to prepare and to process, then go talk to real people. ### What if my design sprint or MVP says the idea does not work? Then it just did its job, cheaply. A failed five-day sprint or a smoke test that nobody signs up for has saved you months and a great deal of money. Feed the result back into [Lean Startup](https://skills.wondel.ai/skills/lean-startup/) and decide between pivot and persevere against the criteria you set in advance. Successful startups commonly pivot one to five times before they find product-market fit — the skill catalogs the types (zoom-in, customer segment, business architecture, and more) so you change direction deliberately instead of flailing. ## Start with one conversation The whole stack reduces to one principle: earn your evidence before you spend your runway. You do not need to run all ten skills this week. You need to run the first one today. Install the discovery skills and write your first Mom Test interview guide: ``` npx skills add wondelai/skills/mom-test --global npx skills add wondelai/skills/jobs-to-be-done --global ``` Then ask your agent to build you an interview guide, go have five honest conversations this week, and let what you hear — not what you hoped — decide what you build next. Add the strategy, positioning, offer, and pricing skills as you move from "is this real?" to "how do I win?" Once you have customers and the question shifts from *creating* a business to *expanding* one, continue with [Grow an Existing Business with AI Skills](https://skills.wondel.ai/guides/grow-an-existing-business-with-ai-skills/). And if your validated idea needs software built around it, the companion playbook is [Create a New App with AI Skills](https://skills.wondel.ai/guides/create-a-new-app-with-ai-skills/). Browse the full library and install what you need with `npx skills add wondelai/skills --all --global`. --- # How to Create a New Website with AI Skills > Build a high-converting website from scratch — message, design, typography, and conversion — with AI agent skills from StoryBrand, Refactoring UI, Making Websites Win, and more. By Michał Jaskólski · Published 2026-06-25 · Updated 2026-08-06 · 17 min read Canonical: https://skills.wondel.ai/guides/create-a-new-website-with-ai-skills/ Skills used: storybrand-messaging, top-design, web-typography, refactoring-ui, made-to-stick, ux-heuristics, cro-methodology, one-page-marketing, scorecard-marketing, steve-jobs-design-review **TL;DR:** You create a website that converts by working in one strict order: write the message first with StoryBrand's customer-as-hero framework, make it memorable with Made to Stick, design and set type to an agency bar with Top Design and Refactoring UI, then remove friction and engineer conversion with UX Heuristics and CRO Methodology before a single visitor arrives. - Words before pixels: visitors judge the message, so the StoryBrand BrandScript comes before any design decision. - The customer is the hero and you are the guide — opening with 'we're an innovative platform' is the most common first-website mistake. - Design in grayscale first and add color last; constrained scales for spacing and type beat talent. - Install all ten skills with npx skills add wondelai/skills --all --global and end with a Steve Jobs-grade review before launch. You are about to build a brand-new website, and the blank page is the most expensive thing in your business right now. Every day it does not exist is a day prospects find a competitor instead. So you open your agent, type "build me a landing page for my SaaS," and out comes something that looks fine — a hero, three feature cards, a pricing table, a footer. It compiles. It is responsive. And it converts almost nobody, because "looks fine" is the floor, not the goal. The reason most first websites fail is not bad code. It is that they are built in the wrong order. Founders start with the design — colors, fonts, a hero image — and bolt copy on at the end as an afterthought. But a visitor decides whether to stay in about five seconds, and that decision is driven almost entirely by whether they instantly understand what you do and why it matters to *them*. Beautiful design wrapped around a confusing message is a gorgeous building with no front door. The clarity has to come first. This guide gives you the correct order. You will start with the message — who the customer is, what they want, and what you do for them — using narrative structure proven across ten thousand brands. Then you will layer on award-level design and typography so the page feels like it was built by a top agency, not a template marketplace. Then you will instrument it for conversion: handle objections, add proof, capture leads, and ship a lead-generating quiz. Finally, you will subject the whole thing to a brutal, Steve-Jobs-grade review before a single visitor sees it. Ten skills, one sequence, one website that converts from day one. The workflow chains like this: [StoryBrand Messaging](https://skills.wondel.ai/skills/storybrand-messaging/) writes the words, [Made to Stick](https://skills.wondel.ai/skills/made-to-stick/) makes them memorable, [Top Design](https://skills.wondel.ai/skills/top-design/) and [Web Typography](https://skills.wondel.ai/skills/web-typography/) make it stunning, [Refactoring UI](https://skills.wondel.ai/skills/refactoring-ui/) makes it consistent, [UX Heuristics](https://skills.wondel.ai/skills/ux-heuristics/) makes it usable, [CRO Methodology](https://skills.wondel.ai/skills/cro-methodology/) and [Scorecard Marketing](https://skills.wondel.ai/skills/scorecard-marketing/) make it convert, [1-Page Marketing Plan](https://skills.wondel.ai/skills/one-page-marketing/) makes sure it sits inside a real strategy, and [Steve Jobs Design Review](https://skills.wondel.ai/skills/steve-jobs-design-review/) holds the whole thing to an insanely-great bar. Work them in this order and each phase feeds the next. > A beautiful website with a confusing message is a gorgeous building with no front door. ## Phase 0: Set the strategic frame before you build a page Before you write a headline, answer a harder question: who is this website *for*, and where does it sit in the journey from stranger to customer? Skip this and you will build a gorgeous page that targets everyone and therefore no one. This is the job of the [1-Page Marketing Plan](https://skills.wondel.ai/skills/one-page-marketing/) skill, drawn from Allan Dib's framework of nine squares across three phases — Before (target, message, media), During (capture, nurture, convert), and After (experience, lifetime value, referrals). For a brand-new website you care most about the Before and During phases. The skill's core insight is the PVP Index: score your candidate niches on Personal fulfillment, Value to the marketplace, and Profitability, then pick *one* to dominate. "If you speak to everyone, you speak to no one." A homepage aimed at "small businesses" is weak; a homepage aimed at "bootstrapped SaaS founders doing their first launch" is a magnet. The second deliverable here is your USP — the answer to "why should I buy from you rather than your nearest competitor?" Run the swap test the book teaches: if a competitor's name fits your tagline, it is too generic and you are competing on price. > **Prompt** — Use the `one-page-marketing` skill to score three candidate niches for my new analytics product using the PVP Index, then write a one-paragraph ideal-customer avatar and a USP that passes the swap test for the niche we pick > (https://skills.wondel.ai/skills/one-page-marketing/) The other thing this phase decides is what the website is actually *for*. A site has one primary conversion goal — start a trial, book a demo, take the quiz — and everything else is secondary. Naming that goal now stops you from building five competing calls to action later. Map the Before and During squares so you know what the homepage must do, what a dedicated landing page must do, and where the lead magnet fits. > **Prompt** — Use the `one-page-marketing` skill to map the Before and During phases of my marketing plan into concrete website pages — tell me what the homepage, a paid-traffic landing page, and a lead-capture page each need to accomplish and what the single primary conversion goal of the site should be > (https://skills.wondel.ai/skills/one-page-marketing/) ## Phase 1: Write the message first with StoryBrand Now the most important phase. Before design, before code, you write the words — because the words are what the visitor judges. The [StoryBrand Messaging](https://skills.wondel.ai/skills/storybrand-messaging/) skill is built on [Donald Miller's SB7 framework](https://storybrand.com/), and its one non-negotiable idea is this: **the customer is the hero, not your brand. You are the guide.** Position yourself as the hero and you compete with your customer; position yourself as the guide — the Yoda to their Luke — and you serve them. Most first websites get this exactly backwards, opening with "We're an innovative platform that leverages..." The visitor does not care about you yet. They care about their problem. SB7 walks seven elements: a Character who wants something, who has a Problem (external, internal, and philosophical), who meets a Guide with empathy and authority, who gives them a Plan, calls them to Action, and helps them avoid Failure while ending in Success. The trick most people miss is the internal problem. Companies sell solutions to external problems ("your invoices are scattered"), but customers buy solutions to internal ones ("you feel disorganized and embarrassed when a client asks for a status"). Name how the problem *feels* and the visitor feels understood. Start by building the complete BrandScript — it is the foundation every other piece of copy inherits from. > **Prompt** — Use the `storybrand-messaging` skill to build a complete StoryBrand BrandScript for my new product, a scheduling tool for independent therapists — define the customer as hero, what they want, the external and internal and philosophical problem, how we show empathy and authority as the guide, a three-step plan, a direct and transitional CTA, the stakes of failure, and a vivid success picture > (https://skills.wondel.ai/skills/storybrand-messaging/) With the BrandScript done, derive the homepage copy from it, section by section. StoryBrand's website wireframe is specific: a header with the one-liner and a direct CTA above the fold, a stakes section, a value proposition section, a guide section with empathy plus proof, a three-step plan, an explanatory paragraph, and a repeated CTA. The headline should state the customer's desired outcome, not your category — "Fill your calendar without the back-and-forth" beats "Cloud-based scheduling software." > **Prompt** — Use the `storybrand-messaging` skill to turn the BrandScript into homepage copy following the StoryBrand wireframe — write the above-the-fold one-liner and headline, the stakes section, the empathy-plus-authority guide section, a three-step process plan, and both a direct CTA and a lower-commitment transitional CTA > (https://skills.wondel.ai/skills/storybrand-messaging/) Finally, lock your one-liner: "We help [character] who struggle with [problem] to [solution] so they can [result]." Test it the way the skill prescribes — can someone repeat it after hearing it once? That single sentence goes in your hero, your meta description, your email signature, and your elevator pitch. Consistency of message across every surface is what makes a small brand feel established. > **Prompt** — Use the `storybrand-messaging` skill to write five variations of my one-liner using the problem-plus-solution-plus-result formula and tell me which is most repeatable after a single hearing, then show how to use it in the hero, the meta description, and an email signature > (https://skills.wondel.ai/skills/storybrand-messaging/) ## Phase 2: Make the message stick with Made to Stick StoryBrand makes your message *clear*. The [Made to Stick](https://skills.wondel.ai/skills/made-to-stick/) skill, from [Chip and Dan Heath](https://heathbrothers.com/books/made-to-stick/), makes it *memorable* — and the two are different jobs. Clear copy is understood in the moment; sticky copy survives the close of the tab and gets repeated to a colleague. The framework is SUCCESs: Simple, Unexpected, Concrete, Credible, Emotional, and wrapped in a Story. The single greatest barrier it fights is the Curse of Knowledge — once you know your product deeply, you literally cannot imagine not knowing it, so you over-abstract and assume context the visitor lacks. The highest-leverage move for a new website is Concrete. Abstraction kills memorability; "bicycle" sticks where "vehicle" evaporates. So everywhere your draft says something abstract, replace it with something you can picture. "Improve customer experience" becomes "Customers get their order in 30 minutes, still hot." "Save time on reporting" becomes "Reduce report generation from 4 hours to 10 minutes." Run your whole homepage through this filter. > **Prompt** — Use the `made-to-stick` skill to score my homepage copy on the SUCCESs checklist, then rewrite every abstract benefit as a concrete, specific outcome with real numbers — turn vague phrases like save time and boost productivity into pictures a visitor can see in their head > (https://skills.wondel.ai/skills/made-to-stick/) Then find your Unexpected angle. Visitors pattern-match landing pages and tune them out; a counterintuitive claim or a curiosity gap snaps attention back. The skill's example is GEICO's "15 minutes could save you 15%" — specific and surprising at once. For credibility, lean on the internal kind the book prizes most: vivid details and the Sinatra Test — one reference so strong it answers every objection ("We handle Super Bowl traffic" proves scalability without a spec sheet). And remember the Mother Teresa principle for emotion: a single named customer's story moves people that a statistic about ten thousand users never will. > **Prompt** — Use the `made-to-stick` skill to find one unexpected, pattern-breaking hook for my hero section and one Sinatra Test proof point that would dissolve a skeptical visitor's doubt, then draft a short customer story that follows the character-problem-journey-solution-outcome structure for my homepage > (https://skills.wondel.ai/skills/made-to-stick/) ## Phase 3: Design the signature experience with Top Design Your words are clear and sticky. Now make the page look like it belongs on Awwwards, not in a template gallery. The [Top Design](https://skills.wondel.ai/skills/top-design/) skill encodes the DNA of agencies like Locomotive, Studio Freight, and Active Theory, and its governing principle is that **every pixel is intentional — nothing default, nothing accidental.** The gap between a 7/10 site and a 10/10 site is not skill, it is intention: an 8 has good typography and smooth animation; a 10 has typography that makes you gasp and motion that tells a story. The skill's most important instruction is counterintuitive: do not start with the header. Start with the *signature moment* — the one thing people will screenshot and describe to a colleague. For a new brand that is usually the hero: viewport-filling display type at a dramatic scale (the skill wants a minimum 10:1 ratio between display and body, e.g. 180px over 14px), an asymmetric composition that breaks the centered-everything default, and a choreographed page-load reveal where hero words stagger in at roughly 80ms intervals rather than fading in as a block. > **Prompt** — Use the `top-design` skill to design the signature hero moment for my homepage — give me viewport-filling display typography with at least a 10 to 1 scale ratio, an asymmetric composition that bleeds out of the grid, a custom color system that avoids pure black and the AI purple-to-blue gradient, and a choreographed page-load sequence with staggered word reveals using custom easing curves > (https://skills.wondel.ai/skills/top-design/) A few hard rules from the skill that separate professional from amateur, and that your agent should follow: ban the default easing curves (`ease`, `ease-in`, `ease-out`, `linear`) and use custom cubic-beziers like expo-out `cubic-bezier(0.16, 1, 0.3, 1)`; never animate anything but `transform` and `opacity` so you hold 60fps; use warm off-blacks and off-whites (`#0a0a0a`, `#fafaf9`) instead of pure `#000`/`#fff`; and treat custom cursors as opt-in only — the skill is explicit that you must ask before replacing the native cursor, because misapplied cursors feel gimmicky. Scroll should feel weighted (Lenis or Locomotive Scroll), and parallax belongs only on decorative elements, never on text. > **Prompt** — Use the `top-design` skill to audit my homepage against the Top Design scoring rubric across typography, composition, motion, color, and details — give me the current score out of 10 in each category and the specific changes needed to reach 10, including which animations to add and which to cut for performance > (https://skills.wondel.ai/skills/top-design/) ## Phase 4: Choose and tune the type with Web Typography Top Design treats typography as architecture; the [Web Typography](https://skills.wondel.ai/skills/web-typography/) skill, from Jason Santa Maria's [*On Web Typography*](https://abookapart.com/products/on-web-typography), makes sure the type is also *readable* — the discipline behind the drama. Its core idea is the "clear goblet" principle: the best typography is invisible, keeping focus on the content (the wine), not the glass. There are two jobs for type — "type for a moment" (headlines, buttons, navigation, where personality and impact win) and "type to live with" (body and long-form, where comfort and endurance win) — and confusing the two is why so many sites have gorgeous headlines and unreadable paragraphs. The skill insists that three measurements matter more than which typeface you pick: body size (16px minimum, prefer 18px because users hold phones farther than designers assume), line length (45–75 characters, 66 optimal, enforced with `max-width: 65ch`), and line height (1.5–1.7 for body, tighter 1.1–1.25 for headlines). Get those right and even a humble typeface reads beautifully; get them wrong and the finest font on earth fatigues the reader. For pairing, the rule is one to two families maximum with clear structural contrast (serif plus sans), or a single family with weight variation. > **Prompt** — Use the `web-typography` skill to recommend a typeface pairing for my new website — a distinctive display face for the hero and a workhorse for body text — then give me the full CSS implementation with a fluid clamp-based type scale, correct line heights per context, a 65ch measure on prose, and a font-loading strategy with preload and font-display swap to avoid layout shift > (https://skills.wondel.ai/skills/web-typography/) Performance is part of the craft here, not a separate concern. The skill sets a budget of under 200KB total font payload, prefers WOFF2, and notes that a single variable font can replace four to six static weight files. It also wants fluid type via `clamp(min, preferred, max)` so a single rule serves a 320px phone and a 1440px desktop without breakpoint jumps. If your hero uses a heavy display font, subset it to just the glyphs that headline needs and preload it; the body font can load with `swap` and a solid system fallback so text is never invisible. > **Prompt** — Use the `web-typography` skill to optimize my web font loading to stay under a 200KB payload — tell me which weights to subset, whether a variable font would cut the file count, and write the preload tags and at-font-face rules so my hero type causes zero cumulative layout shift > (https://skills.wondel.ai/skills/web-typography/) ## Phase 5: Make it systematic and polished with Refactoring UI Top Design supplies the wow; [Refactoring UI](https://skills.wondel.ai/skills/refactoring-ui/) supplies the consistency that keeps the wow from collapsing into chaos on the second and third sections. From [Adam Wathan and Steve Schoger](https://www.refactoringui.com/), its founding move is **design in grayscale first, add color last** — which forces real hierarchy through size, spacing, weight, and contrast before color becomes a crutch. Great UI, the book argues, is not talent; it is systems: constrained scales for spacing (4, 8, 16, 24, 32, 48, 64px), type, color, and shadows that produce professional results by removing arbitrary decisions. The practical wins for a new site are immediate. Visual hierarchy comes from combining levers, not multiplying them — primary text is large *or* bold *or* dark, and you save "all three" for the single most important element. Spacing between groups must exceed spacing within groups, which is what makes a layout read as organized. Constrain widths: prose to ~65ch, forms to 300–500px; full-width is almost never right. And the darkest "black" in your palette should be a near-black like `#111827`, never pure `#000`, with grays subtly tinted toward your brand temperature so they do not look lifeless. > **Prompt** — Use the `refactoring-ui` skill to audit my landing page in grayscale first and tell me where the visual hierarchy is failing, then define a constrained design system — a spacing scale, a 9-shade color palette with tinted grays, a type scale, and a shadow elevation scale — and refactor my feature section and pricing cards to use only those tokens > (https://skills.wondel.ai/skills/refactoring-ui/) Apply the skill to the components every website has and every template gets wrong: buttons (a clear primary/secondary/tertiary hierarchy, not five competing filled buttons), cards (let images bleed to the edges instead of floating in padded boxes), and the empty states and forms that templates ignore entirely. Shadows should map to elevation — small for raised buttons, large for floating modals — and a good shadow has two layers, a tight dark one for crispness plus a soft wide one for atmosphere. Run the blur test: squint at the page; if hierarchy survives, it works. > **Prompt** — Use the `refactoring-ui` skill to review my button styles, form fields, and card components against Refactoring UI principles — give each a score out of 10, fix the button hierarchy so there is one clear primary action per section, restyle the form inputs, and add proper two-layer shadows that match each element's elevation > (https://skills.wondel.ai/skills/refactoring-ui/) ## Phase 6: Make it effortless to use with UX Heuristics A page can be clear, beautiful, and consistent and still make visitors *think* — and thinking is friction. The [UX Heuristics](https://skills.wondel.ai/skills/ux-heuristics/) skill, built on Steve Krug's [*Don't Make Me Think*](https://sensible.com/dont-make-me-think/) and Jakob Nielsen's ten heuristics, exists to remove that friction. Its first law is the title: every page should be self-evident, because users do not read, they scan; they do not make optimal choices, they satisfice; they do not figure out how things work, they muddle through. Design for what users actually do. The most useful tests for a new website are concrete. Run the **Trunk Test**: imagine a visitor dropped onto any page cold — can they instantly answer what site this is, what page, what the major sections are, and where to go next? If not, your orientation is broken. Run Krug's "get rid of half the words" pass — cut the "Welcome to our website!" happy-talk and the polite filler, because every unnecessary word competes with the words that matter. And make CTAs use plain action language ("Sign in," "Start free trial"), never clever names that force a half-second of decoding. > **Prompt** — Use the `ux-heuristics` skill to run a usability audit of my new website against Krug's laws and Nielsen's 10 heuristics — apply the Trunk Test to each page, rate every issue 0 to 4 on severity, flag any mystery-meat navigation or jargon CTAs, and give me a prioritized fix list starting with the catastrophic ones > (https://skills.wondel.ai/skills/ux-heuristics/) Pay special attention to the navigation, the signup form, and system feedback — the three places usability quietly kills new sites. Navigation needs a persistent site ID and a clear "you are here" indicator. Forms should validate inline on blur with specific messages, mark optional fields rather than required ones, and use tap targets of at least 44×44px. And every action needs visible status: "Saving…" then "Saved," skeleton screens while loading, a confirmation after submit. Silent failures destroy trust faster than slow ones. > **Prompt** — Use the `ux-heuristics` skill to evaluate my signup form and primary navigation for usability — check inline validation, required-field marking, tap target sizes, and system-status feedback like loading and success states, then rewrite my error messages so each one says what happened and exactly how to fix it > (https://skills.wondel.ai/skills/ux-heuristics/) ## Phase 7: Engineer the conversion with CRO Methodology Now make the page actually convert. The [CRO Methodology](https://skills.wondel.ai/skills/cro-methodology/) skill, from Karl Blanks and Ben Jesson's [*Making Websites Win*](https://conversion-rate-experts.com/making-websites-win/), is built on one discipline: **don't guess — discover.** Every visitor who does not convert has a reason, and that reason is discoverable through research, then eliminable with evidence. This beats copying competitors, applying generic "best practices," and HiPPO (Highest Paid Person's Opinion) decisions every time. For a brand-new site you will not have exit-survey data yet, so you start from the universal objections and the proof you already own. The central technique is the Objection / Counter-Objection table. Every visitor arrives carrying objections from the "Big 5" — Trust, Price, Fit, Timing, Effort — and if the page does not answer them, they leave. Map each likely objection to a specific, evidence-backed counter, and place that counter at the *point of friction* (the trust counter near the signup button, the price counter on the pricing page), not buried in an FAQ. For implicit objections a visitor would never admit, use "CO Only" — counter it without naming it. > **Prompt** — Use the `cro-methodology` skill to build an objection / counter-objection table for my new pricing page covering the Big 5 objections — trust, price, fit, timing, and effort — and for each one write a counter-objection backed by proof, then tell me exactly where on the page to place each counter so it lands at the point of friction > (https://skills.wondel.ai/skills/cro-methodology/) The second move is a persuasion-asset audit. Most companies sit on overlooked proof — undisplayed testimonials, unmentioned credentials, buried guarantees — and the skill's proof hierarchy ranks specific results with context above named testimonials with photos, above case studies, above bare logos. Use the "proof sandwich": a bold claim, then the proof, then a reinforcement. Specific numbers beat round ones ("47,832 customers," not "about 50,000"). For a new site with little social proof yet, build a wish list of the assets to acquire — your first three testimonials, a money-back guarantee, a security badge — and design the layout to slot them in where objections peak. > **Prompt** — Use the `cro-methodology` skill to audit the persuasion assets I currently have for my new website, rank them by the proof hierarchy, and tell me which high-value assets I'm missing — then design a proof-sandwich layout for my homepage that places risk reversal and social proof exactly where a visitor's doubt would peak > (https://skills.wondel.ai/skills/cro-methodology/) ## Phase 8: Add a lead-generating quiz with Scorecard Marketing A homepage converts the roughly 3% of visitors ready to buy today. The other 97% leave — unless you give them a lower-commitment reason to raise their hand. That is the job of the [Scorecard Marketing](https://skills.wondel.ai/skills/scorecard-marketing/) skill, from Daniel Priestley's playbook, whose core claim is that **everything is downstream from lead generation** — and that an interactive assessment converts 30–50% of visitors versus 3–10% for a static PDF lead magnet, because a quiz creates psychological engagement static content cannot. The mechanics are a four-step system: a landing page whose only job is to make clicking "Start" irresistible (built on a concept hook plus the 3 Cs — Clarity, Credibility, Connection), a questionnaire that *captures the email before the questions* so you keep the lead even on abandonment, a results page with dynamic content per score tier, and a follow-up sequence segmented by tier. The concept hook is the single most important element — "moving toward" hooks ("Are you ready to scale?") outperform fear-based ones. Keep it to 8–15 questions for cold traffic; abandonment spikes past 15. > **Prompt** — Use the `scorecard-marketing` skill to design a complete scorecard quiz funnel for my new website — give me a concept hook and landing page that hits the 3 Cs, 10 to 12 questions grouped into 3 or 4 scored categories that qualify leads, three result tiers with dynamic copy and a tier-appropriate CTA for each, and a follow-up email sequence segmented by score > (https://skills.wondel.ai/skills/scorecard-marketing/) The reason this is so powerful for a brand-new site is that every lead arrives pre-qualified, with self-reported pain points and a score, which makes your follow-up dramatically more relevant than a generic drip. The skill is firm on the ethics: the hook must promise value the assessment actually delivers, results must give genuine insight (real help for low scorers, not manufactured anxiety), and capturing email up front must be transparent. Done right, the quiz becomes the highest-converting page on your new site and the engine that feeds the nurture sequence you mapped back in Phase 0. ## Phase 9: Hold it to an insanely-great bar with Steve Jobs Design Review Everything is built. Before you ship, subject the whole thing to one brutal, honest review — the kind Steve Jobs ran. The [Steve Jobs Design Review](https://skills.wondel.ai/skills/steve-jobs-design-review/) skill distills his documented standards, and its governing line is: **"You've got to start with the customer experience and work backwards."** Not from your feature list, not from the tech you happened to use — from what a customer sees, feels, and accomplishes. And remember the standard: "Design is not just what it looks like. Design is how it works." The review runs a fixed protocol. First, experience the site cold, as a stranger would — first impressions cannot be re-run. State the One Thing the site must do in a single sentence; if you cannot, you have no focus. Then audit against the principles: count steps-to-value (does a new visitor reach the core value in three steps, not nine?), demand the interaction not the mockup (walk the slow paths — the empty form, the error state, the failed payment, the mobile cold-start), and check the "back of the fence" — the 404 page, the error copy, the confirmation email — because users sense plywood where they think nobody looks. The verdict is binary: insanely great, or not done. No "pretty good." > **Prompt** — Use the `steve-jobs-design-review` skill to review my finished website the way Steve Jobs would — experience it cold as a new visitor, state the One Thing it must do, count the steps to first value, walk the failure and empty states, and check the back of the fence including the 404 page and confirmation email, then deliver a binary verdict of INSANELY GREAT or NOT DONE with a ranked cut list and fix list > (https://skills.wondel.ai/skills/steve-jobs-design-review/) The most valuable output here is the cut list. Jobs's other principle — "focusing is about saying no" — applies hard to a first website, where the temptation is to add one more section, one more feature callout, one more testimonial until the page says nothing because it tries to say everything. Ask the skill what to *remove*, not what to add: every element a visitor must perceive and parse taxes their attention. A site that does one thing with total clarity beats one that does six things adequately. > **Prompt** — Use the `steve-jobs-design-review` skill to give me a ruthless cut list for my homepage — tell me which sections, features, and CTAs to delete because they dilute the single primary goal, and justify each cut by what it costs the visitor in attention > (https://skills.wondel.ai/skills/steve-jobs-design-review/) ## Your checklist - [ ] Score your niches with the PVP Index and write a one-paragraph ideal-customer avatar (one niche, not "everyone") - [ ] Write a USP that passes the swap test and name the site's single primary conversion goal - [ ] Build the complete StoryBrand BrandScript with the customer as hero and the internal problem named - [ ] Derive homepage copy from the BrandScript following the StoryBrand wireframe; lock a one-liner you can repeat after one hearing - [ ] Run every line through the SUCCESs checklist; replace abstractions with concrete, specific outcomes and numbers - [ ] Design the signature hero moment first — dramatic scale contrast, custom easing, warm off-blacks, a choreographed reveal - [ ] Choose a 1–2 family type system; set 16–18px body, 65ch measure, correct line heights, and a sub-200KB font payload - [ ] Define constrained design tokens (spacing, color, type, shadow); audit in grayscale; fix button hierarchy to one primary per section - [ ] Run the Trunk Test and "get rid of half the words"; add inline validation and visible system-status feedback - [ ] Build the Objection / Counter-Objection table for the Big 5 and place counters at points of friction - [ ] Audit persuasion assets, build a wish list for missing proof, and lay out a proof sandwich where doubt peaks - [ ] Ship an 8–15 question scorecard quiz with email captured first and dynamic results per tier - [ ] Run the Steve Jobs review cold; act on the binary verdict and the cut list before launch ## Common mistakes **Designing before you have a message.** This is the cardinal error. Founders fall in love with a hero image and a color palette, then jam copy in at the end. The visitor judges the message in five seconds; a stunning page with a vague headline still loses. Always run Phase 1 (StoryBrand) before Phase 3 (Top Design). **Making your brand the hero.** "We're a revolutionary platform that leverages cutting-edge AI..." The visitor does not care about you yet. Open with *their* problem and *their* desired outcome. If your homepage's first sentence starts with "We," rewrite it. **Stacking competing calls to action.** Three filled buttons of equal weight above the fold means the visitor has no idea what to do, so they do nothing. One direct CTA, one optional transitional CTA (the quiz, a free guide), and a clear visual hierarchy between them. Refactoring UI and the Jobs review both catch this. **Confusing clear with sticky.** StoryBrand gets you clarity, but clear copy can still be forgettable. Without the Made to Stick pass — concrete numbers, an unexpected hook, one customer's story — your message is understood and then immediately evaporates. Do both passes. **Testing button colors instead of understanding objections.** CRO methodology is blunt about this: changing a button from green to orange is a "meek tweak" that rarely moves anything. The leverage is in discovering and answering the real objections that stop visitors. Build the O/CO table before you fiddle with details. **Beautiful happy path, broken everywhere else.** Templates and quick builds nail the hero and ignore the empty state, the form error, the 404, the confirmation email, the mobile cold-start. That is exactly where the Jobs review aims — the back of the fence. A polished entrance and a hostile exit reads as a cheap product. **A 30-question quiz for cold traffic.** Scorecard funnels convert because they feel quick. Past ~15 questions for a cold visitor, abandonment spikes — and if you put the email field *after* the questions, you lose every person who drops out. Capture the email first, keep it short. **Letting fonts tank performance.** Loading six static weights of a display font causes layout shift and a slow LCP, which the Top Design and Web Typography skills both treat as a craft failure, not just a metric. Subset, preload the critical face, use `font-display: swap`, and stay under 200KB. ## Frequently asked questions ### In what order should I actually run these skills? Strictly message-first: Phase 0 strategy (1-Page Marketing Plan) to decide who and what for, then Phase 1 message (StoryBrand) and Phase 2 stickiness (Made to Stick), *then* the visual layers — Top Design, Web Typography, Refactoring UI — then usability (UX Heuristics) and conversion instrumentation (CRO Methodology, Scorecard Marketing), and finally the Steve Jobs review as a gate before launch. The reason is dependency: design decisions should serve the message, and conversion instrumentation should sit on top of a page that is already clear, beautiful, and usable. Running them out of order means redoing work — a gorgeous hero built before you know your message usually gets thrown away. ### Do I need all ten skills for a simple landing page? No. For a single landing page on a tight timeline, the irreducible core is four: StoryBrand for the message, Refactoring UI for clean visual hierarchy, UX Heuristics for usability, and CRO Methodology for objection handling and proof. Add Top Design and Web Typography when the brand needs to *impress* (you are competing on craft, or selling design-adjacent products). Add Scorecard Marketing when you need lead generation beyond the ready-to-buy minority. Add 1-Page Marketing Plan when the site is part of a broader funnel, and the Steve Jobs review whenever you can afford one brutal pass before shipping — which is almost always worth it. ### How do I install these skills and use them with my agent? Install the whole library with `npx skills add wondelai/skills --all --global`, or add one skill at a time with `npx skills add wondelai/skills/storybrand-messaging --global` (swap in any slug). Once installed, you invoke a skill by telling your agent to use it in plain language — for example, "Use the `cro-methodology` skill to build an objection table for my pricing page." The skills work with Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw, and Hermes Agent. The prompt blocks throughout this guide are copy-paste ready; each one completes the sentence "Use the `` skill to…". ### My agent built a page that "looks fine." How do I push it to a 10/10? "Looks fine" is the symptom of working without a rubric, and three of these skills exist precisely to fix it. Top Design, Refactoring UI, and the Steve Jobs review each score work 0–10 and tell you the specific changes needed to reach 10. Ask your agent to run those scoring passes explicitly: "Score this against the Top Design rubric and tell me what's blocking a 10." The honest answer is usually flat hierarchy, default easing, too little white space, no signature moment, and unaddressed objections — all of which the skills give you concrete fixes for. The gap between fine and great is almost never talent; it is intention applied through a system. ### Can these skills write the actual code, or just give me advice? Both. Because you invoke them inside a coding agent (Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw, Hermes Agent, or any other agentskills.io-compatible agent), the agent reads the skill's principles and then applies them directly to your files — writing the CSS for your type scale, refactoring your button components, restructuring your homepage copy in the actual markup. The skills supply the *judgment* (what good looks like and why); your agent supplies the *implementation* in your real codebase. Point the agent at concrete artifacts — "refactor `Hero.tsx` and `pricing.astro`" — and it edits them, rather than handing you a document to implement yourself. ## Ship your website, then make it convert better The order is the whole game. Message first, then award-level design and typography, then usability, then conversion, then a brutal review — that sequence is what turns a blank page into a website that converts from the day it goes live. Install the full stack and start with your BrandScript: ``` npx skills add wondelai/skills --all --global ``` Then point your agent at the prompts above, phase by phase. When the new site is live and you have real visitor data, the next move is optimization — turning the assumptions you made today into tested, evidence-backed wins. For that, read [How to Improve an Existing Website with AI Skills](https://skills.wondel.ai/guides/improve-an-existing-website-with-ai-skills/), which picks up where this guide ends. And if your next build is a product rather than a marketing site, [How to Create a New App with AI Skills](https://skills.wondel.ai/guides/create-a-new-app-with-ai-skills/) applies the same message-first discipline to software. --- # How to Create a New App with AI Skills > Go from concept to a well-architected, well-built app — validation, architecture, domain modeling, and clean code — with AI agent skills from Lean Startup, Clean Architecture, DDD, and more. By Michał Jaskólski · Published 2026-06-25 · Updated 2026-08-08 · 19 min read Canonical: https://skills.wondel.ai/guides/create-a-new-app-with-ai-skills/ Skills used: lean-startup, design-sprint, clean-architecture, domain-driven-design, clean-code, pragmatic-programmer, system-design, ios-hig-design, 37signals-way, software-design-philosophy **TL;DR:** You create a new app by sequencing decisions by cost of reversal: validate the riskiest assumption with Lean Startup before writing code, draw Clean Architecture boundaries so the framework stays a detail, model the domain with DDD's ubiquitous language, then keep every function readable and every module deep — building strategically from the first commit. - The most expensive mistake in software is building the wrong thing well — falsify the fatal assumption before you open an editor. - Make the few decisions that are expensive to reverse (boundaries, domain model) early, and defer everything cheap to change. - Invest Ousterhout's 10-20% strategic-programming overhead from day one; early shortcuts compound exactly as the team and codebase grow. - Install the ten skills with npx skills add wondelai/skills --all --global — the stack is a menu matched to your stage, not a mandate. Starting a new app is a race against two opposing failure modes. Move too slowly and carefully, and you spend six months perfecting an architecture for a product nobody wants. Move too fast and recklessly, and the prototype that got you your first hundred users becomes the tangled monolith that buries your next hundred features. Most "build a startup" advice tells you to pick a side. This guide refuses to. The whole point is to validate fast *and* keep your architectural options open — to earn the right to scale before you build for scale, but to never write code so carelessly that scaling means a rewrite. The trick is sequencing. You do not need to be a great architect on day one; you need to make a small number of decisions early that are expensive to reverse later, and defer every decision that is cheap to change. Robert C. Martin calls this keeping options open. Eric Ries calls it minimizing the loop. John Ousterhout calls it strategic programming. They are describing the same discipline from three vantage points: spend your scarce early effort on the things that compound, and aggressively avoid waste everywhere else. This guide walks you through that sequence with ten AI agent skills, each packaging a canonical book so your coding agent — Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw, Hermes Agent, or any other agentskills.io-compatible agent — applies the real framework instead of generic best-practice mush. You start by validating the riskiest assumption with the smallest possible build ([Lean Startup](https://skills.wondel.ai/skills/lean-startup/)) and de-risking the core flow in a week ([Design Sprint](https://skills.wondel.ai/skills/design-sprint/)). Then you establish boundaries that let you swap any detail later ([Clean Architecture](https://skills.wondel.ai/skills/clean-architecture/)), model the business so the code reads like the domain ([Domain-Driven Design](https://skills.wondel.ai/skills/domain-driven-design/)), and write each function to be read ([Clean Code](https://skills.wondel.ai/skills/clean-code/)). You apply the meta-disciplines that keep a codebase healthy ([Pragmatic Programmer](https://skills.wondel.ai/skills/pragmatic-programmer/)), size the system honestly before over-engineering it ([System Design](https://skills.wondel.ai/skills/system-design/)), make the interface feel native if you are on iOS ([iOS HIG Design](https://skills.wondel.ai/skills/ios-hig-design/)), ship on a cadence that fights feature creep ([The 37signals Way](https://skills.wondel.ai/skills/37signals-way/)), and treat complexity itself as the enemy at every step ([Software Design](https://skills.wondel.ai/skills/software-design-philosophy/)). > Validate like you have no budget. Build like you will succeed. You do not have to use all ten. A weekend prototype might lean on just the first two and the last one. A funded team building toward a real launch will want the whole stack. Read it in order, then pull the phases you need. ## Phase 1: Validate the riskiest assumption before you build it The most expensive mistake in software is building the wrong thing well. Before you open an editor, you need to know which of your beliefs would kill the business if it were false. The [Lean Startup](https://skills.wondel.ai/skills/lean-startup/) skill, drawn from [Eric Ries's book](https://theleanstartup.com/), turns that instinct into a method: identify your leap-of-faith assumptions, rank them by *what would be fatal* rather than what is easy to test, and design the minimum viable experiment that could falsify the riskiest one. The key mental move is planning the Build-Measure-Learn loop *backward*. Do not start with "what should I build?" Start with "what do I need to learn?", then "how will I know if I learned it?", and only then "what is the smallest thing I can build to find out?" That reversal is what keeps an MVP genuinely minimal. An MVP is not a small version of the product — it is a learning vehicle, often embarrassingly crude. Dropbox validated demand with a video, not a sync engine. Zappos tested whether people would buy shoes online by photographing a local store's inventory and buying retail when an order came in. Neither wrote the "real" product first. Have your agent map the assumptions and pick the experiment type that tests the riskiest one with the least effort — a smoke test for demand, a concierge MVP for value, a Wizard of Oz for whether automation is even needed. > **Prompt** — Use the `lean-startup` skill to map the leap-of-faith assumptions behind my app idea, rank them by which failure would be fatal, and design the single smallest experiment that tests the riskiest one > (https://skills.wondel.ai/skills/lean-startup/) Once you have a candidate experiment, pressure-test whether it actually measures behavior rather than opinion. The skill is opinionated about this: surveys and "would you use this?" interviews produce vanity validation because people mispredict their own behavior. You want the validation ladder — signups are weak, a paid deposit is strong, active usage is strongest. Aim for level 4-5 before you build at scale. > **Prompt** — Use the `lean-startup` skill to critique my validation plan — I am planning to interview 20 prospects and count how many say they would pay, and tell me why that is a vanity signal and what behavioral test I should run instead > (https://skills.wondel.ai/skills/lean-startup/) A word on what this phase is *not*. It is not an excuse to skip engineering quality later, and it is not permission to ship something broken to real paying users under the banner of "MVP." It is a way to make sure the thing you eventually build well is the thing worth building. When the experiment comes back with a clear signal — people commit, money changes hands, usage sticks — you have earned the right to build. If it comes back flat, you have a pivot-or-persevere decision, and you made it for the cost of a landing page instead of a codebase. ## Phase 2: De-risk the core experience in five days Validation tells you *whether* to build. A design sprint tells you *what* the core flow should be before you commit engineering time to it. The [Design Sprint](https://skills.wondel.ai/skills/design-sprint/) skill packages Jake Knapp's five-day GV process: Map the problem on Monday, Sketch solutions individually on Tuesday, Decide on one on Wednesday, build a realistic Prototype on Thursday, and Test it with five real users on Friday. The output is not code — it is a high-fidelity facade and a pile of evidence about what confuses people, all gathered in a week. This matters for a new app because the riskiest moment is usually the first ten minutes of a user's experience, and that is exactly what a sprint targets. You are not testing whether your tech works; you are testing whether a stranger, handed your prototype with no explanation, understands what it is for and can complete the core task. The "five is the magic number" insight from the book is liberating: you do not need statistical significance, you need patterns, and patterns emerge after three to five people. Use your agent as the sprint facilitator. It can run the structured exercises, generate How Might We reframes, and turn a winning concept into a click-through storyboard. > **Prompt** — Use the `design-sprint` skill to facilitate a Monday map and How Might We session for my app's first-run experience — write the long-term goal, list the sprint questions, draft the customer journey from hearing-about-us to the first successful action, and reframe the top three problems as opportunities > (https://skills.wondel.ai/skills/design-sprint/) When you reach Friday, the discipline that separates a useful sprint from theater is in the interview. The skill enforces the five-act structure and, critically, the rule that you never explain the prototype — you let users struggle and watch where they get stuck. Have your agent write the interview script and a note-taking grid so you capture observations as ✓ / ✗ / ~ per participant and count patterns afterward. > **Prompt** — Use the `design-sprint` skill to write a five-act interview script for testing my prototype with five target users, with open-ended task prompts that never explain the UI, plus a note-taking grid I can fill in live during each session > (https://skills.wondel.ai/skills/design-sprint/) Combine this phase with Phase 1 deliberately: the design sprint is the fastest way to produce a Wizard-of-Oz or single-feature MVP that you then put in front of users for a Lean Startup experiment. One de-risks the *design*, the other validates the *demand*. For the business-side framing around this same moment — positioning, pricing, go-to-market — the sibling guide on [how to create a new business with AI skills](https://skills.wondel.ai/guides/create-a-new-business-with-ai-skills/) picks up where this phase leaves off. ## Phase 3: Draw boundaries that let you defer every other decision Now you have validated demand and a tested core flow. This is the moment most teams blow it — either by reaching straight for a framework and letting it dictate the structure, or by skipping structure entirely "because it's just an MVP." The [Clean Architecture](https://skills.wondel.ai/skills/clean-architecture/) skill, from [Robert C. Martin's book](https://www.informit.com/store/clean-architecture-a-craftsmans-guide-to-software-structure-9780134494166), gives you a single rule that resolves the tension: **source code dependencies point inward**, from frameworks toward use cases toward entities. Your business rules must not know whether data lives in Postgres or DynamoDB, or whether requests arrive over HTTP or a CLI. The payoff for a new app is precisely *option-keeping*. When your business logic is isolated behind interfaces it defines, the database is a detail, the web framework is a detail, the payment provider is a detail — and details are plugins you can defer or swap without a rewrite. You can start with SQLite and a monolith, then move to managed Postgres and split services later, touching only the adapter layer. The skill's diagnostic question is the one to keep asking: *can you test your business rules with no database, no web server, and no framework running?* If not, the dependencies are pointing the wrong way. The mechanism is the Dependency Inversion Principle. Your use case defines an interface like `InvoiceRepository`; your infrastructure provides `PostgresInvoiceRepository`. The controller translates an HTTP request into a plain request object, calls the use case, and the use case returns a plain response object — never an ORM entity, never a framework type crossing the boundary. Have your agent design that layering for your actual feature. > **Prompt** — Use the `clean-architecture` skill to design the Clean Architecture layering for my app's core feature — define the entities, the main use case with its request and response models, the repository interface it depends on, and show how the HTTP controller and the database adapter sit in the outer ring without leaking into the core > (https://skills.wondel.ai/skills/clean-architecture/) Resist the urge to over-build this. The number of circles is not sacred — four is typical, but a small app might collapse adapters and frameworks into one layer. Draw boundaries at points of likely volatility (the database, third-party APIs, the delivery mechanism) and skip ceremony everywhere else. For a far deeper treatment of these decisions — data-intensive tradeoffs, resilience, when to split services — see the dedicated guide on [designing the best architecture for a new app](https://skills.wondel.ai/guides/design-the-best-architecture-for-a-new-app/). For a new app, this skill is the high-leverage subset: get the Dependency Rule right and most other architecture mistakes become cheap to fix. ## Phase 4: Model the domain so the code speaks the business Architecture gives you the *shape* of the system; domain modeling gives it *meaning*. The [Domain-Driven Design](https://skills.wondel.ai/skills/domain-driven-design/) skill, from [Eric Evans's book](https://www.domainlanguage.com/ddd/), starts from a deceptively simple claim: the model is the code, and the code is the model. When the words your team uses in conversation are the exact words in the codebase — a Ubiquitous Language — a whole category of bugs disappears, because there is no translation layer between what the business means and what the code does. For a new app this is cheaper to do now than ever again. You are establishing the vocabulary from scratch, so name things after domain concepts, not technical roles. An `InvoiceDraft` that knows how to `finalize()` is worlds better than a `DataProcessor` with a `process()` method, because a domain expert can read the former and tell you when it's wrong. The skill treats naming difficulty as a design signal: if a concept is hard to name, your model is probably wrong. The two structural ideas that matter most early are **bounded contexts** and **aggregates**. A bounded context is a boundary within which a word means exactly one thing — "Customer" in billing and "Customer" in support can be different models, and that is healthy, not a bug to unify. An aggregate is a cluster of objects with a single root that enforces consistency; keep them small and reference other aggregates by ID, not by object reference. Have your agent build the language and the boundaries first. > **Prompt** — Use the `domain-driven-design` skill to build the ubiquitous language and bounded contexts for my app — find where the team uses the same words to mean different things across features, and tell me where a term legitimately needs a different meaning in a different context > (https://skills.wondel.ai/skills/domain-driven-design/) Then model the consistency boundaries. The most common new-app mistake here is the anemic domain model — objects that are just data bags while all the logic leaks into services. Push the behavior into the entities and value objects where it belongs. > **Prompt** — Use the `domain-driven-design` skill to design the central aggregate of my app's core domain — identify the aggregate root, which fields should be value objects, what invariants the root must enforce, and which related aggregates should be referenced by ID instead of held directly > (https://skills.wondel.ai/skills/domain-driven-design/) Crucially, DDD and Clean Architecture are partners, not alternatives. The DDD repository interface lives in the domain layer; its implementation lives in infrastructure — which is exactly where Clean Architecture's Dependency Rule wants it. Apply strategic design too: not every part of your app deserves deep modeling. Identify your **core domain** (the thing that is your competitive advantage) and invest your best thinking there; for generic subdomains like authentication, email, or payments, buy or use open source rather than over-engineering. ## Phase 5: Write every function to be read, not just to run You have a sound structure and a meaningful model. Now the code itself has to stay readable as it grows, because code is read far more than it is written — the ratio is well over ten to one. The [Clean Code](https://skills.wondel.ai/skills/clean-code/) skill, also from Robert C. Martin, is the discipline that keeps your day-to-day code from rotting: intention-revealing names, small functions that do one thing, error handling kept separate from business logic, and tests treated as first-class code. The temptation in a new app is to tell yourself you will clean it up later. You won't — later never comes, and the broken windows accumulate. The skill's core moves are concrete enough to apply on every commit. Functions should be small and operate at a single level of abstraction; a flag argument is a smell because it means the function does two things; commands and queries should be separate; and the best comment is usually a well-named extracted function. Point your agent at code as you write it and have it score and fix against these rules. > **Prompt** — Use the `clean-code` skill to review my most important service class against Clean Code principles — flag any function over twenty lines or doing more than one thing, every name that does not reveal intent, any flag arguments, and any swallowed exceptions, then give it a score out of ten and the top five fixes in priority order > (https://skills.wondel.ai/skills/clean-code/) The other half of Clean Code is testing. The skill treats dirty tests as worse than no tests, because they become a liability that fights you on every change. Use it to generate tests that read like documentation — descriptive names like `shouldRejectInvoiceWithNegativeTotal`, one concept per test, and the F.I.R.S.T. properties (Fast, Independent, Repeatable, Self-validating, Timely). Because you followed Phase 3, your business logic is already isolated from infrastructure, so these tests are fast and need no database. > **Prompt** — Use the `clean-code` skill to write clean unit tests for my core use case using arrange-act-assert, descriptive behavior-based test names, and a builder helper so each test reads like a sentence, covering the happy path plus the most important failure cases > (https://skills.wondel.ai/skills/clean-code/) ## Phase 6: Apply the meta-disciplines that keep the codebase healthy Clean Code operates at the function and class level. The [Pragmatic Programmer](https://skills.wondel.ai/skills/pragmatic-programmer/) skill, from Hunt and Thomas, operates one level up — the habits and meta-principles that determine whether a codebase stays easy to change over years. Four of its ideas are especially load-bearing for a new app. First, **tracer bullets**. Instead of building layer by layer and integrating at the end, build one thin but *real* vertical slice through every layer — UI to use case to database and back — and keep it. It gives you end-to-end feedback immediately and a skeleton to flesh out, and it surfaces integration problems on day two instead of month two. This pairs perfectly with Phase 3: your first tracer bullet proves the Clean Architecture boundaries actually connect. > **Prompt** — Use the `pragmatic-programmer` skill to design the thinnest possible tracer bullet for my app — one real end-to-end slice from user input through the use case to persisted data and back to the UI — that exercises every architectural layer with minimal functionality so I can confirm the wiring before building features > (https://skills.wondel.ai/skills/pragmatic-programmer/) Second, **DRY — but only for knowledge, not coincidental similarity**. Two code blocks that look alike but encode different business rules are not duplication, and merging them couples concepts that should evolve independently. Third, **orthogonality**: changing the database should not break the UI, changing the auth provider should not touch billing. Fourth, **reversibility**: abstract third-party dependencies behind your own interfaces so you can swap Stripe for another processor, or one model provider for another, without rewriting business logic. Ask your agent to audit a planned design against these. > **Prompt** — Use the `pragmatic-programmer` skill to audit my plan to call the Stripe SDK directly from three different service classes against the reversibility and orthogonality principles, and show me the adapter interface that would let me swap payment providers later without touching business logic > (https://skills.wondel.ai/skills/pragmatic-programmer/) The Broken Window theory is the cultural glue here: the first hack is the most expensive because it gives permission for every subsequent one. If you cannot fix something now, board it up with a tracked ticket rather than leaving it as silent rot. For a brand-new codebase, establishing zero-tolerance for unexplained broken windows is one of the cheapest high-leverage habits you can adopt. ## Phase 7: Size the system honestly — then stop Here is where discipline cuts the other way. Having read about architecture and scaling, the temptation is to build for a million users you do not have. The [System Design](https://skills.wondel.ai/skills/system-design/) skill, from Alex Xu's *System Design Interview*, is as useful for telling you what *not* to build as for telling you what to build. Its first principle is to start with requirements, not solutions — and its estimation tools let you prove, on the back of an envelope, that you do not need sharding yet. Do the math before you provision anything. The skill gives you the numbers: queries per second is daily active users times actions per day divided by 86,400, with peak typically two-to-five times average; storage is records per day times record size times retention. For a new app with a few hundred users, that calculation almost always says "a single well-indexed database and a cache will carry you for a long time." The common mistake the skill explicitly warns against is premature sharding — vertical scaling first, then read replicas, then cache aggressively, and shard last. > **Prompt** — Use the `system-design` skill to do a back-of-the-envelope capacity estimate for my app — ask me for the numbers you need about users and usage, then tell me the QPS and yearly storage, and tell me honestly which scaling techniques I do NOT need yet > (https://skills.wondel.ai/skills/system-design/) When you genuinely do hit a scaling decision — a read-heavy dashboard, a spiky background job like OCR on uploaded photos — the skill gives you the right building block for the right problem: a cache-aside layer for read-heavy paths, a message queue to absorb spikes and decouple the slow OCR work from the request path, a CDN for static assets. Reach for these when an estimate or a real bottleneck justifies them, not because a blog post said to. > **Prompt** — Use the `system-design` skill to redesign the slowest step in my app's main flow so it stops blocking the request — move the slow work behind a message queue and worker pool, and show how the client polls for completion while the happy path stays fast > (https://skills.wondel.ai/skills/system-design/) ## Phase 8: Make it feel native if you are shipping to iOS If your app has an iPhone client, "feels native" is not polish you add later — it is the reason iOS users trust an app at all. The [iOS HIG Design](https://skills.wondel.ai/skills/ios-hig-design/) skill encodes Apple's Human Interface Guidelines: the three pillars of clarity, deference, and depth, plus the concrete rules that make the difference between an app that belongs on the platform and one that feels like a ported website. The specifics are the value. Respect safe areas so nothing hides behind the Dynamic Island or home indicator; keep every touch target at least 44 by 44 points; use semantic colors like `Color(.label)` and `Color(.systemBackground)` so Dark Mode works automatically; use semantic text styles so Dynamic Type scales for accessibility; and use native navigation — tab bars for primary destinations, `NavigationStack` for drill-down, sheets for focused tasks — never an Android-style hamburger menu. Have your agent review your screens against these. > **Prompt** — Use the `ios-hig-design` skill to review my SwiftUI screens against the iOS HIG — check safe-area handling, that all touch targets meet 44pt, that I am using semantic colors and Dynamic Type instead of hardcoded values, and that the navigation uses a tab bar and NavigationStack rather than a hamburger menu > (https://skills.wondel.ai/skills/ios-hig-design/) The skill also treats accessibility as a first-class concern rather than an afterthought: every interactive element needs an accessibility label, state needs an accessibility value, and you should be able to complete every task with VoiceOver alone. Building this in from the first screen is dramatically cheaper than retrofitting it before an enterprise accessibility review. ## Phase 9: Ship on a cadence that fights feature creep A new app's greatest enemy after launch is the slow bloat of "just one more feature." The [The 37signals Way](https://skills.wondel.ai/skills/37signals-way/) skill, distilled from *Getting Real*, *Rework*, and [*Shape Up*](https://basecamp.com/shapeup), is the antidote: build less, fix time and flex scope, and ship on a predictable cadence. Its core principle — *build half a product, not a half-assed product* — is exactly the mindset that keeps a validated MVP from sprawling. The central mechanic is shaping and betting. Before work reaches you or your team, it gets shaped: made rough enough to leave design freedom, solved enough to remove the big unknowns, and bounded by an *appetite* ("this is worth two weeks") rather than an estimate ("how long will it take?"). Appetite is the crucial inversion — you fix the time and cut scope to fit, never the reverse. Then you bet shaped pitches into fixed cycles and let the circuit breaker kill anything not done at the deadline rather than letting it run forever. Have your agent shape your next feature. > **Prompt** — Use the `37signals-way` skill to shape my next big feature into a Shape Up pitch with a two-week appetite — write the problem, the appetite, a breadboarded solution at the level of places and affordances, the rabbit holes to avoid, and the explicit no-gos that keep it from sprawling > (https://skills.wondel.ai/skills/37signals-way/) The skill's bias toward opinionated software is the other half of the discipline: every preference you offer is a decision you refused to make for the user. Pick sensible defaults, detect the timezone from the browser instead of asking, ship one good theme. Use the skill to challenge scope directly — its default answer to a feature request is a respectful "not now." > **Prompt** — Use the `37signals-way` skill to challenge the scope of my v1 feature list — tell me which features to cut to ship a focused first version, which user-facing preferences I should replace with an opinionated default, and draft the polite no-for-now responses for the cut items > (https://skills.wondel.ai/skills/37signals-way/) ## Phase 10: Treat complexity as the enemy at every step The final skill is less a phase than a lens you hold over all the others. The [Software Design](https://skills.wondel.ai/skills/software-design-philosophy/) skill, from John Ousterhout's [*A Philosophy of Software Design*](https://web.stanford.edu/~ouster/cgi-bin/book.php), names the real adversary: complexity, defined as anything about a system's structure that makes it hard to understand and change. Its central design heuristic — *deep modules* — is the one to internalize. A deep module offers powerful functionality behind a simple interface; a shallow module imposes a complex interface for little benefit, adding complexity rather than hiding it. This is the corrective to a subtle trap in the earlier phases. Clean Code's "small functions" and DDD's many building blocks can, applied without judgment, tip into *classitis* — a swarm of tiny shallow classes that each add an interface to learn without hiding meaningful complexity. Ousterhout's measure cuts through it: judge a module by functionality provided divided by interface complexity imposed, not by line count. Sometimes merging three shallow classes into one deep one is the right move. Have your agent evaluate a design through this lens. > **Prompt** — Use the `software-design-philosophy` skill to evaluate my core module against deep-versus-shallow module principles — flag any class whose interface is nearly as complex as its implementation, any pass-through methods that just delegate, and any information leaking across module boundaries, then tell me where to consolidate into deeper modules with simpler interfaces > (https://skills.wondel.ai/skills/software-design-philosophy/) The skill's other essential idea for a new app is **strategic versus tactical programming**. Tactical programming optimizes for getting this feature working now and accrues complexity with every shortcut; strategic programming invests a steady 10-to-20 percent extra effort in design, treating every change as a chance to improve structure. Ousterhout argues startups need this *most*, because early shortcuts compound into crippling debt exactly as the team and codebase grow. That is the throughline of this entire guide: validate cheaply, but once you commit to building, build strategically. > The only way to go fast is to go well — and the only way to go well is to know which decisions are worth the investment. ## Your checklist - [ ] Map your leap-of-faith assumptions and rank them by what would be fatal, not what's easy to test (`lean-startup`) - [ ] Design and run the smallest experiment that could falsify the riskiest assumption; aim for behavioral, level 4-5 validation - [ ] Run a five-day design sprint on the core flow; test the prototype with five real users without explaining it (`design-sprint`) - [ ] Establish the Dependency Rule: business logic testable with no database, framework, or web server (`clean-architecture`) - [ ] Build a Ubiquitous Language and bounded contexts before writing feature code (`domain-driven-design`) - [ ] Keep aggregates small, push behavior into entities, reference other aggregates by ID - [ ] Write small, single-purpose, intention-revealing functions and clean tests on every commit (`clean-code`) - [ ] Fire a tracer bullet — one real end-to-end slice — before building out features (`pragmatic-programmer`) - [ ] Abstract third-party dependencies behind your own interfaces for reversibility - [ ] Do a back-of-the-envelope capacity estimate and confirm what you do NOT need to scale yet (`system-design`) - [ ] If on iOS, audit screens against the HIG: safe areas, 44pt targets, semantic colors, native navigation, accessibility (`ios-hig-design`) - [ ] Shape each feature with an appetite, not an estimate; fix time and flex scope; default to "not now" (`37signals-way`) - [ ] Favor deep modules over many shallow ones; spend 10-20% extra on strategic design (`software-design-philosophy`) ## Common mistakes **Building the architecture before validating the idea.** The most beautiful Clean Architecture is worthless if it serves a product nobody wants. Run Phase 1 first. Validation is cheap; a rewrite is not. The inverse is equally fatal — see the next item. **Treating "MVP" as a license to write garbage.** Lean Startup says ship the *smallest* thing to learn, not the *sloppiest*. The validation experiments in Phase 1-2 are often not even code (landing pages, concierge, Wizard of Oz). Once an experiment greenlights real building, you are building the real thing — apply the engineering phases. Conflating "minimum" with "low quality" is how prototypes calcify into unmaintainable production systems. **Letting the framework dictate the architecture.** If your business rules import your web framework or your ORM entities cross use-case boundaries, the framework has become your architecture and swapping it means a rewrite. Keep frameworks in the outermost ring as plugins (`clean-architecture`). **The anemic domain model.** Objects that are pure data bags while all logic lives in fat service classes is the single most common DDD failure. It scatters business rules and duplicates them. Push behavior into the entities and value objects (`domain-driven-design`). **Classitis — over-applying "small."** Clean Code's small functions and DDD's many concepts can metastasize into dozens of shallow one-method classes that each add cognitive load without hiding complexity. Judge modules by depth (functionality per unit of interface), not by size (`software-design-philosophy`). **Premature scaling.** Designing for a million users you don't have wastes weeks and adds operational complexity that slows you down. Do the estimate; a single database plus a cache carries most apps far further than founders expect. Shard last, not first (`system-design`). **Skipping the tracer bullet.** Building every layer in isolation and integrating at the end hides the integration bugs until they are expensive. One thin real slice through all layers, early, surfaces them when they are cheap (`pragmatic-programmer`). **Estimating instead of setting an appetite.** Asking "how long will this take?" invites scope to grow until it fills the time. Asking "how much time is this problem worth?" fixes the budget and forces you to find the essential version (`37signals-way`). ## Frequently asked questions ### Do I really need ten skills to build one app? No. The stack is a menu, not a mandate. A solo weekend prototype might use only `lean-startup` to scope it, `clean-architecture` to keep options open, and `software-design-philosophy` to stay simple. A funded team building toward a public launch benefits from the full sequence. The value is that each skill is the *real* framework from its source book, so your agent applies Ries or Evans or Ousterhout faithfully instead of improvising. Install the ones that match your stage and add others as the app grows. ### What's the right order — and can I run phases in parallel? The order is deliberate: validate before you build (1-2), establish structure before you fill it in (3-4), then write and harden the code (5-6), size and polish (7-8), and ship sustainably (9), with complexity-awareness (10) running throughout. In practice the engineering phases overlap heavily — you will apply Clean Architecture, DDD, and Clean Code in the same pull request, with Pragmatic Programmer habits and the deep-module lens applied continuously. The one ordering rule that is non-negotiable: do not skip validation to get to the fun part of building. ### How is this different from the architecture deep-dive guide? This guide is the *full lifecycle* of creating an app — from "is this idea worth building?" through shipping and keeping the codebase healthy. The companion guide on [designing the best architecture for a new app](https://skills.wondel.ai/guides/design-the-best-architecture-for-a-new-app/) zooms into Phase 3 and 7 specifically, going much deeper on boundaries, data-intensive tradeoffs, and resilience patterns. Start here for the end-to-end picture; go there when the architecture decisions themselves are the hard part. For the commercial side — positioning, pricing, acquisition — see [how to create a new business with AI skills](https://skills.wondel.ai/guides/create-a-new-business-with-ai-skills/). ### Won't all this discipline slow down my prototype? The framing that quality and speed are opposites is exactly what these skills reject. Ousterhout's data is that strategically designed systems become faster to work in within *months*, not years — the investment pays back fast because every future change is cheaper. The trick is matching effort to stage: in validation, your "build" might be a landing page, so there's almost no code to keep clean. Once you're building the real product, the 10-20% strategic overhead is what keeps you fast as the codebase grows past the point where a tactical mess would have ground you to a halt. ### My agent doesn't seem to apply the skill — what am I doing wrong? Two things usually fix it. First, name the skill explicitly in your prompt — "Use the `clean-architecture` skill to ..." — so the agent loads it rather than relying on general knowledge. Second, give it a concrete artifact to work on: a real class, a real feature, a pasted file. The sample prompts above are deliberately specific ("my `InvoiceService` class", "the photo OCR step") because skills produce sharper output when anchored to your actual code instead of a hypothetical. ## Get started Install the foundational skills and point your agent at the first decision that matters — what to build and whether it's worth building: ``` npx skills add wondelai/skills/lean-startup --global npx skills add wondelai/skills/clean-architecture --global npx skills add wondelai/skills/domain-driven-design --global ``` Add the rest of the stack as you move through the phases, or grab the whole library at once with `npx skills add wondelai/skills --all --global`. Then open your agent and start with the riskiest assumption — validate it cheaply, and you'll have earned the right to build it well. When the validated idea turns out to be more about the *commercial* model than the code, continue with [how to create a new business with AI skills](https://skills.wondel.ai/guides/create-a-new-business-with-ai-skills/). When the architecture itself becomes the hard problem, go deep with [how to design the best possible architecture for a new app](https://skills.wondel.ai/guides/design-the-best-architecture-for-a-new-app/). --- # How to Improve an Existing Business with AI Skills > Sharpen strategy, operations, pricing, and team output in a business that already runs — with AI agent skills from Good Strategy Bad Strategy, Traction, High Output Management, and more. By Michał Jaskólski · Published 2026-06-25 · Updated 2026-08-08 · 16 min read Canonical: https://skills.wondel.ai/guides/improve-an-existing-business-with-ai-skills/ Skills used: good-strategy-bad-strategy, traction-eos, high-output-management, team-topologies, drive-motivation, lean-analytics, negotiation, monetizing-innovation **TL;DR:** You improve an existing business by diagnosing before prescribing: score your strategy against Good Strategy Bad Strategy's kernel, install a weekly execution rhythm with Traction EOS, multiply managerial leverage with High Output Management, then fix structure, motivation, metrics, negotiation, and price — eight layers, applied in order, each unlocking the next. - Diagnose the real challenge first — most stalled businesses have goals and vision but no honest diagnosis, and everything downstream inherits that gap. - Strategy dies without machinery: a weekly EOS-style operating rhythm turns direction into traction before you touch structure or incentives. - The two highest-leverage commercial moves — negotiation discipline and value-based repricing — drop almost entirely to the bottom line. - Install everything with npx skills add wondelai/skills --all --global and work the layers top to bottom, skipping any layer the evidence says is healthy. A stalled business is a confusing place to stand. Revenue is real, customers are real, payroll clears every month — and yet the line has gone flat. You are working harder than ever and the company is not getting better. The instinct is to look for the one missing tactic: a new channel, a new feature, a heroic quarter. But businesses that have plateaued rarely lack effort. They lack a clear diagnosis of what is actually holding them back, and a disciplined operating system to act on it week after week. This guide is for the owner or operator of a company that already works but has stopped moving. The problem is almost never a single thing. Strategy has decayed into a list of ambitions. The team is busy but pulling in different directions. Meetings produce updates instead of decisions. Pricing was set years ago and never revisited. Your best people are quietly disengaging. Each of these compounds the others, which is why poking at one tactic at a time never breaks the plateau. The fix is to work the layers in order — strategy, then execution cadence, then management, then team structure, then motivation, then measurement, then the two highest-leverage commercial levers, negotiation and pricing — and to do it with an AI agent that carries the actual frameworks, not a generic chatbot guessing. Each of the eight skills below packages a specific, battle-tested business book so your agent (Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw, or Hermes Agent) can apply its real method to your real numbers. You install a skill once with `npx skills add wondelai/skills/ --global` and invoke it by telling the agent to use it. > A plateau is not a lack of effort. It is a lack of diagnosis, compounded by an execution system that forgot how to choose. Worked top to bottom, this is roughly a two-quarter turnaround: a week of honest strategy work, a quarter to install the operating rhythm and fix how the team is led and shaped, and a parallel track to repair what you measure, how you negotiate, and what you charge. Let's go layer by layer. ## Phase 1 — Diagnose the real challenge before you touch anything Start with strategy, because everything downstream inherits its mistakes. The single most common reason a working business stalls is that its "strategy" is a goal list wearing a strategy costume: grow 30%, expand to a new region, launch the AI feature, lift NPS to 60. None of those is a strategy. They are ambitions with no diagnosis of the obstacle and no choice about where to concentrate. This is the exact territory of [Good Strategy Bad Strategy](https://skills.wondel.ai/skills/good-strategy-bad-strategy/). [Richard Rumelt's argument](https://profilebooks.com/work/good-strategy-bad-strategy/) is that good strategy has a simple, almost boring structure he calls the kernel: an honest **diagnosis** of the critical challenge, a **guiding policy** for overcoming it, and a set of **coherent actions** that carry the policy out. Bad strategy is not the absence of strategy — it is an active substitute for it: buzzword fluff, a refusal to name the actual obstacle, and laundry lists of forty "priorities" that concentrate nothing. The work is choice: pressing your scarce resources onto the one or two pivot points whose movement unlocks everything else. Hand your agent the plan you actually have — last year's deck, the OKR sheet, whatever passes for direction — and have it audit the plan as strategy, not cheerlead it. > **Prompt** — Use the `good-strategy-bad-strategy` skill to audit our current annual plan as strategy: flag every passage that is fluff, every goal masquerading as strategy, and the fact that we never name the obstacle. Then write a proper kernel — a one-paragraph diagnosis of our critical challenge, a guiding policy, and 3 to 5 coherent actions. > (https://skills.wondel.ai/skills/good-strategy-bad-strategy/) The skill scores strategies 0–10 against the kernel and reports what is missing. Expect a low score the first time; most real plans land at 3–4 because they are mostly goals and vision with no diagnosis. The valuable output is the diagnosis itself. Rumelt's example is Lou Gerstner reframing IBM's 1993 crisis from "mainframes are dying, break up the company" to "our advantage is integrated capability; the obstacle is internal coordination" — and everything downstream changed. Your stalled business has an equivalent reframe waiting, and naming it is the pivot of the whole turnaround. Once you have a diagnosis, sharpen it with two more moves the skill knows well. First, find your **pivot point** — the place where a small concentrated effort is amplified. Rumelt's chain-link idea is decisive for stalled businesses: in a system whose performance is capped by its weakest link, investing in the strong links is wasted until you fix the weak one. A plateau is usually one jammed link masquerading as a general malaise. > **Prompt** — Use the `good-strategy-bad-strategy` skill to treat our funnel as a chain-link system — lead generation, activation, retention, and expansion — and tell me which single link is the binding constraint capping the whole business. Then design a proximate objective focused only on that link, close enough that the team can actually see how to hit it this quarter. > (https://skills.wondel.ai/skills/good-strategy-bad-strategy/) Second, force the choice. Have the agent write the explicit no-list — the things this strategy says you will *not* do — because a guiding policy that rules nothing out is a platitude. If a competitor could paste your guiding policy into their own deck unchanged, it is not a policy. The output of Phase 1 is one page: a diagnosis, a guiding policy, three to five coherent actions, one proximate objective, and a list of what you are deliberately stopping. ## Phase 2 — Install an execution rhythm that survives Monday A perfect strategy dies if the company has no machinery to execute it. This is the gap between vision and traction, and it is exactly what [Traction EOS](https://skills.wondel.ai/skills/traction-eos/) — [Gino Wickman's Entrepreneurial Operating System](https://www.eosworldwide.com/traction-library) — exists to close. Wickman's blunt framing: great vision without traction is hallucination; traction without vision is aimless. EOS connects the two through a weekly operating rhythm built on six components — Vision, People, Data, Issues, Process, Traction. For a stalled business the two components that move the needle fastest are **Rocks** and the **Level 10 Meeting**. Rocks are the 3–7 most important priorities for the next 90 days, each with one owner. Ninety days is long enough to finish something meaningful and short enough to keep urgency. The discipline is brutal scoping: a maximum of seven company Rocks, each SMART and binary (done or not done, no partial credit), aimed squarely at the proximate objective you set in Phase 1. > **Prompt** — Use the `traction-eos` skill to turn the guiding policy and proximate objective from our strategy work into 5 quarterly Rocks for a 22-person company. Each Rock needs one owner, clear binary completion criteria, and a check that it actually advances the strategy rather than being business-as-usual. Flag any Rock that is vague or that nobody can own. > (https://skills.wondel.ai/skills/traction-eos/) Then install the meeting that makes Rocks real. The Level 10 Meeting is the same day, same time, same 90-minute agenda every week: segue, scorecard, Rock review, headlines, to-do list, then sixty minutes of IDS — Identify, Discuss, Solve. Most stalled companies have meetings that are 90% status and 10% problem-solving; EOS inverts that. The point of the meeting is to solve issues permanently, not to narrate them. The IDS track itself is a skill the agent can run: ask "why" until you reach the root cause, state the issue in one sentence, give everyone input but not equal time, then decide and assign an owner. > **Prompt** — Use the `traction-eos` skill to design our weekly Level 10 Meeting agenda with time boxes for a leadership team of six, and facilitate an IDS pass on our top recurring issue: support tickets spike every Monday and nobody owns the root cause. Drive it to a one-sentence problem statement, a decision, and an owner with a date. > (https://skills.wondel.ai/skills/traction-eos/) If you only adopt one thing from this layer, make it the Level 10 cadence. The recurring rhythm is what converts a one-time strategy offsite into a company that actually changes its behavior. Protect the meeting; never cancel it. A stalled business that starts solving its real issues to root cause, weekly, feels different within a month. ## Phase 3 — Fix how the business is managed for output You now have direction and a cadence. The next plateau-breaker is leverage: a manager's job is not to be busy, it is to multiply the output of everyone around them. [High Output Management](https://skills.wondel.ai/skills/high-output-management/) is Andy Grove's operating manual for exactly this, and its core equation is the one most stalled-business owners have never internalized: **a manager's output equals the output of their organization plus the output of the neighboring teams they influence.** Nothing you personally do counts in itself — it counts only through how it raises that combined output. That reframe is uncomfortable for founder-operators because it indicts the habits that feel productive: doing the work yourself, approving everything, being the bottleneck everyone routes through. Grove names these negative-leverage activities — meddling (supervising an expert in detail), waffling (stalling a decision others are waiting on), and broadcasting your own gloom — and shows they multiply *downward* through the team. Start by auditing your own week. > **Prompt** — Use the `high-output-management` skill to audit my calendar for managerial leverage — I am pasting the last two weeks as the operator of a 22-person company. Identify the high-leverage activities I am skipping (1:1s, training, well-prepared decisions) and the negative-leverage habits I am indulging — especially the places where I am the approval bottleneck. Then propose a redesigned week built around forecasted key events. > (https://skills.wondel.ai/skills/high-output-management/) Two specific Grove tools repay the most in a stalled company. The first is the **one-on-one**, which Grove insists is the subordinate's meeting: they own the agenda and bring it, you listen and take the notes, and the real issue usually surfaces in the last five minutes when you ask "what else is on your mind?" Frequency is set by task-relevant maturity (TRM), not seniority — weekly for someone new to a task, monthly for a veteran, never less. The second is **delegation without abdication**: delegate the tasks you know best because monitoring them costs you least, then monitor at the task level, sampling deeper when TRM is low and lighter as it rises. > **Prompt** — Use the `high-output-management` skill to design a 1:1 system for my direct reports. For each, set the cadence based on their task-relevant maturity for their current main task, give me a subordinate-owned agenda template, and show me how to run delegation-with-monitoring for the work I keep grabbing back so I stop being the bottleneck without abandoning quality. > (https://skills.wondel.ai/skills/high-output-management/) The third Grove idea — output indicators paired with quality counterparts — overlaps with the measurement work in Phase 6, so hold it for now. The management layer's job is to convert your own scarce hours into the team's multiplied output, and to make delegation safe enough that you can finally step off the critical path. ## Phase 4 — Reshape teams so work stops getting stuck between them Sometimes the plateau is not strategy, cadence, or management — it is structure. If every meaningful change requires three teams to coordinate, if handoffs eat weeks, if "who owns this?" has no clean answer, the org chart itself is the bottleneck. [Team Topologies](https://skills.wondel.ai/skills/team-topologies/) by [Matthew Skelton and Manuel Pais](https://teamtopologies.com/book) is the skill for this, and its founding observation is Conway's law: organizations ship their communication structure. Your systems and processes are a mirror of how your teams actually talk, so if the output is tangled, the team boundaries are tangled. The skill reduces every team to one of four types — **stream-aligned** (owns a flow of business value end to end; the default and the majority), **enabling** (grows a capability in other teams, then leaves), **complicated-subsystem** (encapsulates deep specialist knowledge), and **platform** (provides an internal product that reduces everyone else's load). The diagnostic value for a stalled business is enormous: most plateaued orgs are full of ambiguous charters — "the operations team," "the data team" — that accumulate work belonging nowhere and interact unpredictably. > **Prompt** — Use the `team-topologies` skill to classify our current teams against the four fundamental team types — I am pasting each team and what it actually does day to day. Flag the anti-patterns — especially any shared-services ticket queue or a team split by function rather than by value stream — and propose a structure where each stream-aligned team can deliver a typical change without waiting on another team. > (https://skills.wondel.ai/skills/team-topologies/) The second lever is **cognitive load**. Teams thrash not because they are too small but because they own too many domains. The heuristic is concrete: at most one complicated domain per team, and never split a single complicated domain across two teams. When a team is drowning, the fix is fewer domains, not more headcount. And the cheapest load to remove is extraneous — the tooling, environments, and process friction that a thin internal platform or a few paved paths can eliminate without any reorg at all. > **Prompt** — Use the `team-topologies` skill to diagnose our overloaded delivery team, whose lead times keep climbing. Count and classify the domains it currently owns, tell me whether the problem is too many domains or genuine overload, and recommend which domains to shed to another team versus which extraneous load we could remove with better tooling. Then define the explicit interaction mode — collaboration, X-as-a-service, or facilitating — between that team and each team it depends on. > (https://skills.wondel.ai/skills/team-topologies/) A word of judgment: a reorg is disruptive, so reach for this layer only when the evidence points at structure — handoffs dominating lead time, the same coordination meetings recurring, shared ownership making everything everyone's-and-no-one's. If your teams already deliver cleanly, skip ahead. Team Topologies is the right tool precisely when the work keeps getting stuck *between* people rather than *within* them. ## Phase 5 — Re-motivate the people who quietly checked out A stalled business has a morale signature: your best people are still showing up, but the spark is gone. The reflexive fix — a spot bonus, a contest, a new incentive plan — usually makes it worse, and [Drive Motivation](https://skills.wondel.ai/skills/drive-motivation/) explains exactly why. Daniel Pink's research is that for any task requiring even rudimentary cognitive effort, "if-then" rewards either do not work or actively degrade performance: they extinguish intrinsic motivation, narrow focus, crush creativity, and foster short-term thinking. The carrot-and-stick model is built for routine algorithmic work, and almost nothing in your business is routine algorithmic work anymore. What actually sustains performance is intrinsic — Pink's three pillars of **Autonomy, Mastery, and Purpose** (AMP). Autonomy is choice over the four T's: task, time, technique, and team. Mastery is the chance to visibly get better at something that matters, calibrated so the challenge sits between boredom and anxiety. Purpose is the sense of serving something larger than the next quarterly number. Audit your current setup against all three. > **Prompt** — Use the `drive-motivation` skill to audit our team's motivation system — how we run incentives, reviews, and goals — against Autonomy, Mastery, and Purpose. Score it 0 to 10, identify where we are accidentally using controlling if-then rewards that crowd out intrinsic motivation, and give me specific changes — including how to shift to now-that recognition — that restore autonomy and a sense of progress. > (https://skills.wondel.ai/skills/drive-motivation/) The compensation principle is worth stating plainly because it contradicts most operators' instincts: pay people enough to take money off the table — fair, ideally above market — and then stop using money as the lever. Beyond "enough," more money does not increase motivation for cognitive work; it just resets expectations. Replace "if-then" bonuses ("hit the target and you get X") with "now-that" recognition ("you hit the target — here's an unexpected thank-you"), which delivers the reward without the pressure and gaming that come from dangling it in advance. This layer pairs naturally with Phases 3 and 4: the autonomy Grove's delegation creates and the clear ownership Team Topologies establishes are themselves powerful motivators. When you stop being the bottleneck and give people a domain they genuinely own, you are not just improving flow — you are rebuilding the autonomy and mastery that a plateau erodes. ## Phase 6 — Measure the one number that actually tells you the truth By now you have direction, cadence, leverage, structure, and motivation. The risk is that you are still steering by the wrong instruments. Stalled businesses are usually swimming in data and starving for insight: a dashboard of forty metrics, every meeting citing a different number, and nobody able to say whether last month was good. [Lean Analytics](https://skills.wondel.ai/skills/lean-analytics/) by [Alistair Croll and Benjamin Yoskovitz](https://leananalyticsbook.com/) is the discipline that fixes this, and its core principle is ruthless: focus on the one metric that matters right now — everything else is noise that feels like progress. The skill teaches you to separate good metrics from vanity metrics. A good metric is comparative, understandable, a ratio or rate (not an ever-growing total), and behavior-changing — if a number will not change what you do next, stop watching it. The single most reliable vanity tell is the cumulative up-and-to-the-right chart: total signups, total users, total revenue all rise even while the business bleeds. Start by purging the dashboard. > **Prompt** — Use the `lean-analytics` skill to purge our metrics dashboard — I am pasting the 30-plus numbers currently on it. Identify which are vanity metrics — especially the cumulative totals — and rewrite each as an actionable ratio or rate. Then, given that we are a B2B SaaS business that is past product-market fit but with growth flattening, pick our One Metric That Matters plus a counter-metric that keeps it honest, and tell me what business model and stage you think we are in. > (https://skills.wondel.ai/skills/lean-analytics/) The second move is the **One Metric That Matters (OMTM)** with a counter-metric and a line in the sand. The OMTM is the number that tells you whether the riskiest part of the business is working right now; it rotates as you pass stage gates. You pair it with a counter-metric so it cannot be gamed — activation speed paired with 30-day retention, sales velocity paired with refund rate. And you draw a line in the sand with three parts: a target number, a date, and a pre-committed answer to "what do we do if we miss?" decided *before* the results arrive, so the goalposts cannot move. > **Prompt** — Use the `lean-analytics` skill to walk me through the stickiness gate, because our growth has stalled and I suspect we are pouring acquisition spend into a leaky bucket. Build cohort retention tables from our signup-month data, tell me whether our retention curve has actually flattened, and draw a line in the sand for our OMTM — target, date, and the pre-committed action if we miss it. > (https://skills.wondel.ai/skills/lean-analytics/) This layer is the feedback loop for everything above it. The chain-link constraint from Phase 1, the Rocks from Phase 2, and Grove's paired output indicators from Phase 3 all become testable here. Without a real OMTM, every result gets rationalized and no experiment can fail — which is its own quiet kind of plateau. ## Phase 7 — Stop leaking margin in every negotiation The last two layers are the highest-leverage commercial moves in a business that already has customers, because they drop almost entirely to the bottom line. Start with the conversations you are probably handling on instinct: renewals, vendor contracts, big-deal terms, and the relentless pressure to discount. [Negotiation](https://skills.wondel.ai/skills/negotiation/) packages Chris Voss's tactical-empathy method from [*Never Split the Difference*](https://www.blackswanltd.com/never-split-the-difference), and its governing idea is that the path to a good outcome runs through making the other side feel understood — not through logic, argument, or splitting the difference. Voss's hard rule: no deal is better than a bad deal. The most immediately useful pattern for a stalled business is the renewal under price pressure, where the operator's instinct is to cave on price the moment a customer mentions a cheaper competitor. The skill arms you with the **accusation audit** (preemptively voicing every negative the other side might be thinking, which defuses it), **calibrated questions** ("how am I supposed to do that?" is the most powerful pushback that isn't a no), **labeling** ("it sounds like…"), and the **Ackerman** bargaining structure of decreasing increments ending on a precise, non-round number plus a non-monetary sweetener. > **Prompt** — Use the `negotiation` skill to prepare me for a renewal where our largest customer at 180K per year says they have a competing bid 30 percent cheaper and my instinct is to discount. Write an accusation audit to open the call, draft five calibrated questions that surface the real driver behind the threat (a Black Swan), and design an Ackerman plan with my target price, three decreasing increments, and a non-monetary concession to add at the end instead of cutting price. > (https://skills.wondel.ai/skills/negotiation/) The deeper payoff is **Black Swans** — the hidden pieces of information that transform a negotiation once you find them. Voss's claim is that every negotiation has roughly three lurking: secret constraints (their boss capped the budget), hidden motivations (this deal saves someone's job), or unknown context (a competitor just moved). The competing bid is rarely the real story; tactical empathy and calibrated questions are how you uncover what is. The same skill works on vendor renewals, where the discipline of never conceding without getting something in return can claw back real cash from your cost base. > **Prompt** — Use the `negotiation` skill to help me prepare for renegotiating our biggest software vendor contract at renewal, where they have proposed a 12 percent increase. Build a plan that uses labeling and calibrated questions to understand their position, anchors against the increase without an extreme counter, and trades any concession I make for something of value — a longer term, a case study, a reference — rather than giving ground for free. > (https://skills.wondel.ai/skills/negotiation/) ## Phase 8 — Reprice around the value you actually deliver The final and often largest lever is the one most stalled businesses are most afraid to touch: price. If your pricing was set years ago from cost-plus math or by copying a competitor, you are almost certainly leaving money on the table, charging the wrong segments the wrong amounts, or both. [Monetizing Innovation](https://skills.wondel.ai/skills/monetizing-innovation/) by [Madhavan Ramanujam and Georg Tacke](https://www.wiley.com/en-us/Monetizing+Innovation%3A+How+Smart+Companies+Design+the+Product+to+Capture+Value-p-9781119240860) is the skill for repricing, and its core finding is sobering: 72% of new products miss their revenue targets, and the common root cause is treating price as an afterthought. Price is the clearest measure of how much customers value what you offer — which makes it a diagnostic, not just a number. The skill's first contribution is naming which **monetization failure** you are drifting toward. There are four: *feature shock* (cramming so much in that value and clarity collapse), *minivation* (the right product priced too timidly — its signature is a near-100% win rate and zero price pushback), *hidden gem* (a valuable offering nobody monetizes because it has no owner), and *undead* (a product kept alive past the evidence). A stalled business with a high close rate and no pricing objections is very often minivating — quietly undercharging — and does not realize it. > **Prompt** — Use the `monetizing-innovation` skill to diagnose which of the four monetization failures we are drifting toward — feature shock, minivation, hidden gem, or undead — using our win rates, price-objection frequency, and recent deals, and tell me what evidence confirms or rules each one out. > (https://skills.wondel.ai/skills/monetizing-innovation/) The second contribution is **segmentation by willingness to pay** and **leader-filler-killer packaging**. Customers differ in what they value and what they will pay, so one offer at one price overcharges some and undercharges the rest; the fix is three or four offers built on WTP clusters, not demographics. Within those tiers, every feature is a *leader* (drives the purchase), a *filler* (modest value), or a *killer* (actively reduces willingness to pay if customers are forced to fund it). The classic mistakes a stalled business makes are giving the leader feature away in the cheapest tier, so nobody has a reason to upgrade, and bundling a killer that gives buyers a reason to reject the whole package. > **Prompt** — Use the `monetizing-innovation` skill to audit our pricing tiers using leader-filler-killer. Tell me which feature is the leader that we are mistakenly giving away in the entry tier, whether any killer feature is dragging down a bundle and should become an add-on, and how to restructure the tiers so the middle tier is the one we actually want to sell — anchored by a deliberately premium top tier. > (https://skills.wondel.ai/skills/monetizing-innovation/) Before any price change ships, have the agent design a **willingness-to-pay conversation** you can run with real customers — the acceptable / expensive / prohibitively-expensive probes, purchase-probability on a 1–5 scale where only the top box counts — so the new pricing rests on evidence, not nerve. Repricing is the move with the shortest path to profit in a business that already has demand; done from validated WTP rather than gut feel, it routinely breaks a revenue plateau on its own. ## Your checklist - [ ] Run a `good-strategy-bad-strategy` audit of your current plan; score it and write a one-page kernel — diagnosis, guiding policy, coherent actions - [ ] Identify the single binding chain-link constraint and set one proximate objective against it - [ ] Write your explicit no-list: what this strategy says you will stop doing - [ ] Translate the strategy into 5–7 quarterly Rocks with one owner each, using `traction-eos` - [ ] Install the weekly Level 10 Meeting and start running IDS on recurring issues to root cause - [ ] Audit your own calendar for leverage with `high-output-management`; cut the negative-leverage habits - [ ] Set up subordinate-owned 1:1s on a TRM-based cadence and delegate-with-monitoring off your critical path - [ ] If work keeps getting stuck between teams, classify them with `team-topologies` and realign to value streams - [ ] Check team cognitive load — at most one complicated domain per team — and shed or platform-ize the excess - [ ] Audit incentives against Autonomy, Mastery, Purpose with `drive-motivation`; replace if-then bonuses with now-that recognition - [ ] Purge vanity metrics with `lean-analytics`; pick one OMTM, a counter-metric, and a line in the sand - [ ] Build cohort retention tables and confirm whether you've actually passed the stickiness gate - [ ] Prepare your next big renewal with `negotiation`: accusation audit, calibrated questions, an Ackerman plan - [ ] Diagnose your monetization failure with `monetizing-innovation` and reprice from validated willingness to pay ## Common mistakes **Jumping to tactics before the diagnosis.** The plateau tempts you to grab a channel or a feature. Without Phase 1's honest diagnosis, you will pour effort into a strong link while the weak one stays jammed. Do the strategy work first, even though it feels slower — it is the thing that makes everything else land. **Treating the strategy offsite as the finish line.** A kernel that lives in a deck changes nothing. The Level 10 cadence from Phase 2 is what converts a one-time decision into a company that behaves differently. If you adopt one thing, adopt the weekly rhythm — and never cancel it. **Confusing being busy with creating output.** The hardest habit for a founder-operator to break is doing the work themselves. Grove's whole point is that your output is your *organization's* output. Every hour you spend as the approval bottleneck is negative leverage multiplying downward. Delegate the work you know best, monitor by task-relevant maturity, and get off the critical path. **Reorganizing when the problem isn't structure.** Team Topologies is powerful, but a reorg is disruptive and seductive — it *feels* like decisive action. Only reach for Phase 4 when the evidence points at structure: handoffs dominating lead time, recurring coordination meetings, ownership that's everyone's-and-no-one's. If teams already deliver cleanly, skip it. **Throwing money at disengagement.** A contest or a spot bonus to re-energize the team usually backfires. If-then rewards crowd out the intrinsic motivation that actually sustains cognitive work. Pay fairly enough to take money off the table, then rebuild autonomy, mastery, and purpose instead. **Steering by vanity metrics.** A cumulative chart that only goes up will hide a business that's quietly decaying. If a number won't change a decision, it's noise. Pick the one metric that reflects your riskiest assumption, guard it with a counter-metric, and commit to a miss response in advance. **Discounting on instinct at renewal.** Caving the moment a customer names a cheaper competitor leaves margin on the table and trains them to push every time. The competing bid is rarely the real story — hunt the Black Swan, and never concede without getting something back. **Repricing from cost or competitors instead of value.** Cost-plus and copycat pricing anchor on the wrong thing entirely. A high win rate with no price pushback is the signature of undercharging. Reprice from validated willingness to pay, segment by it, and make sure your cheapest tier doesn't give away the leader feature. ## Frequently asked questions ### Which skill should I start with if I can only install one? [Good Strategy Bad Strategy](https://skills.wondel.ai/skills/good-strategy-bad-strategy/). Every other layer inherits the quality of your diagnosis. If you skip it, you risk installing a flawless execution rhythm (Phase 2) around the wrong objective, or repricing (Phase 8) without knowing which constraint is actually capping the business. An hour spent forcing your plan through the kernel — diagnosis, guiding policy, coherent action — reframes everything that follows. If you want a fast second, add `traction-eos`, because the Level 10 cadence is what makes the strategy stick. ### How long does this realistically take? Plan for two quarters. Phase 1 is about a week of focused strategy work. Phases 2 through 5 — installing the operating rhythm, fixing how you manage and shape teams, and re-motivating people — take a full quarter to bed in, because cadence and behavior change need repetition. Phases 6 through 8 (metrics, negotiation, pricing) run as a parallel track and can produce results faster, since fixing your OMTM or repricing from validated willingness to pay can move numbers within weeks. The eight skills combine into one workflow, but you don't install them all on day one — work the layers in order. ### Do these skills work for a services or brick-and-mortar business, not just SaaS? Mostly yes, with judgment. The strategy, EOS, management, team, and motivation skills are model-agnostic — `good-strategy-bad-strategy`, `traction-eos`, `high-output-management`, and `drive-motivation` were written for general business and apply cleanly to an agency, a clinic, or a manufacturer. `lean-analytics` and `monetizing-innovation` lean toward digital and subscription models but carry frameworks (the OMTM, willingness-to-pay segmentation, leader-filler-killer packaging) that translate well — a services firm absolutely has an OMTM and a WTP curve. `team-topologies` is the most engineering-specific; treat it as the optional structural layer and apply it only if you run technology teams. ### What's the difference between this guide and the "grow" guide? This guide is about *improving* a business that has stalled — fixing the internal machinery (strategy clarity, execution, management, motivation, pricing) so it can move again. The companion guide, [grow an existing business with AI skills](https://skills.wondel.ai/guides/grow-an-existing-business-with-ai-skills/), focuses on *expansion* once the engine is healthy — acquisition channels, demand generation, and scaling what already works. Improve first, then grow: pouring growth effort into a business with a jammed chain-link or a leaky retention bucket just burns money faster. ### How do I actually invoke a skill once it's installed? Install it once with `npx skills add wondelai/skills/ --global` — for example `npx skills add wondelai/skills/lean-analytics --global`. Then in your AI agent (Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw, or Hermes Agent) you invoke it by writing a prompt that names it, exactly like the prompt blocks throughout this guide: "Use the `lean-analytics` skill to…". The skill loads its full framework into the agent's context so it applies the real method — Rumelt's kernel, Grove's leverage equation, Voss's tactical empathy — to the specific numbers, plans, and conversations you paste in. Be concrete: reference your actual dashboard, your real renewal, your current pricing page. ## Get started A stalled business doesn't need a hero quarter. It needs an honest diagnosis, a cadence that survives Monday, a manager who multiplies instead of bottlenecks, and the discipline to measure, negotiate, and price from reality. These eight skills give your AI agent the actual frameworks to do all of it with you — free, open-source, and MIT-licensed. Install the whole library in about thirty seconds: `npx skills add wondelai/skills --all --global` Then start with Phase 1: paste your current plan into your agent and tell it to use the `good-strategy-bad-strategy` skill to audit it as strategy. The diagnosis you get back is usually the first time the real obstacle has been named out loud — and that's where every turnaround begins. When the engine is running clean again, move on to [grow an existing business with AI skills](https://skills.wondel.ai/guides/grow-an-existing-business-with-ai-skills/) to scale what works. If your stall is on the product side rather than the business side, [improve an existing app with AI skills](https://skills.wondel.ai/guides/improve-an-existing-app-with-ai-skills/) runs the same diagnose-then-fix discipline on the product experience itself. --- # How to Improve an Existing Website with AI Skills > Diagnose and fix an underperforming website — conversion, usability, messaging, speed, and polish — with AI agent skills from Making Websites Win, Don't Make Me Think, Refactoring UI, and more. By Michał Jaskólski · Published 2026-06-25 · Updated 2026-08-06 · 16 min read Canonical: https://skills.wondel.ai/guides/improve-an-existing-website-with-ai-skills/ Skills used: cro-methodology, ux-heuristics, refactoring-ui, web-typography, storybrand-messaging, high-perf-browser, made-to-stick, design-everyday-things **TL;DR:** You improve an existing website by diagnosing before redesigning: research why visitors don't convert with CRO Methodology, remove usability friction against Nielsen's heuristics, fix visual hierarchy and typography, sharpen the message with StoryBrand, then make the page fast against Core Web Vitals — a ranked list of evidence-backed fixes instead of a prettier page that converts the same. - Never redesign on a hunch — every non-converting visitor has a discoverable reason, and research beats best-practice guessing every time. - Fix severity-4 usability catastrophes before cosmetic polish: frequency, impact, and persistence rank the queue. - Speed is a message: no amount of copy or design survives a hero section that takes four seconds to paint. - Install the whole diagnostic stack with npx skills add wondelai/skills --all --global and work the phases in order — research feeds message, message feeds proof. You already have a website. It is live, it gets traffic, and it is quietly underperforming. Visitors land and leave. The signup count is flat. Someone on the team says "the homepage feels off" and someone else says "we should redesign it," and three weeks later you have a prettier page that converts exactly the same. The problem with improving an existing site is not a shortage of opinions — it is a shortage of evidence about which opinion is right. This guide gives you a different approach: a sequenced diagnostic that turns vague dissatisfaction into a ranked list of specific, defensible fixes. Each phase is driven by an AI agent skill that packages a canonical book on its subject, so your agent (Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw, or Hermes Agent) isn't improvising from generic web-tips — it is applying the actual methodology from *Making Websites Win*, *Don't Make Me Think*, *Refactoring UI*, *On Web Typography*, *Building a StoryBrand*, *High Performance Browser Networking*, *Made to Stick*, and *The Design of Everyday Things*. The order matters, and it is deliberate. You start by finding out **why** visitors don't convert (research, not guessing). Then you remove the **usability** friction that makes them stumble, sharpen the **visual hierarchy** and **typography** so the page reads at a glance, rewrite the **message** so a stranger understands the offer in five seconds, make the page **fast** so none of that work is wasted on a slow load, make the core idea **memorable** so it survives the trip to a buying decision, and finally close the loop with **error-tolerant design** so the few visitors who do act never get stuck. By the end you will not have "a redesign." You will have a prioritized backlog of changes, each tied to a reason, plus the experiment design to prove the big ones actually worked. You don't need all eight skills on day one. But installed together they form a single pipeline — diagnose, fix, prove — that you can run on a homepage, a pricing page, a checkout flow, or the entire funnel. Let's walk it. ## Phase 1 — Diagnose why visitors don't convert **Skill: [CRO Methodology](https://skills.wondel.ai/skills/cro-methodology/)** (from [*Making Websites Win*](https://conversion-rate-experts.com/making-websites-win/)) Before you change a single pixel, find out what is actually broken. The central rule of the CRO Methodology skill is blunt: **don't guess — discover.** Every visitor who doesn't convert has a reason, and your team's theory about that reason is, statistically, almost always wrong. Conversion Rate Experts built a career on doubling the sales of sites for Google, Apple, and Amazon precisely by researching visitors instead of copying competitors or applying "best practices" on faith. So the first job is research, not redesign. Point your agent at the page and have it map the funnel to find **blocked arteries** (high-traffic stages that underperform) and **missing links** (funnel stages that don't exist yet). A homepage with a 70% bounce rate and a checkout with 40% abandonment are two completely different problems, and you want to spend your effort on the one that moves the most money. The skill also forces you to name the **ONE action** the page exists to drive — a page with three competing CTAs has no conversion goal, it has a committee. The richest output of this phase is the **Objection/Counter-Objection (O/CO) table**. Visitors arrive with objections — the "Big 5" are Trust, Price, Fit, Timing, and Effort — and if the page doesn't answer them at the point they arise, the visitor leaves. The skill builds a table mapping each researched objection to a specific, evidence-backed counter, placed where the friction actually occurs (the security objection next to the credit-card field, not buried in an FAQ). Critically, the counter-objections use the customer's *own language* pulled from reviews, support tickets, and exit surveys — which out-persuades any copywriter's invention. > **Prompt** — Use the `cro-methodology` skill to audit my pricing page: map the funnel to find where the biggest drop-off is, then build an Objection/Counter-Objection table for each plan tier using the Big 5 objections, and tell me which persuasion assets (testimonials, guarantees, specificity) are missing > (https://skills.wondel.ai/skills/cro-methodology/) > **Prompt** — Use the `cro-methodology` skill to design an exit-intent survey with a single question to discover why visitors leave my homepage without signing up, then draft the post-purchase survey question that reveals what almost stopped converting customers from buying > (https://skills.wondel.ai/skills/cro-methodology/) > Don't guess — discover. Every visitor who doesn't convert has a reason, and your team's theory about that reason is almost always wrong. One more thing the skill will insist on, and you should let it: prioritize with **ICE scoring** (Impact, Confidence, Ease) and design **bold experiments, not meek tweaks**. Testing a button color wastes traffic on an effect too small to ever reach significance. Testing a fundamentally clearer value proposition can double conversion. The skill ends Phase 1 by handing you a ranked list of hypotheses in the format "If we change X, then metric Y will improve because [reason from research]." That ranked list is the spine of everything that follows. ## Phase 2 — Remove the usability friction **Skill: [UX Heuristics](https://skills.wondel.ai/skills/ux-heuristics/)** (from *Don't Make Me Think*) Research tells you what visitors object to. Usability tells you where they *stumble* — the friction that makes them give up before they ever weigh your offer. [Steve Krug's first law](https://sensible.com/dont-make-me-think/) is the title of his book: **Don't Make Me Think.** Every question mark that pops into a visitor's head ("Wait, is that a link?" "Where am I?" "What does this label mean?") is cognitive load that competes with the task. Users don't read, they scan; they don't make optimal choices, they satisfice; they don't figure out how things work, they muddle through. Have your agent run a heuristic evaluation against [**Nielsen's 10 heuristics**](https://www.nngroup.com/articles/ten-usability-heuristics/) and rate each violation on the 0–4 severity scale, so you fix catastrophes (severity 4: prevents task completion) before cosmetics (severity 1: minor annoyance). The skill weighs three factors — frequency, impact, and persistence — so a small annoyance that hits every visitor on every page can outrank a big problem buried in a rarely-seen corner. A few checks pay off immediately on most sites. The **Trunk Test**: drop the agent on a random interior page and ask whether a visitor can instantly answer "What site is this? What page? What are my options? Where am I in the hierarchy? Where's search?" If not, your navigation is leaking visitors who feel lost. **Get rid of half the words**, then half of what's left — happy-talk ("Welcome to our website!") and instructions nobody reads are pure noise that buries the words that matter. And kill **mystery-meat navigation** — icons without labels force guessing, and every guess is a thought you promised not to make them have. > **Prompt** — Use the `ux-heuristics` skill to run a heuristic evaluation of my checkout flow against Nielsen's 10 heuristics, rate every issue 0-4 for severity weighing frequency and impact, and run the Trunk Test on each step to confirm a user always knows where they are and what to do next > (https://skills.wondel.ai/skills/ux-heuristics/) > **Prompt** — Use the `ux-heuristics` skill to review my signup form for usability problems: flag missing inline validation, unclear required fields, jargon labels, and tiny tap targets, then rewrite the error messages to say what went wrong and how to fix it > (https://skills.wondel.ai/skills/ux-heuristics/) The payoff here compounds with Phase 1: an O/CO table is worthless if visitors can't find the answer because the page is confusing. Usability is what lets your persuasion actually land. ## Phase 3 — Fix the visual hierarchy **Skill: [Refactoring UI](https://skills.wondel.ai/skills/refactoring-ui/)** (from *Refactoring UI*) Now the page reads clearly in principle — but does it *look* like it reads clearly? The Refactoring UI skill, built from Adam Wathan and Steve Schoger's book, rests on one counterintuitive idea: **great UI isn't about talent, it's about systems.** Constrained scales for spacing, type, color, and shadow produce professional results without a designer. And the foundational move is to **design in grayscale first** — strip the color out, and force the page to establish hierarchy through size, weight, contrast, and spacing alone. If the page falls apart in grayscale, color was a crutch. The most common reason an existing site "looks amateur" is not ugly colors — it is that **everything competes for attention**. The skill's first principle is visual hierarchy through three levers (size, weight, color), with a rule most people break: combine levers, don't multiply. Primary text is large *or* bold *or* dark — save all three for the single most important element on the page. Form labels, table headers, and metadata are *secondary*; make them smaller, lighter, or uppercase-small so the data they describe can dominate. The second-most-common problem is spacing. Have the agent enforce the spacing scale (4, 8, 16, 24, 32, 48, 64px) and the rule that **spacing between groups must exceed spacing within groups** — that single relationship is what makes a layout read as organized instead of soupy. Constrain text width to 45–75 characters; full-width body text is almost never right. And tell it to start with too much white space and remove, because you will almost never remove enough. > **Prompt** — Use the `refactoring-ui` skill to audit my homepage hero and feature section in grayscale first: fix the visual hierarchy using size, weight, and color without pulling all three levers at once, enforce the 4/8/16/24/32/48/64 spacing scale so gaps between groups exceed gaps within them, and give me the exact Tailwind classes to change > (https://skills.wondel.ai/skills/refactoring-ui/) > **Prompt** — Use the `refactoring-ui` skill to fix my primary CTA button so it stands out from the page — increase its contrast and apply the right shadow elevation, and tone down the three secondary buttons competing with it so there is one obvious primary action > (https://skills.wondel.ai/skills/refactoring-ui/) Only after the grayscale layout works should the agent add color — a systematic palette of 5–9 shades per hue, with grays tinted (never pure `#000`) so the interface feels alive instead of lifeless. Color is the last 10%, not the first. ## Phase 4 — Make the words readable **Skill: [Web Typography](https://skills.wondel.ai/skills/web-typography/)** (from *On Web Typography*) Hierarchy and typography overlap, but typography deserves its own pass because it is where "the text is hard to read" complaints actually live — and because, as Jason Santa Maria argues, **getting size, line length, and line height right matters more than which typeface you pick.** Typography is the voice of your content; the best of it is invisible, immersing readers in the words rather than calling attention to itself (the "clear goblet" principle). The three measurements to fix first: **body size** of at least 16px, ideally 18px for reading-heavy pages (people hold phones farther than designers assume); **line length** of 45–75 characters, with 66 the sweet spot, enforced via `ch` units or `max-width`; and **line height** of 1.5–1.7 for body text, tighter (1.1–1.25) for headings. These three govern how the eye tracks across and down the page — get them wrong and reading slows, the return sweep lands on the wrong line, and visitors bail on your carefully-written copy. Have the agent build a hierarchy on a consistent modular scale (a 1.2–1.5 ratio between levels) and apply the **squint test**: blur the page, and the hierarchy should still be obvious. It will also catch the small stuff that signals amateurism — headings with too much space above and not enough below (which visually detaches them from the content they introduce), orphaned words on heading lines (`text-wrap: balance`), and body weights set below 400. > **Prompt** — Use the `web-typography` skill to evaluate the typography on my blog article template: check that body text is at least 16px, line length is capped near 66 characters with max-width, and line height is 1.5-1.7, then deliver the corrected CSS with a fluid clamp() scale for headings > (https://skills.wondel.ai/skills/web-typography/) There is a performance angle here too, which is why this phase sits right before the speed phase: web fonts are render-blocking by default. The skill will push `font-display: swap` so fallback text shows immediately, preload the one critical font, subset to the characters you actually use, and keep the total font payload under 200KB — a single variable font often replacing four to six static weight files. Hold that thought; Phase 6 picks it up. ## Phase 5 — Sharpen the message **Skill: [StoryBrand Messaging](https://skills.wondel.ai/skills/storybrand-messaging/)** (from *Building a StoryBrand*) A visitor can see your page perfectly and read it comfortably and still leave — because they can't tell what you do or why it matters to them. [Donald Miller's core principle](https://storybrand.com/) is the one most brands get backwards: **the customer is the hero, not your brand.** Your brand is the guide who helps the hero win — think Yoda, not Luke. The moment your copy makes *you* the hero ("We're the industry-leading platform..."), you start competing with your customer instead of serving them. Run the agent through the **SB7 framework** on your homepage copy: a Character (the customer) who wants one specific thing, a Problem defined at three levels (external, internal, and philosophical — most brands only name the external one and miss the emotional driver that actually closes sales), a Guide who shows empathy *and* authority, a Plan (3–4 simple steps that make the path feel safe), a Call to Action (one prominent Direct CTA, plus a Transitional CTA for the not-yet-ready), a stake of Failure, and a vivid picture of Success. The diagnostic question the skill applies: **can a caveman grasp the offer in five seconds?** If not, the message is too complex. The single highest-leverage artifact is the **one-liner** — one sentence in the form "We help [character] who struggle with [problem] to [solution] so they can [result]" — that you then use everywhere: homepage header, email signature, sales calls, ad copy. The test is whether someone can repeat it after hearing it once. > **Prompt** — Use the `storybrand-messaging` skill to rewrite my homepage above-the-fold copy using the SB7 framework: make the customer the hero, name their internal problem not just the external one, position us as the guide with empathy and authority, and give me one Direct CTA plus one Transitional CTA > (https://skills.wondel.ai/skills/storybrand-messaging/) > **Prompt** — Use the `storybrand-messaging` skill to write three one-liner options for my SaaS in the format we help [character] who struggle with [problem] to [solution] so they can [result], then tell me which passes the repeat-after-one-hearing test > (https://skills.wondel.ai/skills/storybrand-messaging/) This phase feeds back into Phase 1 beautifully: the objections you researched in the CRO phase tell you exactly which internal problems and which proof points the StoryBrand copy must address. Research and message are two ends of the same rope. ## Phase 6 — Make the page fast **Skill: [High Perf Browser](https://skills.wondel.ai/skills/high-perf-browser/)** (from *High Performance Browser Networking*) None of the previous five phases survive a slow page. A visitor who waits four seconds for the hero to paint has already formed an impression — and bounced — before reading your perfect one-liner. [Ilya Grigorik's foundational insight](https://hpbn.co/) reframes the whole problem: **latency, not bandwidth, is the bottleneck.** Most slow pages suffer from too many round trips, not too little throughput. Throwing a bigger pipe at the problem barely helps; cutting round trips transforms the experience. Have the agent diagnose against [**Core Web Vitals**](https://web.dev/articles/vitals) with concrete targets: LCP under 2.5s, INP under 200ms, CLS under 0.1, TTFB under 800ms. Each maps to a specific class of fix. For **LCP**, identify the largest above-the-fold element (usually the hero image or headline block) and preload it with `fetchpriority="high"`. For **CLS** — the layout-shift jank that destroys trust as content jumps around — reserve space with explicit `width`/`height` or CSS `aspect-ratio` on every image, embed, and ad slot. For **INP**, keep the main thread free by deferring non-critical JavaScript and breaking up long tasks. The skill is opinionated about the network layer in ways that matter for an existing site. CSS is **render-blocking** and JavaScript is **parser-blocking**, so each needs a different strategy: inline critical above-the-fold CSS and async-load the rest; `defer` scripts by default and reserve `async` for genuinely independent ones. Add `preconnect` for critical third-party origins and `dns-prefetch` for the rest. Content-hash your static assets and cache them `immutable` so repeat visitors re-download nothing. And if your site still uses HTTP/1.1 workarounds — domain sharding, image sprites, file concatenation — note that on HTTP/2 these become *counterproductive*, defeating multiplexing; the skill will tell you to undo them. > **Prompt** — Use the `high-perf-browser` skill to diagnose why my landing page is slow: identify the LCP element and preload it, find every image and embed missing explicit dimensions that cause layout shift, list the render-blocking CSS and parser-blocking scripts, and give me a prioritized fix list to get LCP under 2.5s and CLS under 0.1 > (https://skills.wondel.ai/skills/high-perf-browser/) > **Prompt** — Use the `high-perf-browser` skill to review my caching and resource hints: tell me which static assets need content-hashed filenames with immutable Cache-Control, where to add preconnect and preload, and whether any HTTP/1.1 workarounds like domain sharding are hurting me now that I am on HTTP/2 > (https://skills.wondel.ai/skills/high-perf-browser/) Pair this with the font-loading work from Phase 4 and the image treatment from Phase 3, and the page that *reads* clearly now also *arrives* before the visitor's patience runs out. ## Phase 7 — Make the core idea stick **Skill: [Made to Stick](https://skills.wondel.ai/skills/made-to-stick/)** (from *Made to Stick*) Clarity gets a visitor to understand your offer in the moment. Stickiness gets them to *remember* it long enough to act — through the comparison shopping, the "let me think about it," the conversation with a colleague that happens between the visit and the decision. Chip and Dan Heath's central villain is the **Curse of Knowledge**: once you know your product deeply, you literally cannot imagine not knowing it, which makes you systematically bad at explaining it to a newcomer. The antidote is the **SUCCESs** checklist — Simple, Unexpected, Concrete, Credible, Emotional, Stories. Have the agent score your key messages (headline, value prop, the pitch a salesperson gives) on all six and rewrite the weak ones. The two principles that fix the most damage on most sites are **Concrete** and **Simple**. Concrete means replacing abstraction with sensory specifics: not "improve customer experience" but "customers get their order in 30 minutes, still hot"; not "saves time" but "save 16 hours a month." The Velcro theory of memory — concrete ideas have more hooks for the mind to grab. Simple means the **Commander's Intent**: if visitors remember exactly one thing, what must it be? "If you say three things, you say nothing." This phase is where you also fix the credibility numbers. The skill makes statistics human-scale (the Sinatra Test: one example so good it proves everything — "We handle Super Bowl traffic" settles the scalability objection in four words) and uses specific figures over round ones, which dovetails with the CRO skill's persuasion-asset work from Phase 1. > **Prompt** — Use the `made-to-stick` skill to score my homepage headline and three feature descriptions on the SUCCESs checklist, then rewrite each: replace every abstraction with a concrete specific outcome, find the one Commander's Intent message visitors must remember, and make our key statistic human-scale > (https://skills.wondel.ai/skills/made-to-stick/) > Clarity makes a visitor understand you in the moment. Stickiness makes them remember you long enough to act. ## Phase 8 — Design out the errors **Skill: [Design of Everyday Things](https://skills.wondel.ai/skills/design-everyday-things/)** (from *The Design of Everyday Things*) The final phase protects the visitors who actually decided to act. Don Norman's most quoted line reframes every "user mistake" on your site: **there is no such thing as human error — only bad design.** When a visitor fat-fingers the wrong option, abandons a form, or misreads a control, the fault is in the design, not the person. So instead of adding more error messages, the goal is to make the wrong action *impossible*. Have the agent analyze your conversion-critical flows — signup, checkout, account setup — through Norman's two gulfs. The **Gulf of Execution** ("how do I do what I want?") is bridged with clear **signifiers** (a button that looks pressable, a field that looks editable — flat design that erases these is a frequent culprit), natural **mappings**, and **constraints** that limit wrong actions (a date picker instead of a free-text date field, a Submit button disabled until the form is valid). The **Gulf of Evaluation** ("what just happened?") is bridged with immediate **feedback** — within 0.1s for direct manipulation — and visible system state, so a visitor never wonders whether their click registered. The skill's error taxonomy is practical. **Slips** (right intention, wrong action — clicking Delete instead of Edit) are fixed by separating destructive actions and offering undo. **Mistakes** (wrong intention from a flawed mental model) are fixed by aligning the system image with how users actually think. And the error-message checklist is non-negotiable: say what went wrong in human language, say how to fix it, never blame the user, and **preserve their work** — nothing destroys trust like a form that wipes itself on a validation error. > **Prompt** — Use the `design-everyday-things` skill to analyze my checkout flow using Norman's two gulfs: find controls with weak or missing signifiers where users can't tell what is clickable, identify where constraints like input validation or disabled states would make errors impossible, and confirm every action gives feedback within 0.1 seconds > (https://skills.wondel.ai/skills/design-everyday-things/) > **Prompt** — Use the `design-everyday-things` skill to review my signup form's error handling against Norman's error-message checklist: make sure every message says what went wrong and how to fix it, never blames the user, and preserves their input, and recommend where undo should replace are-you-sure confirmations > (https://skills.wondel.ai/skills/design-everyday-things/) ## Your checklist Run these in order. Each builds on the last. - [ ] **Define the ONE action** each key page exists to drive; remove competing CTAs (`cro-methodology`) - [ ] **Map the funnel** to find the highest-impact blocked artery or missing link (`cro-methodology`) - [ ] **Research, don't guess** — run an exit survey and mine reviews and support tickets for real objections (`cro-methodology`) - [ ] **Build the O/CO table** and place counter-objections at the point of friction (`cro-methodology`) - [ ] **Heuristic evaluation** against Nielsen's 10, with 0–4 severity ratings (`ux-heuristics`) - [ ] **Trunk Test** every interior page; fix navigation that leaves visitors lost (`ux-heuristics`) - [ ] **Cut half the words**, then half again (`ux-heuristics`) - [ ] **Grayscale-first hierarchy** using size, weight, and color — one lever at a time (`refactoring-ui`) - [ ] **Enforce the spacing scale** so gaps between groups exceed gaps within them (`refactoring-ui`) - [ ] **Fix the three measurements**: body ≥16px, line length ~66ch, line height 1.5–1.7 (`web-typography`) - [ ] **Rewrite copy with SB7** — customer as hero, internal problem named, one Direct CTA (`storybrand-messaging`) - [ ] **Write the one-liner** and deploy it everywhere (`storybrand-messaging`) - [ ] **Hit Core Web Vitals** — `LCP < 2.5s`, `INP < 200ms`, `CLS < 0.1` (`high-perf-browser`) - [ ] **Inline critical CSS, defer scripts, preconnect, and cache static assets immutable** (`high-perf-browser`) - [ ] **Score messages on SUCCESs** and make every abstraction concrete (`made-to-stick`) - [ ] **Bridge both gulfs** with signifiers, constraints, and 0.1s feedback (`design-everyday-things`) - [ ] **Design a bold A/B test** for each high-ICE change and run it to 95% confidence over a full business cycle (`cro-methodology`) ## Common mistakes **Redesigning before researching.** The cardinal sin. A fresh coat of paint on the same unaddressed objections converts identically. Always run Phase 1 first — the CRO skill exists precisely to stop you from spending three weeks on a prettier page that performs the same. Diagnosis before treatment, every time. **Testing meek tweaks.** Button colors, font-size nudges, and image swaps produce effects too small to ever reach statistical significance — you'll burn weeks of traffic to learn nothing. The CRO skill's ICE scoring is designed to push you toward bold changes (a new value proposition, a fundamentally clearer page) that can actually double conversion. Ask "could this 10x our results?" before you test it. **Letting the HiPPO decide.** The Highest Paid Person's Opinion is not data. When the founder insists the hero image is fine and the head of sales swears the pricing copy works, the answer is not a meeting — it is research and a test. Both the CRO and UX Heuristics skills are built to replace opinion with evidence; use them to settle the argument. **Adding color before the layout works.** Reaching for brand colors to "make it pop" while the grayscale hierarchy is still broken just paints over the real problem. Refactoring UI is emphatic: grayscale first, color last. If the page doesn't read when desaturated, no palette will save it. **Optimizing speed in a vacuum.** Shaving 200ms off a page nobody understands is a rounding error on a rounding error. Performance amplifies good design and clear messaging — it doesn't substitute for them. That's why Phase 6 sits after the clarity work, not before it. (The exception: if your page is so slow that visitors leave before *anything* renders, a quick LCP fix unblocks all the other work — let the high-perf-browser skill triage that case.) **Treating "user error" as the user's fault.** Every abandoned form and mis-clicked control is a design signal, not a user failing. The instinct to add a warning dialog or a longer instruction is usually wrong; the Design of Everyday Things skill will push you toward constraints that prevent the error and undo that forgives it. **Confusing clarity with stickiness.** A message can be perfectly clear in the moment and instantly forgotten. StoryBrand makes you understood; Made to Stick makes you remembered. You need both — run Phase 5 and Phase 7, not one or the other. ## Frequently asked questions ### Which skill should I start with if I can only use one? [CRO Methodology](https://skills.wondel.ai/skills/cro-methodology/). It is the diagnostic that tells you where every other skill should be aimed. Without it you are optimizing blind — fixing typography on a page whose real problem is an unanswered Trust objection, or speeding up a checkout that's actually losing people to a confusing form. Run the CRO research first; it will frequently tell you *which* of the other seven skills to reach for next. If your single biggest complaint is "it looks unprofessional," start with [Refactoring UI](https://skills.wondel.ai/skills/refactoring-ui/) instead; if it's "nobody understands what we do," start with [StoryBrand Messaging](https://skills.wondel.ai/skills/storybrand-messaging/). ### Do these skills conflict with each other? Rarely, and when they do the conflict is productive. The UX Heuristics skill's "get rid of half the words" can tug against the CRO skill's instinct to add proof and counter-objections — the resolution is that you add *the words that answer a researched objection* and cut *everything else*. Refactoring UI's "aesthetic and minimalist" principle and Made to Stick's "unexpected" can feel opposed, but minimalism is about visual noise while unexpectedness is about the idea — a clean page can carry a surprising claim. The skills are designed to be run in sequence precisely so each one's output becomes the next one's input. ### How do I know a change actually worked instead of just feeling better? You measure it. The CRO Methodology skill is rigorous about this: calculate the required sample size *before* you start, run the test for at least one full business cycle (covering weekdays and weekends), never peek and stop early (it inflates false positives dramatically), and require 95% confidence. For low-traffic sites, the skill's advice is to test *bold* changes — a dramatic difference is detectable with a far smaller sample (roughly 4,000 visitors for a 50% lift) than a subtle one. A failed test that teaches you something about your customers beats a "win" you don't understand. ### My site is small and I get very little traffic. Is A/B testing even worth it? Often not in the classic sense — you may not reach significance in a reasonable time. But that doesn't mean you optimize blind. Lean harder on the *qualitative* side of the CRO skill (exit surveys, session research, support-ticket mining) and the *evaluative* skills (UX Heuristics, Design of Everyday Things) that find problems by expert analysis rather than statistics. A heuristic evaluation needs zero traffic. And when you do test, make the change big enough that even a small sample can detect it. Most small sites have catastrophic, obvious problems that don't need a test to justify fixing. ### Can my AI agent run all of this end to end, or do I need to drive each phase? Both work. You can hand the agent one phase at a time using the prompts above, reviewing the output between phases — this is the recommended approach because each phase's findings should inform the next. Or you can ask it to run the full pipeline and produce a single prioritized report. Either way, give it real access: paste actual page URLs, real copy, real CSS, real analytics screenshots. The skills are only as good as the evidence you feed them — generic input produces generic output, and the entire point of this stack is to escape generic advice. ## Get the skills and start diagnosing Stop guessing about your website. Install the stack and let your agent diagnose it against the actual methodologies that built the world's highest-converting sites: ``` npx skills add wondelai/skills --all --global ``` Everything is free, open-source, and MIT-licensed. Install all 51 skills, or add just the ones for the phase you're tackling — `npx skills add wondelai/skills/cro-methodology --global` gets you the diagnostic engine on its own. Once your site is converting, the natural next move is to turn that working funnel into a growth engine — more traffic, more channels, more compounding. Head to [Grow an Existing Website with AI Skills](https://skills.wondel.ai/guides/grow-an-existing-website-with-ai-skills/) for that playbook. And if your product is an app rather than a marketing site, the parallel walkthrough lives in [Improve an Existing App with AI Skills](https://skills.wondel.ai/guides/improve-an-existing-app-with-ai-skills/). --- # How to Improve an Existing App with AI Skills > Fix how a shipped app feels — product fit, UX friction, visual hierarchy, microinteractions, in-app copy, and honest persuasion — with AI agent skills from Competing Against Luck, Don't Make Me Think, Refactoring UI, Influence, and more. By Michał Jaskólski · Published 2026-06-25 · Updated 2026-08-06 · 16 min read Canonical: https://skills.wondel.ai/guides/improve-an-existing-app-with-ai-skills/ Skills used: jobs-to-be-done, ux-heuristics, design-everyday-things, refactoring-ui, microinteractions, made-to-stick, influence-psychology, high-perf-browser, steve-jobs-design-review **TL;DR:** You improve a shipped app by fixing what users feel, in evidence order: re-anchor on the job users hire it for with Jobs to Be Done, remove think-friction with Krug and Nielsen's usability canon, design out errors with Norman's Design of Everyday Things, then polish hierarchy, microinteractions, copy, and perceived speed — ending with a review brutal enough to cut features. - Re-anchor on the job first: an app that shipped features for two years has usually drifted from what users originally hired it for. - There is no human error, only bad design — prefer constraints and undo over warning dialogs users click through on reflex. - Friction findings come before visual polish; a beautiful screen that confuses users is still a leak. - Install the nine skills with npx skills add wondelai/skills --all --global and let each phase's audit feed the next one's backlog. The app already ships and works. It has users, screens, and a real flow — and a steady undertow of complaints that never quite become bugs. People call the interface confusing. Onboarding "works" but half of new signups never reach the moment the app is for. The screens look like a developer laid them out, because a developer did. The upgrade prompt converts almost nobody, the empty states read like API documentation, and everything feels a half-second slower than it should. Nothing is broken. Everything is rough. The instinct is to reach for a redesign — new colors, new navigation, maybe a rebrand. That instinct fails for a predictable reason: **a prettier screen on a confusing flow loses users at the same rate.** The visual layer is usually the *third* problem, behind a product that has drifted off the job users hire it for and flows that make people stop and think. Fixing the surface first is painting over the leak. What actually works is fixing what users feel, in evidence order: re-anchor on the job, remove friction before polish, sharpen the words, persuade honestly, and end with a review brutal enough to cut. Each of the nine skills in this guide packages a canonical product or design discipline — Christensen's *Competing Against Luck*, Krug and Nielsen's usability canon, Norman's *The Design of Everyday Things*, Wathan and Schoger's *Refactoring UI*, Saffer's *Microinteractions*, the Heath brothers' *Made to Stick*, Cialdini's *Influence*, Grigorik's performance engineering, and a Steve Jobs-style final review — into a skill your AI agent loads on demand. Installed, they turn "make the app feel better" from a vibe into a sequence of audits, findings, and fixes your agent can execute and defend. One boundary before we start: this is the *product experience* pass, not the code pass. If your real problem is untested code, crashy deploys, or a data layer you're afraid of, that work has its own playbooks — [take a vibe-coded prototype to production](https://skills.wondel.ai/guides/vibe-coded-prototype-to-production/) or [dig out of technical debt](https://skills.wondel.ai/guides/refactor-a-codebase-buried-in-technical-debt/). This guide assumes the engine runs and asks a different question: why doesn't anyone enjoy driving the car? > Users don't file tickets about rough experiences. They just leave — and the order in which you fix what they feel is the whole game. ## Phase 1 — Re-anchor on the job users hire the app for Every later phase aims at whatever this one finds, which is why it gates the journey. [Jobs to Be Done](https://skills.wondel.ai/skills/jobs-to-be-done/) starts from [Christensen's premise](https://www.christenseninstitute.org/theory/jobs-to-be-done/): **customers don't buy products, they hire them to make progress in a specific circumstance.** An app that has shipped features for two years has usually drifted from the job it was originally hired for — and the roughness users report is often the gap between what they came to do and what the screens now optimize for. The skill forces the job into a statement that never names your product — "When [situation], I want to [motivation], so I can [outcome]" — and then maps it across three dimensions: functional, emotional, and social. The emotional and social dimensions are where shipped apps quietly underdeliver; the feature works, but the user feels dumb using it or wouldn't want a colleague looking over their shoulder. It also separates the **Big Hire** (the day they signed up) from the **Little Hire** (the moment they choose to open it again today) — two different failure modes that call for two different fixes. > **Prompt** — Use the `jobs-to-be-done` skill to derive the job statement for our app from these support tickets, reviews, and usage patterns — state it without naming the product, break it into functional, emotional, and social dimensions, and tell me where we underdeliver on each > (https://skills.wondel.ai/skills/jobs-to-be-done/) Feed it real evidence: session recordings, churn-survey answers, App Store reviews, the flows users abandon. Ask for the competing alternatives too — including the spreadsheet, the group chat, and doing nothing at all — because users benchmark your app against whatever they'd muddle through with, not against your competitors' feature grids. > **Prompt** — Use the `jobs-to-be-done` skill to map the alternatives users hire instead of our app for this job, including workarounds and non-consumption, and identify whether our biggest leak is a Big Hire failure in onboarding or a Little Hire failure in daily use > (https://skills.wondel.ai/skills/jobs-to-be-done/) The rule that makes the rest of the journey honest: **no screen, copy, or flow changes ship without a finding from Phases 1–3 behind them.** Evidence before redesign. It's the difference between improving the app and redecorating it. ## Phase 2 — Remove the friction that makes users think With the job named, hunt the places the interface makes people stop and puzzle. [UX Heuristics](https://skills.wondel.ai/skills/ux-heuristics/) brings Krug's [*Don't Make Me Think*](https://sensible.com/dont-make-me-think/) and [Nielsen's ten heuristics](https://www.nngroup.com/articles/ten-usability-heuristics/), and its model of the user is the one product teams keep forgetting: **users don't read, they scan; they don't choose optimally, they satisfice; they don't figure it out, they muddle through.** Every question mark that forms in a user's head is cognitive load, and cognitive load is where flows leak. The skill runs a heuristic evaluation with **0–4 severity ratings**, ordered by severity times how often users hit the problem — so a catastrophe on the daily-use screen outranks a cosmetic flaw on the settings page. It applies the **Trunk Test** to key screens (dropped here cold, can I tell what app this is, what screen, what my options are, where I am, where search lives?), cuts half the words and then half again, and rewrites the error and form copy that quietly kills completion. > **Prompt** — Use the `ux-heuristics` skill to run a heuristic evaluation of our highest-leak flow against Nielsens ten heuristics, rate every issue 0-4 for severity, and order the fix list by severity times how often users hit it — catastrophes before cosmetics > (https://skills.wondel.ai/skills/ux-heuristics/) Point it at the flow from Phase 1 that leaks the most users or generates the most tickets. The output is a fix list, not a redesign: severity-4 issues get owners now, severity-1 nitpicks get backlogged, and each fix lands as an experiment with a metric — completion rate, time to task, support-ticket volume — so you can prove it worked. > **Prompt** — Use the `ux-heuristics` skill to apply the Trunk Test to our five key screens, then rewrite the labels, form fields, and error messages that fail it — cut the word count in half and make every error say what happened, why, and how to fix it > (https://skills.wondel.ai/skills/ux-heuristics/) ## Phase 3 — Design out the errors users keep making Some friction isn't confusion — it's users confidently doing the wrong thing. [Design of Everyday Things](https://skills.wondel.ai/skills/design-everyday-things/) brings [Norman's uncompromising frame](https://jnd.org/): **there is no human error, only bad design.** When users keep acting wrong, the design misled them, and adding a warning dialog is punishing them for your mistake. The skill audits your core flows across Norman's two gulfs. The **Gulf of Execution** — "how do I do this?" — closes with clear signifiers and constraints: a date picker instead of free text, a Submit button disabled until the form is valid, a destructive action that physically can't hit the wrong target. The **Gulf of Evaluation** — "what just happened?" — closes with feedback under a tenth of a second and system state you can see. It also distinguishes **slips** (right intention, wrong action) from **mistakes** (wrong intention), because they need opposite fixes — and it prefers undo over are-you-sure dialogs, which users click through on reflex anyway. > **Prompt** — Use the `design-everyday-things` skill to audit our onboarding, primary action, and destructive flows for Norman gulfs — find the weak signifiers, the places a constraint would make the error impossible, and the actions missing immediate feedback > (https://skills.wondel.ai/skills/design-everyday-things/) The highest-leverage question this phase asks: **where should a constraint replace an error message, and where should undo replace a confirmation?** Every error dialog you delete by making the error impossible is friction that never comes back. > **Prompt** — Use the `design-everyday-things` skill to rewrite our error messages to say what went wrong and how to fix it without blaming the user, and replace the are-you-sure dialogs on reversible actions with undo > (https://skills.wondel.ai/skills/design-everyday-things/) ## Phase 4 — Make it look as clear as it works Only now — with friction findings in hand — does the visual pass earn its slot. [Refactoring UI](https://skills.wondel.ai/skills/refactoring-ui/) is [Wathan and Schoger's system](https://www.refactoringui.com/) for developers who design, and its liberating claim is that **great UI is a system, not a talent**: hierarchy, spacing, and color follow learnable rules, and an agent can apply them consistently across every screen. The discipline is **grayscale first**. Establish visual hierarchy with size, weight, and contrast before any color enters — if a screen doesn't read desaturated, no palette will save it. Then a strict spacing scale (4/8/16/24/32/48/64) where gaps between groups always exceed gaps within them; text measures of 45–75 characters; forms constrained to 300–500px instead of sprawling across the viewport; and finally color as a system — five to nine shades per hue, grays tinted toward your brand, never pure black. > **Prompt** — Use the `refactoring-ui` skill to do a grayscale hierarchy pass on our three key screens — set size, weight, and contrast so one primary action dominates each screen, then fix every spacing violation against a 4/8/16/24/32/48/64 scale > (https://skills.wondel.ai/skills/refactoring-ui/) Anchor the pass to the Phase 2–3 findings: the screens users actually stumble on, not the ones the team is bored of. And make the output durable — design tokens and component decisions recorded, not one-off CSS — so the next feature inherits the system instead of eroding it. > **Prompt** — Use the `refactoring-ui` skill to build us a systematic palette from the current brand color — 5 to 9 shades per hue with tinted grays — and apply it to the screens only after the grayscale layout reads, keeping the exact token changes as a design-system diff > (https://skills.wondel.ai/skills/refactoring-ui/) ## Phase 5 — Make every action feel alive The difference between a product users tolerate and one they love is almost always here, in the moments they touch a hundred times a day. [Microinteractions](https://skills.wondel.ai/skills/microinteractions/) brings Saffer's four-part anatomy — **Trigger, Rules, Feedback, Loops & Modes** — and audits your most-used interactions against it: save, submit, toggle, delete, load. The failure it catches most is missing or late feedback. Direct manipulation needs a response **under 100 milliseconds**, and the response should live in the element the user touched — the button depresses and becomes "Saving…", the checkbox fills, the row slides out — not in a toast stapled to the corner. The skill also maps every state the happy path skips: empty, loading, partial, full, error, disabled. Shipped apps break quietly in exactly those states. > **Prompt** — Use the `microinteractions` skill to audit our five most-used interactions with the Trigger, Rules, Feedback, Loops and Modes structure — find every action with missing or late feedback and specify the exact response each needs, animating the element the user touched rather than a separate toast > (https://skills.wondel.ai/skills/microinteractions/) Then pick **one signature moment** — a single interaction worth disproportionate craft, validated by the removal test: would the product feel materially worse without it? One is a personality; five is noise. Feedback overload is the equal-and-opposite failure, so everything else gets the *smallest* feedback that communicates. > **Prompt** — Use the `microinteractions` skill to map the full state model for our core screen — empty, loading, partial, full, error, disabled — design what each state shows, and propose one signature moment that passes the removal test > (https://skills.wondel.ai/skills/microinteractions/) ## Phase 6 — Sharpen the words inside the app In-app copy is interface. Onboarding lines, empty states, error strings, CTAs, tooltips — users read them under pressure, and most were written by whoever built the feature, in the team's internal dialect. [Made to Stick](https://skills.wondel.ai/skills/made-to-stick/) attacks the root cause, which the Heath brothers call the **Curse of Knowledge**: once you know the product, you cannot imagine not knowing it, so you write "Configure your workspace sync preferences" and genuinely believe it's clear. The skill scores each surface against the **SUCCESs** checklist — Simple, Unexpected, Concrete, Credible, Emotional, Stories — and the axis that matters most in-app is *concrete*. "Users open the app 8 times a day" beats "increase engagement"; "Add your first invoice" beats "Get started with billing workflows". It also forces the **Commander's Intent** question per screen: the one thing this screen must land — because if a label needs a tooltip, the fix is the label. > **Prompt** — Use the `made-to-stick` skill to score our onboarding copy, empty states, error strings, CTAs, and tooltips against the SUCCESs checklist, then rewrite each one concrete and jargon-free using the job language from our customer research > (https://skills.wondel.ai/skills/made-to-stick/) Use the Phase 1 job statement as the vocabulary source: the words users said in interviews and reviews are the words that will read as clear inside the app. Ship the rewrites as experiments — copy is the cheapest thing in the product to test and the most commonly shipped on gut feel. > **Prompt** — Use the `made-to-stick` skill to name the Commanders Intent for each of our key screens — the one thing that screen must communicate — and flag every element on the screen that competes with it > (https://skills.wondel.ai/skills/made-to-stick/) ## Phase 7 — Persuade honestly where users decide Every app with a business model has in-app marketing surfaces: the paywall, the upgrade prompt, the trial-ending nudge, the social-proof strip, the badges. Most teams either neglect them (a gray "Upgrade" link) or overheat them (fake countdown timers). [Influence Psychology](https://skills.wondel.ai/skills/influence-psychology/) applies Cialdini's seven principles — reciprocity, commitment, social proof, authority, liking, scarcity, unity — exactly where the user decides, with an ethics gate bolted on. The gate is not decoration, it's the operating rule of this phase: **every scarcity cue, social-proof claim, and upgrade promise must be true.** A tactic that only works if the user doesn't know the strategy is manipulation, not persuasion — and beyond the ethics, dishonest cues get noticed, screenshotted, and churned over. The skill pairs each decision point with the principle that fits it (commitment and consistency at trial end, social proof at the paywall, reciprocity before the first ask), keeps the decision reversible, and flags any cue that would need invented evidence. > **Prompt** — Use the `influence-psychology` skill to audit our paywall, upgrade prompt, and trial-end nudge — assign the persuasion principle that fits each decision point, write the honest copy for it, and flag every scarcity or social-proof claim we cannot back with real evidence today > (https://skills.wondel.ai/skills/influence-psychology/) If a claim fails the audit, the move is to cut it or make it true — real usage numbers, real testimonials with names, real deadlines that actually expire. Honest persuasion converts worse than dark patterns for a week and better for every week after. > **Prompt** — Use the `influence-psychology` skill to redesign our upgrade moment so it layers commitment, social proof, and reciprocity honestly — show what we give before we ask, cite evidence we actually have, and keep the decision reversible > (https://skills.wondel.ai/skills/influence-psychology/) ## Phase 8 — Make it feel fast where users touch it Speed is part of the experience, and users judge it at the moments they touch — not in your backend dashboards. [High Perf Browser](https://skills.wondel.ai/skills/high-perf-browser/) brings [Grigorik's correction](https://hpbn.co/) to the usual misdiagnosis: **latency, not bandwidth, is the bottleneck.** Most perceived slowness is too many round trips and a blocked main thread, which is why the app still feels sluggish after the server upgrade. The skill targets the field metrics users feel: **INP under 200ms** on key interactions (break up long tasks, defer non-critical JavaScript), **LCP under 2.5s** on entry views (preload the hero element, raise its fetch priority), **CLS under 0.1** (reserve space so nothing jumps). And where real latency remains — a genuinely slow query, a third-party call — it hides the wait with skeleton screens and optimistic UI, so the interface responds before the server does. > **Prompt** — Use the `high-perf-browser` skill to profile our slowest key interaction and entry view — find the long tasks behind the poor INP and the render-blocking resources behind the LCP, then give me a fix list ordered by user-perceived impact > (https://skills.wondel.ai/skills/high-perf-browser/) Keep this phase scoped to perception: the interactions from Phase 5 and the entry views users hit daily. If profiling keeps surfacing code-level causes — N+1 queries, an untested module nobody dares touch — that's your signal to schedule the [code-quality journey](https://skills.wondel.ai/guides/vibe-coded-prototype-to-production/) rather than stretch this one. > **Prompt** — Use the `high-perf-browser` skill to add skeleton screens and optimistic UI to the flows where real latency remains after optimization, so every tap gets a visual response under 100 milliseconds even when the network does not cooperate > (https://skills.wondel.ai/skills/high-perf-browser/) ## Phase 9 — Submit it to a brutal, honest review Eight phases of fixes produce a better app. This phase asks the question teams flinch from: *is it actually great, or just better?* [Steve Jobs Design Review](https://skills.wondel.ai/skills/steve-jobs-design-review/) holds the whole experience to a binary standard — **insanely great, or not done** — starting from "you've got to start with the customer experience and work backwards." The review is structured and cold: walk the product as a brand-new user, name the **One Thing** it must do, count the steps from open to core value, and deliver a verdict with a ranked **cut list** and fix list. The cut list is the move no other phase makes — every feature shipped in the last two years is a candidate for deletion, because focusing is saying no. And it audits the **back of the fence**: the empty states, error copy, 404, billing screen, cancellation flow, and receipt emails — held to the same bar as the hero screen, because that's where users subconsciously read your craft. > **Prompt** — Use the `steve-jobs-design-review` skill to review our app cold as a first-time user — name the one thing it must do, count the steps to core value, deliver a binary verdict, and give me a ranked cut list of features to remove before a fix list of things to add > (https://skills.wondel.ai/skills/steve-jobs-design-review/) Accept the cut list seriously. The improvements from Phases 2–8 made everything better; this phase decides what shouldn't exist at all. Subtraction is the highest-leverage edit left after a quality pass. > **Prompt** — Use the `steve-jobs-design-review` skill to audit our back-of-the-fence surfaces — empty states, error copy, the 404, billing, cancellation, and transactional emails — and list every one that falls below the hero-screen bar with the specific fix it needs > (https://skills.wondel.ai/skills/steve-jobs-design-review/) ## Your checklist - [ ] State the job with `jobs-to-be-done` — no product name, three dimensions, Big Hire vs Little Hire — and log where the app underdelivers - [ ] Adopt the evidence rule: no UI or copy change ships without a Phase 1–3 finding behind it, and every change lands as an experiment with a metric - [ ] Run a `ux-heuristics` evaluation on the leakiest flow; rate 0–4, fix by severity × frequency, Trunk-Test the key screens - [ ] Close the Norman gulfs with `design-everyday-things`: constraints over error messages, undo over confirmations, feedback under 0.1s - [ ] Do the `refactoring-ui` grayscale pass before any color work; enforce the spacing scale and one primary action per screen - [ ] Audit the top five interactions with `microinteractions`; sub-100ms feedback in the touched element, every state mapped, one signature moment - [ ] Rewrite in-app copy with `made-to-stick`: SUCCESs-scored, concrete, jargon-free, in the users' own job language - [ ] Pass every paywall and upgrade surface through `influence-psychology`; verify each scarcity and social-proof claim is true today, or cut it - [ ] Hit the field targets with `high-perf-browser` — INP < 200ms, LCP < 2.5s, CLS < 0.1 — and mask remaining latency with skeletons and optimistic UI - [ ] End with `steve-jobs-design-review`: binary verdict, ranked cut list, and a back-of-the-fence audit at hero-screen standard ## Common mistakes **Polishing visuals before removing friction.** The most common failure order. A beautiful screen on a confusing flow loses users at the same rate — run the `ux-heuristics` and `design-everyday-things` audits first, and let their findings aim the visual pass. No finding, no redesign. **Adding color before the grayscale layout works.** Color flatters a broken hierarchy just long enough to ship it. `refactoring-ui` is explicit: establish size, weight, and contrast in grayscale; if the screen fails desaturated, no palette saves it. **Blaming user error and stacking on warnings.** When users keep doing the wrong thing, the design misled them. `design-everyday-things` replaces the blame reflex with constraints that make the error impossible and undo that forgives it — not another are-you-sure dialog users click through blind. **Rewriting copy from inside the Curse of Knowledge.** The team's rewrite is usually the same jargon, rearranged. `made-to-stick` forces the SUCCESs pass and the users' own vocabulary from Phase 1 — then ships the rewrite as an experiment, not a decree. **Fake scarcity and invented social proof in upgrade prompts.** Dark patterns convert for a week and churn forever, and they fail this journey's ethics gate outright. `influence-psychology` cuts any cue that needs evidence you don't have — real numbers or nothing. **Treating slowness as a backend problem.** Users feel round trips and blocked main threads, not server CPU. `high-perf-browser` fixes the metrics users experience — INP, LCP, CLS — and masks the latency that remains, which no amount of horizontal scaling will do. **Shipping the fixes and skipping the cold review.** Phase-by-phase improvements accumulate local optima. The `steve-jobs-design-review` walkthrough catches what they miss — including the features that should be deleted rather than improved. ## Frequently asked questions ### In what order should I run the nine skills? The order above is deliberate: the job first (`jobs-to-be-done` gates everything, because every later phase aims at what it finds), then friction (`ux-heuristics`, `design-everyday-things`), then polish (`refactoring-ui`, `microinteractions`), then words (`made-to-stick`), persuasion (`influence-psychology`), perceived speed (`high-perf-browser`), and the brutal review last. The one hard rule is *evidence before redesign* — the audits in Phases 1–3 precede visual and copy changes. Within that, enter where your app hurts most: rough screens can start at Phase 4, ignored upgrade prompts at Phase 7, as long as the audit that justifies the change has run. ### Isn't this what the improve-website guide covers? Different surface, overlapping toolkit. [Improve an existing website](https://skills.wondel.ai/guides/improve-an-existing-website-with-ai-skills/) targets the marketing site — landing pages, conversion paths, visitors who haven't bought yet. This guide targets the product itself: flows behind the login, in-app copy, upgrade moments, and daily-use interactions for people who already signed up. Several skills appear in both because the disciplines transfer; the questions they answer here are product questions. ### Where did the code-quality phases go? To their own journeys, deliberately. Mixing test coverage and refactoring into an experience pass meant neither got done well. If your audits keep hitting code-level causes — slow queries, crashes, modules nobody dares touch — run [vibe-coded prototype to production](https://skills.wondel.ai/guides/vibe-coded-prototype-to-production/) for a fresh codebase or [refactor a codebase buried in technical debt](https://skills.wondel.ai/guides/refactor-a-codebase-buried-in-technical-debt/) for an aged one. This guide assumes the engine runs; it fixes the car. ### What if I have no analytics or user research to feed Phase 1? Use what you have: support tickets, App Store reviews, churn emails, and your own cold walkthrough are enough evidence to state the job and pick the leakiest flow. What you shouldn't do is skip to redecorating because research feels heavy — even one honest hour with recordings or five user conversations beats zero. If ideas keep coming from opinions instead of contact with users, add a weekly discovery habit before investing in bigger fixes. ### How is this different from growing the app? Improvement makes the existing experience work; growth adds engagement loops on top. If users sign up and vanish, fix the experience first — no habit loop papers over a confusing product. When the app holds up and the goal shifts to activation, retention mechanics, and a metric the team trusts, continue with [grow an existing app](https://skills.wondel.ai/guides/grow-an-existing-app-with-ai-skills/), which builds the retention engine this guide clears the ground for. ## Start improving today Pick the surface where your app feels roughest — the confusing flow, the amateur screen, the upgrade prompt nobody clicks — and install the skills: ``` npx skills add wondelai/skills --all --global ``` Then point your agent at real evidence: the support tickets, the reviews, the flow recordings. Start with the `jobs-to-be-done` statement so every later fix has an aim, run the audits, and ship each change as an experiment with a metric. When the experience holds up and the question becomes growth, continue with [grow an existing app](https://skills.wondel.ai/guides/grow-an-existing-app-with-ai-skills/). Your app doesn't need a redesign. It needs the rough edges found, ranked, and fixed in the right order — and now you know the order. --- # How to Grow an Existing Business with AI Skills > Build a repeatable growth engine — marketing system, outbound sales, word-of-mouth, and pricing — with AI agent skills from The 1-Page Marketing Plan, Predictable Revenue, Contagious, and more. By Michał Jaskólski · Published 2026-06-25 · Updated 2026-08-08 · 17 min read Canonical: https://skills.wondel.ai/guides/grow-an-existing-business-with-ai-skills/ Skills used: one-page-marketing, predictable-revenue, contagious, influence-psychology, crossing-the-chasm, cold-start-problem, hundred-million-offers, lean-analytics, negotiation **TL;DR:** You grow an existing business by building a repeatable engine instead of chasing tactics: install a 1-Page Marketing Plan operating system, strengthen the offer with $100M Offers, manufacture pipeline with Predictable Revenue's outbound, engineer word-of-mouth with Contagious, then align persuasion, pricing, and the one metric that matters. - The offer is a bigger lever than the marketing — fix it before spending a dollar on traffic. - Predictable growth needs a motion you can turn up and down: specialized roles running outbound as a system, not heroics. - Word-of-mouth is engineered, not luck — most of it happens offline, so design for triggers and practical value, not share buttons. - Get every skill in one command with npx skills add wondelai/skills --all --global, then let Lean Analytics pick the one metric every experiment serves. You already have the hard part: a product people pay for. Customers renew, word trickles in, and revenue is real but lumpy. The problem now is not whether the thing works — it is that growth depends on you. A good month came from a conference you happened to attend, a referral a happy customer happened to make, a tweet that happened to land. None of it repeats on demand. That is the difference between a business with traction and a business with a growth engine, and closing that gap is what this guide is about. A growth engine is not a single tactic. It is a system where each part feeds the next: a marketing plan that says exactly who you serve and why they should choose you, an offer so good that conversion stops being a fight, an outbound motion that manufactures pipeline instead of waiting for it, word-of-mouth engineered into the product instead of hoped for, persuasion built into every page and email, a go-to-market that survives the jump from enthusiasts to pragmatists, referral loops that compound, a single metric that tells you whether any of it is working, and the negotiation discipline to capture the value you create instead of discounting it away. Nine moving parts. Most founders try to assemble them by reading nine books and never finishing the first. This is where AI agent skills change the economics. Each [wondel.ai Skill](https://skills.wondel.ai/) packages one of those bestselling frameworks into something your coding agent — Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw, or Hermes Agent — can actually execute against *your* business: your pricing page, your funnel, your customer list, your real numbers. You are not reading about the PVP Index at 11pm; you are telling an agent to run it on your three customer segments and hand you back a scored decision. The skill carries the methodology so you can stay focused on judgment and your actual market. > A business with traction has lucky months. A business with a growth engine has a forecast. This guide walks the nine skills in the order you should build them. You can install the whole stack at once with `npx skills add wondelai/skills --all --global`, but the sequence matters: each phase produces an artifact — a plan, an offer, a sequence, a dashboard — that the next phase consumes. Work through them in order and you finish with a system, not a stack of disconnected documents. ## Phase 1: Install your marketing operating system Before you optimize a single ad or write a single cold email, you need a map of the whole machine. That is what the [1-Page Marketing Plan](https://skills.wondel.ai/skills/one-page-marketing/) gives you: a 3x3 grid of nine squares spanning the full customer journey — **Before** (target market, message, media), **During** (capture leads, nurture, convert), and **After** (deliver an experience, increase lifetime value, orchestrate referrals). The core idea from [Allan Dib's book](https://successwise.com/) is blunt and correct: marketing is not an event, it is a process. Random tactics fail because they address one square while the other eight stay empty. The reason to start here is diagnostic. Most stalled businesses are not bad at marketing in general — they are missing a specific square, and they cannot see which one because they have never laid the whole thing out. Almost always the gap is in the **After** phase: a business pours money into acquisition while ignoring the highest-ROI activities it owns, namely retention, lifetime value, and referrals from customers who already trust it. Filling the grid forces that gap into the open. The `one-page-marketing` skill scores your plan zero to ten on how completely and specifically all nine squares are filled, and it will not let you hand-wave. A "10" means named target segments, a written USP, channels with budgets, a designed lead magnet, a mapped nurture sequence, a defined sales process, a documented experience, an ascension model with pricing tiers, and a referral system with scripts. Have the agent run the PVP Index — scoring each niche on Personal fulfillment, Value to the marketplace, and Profitability — so you stop trying to sell to everyone and pick the niche you can dominate. > **Prompt** — Use the `one-page-marketing` skill to fill out all nine squares of the 1-Page Marketing Plan for my business — ask me what we sell, to whom, and where new business comes from today. Score the plan out of 10, then tell me which single square is weakest and the three specific actions to fix it > (https://skills.wondel.ai/skills/one-page-marketing/) > **Prompt** — Use the `one-page-marketing` skill to run the PVP Index on my candidate customer segments — scoring each on Personal fulfillment, Value to marketplace, and Profitability — then recommend the one niche to dominate first and write the ideal customer avatar for it > (https://skills.wondel.ai/skills/one-page-marketing/) The output here is not a deck you file away. It is the brief every later phase reads from: the segment you picked feeds your beachhead in Phase 6, the USP feeds your cold-email value prop in Phase 3, and the referral square feeds your network loops in Phase 7. Get the map right and the rest of the build has a destination. ## Phase 2: Make the offer impossible to refuse Here is the uncomfortable truth most growth advice skips: the offer is a bigger lever than the marketing. Alex Hormozi's argument in [*$100M Offers*](https://www.acquisition.com/books) — captured in the [$100M Offers](https://skills.wondel.ai/skills/hundred-million-offers/) skill — is that a great offer sells despite mediocre marketing, while the best marketing on earth cannot rescue a weak one. If you are about to spend money driving traffic, fixing the offer first multiplies the return on every dollar that follows. That is why it comes before outbound, before virality, before everything except knowing who you are selling to. The engine is the Value Equation: value equals Dream Outcome times Perceived Likelihood of Achievement, divided by Time Delay times Effort and Sacrifice. You maximize the top and minimize the bottom. A guarantee raises perceived likelihood and reduces risk in one move. Faster time-to-value commands premium pricing. Done-for-you components strip out effort. Then you assemble a Grand Slam Offer — core product plus named bonuses that each kill a specific objection, a risk-reversing guarantee, and ethical scarcity — until the sum of the parts is so far past the price that comparison shopping becomes impossible. You stop being a commodity and become a category of one. The `hundred-million-offers` skill is built to do exactly this against your real pricing. Point it at your current offer and it will score it out of ten, find the weak lever in the Value Equation, design objection-killing bonuses with defensible dollar values, recommend a guarantee type, and apply the MAGIC naming formula (Magnetic reason, Avatar, Goal, time Indicator, Container word). It is also opinionated about pricing in the right direction: premium pricing attracts committed customers who get better results and churn less, so "people say it's too expensive" is usually an offer-construction problem, not a price problem. > **Prompt** — Use the `hundred-million-offers` skill to score my current offer out of 10 using the Value Equation — right now it is bare access to the product. Identify the weakest lever, then rebuild it into a Grand Slam Offer with three named bonuses that each kill a specific objection, a risk-reversing guarantee, and a name using the MAGIC formula > (https://skills.wondel.ai/skills/hundred-million-offers/) > **Prompt** — Use the `hundred-million-offers` skill to diagnose whether the too-expensive objection on our product is a price problem or a value-construction problem — prospects keep saying it costs too much. Then show me how raising the price and adding a done-for-you onboarding bonus could increase conversions rather than reduce them > (https://skills.wondel.ai/skills/hundred-million-offers/) The reordering here is deliberate. You build the offer in Phase 2 so that every channel you turn on next — outbound, referral, mainstream go-to-market — is pointing at something that converts. Sending traffic to a weak offer is the most expensive mistake in growth. ## Phase 3: Manufacture pipeline with outbound Word-of-mouth and inbound are wonderful, but you cannot summon them on the first of the month when you need deals. For predictable, controllable growth you need a motion you can turn up by hiring or turn down by pausing — and that is outbound. [Predictable Revenue](https://skills.wondel.ai/skills/predictable-revenue/), [Aaron Ross's account](https://predictablerevenue.com/) of the system that added over $100M in recurring revenue at Salesforce, is the playbook. Two ideas do most of the work. First, lead types: **Seeds** (referrals, word-of-mouth — highest conversion, slowest to manufacture), **Nets** (marketing and inbound — medium), and **Spears** (outbound prospecting — lower conversion but the most predictable, because you control the volume). Most companies over-invest in Nets and under-invest in Spears, then wonder why pipeline is feast-or-famine. Second, specialization: the single biggest mistake is having the same people prospect *and* close. Separate the roles — SDRs generate qualified opportunities, AEs close them, CSMs retain and grow — and the machine becomes repeatable instead of dependent on heroics. The signature tactic is Cold Calling 2.0: instead of emailing the decision-maker with a pitch, you email *above* them with a short, no-pitch note asking to be pointed to the right person. Internal referrals convert three to five times better, and response rates run 9 to 15 percent versus 1 to 3 percent for traditional cold email. The `predictable-revenue` skill writes these sequences, builds the ANUM qualification framework (Authority, Need, Urgency, Money), and — crucially — runs the pipeline math backward from your revenue goal so you know how many emails and how many SDRs it actually takes. > **Prompt** — Use the `predictable-revenue` skill to work backward from our new-revenue goal for next year — ask me for the goal, average deal size, and win rate, then tell me how many qualified opportunities, prospects, and emails we need, and how many SDRs that implies at realistic response rates > (https://skills.wondel.ai/skills/predictable-revenue/) > **Prompt** — Use the `predictable-revenue` skill to write a four-touch Cold Calling 2.0 referral email sequence for my target accounts, asking to be pointed to whoever owns the problem we solve — short, no pitch, easy to forward, with a day-14 break-up email > (https://skills.wondel.ai/skills/predictable-revenue/) > **Prompt** — Use the `predictable-revenue` skill to design our SDR to AE handoff: a qualification checklist using ANUM, what context the SDR must capture, and the exact format of the handoff so no qualified lead falls through the cracks > (https://skills.wondel.ai/skills/predictable-revenue/) Outbound gives your growth engine a throttle. When you need more deals, you know precisely which dial to turn — and Phase 8's metrics will tell you whether turning it is paying off. ## Phase 4: Engineer word-of-mouth instead of hoping for it Spears are predictable but expensive; Seeds are cheap but feel like luck. [Jonah Berger's research](https://jonahberger.com/books/contagious/), packaged in the [Contagious](https://skills.wondel.ai/skills/contagious/) skill, argues that the luck is an illusion — virality is engineered, not born. Things spread because they were designed, consciously or not, to be shared. And tellingly, only about 7 percent of word-of-mouth happens online; the other 93 percent is offline conversation. So this is about the psychology of sharing, not about adding share buttons. The framework is STEPPS: **Social Currency** (sharing it makes people look good), **Triggers** (everyday cues that keep you top-of-mind), **Emotion** (high-arousal feelings — awe, excitement, anger — drive sharing; low-arousal contentment suppresses it), **Public** (visible usage that others can imitate), **Practical Value** (useful enough to pass along), and **Stories** (a narrative people retell with your brand baked in). It is a multiplier, not a checklist — even one or two done well dramatically increases word-of-mouth. For an existing business, the highest-leverage move is often Triggers and Practical Value. A "year-in-review" report your customers want to show off is Social Currency. A benchmark report they cite in meetings is Practical Value with a Trojan-Horse Story attached. Berger's Trojan Horse test is the discipline that matters: if someone can retell the story without naming your brand, the story has failed. The `contagious` skill audits any feature, campaign, or piece of content against all six drivers, scores it, and tells you which to strengthen. > **Prompt** — Use the `contagious` skill to audit our quarterly customer email against the STEPPS framework and score it out of 10. Then redesign it into a shareable year-in-review for each law firm — hours saved, no-shows prevented, fastest booking — engineered for Social Currency and Public visibility so partners forward it to peers > (https://skills.wondel.ai/skills/contagious/) > **Prompt** — Use the `contagious` skill to find a daily or weekly Trigger in a law firm's routine that we can link our scheduling tool to, so the product comes to mind in conversation. Then write a Trojan Horse story about a customer that fails the retell test if our brand is removed > (https://skills.wondel.ai/skills/contagious/) Engineered word-of-mouth lowers your blended acquisition cost over time: every Seed you manufacture is a deal you did not have to pay an SDR to source. It also seeds the network loops you will formalize in Phase 7. ## Phase 5: Build persuasion into every surface You now have traffic from three directions hitting an offer. Whether they say yes turns on persuasion — and [Robert Cialdini's six decades of research](https://www.influenceatwork.com/), distilled in the [Influence Psychology](https://skills.wondel.ai/skills/influence-psychology/) skill, is the science of why people do. People rarely decide rationally; they use mental shortcuts, and you can design your pages, emails, and flows to align with how humans actually choose. Ethically — the line the skill enforces relentlessly is that persuasion helps people see value they would appreciate anyway, while manipulation tricks them into choices against their interest. The seven principles — Reciprocity, Commitment and Consistency, Social Proof, Authority, Liking, Scarcity, and Unity — layer. A strong landing page might stack Authority ("built by ex-litigators"), Social Proof ("trusted by 140 firms"), Liking (warm, human copy), Reciprocity (a genuinely useful free tool), and real Scarcity ("founding-member pricing, 50 seats"). The research is specific in ways that matter: specific numbers beat vague claims ("2,347 firms" outperforms "thousands"), negative social proof backfires, admitting a weakness paradoxically *increases* authority, and newly-scarce beats always-scarce because of loss framing. The `influence-psychology` skill audits any persuasive element — a pricing page, a testimonial block, a checkout flow, an upgrade prompt — names which principles are present and which are missing, scores it out of ten, and rewrites the weak spots. It also runs an ethics checklist on every tactic, which matters because faked scarcity and fabricated proof destroy trust faster than they generate sales. > **Prompt** — Use the `influence-psychology` skill to audit my pricing page against Cialdini's seven principles, score it out of 10, and tell me which principles are missing. Then rewrite the page to layer Authority, Social Proof with specific numbers, and a genuinely scarce founding-member tier — flagging anything that crosses from persuasion into manipulation > (https://skills.wondel.ai/skills/influence-psychology/) > **Prompt** — Use the `influence-psychology` skill to rewrite our ten customer testimonials to be concrete and outcome-focused using the Social Proof principle, prioritizing similar-customer proof, then tell me exactly where on the landing page to place them so they appear right where objections peak > (https://skills.wondel.ai/skills/influence-psychology/) Persuasion is the multiplier on every other phase: it lifts the conversion rate of your outbound replies, your referral landing pages, and your mainstream go-to-market alike, without spending a cent more on traffic. ## Phase 6: Cross the chasm to the mainstream Here is the trap that kills businesses with early traction: the customers who loved you first are not the customers you need next, and the strategy that won the first group actively repels the second. Geoffrey Moore's [Crossing the Chasm](https://skills.wondel.ai/skills/crossing-the-chasm/) maps this precisely. Your early adopters were visionaries — they tolerated rough edges, bought your vision, and needed no references. The early majority are pragmatists: they want proven solutions, a complete product, references from peers, and "it just works." Market to them like visionaries and you stall in the chasm. The D-Day strategy is to stop trying to be everything to everyone and instead target a single narrow beachhead, dominate it, and expand from strength. A good beachhead has an urgent and expensive pain, is reachable through known channels, and — critically — its members talk to each other so references propagate. This is where Phase 1's PVP work pays off: the niche you scored highest is your beachhead candidate. Then you assemble the *whole product* — not just your software, but the integrations, onboarding, migration, training, and support that pragmatists demand — partnering to fill the gaps you cannot build. The `crossing-the-chasm` skill scores your go-to-market out of ten against these principles, runs the whole-product gap analysis, and rewrites your positioning for pragmatists using Moore's formula. The messaging shift is concrete: "revolutionary new approach" becomes "proven solution for [problem]"; "be the first" becomes "join 500 firms like yours." Evolution, not revolution. > **Prompt** — Use the `crossing-the-chasm` skill to score our go-to-market out of 10 given that we have strong traction with early adopters but cannot break into the pragmatist mainstream. Run the whole-product gap analysis for our next beachhead, and tell me which integrations, migration support, and references we must add before pragmatist buyers will switch > (https://skills.wondel.ai/skills/crossing-the-chasm/) > **Prompt** — Use the `crossing-the-chasm` skill to rewrite our homepage positioning for pragmatist early-majority buyers using Moore's positioning formula — for, who, our product is a, that, unlike, our product — reframing us as a proven evolution rather than a revolutionary new tool, and positioning against the spreadsheets and legacy systems firms actually use today > (https://skills.wondel.ai/skills/crossing-the-chasm/) Crossing the chasm is the move that turns a niche success into a mainstream business. Skip it and you will keep selling to a shrinking pool of enthusiasts while the real market buys from whoever speaks pragmatist. ## Phase 7: Turn customers into a compounding network If any part of your product gets better as more people use it — shared workspaces, referrals, a directory, anything multiplayer — then growth has a flywheel you may not be using. Andrew Chen's [Cold Start Problem](https://skills.wondel.ai/skills/cold-start-problem/) is the framework, and even for a business that is past the cold start, its later stages are the playbook for compounding what you have. The core reframe: network effects are a liability before they are an asset, and they grow not by launching to a market but by saturating one tiny, complete network at a time. For an existing business, three ideas earn their keep. **Atomic networks**: rather than "more users everywhere," find the smallest self-sustaining unit — one firm, one city, one practice area — and over-deliver until it is dense, then replicate with a repeatable playbook. **The hard side**: every network has a minority who do the disproportionate work and are disproportionately hard to keep — the organizer who sets up the firm's account, the power user who invites the team. Build for them first. And the **tipping playbook**: invite-only mechanics and two-sided referral incentives import each new user along an existing relationship, which is exactly how referrals compound instead of fizzle. This is where Phase 1's referral square and Phase 4's word-of-mouth become a system. The `cold-start-problem` skill will define your atomic network, identify your hard side and what keeps them, and design the referral and invite loops with real (never faked) scarcity. It scores the plan out of ten and pushes you toward density metrics over vanity signups. > **Prompt** — Use the `cold-start-problem` skill to define our atomic network — the smallest group of users for whom the product gets stickier when they all adopt it together. Identify who the hard side is and why they would stay, and design a two-sided referral loop that imports new firms along existing relationships > (https://skills.wondel.ai/skills/cold-start-problem/) > **Prompt** — Use the `cold-start-problem` skill to design an invite mechanic where existing firms can refer peer firms with a genuine incentive for both sides, and tell me which density and liquidity metrics — not raw signups — prove a new referral cohort has tipped into self-sustaining growth > (https://skills.wondel.ai/skills/cold-start-problem/) A working network loop is the cheapest growth you will ever buy, because the network does the acquiring. It is also your moat: competitors can copy your features but not the people already connected on your platform. ## Phase 8: Point everything at the one metric that matters By now you have a lot of moving parts and a real risk of drowning in dashboards. [Croll and Yoskovitz's](https://leananalyticsbook.com/) [Lean Analytics](https://skills.wondel.ai/skills/lean-analytics/) is the antidote: at any moment there is *one* metric that matters most — the number that tells you whether the riskiest part of the business right now is working — and your job is to find it, put it on the wall, and let it drive every experiment until you graduate to the next stage. Startups, the authors argue, die from lack of focus far more often than lack of data. The discipline starts by separating good metrics from vanity metrics. A good metric is comparative, a ratio or rate (not an ever-growing total), and behavior-changing — if a number will not change what you do next, stop measuring it. The classic tell is the cumulative up-and-to-the-right chart: total signups always rises, even while the product bleeds active users. Your One Metric That Matters is the intersection of your business model (for most subscription businesses, that is SaaS — so churn, MRR, LTV:CAC, time-to-value) and your current stage (Empathy, Stickiness, Virality, Revenue, Scale). Pair it with a counter-metric so it cannot be gamed, and draw a line in the sand: a target number, a date, and a pre-committed answer to "what do we do if we miss?" The `lean-analytics` skill cuts through a bloated dashboard, names which numbers are vanity, derives your OMTM from model and stage, and designs the one-screen dashboard — OMTM big, four to six supporting metrics small. It will also insist on cohorts and segments, because blended averages hide the truth: one segment soaring while another collapses can look perfectly flat in aggregate. > **Prompt** — Use the `lean-analytics` skill to cut through the 28 metrics we track and leadership argues about. We are a subscription SaaS at roughly $170K ARR with churn creeping up. Tell me which metrics are vanity, derive our One Metric That Matters from our model and stage, pair it with a counter-metric, and design the one-screen dashboard > (https://skills.wondel.ai/skills/lean-analytics/) > **Prompt** — Use the `lean-analytics` skill to draw a line in the sand for our churn: a target rate, a date, and a pre-committed action if we miss it. Then show me how to cohort retention by signup month so I can see whether the product is actually getting stickier instead of hiding it in a blended average > (https://skills.wondel.ai/skills/lean-analytics/) The OMTM is what keeps the previous seven phases honest. It tells you whether the new offer lifted conversion, whether outbound is paying back, whether the referral loop is real — so you double down on what works and kill what does not, on evidence rather than gut. ## Phase 9: Stop discounting — capture the value you create You have built demand. The final phase is making sure you keep the value instead of giving it away at the negotiating table. Chris Voss's [Negotiation](https://skills.wondel.ai/skills/negotiation/) skill — from the former FBI hostage negotiator's *Never Split the Difference* — is built on a counterintuitive principle: the path to "yes" runs through empathy and being understood, not through logic or compromise. And never split the difference: no deal is better than a bad deal, because a discount granted under pressure trains every future customer to ask for one. The techniques are concrete and they work in business settings. **Tactical empathy** and **labeling** ("it sounds like adding another tool to the stack feels risky right now") name the other side's concern before they do, which diffuses it. **Calibrated questions** — "how am I supposed to do that at that price?" — push back without refusing and make the other side solve your problem. The **accusation audit** preempts every objection before the prospect raises it. And the **Ackerman method** gives you a systematic way to hold price: set your target, then move in decreasing increments to precise non-round numbers, closing with a non-monetary concession instead of more discount. The `negotiation` skill prepares you for any high-stakes conversation — a renewal at risk, a procurement squeeze, an enterprise deal — by building the accusation audit, drafting calibrated questions, designing the Ackerman plan, and helping you hunt for Black Swans, the hidden constraints that explain seemingly irrational behavior. It is the difference between defending your pricing and apologizing for it. > **Prompt** — Use the `negotiation` skill to prepare me for a renewal call where our largest customer at $24K a year says a competitor quoted 30 percent less and wants a discount to renew. Write an accusation audit for the call, five calibrated questions to uncover what is really driving the threat, and an Ackerman plan with my target, three decreasing increments, and a non-monetary concession instead of cutting price > (https://skills.wondel.ai/skills/negotiation/) > **Prompt** — Use the `negotiation` skill to write tactical-empathy responses to our three most common sales objections — it's too expensive, we need to think about it, and we already use a spreadsheet — each starting with a label, following with a calibrated question, and aiming for a That's Right moment rather than a discount > (https://skills.wondel.ai/skills/negotiation/) Negotiation closes the loop. The offer in Phase 2 created the value; this phase makes sure it lands in your bank account at full price. ## Your checklist - [ ] Install the stack: `npx skills add wondelai/skills --all --global` - [ ] Fill all nine squares of the 1-Page Marketing Plan and score it out of 10 - [ ] Run the PVP Index to pick the one niche to dominate first - [ ] Rebuild your core offer into a Grand Slam Offer with bonuses, a guarantee, and a MAGIC name - [ ] Calculate pipeline math backward from your revenue goal - [ ] Write a Cold Calling 2.0 referral email sequence and an SDR-to-AE handoff - [ ] Audit one campaign or feature against STEPPS and engineer a Trigger plus a Trojan Horse story - [ ] Audit your pricing page against Cialdini's seven principles and rewrite the weak spots - [ ] Run the whole-product gap analysis for your beachhead and reposition for pragmatists - [ ] Define your atomic network and design a two-sided referral loop with real scarcity - [ ] Name your One Metric That Matters, pair it with a counter-metric, and draw a line in the sand - [ ] Prepare your next renewal with an accusation audit, calibrated questions, and an Ackerman plan ## Common mistakes **Optimizing the funnel before fixing the offer.** Founders spend weeks A/B testing button colors on top of an offer nobody finds compelling. The offer is the bigger lever — run `hundred-million-offers` against your pricing before you touch the funnel, or you are polishing the wrong thing. **Treating the nine skills as a buffet.** The order is load-bearing. Your PVP niche feeds your beachhead; your USP feeds your cold-email value prop; your referral square feeds your network loops. Skip Phase 1 and the later phases have no shared target, so you end up with nine disconnected documents instead of one engine. **Marketing to pragmatists like they are early adopters.** Visionary testimonials and "revolutionary" language scare off the early majority, who read "disruptive" as "risky and unproven." When growth stalls after your enthusiast pool dries up, that is the chasm — reframe as proven evolution, not revolution. **Faking scarcity, social proof, or guarantees.** Every persuasion and offer skill here enforces the same ethical line for a reason: a resetting countdown timer or a fabricated "only 2 left" works once and poisons trust permanently. The frameworks are powerful enough that you never need the fake version. Use real inventory, real numbers, real deadlines. **Celebrating vanity metrics.** Total signups and cumulative revenue charts only go up, so they feel like progress while the product quietly bleeds. If a number cannot go down and will not change a decision, it is decoration. Watch the one ratio that matters. **Splitting the difference to close a deal.** Discounting under pressure feels like winning the deal, but it trains every future customer to negotiate and erodes the value the rest of the engine worked to build. Hold your price with calibrated questions; no deal beats a bad one. **Building outbound on top of a leaky bucket.** Pouring SDR-sourced pipeline into a product that does not retain is the most expensive way to grow. Let Phase 8's stickiness metric gate your acquisition spend — fix retention first, then pour in pipeline. ## Frequently asked questions ### Do I have to install all nine skills, or can I start with one? You can start with one — installing the whole stack with `npx skills add wondelai/skills --all --global` is convenient but not required, and each skill works on its own. That said, the value compounds when they share artifacts. If you only have time for one this week, start with `one-page-marketing`: it produces the map that tells you which of the other eight skills addresses your actual bottleneck. If your sales calls keep dying on price, start with `hundred-million-offers` instead. Let your weakest square choose your first skill. ### What is the difference between this guide and the "improve an existing business" guide? This guide is about building a *growth engine* — adding new demand, pipeline, word-of-mouth, and pricing power on top of a business that already works. The companion guide, [Improve an Existing Business with AI Skills](https://skills.wondel.ai/guides/improve-an-existing-business-with-ai-skills/), is about fixing what is leaking: retention, churn, conversion, and operational drag. Growth without retention is a leaky bucket, so many businesses run both in parallel — use Lean Analytics here to decide which problem is more urgent right now. ### How do these business skills relate to my actual product and codebase? Several phases touch the product directly — referral loops, in-app share mechanics, network effects, and persuasion built into your UI all require shipping code. The agent can scope and often implement those changes, but if your growth bottleneck is genuinely in the product, pair this guide with [Grow an Existing App with AI Skills](https://skills.wondel.ai/guides/grow-an-existing-app-with-ai-skills/), which covers the engineering side of growth — instrumentation, experimentation infrastructure, and the technical work behind referral and retention features. ### Are these skills going to make my marketing feel manipulative or spammy? The opposite, if you follow them. Every skill in the persuasion and offer stack — `influence-psychology`, `hundred-million-offers`, `contagious`, `negotiation` — carries an explicit ethical boundary the agent enforces: no faked scarcity, no fabricated proof, no guarantees you will not honor, no exploiting vulnerable buyers. The whole premise of `predictable-revenue`'s referral email is that it is a *genuine* request, which is exactly why it outperforms a pitch. Done right, this is persuasion that helps customers see value they would appreciate anyway, not manipulation. ### How long does it take to work through the whole stack? Generating the artifacts is fast — an agent can produce a scored 1-Page Marketing Plan, a Grand Slam Offer, a cold-email sequence, and a metrics dashboard in an afternoon of focused prompting. The real timeline is *execution*: writing real cold emails, shipping the referral feature, repositioning the site, and running the experiments your OMTM gates. Treat the skills as compressing the strategy and drafting work from weeks into hours, so your time goes to judgment and shipping rather than to reinventing nine frameworks from scratch. ## Start building your growth engine You do not have to assemble this by reading nine business books and hoping you remember the right framework at the right moment. The whole stack is one command away, ready to run against your real pricing page, your real customer list, and your real numbers: `npx skills add wondelai/skills --all --global` Start with Phase 1 — have your agent fill out the 1-Page Marketing Plan and score it — so you know which square is your real bottleneck before you build anything. Then work the phases in order. Each one hands an artifact to the next, and by the end you have a system that produces a forecast instead of lucky months. When growth is humming, point the same agent at the leaks: read [Improve an Existing Business with AI Skills](https://skills.wondel.ai/guides/improve-an-existing-business-with-ai-skills/) to shore up retention and conversion, or [Grow an Existing App with AI Skills](https://skills.wondel.ai/guides/grow-an-existing-app-with-ai-skills/) if your bottleneck turns out to live in the product itself. --- # How to Grow an Existing Website with AI Skills > Turn more of your existing traffic into leads and customers — testing, lead capture, persuasion, and shareability — with AI agent skills from Making Websites Win, Scorecard Marketing, Contagious, and more. By Michał Jaskólski · Published 2026-06-25 · Updated 2026-08-08 · 15 min read Canonical: https://skills.wondel.ai/guides/grow-an-existing-website-with-ai-skills/ Skills used: cro-methodology, scorecard-marketing, contagious, influence-psychology, made-to-stick, storybrand-messaging, one-page-marketing, hundred-million-offers **TL;DR:** You grow an existing website by converting more of the traffic you already have: discover why visitors leave with CRO Methodology, capture the 97% who are not ready to buy with a Scorecard quiz funnel, clarify the message with StoryBrand, layer in Cialdini's persuasion principles, then make satisfied visitors bring new ones with Contagious's STEPPS. - Only about 3% of your market is ready to buy today — a site that only converts buyers throws away the other 97%. - An interactive scorecard converts 30-50% of visitors where a PDF lead magnet converts 3-10%. - Evidence beats brainstorming: every leaving visitor had a reason, and exit research finds it before any redesign. - Install the full stack with npx skills add wondelai/skills --all --global and connect capture, nurture, and referral so wins compound instead of leaking. You already have a website that works. People find it, they land, some of them read. And then most of them leave without doing anything. That gap between "traffic" and "revenue" is the most expensive thing in your business, and it is also the most fixable. You do not need more visitors to grow. You need more of the visitors you already paid for to convert. This is the situation this guide is built for: a site with real traffic that under-monetizes it. Maybe you bounce at 70%. Maybe people add to cart and vanish at checkout. Maybe your homepage is "clever" and nobody can tell what you sell. Maybe you have a great product hidden behind a thin offer and a confusing message. The fix is not a redesign and it is not a prayer. It is a sequence: discover why people do not convert, capture the ones who are not ready yet, make the message land, sharpen the offer so saying no feels stupid, and engineer the whole thing to spread. The eight skills in this stack do exactly that, and they are stronger together than apart. [CRO Methodology](https://skills.wondel.ai/skills/cro-methodology/) tells you *what* to fix by researching real visitors instead of guessing. [Scorecard Marketing](https://skills.wondel.ai/skills/scorecard-marketing/) captures the 97% who are not ready to buy today. [StoryBrand Messaging](https://skills.wondel.ai/skills/storybrand-messaging/) and [Made to Stick](https://skills.wondel.ai/skills/made-to-stick/) make your words clear and memorable. [Influence Psychology](https://skills.wondel.ai/skills/influence-psychology/) adds the proof and triggers that move people from interested to committed. [$100M Offers](https://skills.wondel.ai/skills/hundred-million-offers/) rebuilds the thing you are actually selling. [Contagious](https://skills.wondel.ai/skills/contagious/) makes visitors bring you more visitors. And [1-Page Marketing Plan](https://skills.wondel.ai/skills/one-page-marketing/) ties the lifecycle together so wins compound instead of leaking. > You do not have a traffic problem. You have a conversion problem wearing a traffic-problem costume. Each skill is a self-contained package of a bestselling book's framework that an AI coding agent — Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw, or Hermes Agent — can actually apply to your code, your copy, and your funnel. You install one with `npx skills add wondelai/skills/ --global` and invoke it by telling your agent to use it. Work through the phases below in order. By the end you will have a research-driven optimization loop running on your live site, not a folder of "best practices" you copied from a competitor who is also guessing. ## Phase 1 — Discover why visitors do not convert (CRO Methodology) Before you change a single pixel, you need to know what is actually broken. This is the part almost everyone skips, and it is why almost everyone's "optimization" fails. The core idea behind [CRO Methodology](https://skills.wondel.ai/skills/cro-methodology/) — drawn from Karl Blanks and Ben Jesson's [*Making Websites Win*](https://conversion-rate-experts.com/making-websites-win/) and the agency methodology that doubled sales for Google, Apple, and Dropbox — is brutally simple: **don't guess, discover.** Every visitor who leaves had a reason. Your job is to find that reason from evidence, not to brainstorm it in a meeting. The skill drives a structured process. Start by mapping your funnel to find what the book calls "blocked arteries" — high-traffic pages where people drop off — and "missing links," funnel stages that should exist but don't. Then research visitors in three dimensions: who they are, what blocks them (UX problems), and what stops them (objections). The crucial output is an **Objection / Counter-Objection (O/CO) table**: every objection a visitor has, mapped to a specific, evidence-backed answer, placed at the exact point in the page where the objection arises. The credit-card fear goes next to the payment form, not buried in an FAQ nobody reads. Why does this work when "10 tips to boost conversions" doesn't? Because teams are almost always wrong about why visitors leave. The customer's own language — pulled from exit surveys, support tickets, chat logs, and reviews — out-persuades any copywriter's invention. A modest claim backed by overwhelming proof beats a bold claim with none. So the agent's first job is to inventory the proof you already have and are not showing: undisplayed testimonials, unmentioned awards, buried guarantees. > **Prompt** — Use the `cro-methodology` skill to audit my checkout flow, map where the funnel drops off, and build an Objection/Counter-Objection table for the payment step using the real language from my support tickets and reviews > (https://skills.wondel.ai/skills/cro-methodology/) Start with the highest-traffic, worst-performing page — that is your blocked artery and your biggest win. Have the agent run a real diagnostic, not a vibe check. > **Prompt** — Use the `cro-methodology` skill to run the Quick Diagnostic on my pricing page, score it 0-10 against the CRE principles, and tell me the three specific changes that would move it closest to 10/10 > (https://skills.wondel.ai/skills/cro-methodology/) One more thing this skill insists on, and it matters: when you eventually test changes, design **bold experiments, not meek tweaks.** Button-color tests almost never reach statistical significance and waste your traffic. Test new value propositions, new offers, full-page rewrites — changes that could plausibly *double* conversion. Score every idea with ICE (Impact, Confidence, Ease) so you spend your limited traffic on the experiments that can actually move the number. > **Prompt** — Use the `cro-methodology` skill to take my list of conversion ideas, score each one with ICE, write a research-grounded hypothesis for the top two in the If-we-change-X-then-Y-because-Z format, and define the primary, secondary, and guardrail metrics for each > (https://skills.wondel.ai/skills/cro-methodology/) ## Phase 2 — Capture the 97% who are not ready to buy (Scorecard Marketing) Here is the uncomfortable math from Allan Dib that this whole stack respects: only about 3% of any market is ready to buy right now. If your site only converts buyers, you are throwing away the other 97% the moment they leave. The fix is to capture them — and the highest-converting capture mechanism on the internet is not a PDF download. It is an interactive assessment. [Scorecard Marketing](https://skills.wondel.ai/skills/scorecard-marketing/), built on Daniel Priestley and Glen Carlson's book and the [ScoreApp methodology](https://scoreapp.com/), makes the case with hard numbers: a traditional PDF lead magnet converts 3-10% of visitors, while a well-designed scorecard or quiz funnel converts **30-50%**, and top performers hit 70%+. Why such a gap? Because people enjoy answering questions about themselves, because a score taps the primal drive to measure and rank yourself, and because — critically — you capture the email *before* the questions, so you keep the lead even when someone abandons halfway. The skill walks the agent through the full 4-step system: a landing page whose only job is to make clicking "Start" irresistible (built on the 3 Cs — Clarity, Credibility, Connection); a questionnaire that captures contact info first, then asks 8-15 scored questions for cold traffic grouped into 2-7 meaningful categories; a results page with **dynamic content per tier** that creates tension between where the visitor is and where they could be; and a follow-up engine that segments leads by score. A scorecard lead arrives with self-reported pain points and qualification signals already attached, which is why sales conversations shift from discovery to recommendation. > **Prompt** — Use the `scorecard-marketing` skill to design a Website Conversion Scorecard for my SaaS visitors — write the concept hook, 12 scored questions across 4 categories, three result tiers with dynamic copy, and the lead-capture form that fires before question one > (https://skills.wondel.ai/skills/scorecard-marketing/) The concept hook is the single most important element — it defines what visitors score themselves on, and "moving toward" hooks ("Are you ready to scale?") beat fear-based ones. Get the agent to generate and pressure-test several before you commit. > **Prompt** — Use the `scorecard-marketing` skill to write five concept hooks for a lead-generation quiz aimed at e-commerce founders who feel their store under-converts, then tell me which taps the strongest dormant desire and why > (https://skills.wondel.ai/skills/scorecard-marketing/) Once the scorecard exists, it needs a tier-segmented follow-up sequence so a low scorer (who needs education and a free first step) and a high scorer (who is ready for a direct consultation) never get the same generic email. > **Prompt** — Use the `scorecard-marketing` skill to build the post-assessment email sequence for my Marketing Score quiz — separate three-email tracks for the Low, Medium, and High tiers, each referencing the category they scored worst on > (https://skills.wondel.ai/skills/scorecard-marketing/) ## Phase 3 — Make your message clear before you make it clever (StoryBrand Messaging) Most websites fail at the most basic test: a visitor cannot tell what you do, who it is for, or why they should care, within five seconds. They leave not because your offer is bad but because they never understood it. [Donald Miller's](https://storybrand.com/) [StoryBrand Messaging](https://skills.wondel.ai/skills/storybrand-messaging/) fixes this with one disciplined move: **make the customer the hero, and make your brand the guide.** When you position yourself as the hero ("we're the best, we're award-winning, we're passionate") you compete with your customer for the spotlight. When you position yourself as the guide — Yoda, not Luke — you serve them, and they trust you. The skill runs your copy through the SB7 framework: a Character who wants one specific thing; a Problem named at three levels (external, internal, and philosophical — companies sell solutions to external problems but customers buy solutions to *internal* ones); a Guide who shows empathy *and* authority; a Plan of three to four steps that makes the path feel safe; a Call to Action that is direct and repeated; the stakes of Failure; and a vivid picture of Success. It also generates the **one-liner** — a single sentence using the formula "We help [character] who struggle with [problem] to [solution] so they can [result]" — that you use everywhere from your homepage hero to your email signature. This phase comes after research deliberately. The objections you discovered in Phase 1 are the raw material for the Problem and the Plan. The proof you inventoried becomes the Guide's authority. Rewriting copy before you understand visitors is just rearranging guesses. > **Prompt** — Use the `storybrand-messaging` skill to rewrite my homepage hero using the SB7 framework — position my customer as the hero, name their internal problem not just the external one, and give me a direct CTA plus a transitional CTA > (https://skills.wondel.ai/skills/storybrand-messaging/) > **Prompt** — Use the `storybrand-messaging` skill to generate three one-liner options for my B2B analytics product using the problem-solution-result formula, then tell me which one a stranger could repeat after hearing it once > (https://skills.wondel.ai/skills/storybrand-messaging/) A clear message is not the same as a clever one. The skill is emphatic here, and it is the right instinct: **when forced to choose between clever and clear, always choose clear.** Clever copy makes people decode; people do not decode, they leave. ## Phase 4 — Make the message stick in memory (Made to Stick) Clarity gets you understood. Stickiness gets you remembered. A visitor who understands you but forgets you by the time they are ready to buy is still a lost sale. [Made to Stick](https://skills.wondel.ai/skills/made-to-stick/), from [Chip and Dan Heath](https://heathbrothers.com/books/made-to-stick/), gives the agent the **SUCCESs** toolkit — Simple, Unexpected, Concrete, Credible, Emotional, Stories — to make any message survive in memory and drive action. The single biggest barrier it targets is the **Curse of Knowledge**: once you know your product deeply, you literally cannot imagine not knowing it, so you drown visitors in jargon and abstraction. The antidotes are concrete. Replace "improve customer experience" with "customers get their order in 30 minutes, still hot." Replace "saves 40%" with "saves 16 hours a month." Replace a statistic nobody can feel with a human-scale comparison. Lead with the counterintuitive thing, not the expected thing. And wherever possible, wrap the transformation in a story about one specific customer, because as the Heaths put it, "If I look at the mass, I will never act. If I look at the one, I will." Made to Stick and StoryBrand are complementary, not redundant: StoryBrand structures *what you say* into a narrative the customer recognizes; Made to Stick sharpens *how you say it* so each line is concrete, surprising, and memorable. Run them in that order. > **Prompt** — Use the `made-to-stick` skill to audit my pricing page copy for the Curse of Knowledge — flag every abstract claim and jargon phrase, then rewrite each one concrete and specific with real numbers > (https://skills.wondel.ai/skills/made-to-stick/) > **Prompt** — Use the `made-to-stick` skill to turn our flagship case study into a sticky customer story using the character-problem-journey-solution-outcome structure, with a concrete before-and-after and one unexpected detail that makes it memorable > (https://skills.wondel.ai/skills/made-to-stick/) ## Phase 5 — Add the proof and triggers that move people to yes (Influence Psychology) Now layer in persuasion. [Robert Cialdini's](https://www.influenceatwork.com/) [Influence Psychology](https://skills.wondel.ai/skills/influence-psychology/) packages the seven research-backed principles of ethical persuasion — Reciprocity, Commitment & Consistency, Social Proof, Authority, Liking, Scarcity, and Unity — and shows the agent exactly where each belongs on your site and in your copy. The highest-leverage ones for an existing site are usually **social proof** and **authority**, because they directly answer the "why should I believe you?" objection your research surfaced. Specific numbers beat vague claims every time: "2,347 founders use this" out-converts "thousands of customers." Similar-other proof beats generic proof: a testimonial from someone the visitor recognizes as *like them* lands harder than a celebrity. And one counterintuitive insight worth deploying — admitting a small weakness *before* your strengths actually increases trust ("Works best for teams of 10-50" reads as honest, and honesty buys credibility). The most powerful pages stack several principles at once: authority ("built by ex-Stripe engineers") plus social proof ("trusted by 5,000+ teams") plus reciprocity ("start free, no credit card") plus genuine scarcity ("founding-member pricing, 100 spots"). But the skill is strict about the line between persuasion and manipulation, and you should be too: real numbers only, real deadlines only, real scarcity only. Fake scarcity — the countdown timer that resets on refresh, the "only 2 left!" that is always there — is the fastest way to destroy the trust you are trying to build. > **Prompt** — Use the `influence-psychology` skill to audit my landing page for the seven principles of influence, then redesign the testimonial and trust-signal section to stack social proof, authority, and a genuine scarcity element — flag anything that would cross into manipulation > (https://skills.wondel.ai/skills/influence-psychology/) > **Prompt** — Use the `influence-psychology` skill to rewrite my free-trial signup flow to use commitment and consistency — start with a small micro-commitment question, then escalate to the larger ask, keeping every step easily reversible > (https://skills.wondel.ai/skills/influence-psychology/) ## Phase 6 — Rebuild the thing you are actually selling (\$100M Offers) You can optimize a page forever, but if the underlying offer is weak you are polishing a problem. Alex Hormozi's [$100M Offers](https://skills.wondel.ai/skills/hundred-million-offers/) is the most upstream lever in this entire stack, and its thesis is blunt: **a Grand Slam Offer sells despite mediocre marketing, while the best marketing in the world cannot save a bad offer.** Before you run another test, make sure the offer itself is irresistible. The engine is the **Value Equation**: Value = (Dream Outcome × Perceived Likelihood of Achievement) ÷ (Time Delay × Effort & Sacrifice). You make an offer feel like a no-brainer by maximizing the top — a bigger dream, more proof it will work — and minimizing the bottom — faster results, less work for the customer. The skill then has the agent build a complete package rather than a bare product: list every obstacle between the customer and the dream outcome, create a solution for each, apply **Trim & Stack** (cut the low-value/high-cost components, stack the high-value/low-cost ones), add named **bonuses** that each kill a specific objection, attach a **risk-reversing guarantee**, add **ethical scarcity**, and give it a name using the **MAGIC** formula (Magnetic reason, Avatar, Goal, Indicate timeframe, Container word). Two ideas here pay for themselves immediately. First, a strong guarantee counterintuitively *reduces* refunds, because it signals confidence and attracts committed buyers rather than tire-kickers. Second, raising your price often *increases* conversions, because price communicates quality — anchoring against the cost of *not* solving the problem, not against a cheaper competitor. > **Prompt** — Use the `hundred-million-offers` skill to score my current offer on the pricing page against the Value Equation, then redesign it into a Grand Slam Offer — list the obstacles my customers face, propose named bonuses that each kill a specific objection, and recommend a guarantee that reverses their risk > (https://skills.wondel.ai/skills/hundred-million-offers/) > **Prompt** — Use the `hundred-million-offers` skill to diagnose whether my customers calling the product too expensive is a price problem or a value-perception problem, then rewrite the offer so the perceived value is at least 10x the price > (https://skills.wondel.ai/skills/hundred-million-offers/) > **Prompt** — Use the `hundred-million-offers` skill to rename my main offer using the MAGIC formula so the headline names who it is for, the outcome they get, and the timeframe — give me five variations to test > (https://skills.wondel.ai/skills/hundred-million-offers/) Once the offer is rebuilt, it flows straight back into Phase 3's messaging and Phase 1's test queue. A new offer is exactly the kind of bold change CRO Methodology says is worth testing. ## Phase 7 — Make visitors bring you more visitors (Contagious) Everything so far squeezes more value out of each visitor. This phase makes each satisfied visitor *generate* new ones — for free. [Jonah Berger's](https://jonahberger.com/books/contagious/) [Contagious](https://skills.wondel.ai/skills/contagious/) is built on a claim that reframes the whole problem: **virality is engineered, not born.** Products spread because someone designed them to be shared. And the design rules are the **STEPPS** framework: Social Currency, Triggers, Emotion, Public, Practical Value, Stories. A few of these map unusually well to an existing website. **Social Currency** — does sharing this make people look good? — is why a personalized result from your Phase 2 scorecard is so shareable: it gives people a remarkable stat about themselves to post. **Practical Value** — useful enough to forward — turns a free calculator or a genuinely good "7 ways to..." resource into a sharing engine, and the skill brings the Rule of 100 for framing your promotions (percentages under \$100, dollar amounts over). **Public** — built to show, built to grow — is the principle behind a "Powered by [you]" credit on customer outputs and behavioral residue that markets you long after use. And **Stories** insists on the Trojan Horse test: if someone can retell your story without mentioning your brand, the story has failed you. One correction to a common instinct: only about 7% of word-of-mouth happens online. The other 93% is offline conversation. So the goal is not "add share buttons" — it is to design things worth talking about and triggers that bring you up in everyday conversation. > **Prompt** — Use the `contagious` skill to redesign the results page of my scorecard quiz to maximize Social Currency — make the score worth sharing, add a remarkable personalized stat, and build a share card that passes the Trojan Horse test > (https://skills.wondel.ai/skills/contagious/) > **Prompt** — Use the `contagious` skill to audit my product for the six STEPPS drivers, score how shareable it is out of 10, and give me three concrete features that would add Public visibility and behavioral residue > (https://skills.wondel.ai/skills/contagious/) ## Phase 8 — Tie the lifecycle together so wins compound (1-Page Marketing Plan) The final skill is the connective tissue. It is easy to fix a page, capture a lead, and then let it all leak out the back because nothing connects acquisition to nurture to retention to referral. Allan Dib's [1-Page Marketing Plan](https://skills.wondel.ai/skills/one-page-marketing/) prevents that with a 3×3 grid covering the full journey from stranger to raving fan: **BEFORE** (Target Market, Message, Media), **DURING** (Capture Leads, Nurture, Convert), and **AFTER** (Experience, Lifetime Value, Referrals). For a site you are growing, the AFTER column is usually where the money is hiding. Acquiring a new customer costs 5-25x more than retaining one, and a 5% retention gain can lift profits 25-95%. The skill's core principle — "marketing is not an event, it is a process" — is the antidote to the disconnected-tactics trap. It also surfaces the squares you are almost certainly neglecting: a documented nurture sequence for leads who are not ready, an ascension model so your best customers can spend more, and a systematic referral program (the #1 reason customers don't refer is simply that nobody asked). Use this skill last, as an audit, to make sure the work from Phases 1-7 actually links into one engine. The scorecard from Phase 2 fills the Capture square. The offer from Phase 6 fills the Convert square. Contagious from Phase 7 powers the Referrals square. The plan makes the whole thing legible on a single page. > **Prompt** — Use the `one-page-marketing` skill to fill in the 9-square 1-Page Marketing Plan for my business, score each square 0-10 for specificity, and flag which squares in the AFTER phase — experience, lifetime value, referrals — I have left empty > (https://skills.wondel.ai/skills/one-page-marketing/) > **Prompt** — Use the `one-page-marketing` skill to design the lead-nurture sequence for the After phase of my plan — a five-email welcome series at a 3-to-1 value-to-ask ratio that turns a fresh scorecard lead into a paying customer > (https://skills.wondel.ai/skills/one-page-marketing/) ## Your checklist - [ ] Install the stack: run `npx skills add wondelai/skills/cro-methodology --global` and repeat for each slug in this guide. - [ ] Map your funnel and identify the single highest-traffic, worst-converting page (your blocked artery). - [ ] Run customer research — exit surveys, support tickets, chat logs, reviews — instead of guessing why people leave. - [ ] Build an Objection / Counter-Objection table and place each counter at its point of friction. - [ ] Inventory the proof you already have and are not showing (testimonials, awards, guarantees). - [ ] Launch a scorecard or quiz that captures email *before* the questions, with dynamic results by tier. - [ ] Rewrite your homepage with the customer as hero and ship a one-liner you use everywhere. - [ ] De-jargon every page — replace abstractions with concrete numbers and one specific customer story. - [ ] Stack real social proof and authority on your conversion pages; remove any fake scarcity. - [ ] Rebuild your offer with the Value Equation, named bonuses, and a risk-reversing guarantee. - [ ] Engineer shareability into your highest-value asset using two or three STEPPS drivers. - [ ] Complete the 9-square marketing plan and fill the empty AFTER-phase squares. - [ ] Queue bold A/B tests (not button colors), score them with ICE, and run each to 95% confidence over a full business cycle. ## Common mistakes **Optimizing before researching.** The number-one trap. Teams jump straight to changing headlines and button colors based on intuition or a competitor's site. You do not know if it even works for the competitor. CRO Methodology is explicit: research *your* visitors' objections first, then change things. Skipping this is why most "optimization" produces noise. **Testing meek tweaks instead of bold changes.** A button-color test on normal traffic will almost never reach statistical significance — you will burn weeks and learn nothing. Test changes that could plausibly double conversion: a new offer, a new value proposition, a full-page rewrite. Use ICE scoring to kill the trivial ideas before they waste your traffic. **Capturing email after the quiz instead of before.** If your lead form comes at the end of the assessment, you lose every person who abandons partway — which is most of them. Scorecard Marketing is unambiguous: the lead-capture form goes *first*. You keep the lead even on abandonment, and you can send a recovery email. **Choosing clever over clear.** A witty homepage that makes visitors work to understand what you sell will out-lose a plain one every time. People do not decode marketing; they leave. Win the five-second test first, then add personality. **Faking scarcity or proof.** A countdown timer that resets, a "only 2 left!" that never changes, an invented testimonial — these work until someone notices, and then they poison every honest claim you make afterward. Both Influence Psychology and $100M Offers draw a hard line: every scarcity, urgency, and proof claim must be 100% true. Persuasion helps people see value they would appreciate anyway; manipulation tricks them against their interest. **Polishing the page while ignoring the offer.** You can A/B test a weak offer forever and get nowhere. If people keep saying "too expensive," that is usually a value-perception problem, not a price problem. Fix the offer upstream — it is the highest-leverage change you can make — then optimize the page around it. **Ignoring the AFTER phase.** Most sites pour everything into acquisition and let customers churn silently. Retention and referrals are the cheapest growth you will ever buy. If your 1-Page Marketing Plan has empty squares, they are almost always Experience, Lifetime Value, and Referrals. ## Frequently asked questions ### Which skill should I start with if I only have time for one? [CRO Methodology](https://skills.wondel.ai/skills/cro-methodology/). It is the foundation the rest build on, because it replaces guessing with evidence. Have your agent map your funnel, find your worst-performing high-traffic page, and build an Objection / Counter-Objection table from your real support and chat data. That single artifact will tell you which of the other skills you need most — if objections cluster around trust, reach for Influence Psychology; if they cluster around "too expensive," reach for $100M Offers; if visitors do not even understand the page, reach for StoryBrand. ### Do I need a lot of traffic for A/B testing to work? You need enough to reach statistical significance, which is exactly why the stack pushes **bold** changes over tiny tweaks. A dramatic change — a fundamentally different offer or layout — produces a large effect that is detectable with a smaller sample (the skill notes roughly 4,000 visitors can detect a 50% lift), whereas a button-color tweak needs enormous traffic to prove a 2% difference. If your traffic is genuinely low, lean harder on the qualitative side of CRO Methodology (surveys, session research) and on the offer and messaging skills, where you can reason from principles rather than wait on a test. ### Isn't a scorecard quiz a gimmick? Will it cheapen my brand? Done badly, yes — a bait-and-switch that pretends to assess you and then hard-sells is a gimmick, and Scorecard Marketing explicitly forbids it. Done well, a scorecard is a genuinely useful diagnostic that gives visitors a personalized result they could not get anywhere else, which is precisely why it converts at 30-50% versus 3-10% for a PDF. The ethical boundary is the design constraint: the hook must promise value the assessment actually delivers, and low scorers must get real, actionable help rather than manufactured anxiety. Build it to be genuinely helpful and it elevates your brand instead of cheapening it. ### How do these skills know about my specific site? They do not start with knowledge of your site — you give it to them. Each skill is a framework the agent applies to the context you provide: point it at your actual pages, paste in your support-ticket export, reference your `pricing.tsx` component or your `/checkout` route, attach your analytics. The skill supplies the *method* (the O/CO table, the Value Equation, SUCCESs, STEPPS); you and your codebase supply the *material*. That is why the sample prompts above reference concrete artifacts — the more real context you hand the agent, the better the output. ### Can I run these in parallel, or must it be strictly sequential? The sequence is the recommended path because each phase feeds the next — research informs messaging, messaging informs the offer, the offer informs your tests. But there are natural pairings you can run together. Messaging clarity (StoryBrand) and stickiness (Made to Stick) are best done in one pass. Offer design ($100M Offers) can begin in parallel with research, since a great offer is valuable regardless of what the research finds. Just resist the urge to start testing (the CRO experiment loop) before you have done the research that tells you *what* to test. ## Start growing your site today Pick your worst-converting page, install the foundation skill, and let your agent show you — with evidence, not opinion — exactly why visitors are leaving and what to do about it: ``` npx skills add wondelai/skills --all --global ``` Then point your agent at that page with one of the prompts above. Work the phases in order and you will have turned a static site into a research-driven growth engine that captures more leads, persuades more buyers, sells a sharper offer, and brings you new visitors for free. When you are ready to extend the same playbook to the product behind the site, read [How to Grow an Existing App with AI Skills](https://skills.wondel.ai/guides/grow-an-existing-app-with-ai-skills/). Starting fresh instead? See [How to Create a New Website with AI Skills](https://skills.wondel.ai/guides/create-a-new-website-with-ai-skills/). --- # How to Grow an Existing App with AI Skills > Drive activation, retention, and engagement in an app that already has users — habit loops, retention behavior design, discovery, and metrics — with AI agent skills from Hooked, Tiny Habits, Continuous Discovery, and more. By Michał Jaskólski · Published 2026-06-25 · Updated 2026-08-08 · 16 min read Canonical: https://skills.wondel.ai/guides/grow-an-existing-app-with-ai-skills/ Skills used: hooked-ux, improve-retention, continuous-discovery, lean-ux, inspired-product, lean-analytics, microinteractions, drive-motivation **TL;DR:** You grow an existing app by fixing the return loop before buying traffic: design a Hooked habit loop, make the first-run action effortless, run Teresa Torres-style continuous discovery weekly, experiment cheaply with Lean UX, then point the team at the one retention metric that matters — because acquisition poured into a leaky bucket only multiplies churn. - Pass the Stickiness gate first — a flattening retention curve — before you spend anything on acquisition or virality. - Move users from external triggers (notifications) to internal ones (emotions): if day-30 users still need a push to return, you are renting attention, not owning a habit. - Replace quarterly research bursts with at least one customer touchpoint per week, run by the product trio. - Install the stack with npx skills add wondelai/skills --all --global and audit every gamification idea against Autonomy, Mastery, and Purpose before it ships. You have an app. People sign up. Then most of them quietly disappear. Your charts go up and to the right — total registered users, total downloads, cumulative everything — but the truth is hiding underneath: each week's new cohort retains a little worse than you'd like, daily actives are flat, and the activation funnel leaks where it always has. This is the hardest stage of a product's life, because nothing is obviously broken. The app works. It just doesn't *stick*. Growth here is not a bigger marketing budget. Pouring acquisition into a product that doesn't retain is the classic leaky bucket: you pay to fill the top while the bottom drains. The real work is closing the bucket — turning first-time users into activated users, activated users into habitual users, and habitual users into people who would be genuinely annoyed if your app disappeared. That is an engineering and design problem with a known shape, not a mystery. This guide gives you a sequenced workflow that an AI coding agent can execute alongside you, step by step. You will design a habit loop with [Hooked UX](https://skills.wondel.ai/skills/hooked-ux/), make your first-run action reliable with [Improve Retention](https://skills.wondel.ai/skills/improve-retention/), set up a weekly cadence of customer learning with [Continuous Discovery](https://skills.wondel.ai/skills/continuous-discovery/), replace endless internal debate with cheap experiments using [Lean UX](https://skills.wondel.ai/skills/lean-ux/), restructure how the team decides what to build with [Inspired](https://skills.wondel.ai/skills/inspired-product/), point the whole company at the one number that matters with [Lean Analytics](https://skills.wondel.ai/skills/lean-analytics/), polish the small moments with [Microinteractions](https://skills.wondel.ai/skills/microinteractions/), and sustain it all on intrinsic motivation with [Drive Motivation](https://skills.wondel.ai/skills/drive-motivation/). > You don't grow a leaky-bucket app by pouring in more water. You grow it by fixing the bucket — one cohort, one loop, one micro-moment at a time. Each skill packages a bestselling book into something your agent can apply directly to your codebase, your funnel, and your copy. You install one with `npx skills add wondelai/skills/ --global` and invoke it by telling the agent to use it. Work through the phases in order — they build on each other — and by the end you'll have a retention engine you can keep turning long after this guide. ## Phase 1 — Design the habit loop that brings users back Start with the engine of return: the habit loop. **[Hooked UX](https://skills.wondel.ai/skills/hooked-ux/)** is built on [Nir Eyal's Hook Model](https://www.nirandfar.com/hooked/) — `Trigger → Action → Variable Reward → Investment` — a four-phase cycle that, run frequently enough, moves your app from a deliberate choice to an automatic one. The insight that matters most for an existing app is the migration from *external* triggers (your push notifications, your re-engagement emails) to *internal* triggers (an emotion the user feels — boredom, anxiety, FOMO, the itch to check something). If after thirty days your users still need a notification to come back, no internal trigger has formed, and you're renting attention rather than owning a habit. Map your existing product against all four phases before you change anything. What emotion does someone feel right before they open your app? What is the simplest action they take — and is it genuinely simple, or does it sit behind a load screen and three taps? Is the reward variable (you never quite know what you'll get) or predictable (the dopamine fades the third time)? And does the user invest something — data, content, a preference, a connection — that makes the next loop better and loads the next trigger? A loop with a weak phase doesn't half-work; it stalls. > **Prompt** — Use the `hooked-ux` skill to audit my note-taking app's core loop against the four phases of the Hook Model — map the internal trigger our daily-active users are responding to, rate each phase 0-10, and tell me which phase is weakest and the single highest-leverage change to strengthen it > (https://skills.wondel.ai/skills/hooked-ux/) The variable reward is where most utility apps go flat. A to-do app that shows the same empty checklist every morning has a predictable reward; one that surfaces a streak, a surprise insight from your week, or what your teammates touched while you were away taps the three reward types Eyal names — tribe (social validation), hunt (a stream of resources), and self (mastery and progress). Ask your agent to design reward variability that fits your product honestly, not a slot-machine bolt-on. > **Prompt** — Use the `hooked-ux` skill to design three variable-reward concepts for my app's most-visited moment — one tribe reward, one hunt reward, one self reward — and for each specify the exact data we already have to power it and the copy that would appear, then flag any that risk feeling manipulative under the Manipulation Matrix > (https://skills.wondel.ai/skills/hooked-ux/) Crucially, sequence the loop correctly: ask for investment *after* the reward, never before. Users invest when they feel good, and each investment — saving a draft, following a topic, inviting a teammate — should both raise switching costs and load the next trigger (your post creates a notification when someone replies). Have the agent re-engineer your onboarding so a new user completes one full Hook cycle before they ever leave the first session. That single change is often the difference between a Day-1 number and a Day-7 number. ## Phase 2 — Fix activation by making the first action almost effortless A habit loop only matters if users reach it. **[Improve Retention](https://skills.wondel.ai/skills/improve-retention/)** brings BJ Fogg's Behavior Model — `B=MAP`, where Behavior happens only when Motivation, Ability, and a Prompt converge at the same moment — to the activation problem. The strategic core of the book is counterintuitive and liberating: motivation is unreliable and you can't engineer it, but *ability* you can. Every field you remove, every step you collapse, every smart default you set moves the behavior to the right on the model, crossing the Action Line even when motivation is low. Stop trying to pump up excitement; make the thing easier. The most useful diagnostic the skill gives you is the Ability Chain: simplicity is governed by the *scarcest* of six resources — time, money, physical effort, mental effort, social deviance, and non-routineness. Teams reflexively optimize time ("now it's three taps instead of five") when the real bottleneck is mental effort (the user doesn't understand what to type) or non-routine (you're asking them to do something they've never done). Fixing the wrong link does nothing. Have your agent run the friction audit on your real activation flow and name the actual bottleneck. > **Prompt** — Use the `improve-retention` skill to diagnose why 60% of signups in our project-management app never create their first project — walk our five-step onboarding flow step by step, rate each of the six Ability Chain factors 1-5 for the create-project action, identify the scarcest resource, and give me a prioritized fix list that targets that bottleneck first > (https://skills.wondel.ai/skills/improve-retention/) Then shrink the target behavior to its Starter Step — the tiniest meaningful version. The goal of onboarding is not "complete your profile" (that's a project, not a behavior); it's "fill in one field," "open the dashboard," "send one comment." Momentum from a completed micro-action does more for retention than any aspirational tour. And pair every Starter Step with a celebration: an immediate, honest moment of success, because repetition alone doesn't wire a habit — the *feeling* of success does. This is exactly where most onboarding flows are silent and cold. > **Prompt** — Use the `improve-retention` skill to redesign our budgeting app's first-run experience as a Tiny Habits sequence — define the Starter Step that delivers value in under 30 seconds, write the anchor-to-existing-routine prompt, and specify the celebration moment after the user logs their first expense, then map each of our day-1, day-7, and day-30 drop-offs to its likely B=MAP failure > (https://skills.wondel.ai/skills/improve-retention/) Finally, fix your prompts. A push notification sent to a user below the Action Line — without the motivation or ability to act — is spam, and every unnecessary prompt degrades the value of the next one. The skill's rule is to prompt only on real events and to anchor new behaviors to existing routines ("after I open Slack, I will…"). Switch your re-engagement from time-based ("We miss you!") to event-based ("Your weekly report is ready"). Ask the agent to redesign your notification strategy around the question: *would I genuinely appreciate receiving this right now?* ## Phase 3 — Run continuous discovery so you stop guessing By now you've improved the loop and the funnel based on best-practice diagnosis. But to keep growing you need a steady stream of evidence about *your* users, not generic patterns. **[Continuous Discovery](https://skills.wondel.ai/skills/continuous-discovery/)** brings [Teresa Torres's framework](https://www.producttalk.org/) for embedding customer learning into the weekly rhythm of product work — the benchmark being at least one customer touchpoint per week, every week, by the product trio (PM, designer, engineer), not a quarterly research burst that goes stale by week two. The centerpiece is the Opportunity Solution Tree: a living visual that connects a desired outcome at the top, to customer opportunities (needs and pain points, framed from the customer's perspective) in the middle, to candidate solutions and experiments at the bottom. Most teams leap straight from "increase retention" to "let's build streaks" — skipping the entire opportunity space and betting everything on one untested solution. The tree forces you to understand *why* users drop off before you decide *what* to build, and to pursue several opportunities at once instead of betting the quarter on a hunch. > **Prompt** — Use the `continuous-discovery` skill to build an Opportunity Solution Tree for our podcast app with the outcome 'increase week-4 retention' at the top — propose 6-8 customer opportunities framed from the listener's perspective based on the churn patterns I'll describe, break the two biggest into sub-opportunities, and suggest two or three candidate solutions under each > (https://skills.wondel.ai/skills/continuous-discovery/) Pair the tree with a current-state experience map and a weekly interview habit. Map how churned users actually try to accomplish their goal today — step by step, including thoughts and feelings — and the high-emotion failure points become opportunities on the tree. Then make interviews story-based: ask "tell me about the last time you…" rather than "would you use…", because customers are poor predictors of their own behavior but reliable narrators of what they actually did. Each interview becomes a one-page snapshot the whole team can absorb. > **Prompt** — Use the `continuous-discovery` skill to design a repeatable weekly discovery system for our two-person team — a current-state experience map of how users abandon our app in week two, a 20-minute story-based interview snapshot template that follows Mom Test rules, and an in-app recruitment prompt that fills two interview slots a week without manual chasing > (https://skills.wondel.ai/skills/continuous-discovery/) The discipline that protects you from building on sand is assumption testing. Before committing engineering, identify the assumptions a solution rests on — desirability, viability, feasibility, usability — map them by importance versus existing evidence, and test the riskiest leap-of-faith assumptions first with the smallest possible experiment. A painted-door button measuring click-through can invalidate a feature in days that would otherwise eat a month of build time. Have the agent map the assumptions hiding inside your next planned feature and design the cheapest test for the scariest one. ## Phase 4 — Replace debate with cheap experiments using Lean UX Discovery surfaces opportunities; **[Lean UX](https://skills.wondel.ai/skills/lean-ux/)** turns them into testable bets instead of endless meetings. Jeff Gothelf and Josh Seiden's core shift is from *outputs* to *outcomes*: the value of a design is the change in user behavior it produces, not the fidelity of the deliverable or the fact that it shipped. The method compresses the distance between idea and evidence — declare your assumptions, write a hypothesis, run the smallest experiment that could disprove it, and let real behavior settle the argument. The hypothesis statement is the workhorse. Instead of "make onboarding better," you commit to a falsifiable prediction in a fixed format: "We believe [outcome] will happen if [persona] achieves [action] with [feature]," with the success metric and threshold agreed *before* you run the test so you can't move the goalposts afterward. This is the antidote to the three-week design debate where two mockups and zero data go in circles. > **Prompt** — Use the `lean-ux` skill to turn our two-week-long argument about whether to redesign the empty-state of our analytics dashboard into a Lean UX experiment — write three hypothesis statements in the standard format, pick the lowest-fidelity experiment that could validate the top one, and define the metric, threshold, and two-week timebox before we build anything > (https://skills.wondel.ai/skills/lean-ux/) Match experiment fidelity to assumption risk: a paper prototype tested with five users in an afternoon (which uncovers roughly 85% of usability problems) beats a fully coded redesign when the question is "do users even understand this?" Reserve expensive A/B tests for when you already know the concept works and you're tuning the margin. Have the agent pick the cheapest experiment that answers your actual question, and run a collaborative design-studio session — where engineers and the PM sketch alongside the designer — so the whole team shares understanding rather than waiting on a 40-page spec. > **Prompt** — Use the `lean-ux` skill to design a one-week minimum-viable experiment for my riskiest onboarding idea — specify the proto-persona, the exact behavior we're measuring, the instrumentation we need, and the pass/fail line, and tell me what to remove from the backlog if the hypothesis is invalidated > (https://skills.wondel.ai/skills/lean-ux/) The last Lean UX discipline matters for sustaining growth: when a hypothesis is invalidated, *remove* the feature from the backlog — don't defer it. A backlog full of disproven ideas is a graveyard that drags on every planning session. Treating a killed experiment as a win, not a failure, is what keeps learning velocity high. ## Phase 5 — Build the right things with an empowered team Growth stalls when a team becomes a feature factory — shipping whatever stakeholders request, measuring stories-shipped instead of outcomes, nobody owning whether any of it moved a metric. **[Inspired](https://skills.wondel.ai/skills/inspired-product/)** brings [Marty Cagan's model](https://www.svpg.com/books/inspired-how-to-create-tech-products-customers-love-2nd-edition/) of empowered product teams: small, durable, cross-functional groups given *problems to solve* rather than *features to build*, accountable for outcomes (activation, retention, revenue) rather than output. The difference between a feature factory and a growth engine is whether your people are missionaries who believe in what they build because they discovered it, or mercenaries executing a handed-down backlog. The mechanism is dual-track: discovery (deciding what's worth building) runs continuously and cheaply alongside delivery (building production-quality software). Discovery exists to address four risks before you spend engineering time — *value* (will customers use it?), *usability* (can they figure it out?), *feasibility* (can we build it?), and *viability* (does it work for the business?). Cagan's rule of thumb is sobering: expect ten to twenty discovery iterations for every feature that reaches delivery, because most ideas don't survive contact with real users. Failing fast and cheap in discovery is the whole point. > **Prompt** — Use the `inspired-product` skill to write an opportunity assessment for the three biggest feature requests in our backlog — for each, answer what business objective it serves, who the target user is, what problem it solves, how we'll measure success, and what alternatives exist — then tell me which one has the strongest evidence and which I should kill before it reaches the sprint > (https://skills.wondel.ai/skills/inspired-product/) Two habits from the book compound especially well for an existing app. First, get engineers into discovery, not just delivery — they're the best source of innovation because they know what's newly possible, and a clickable prototype tested with five target users will save you a quarter of misdirected building. Second, give the team strategic context so it can make good autonomous calls: a real product vision (the world you're building toward) and a quarterly strategy that sequences the hard choices — which users first, which problems first. Outcome-based roadmaps that name problems to solve, not features with delivery dates, are what let an empowered team out-decide any top-down plan. > **Prompt** — Use the `inspired-product` skill to replace our dated feature-list roadmap, which leaves the team no context for tradeoffs, by drafting a one-paragraph product vision for our habit-tracking app and a quarter of outcome-based roadmap items framed as problems to solve and key results, so the team can prioritize without escalating every decision > (https://skills.wondel.ai/skills/inspired-product/) ## Phase 6 — Measure the one number that actually matters You cannot grow what you cannot see honestly, and most dashboards lie by flattering. **[Lean Analytics](https://skills.wondel.ai/skills/lean-analytics/)** distills [Croll and Yoskovitz's discipline](https://leananalyticsbook.com/) into a single demand: focus on the One Metric That Matters right now — the number that tells you whether the riskiest part of the business is working — and treat everything else as drill-down. A good metric is comparative, a ratio or rate (not an ever-growing total), and behavior-changing: if a number won't change what you do next, stop watching it. The cumulative up-and-to-the-right chart is the single most reliable vanity tell, because totals can't go down and so they hide the decay underneath. Two ideas reframe how you read your own data. First, business model dictates which metrics matter — a habitual app lives on DAU/MAU and retention cohorts, a SaaS on churn and time-to-value, a marketplace on liquidity — so stop copying another company's north star. Second, stage dictates sequencing: the Lean Analytics stages run Empathy → Stickiness → Virality → Revenue → Scale, and working a later stage's metric before passing the current gate is the canonical startup mistake. An app with weak retention is squarely in the Stickiness stage, which means *retention is your OMTM* — and pouring referral or paid-acquisition effort in now just multiplies a leaky bucket faster. > **Prompt** — Use the `lean-analytics` skill to cut our meditation app's 30-metric dashboard down to what matters — every meeting currently cites a different number, and we're a habitual mobile app with flat retention, so identify which of our current metrics are vanity metrics, pick the One Metric That Matters for the Stickiness stage plus a counter-metric that keeps it honest, and design a one-screen dashboard with the OMTM big and at most six supporting metrics > (https://skills.wondel.ai/skills/lean-analytics/) Then draw a line in the sand: a target number, a date, and a pre-committed answer to "what do we do if we miss?" — decided in advance, so "good enough" is a decision rather than a rationalization made after results arrive. Pair the OMTM with a counter-metric so it can't be gamed (activation speed paired with 30-day retention; a referral push paired with the quality of referred users). And make time honest with cohorts: track each signup month separately, because real improvement vanishes inside a blended average and a flat aggregate often hides one segment soaring while another collapses. > **Prompt** — Use the `lean-analytics` skill to build me a cohort-based retention view and a line in the sand for our e-learning app — define the exact formula for our core engagement action, segment by acquisition channel, set a week-4 retention target with a date and a pre-committed action if we miss it, and pair it with a counter-metric so we don't optimize engagement at the expense of completion quality > (https://skills.wondel.ai/skills/lean-analytics/) ## Phase 7 — Polish the micro-moments that make it feel alive With the loop, funnel, discovery, and metrics in place, the remaining gap between an app people tolerate and one they love lives in the details. **[Microinteractions](https://skills.wondel.ai/skills/microinteractions/)** brings Dan Saffer's four-part structure — `Trigger → Rules → Feedback → Loops & Modes` — to the tiny contained moments users touch every day: the toggle, the like button, the pull-to-refresh, the loading state, the form field. These are too small for users to think about consciously, but they *feel* every one, and they accumulate into the sense that a product is either crafted or assembled. Feedback is where most apps feel dead. The rule is immediate — under 100ms for direct manipulation — and proportionate: a small action gets small feedback, a big result gets a big one. Prefer animating the element the user already touched (the button itself becoming "Saving…") over throwing a separate toast. And the most overlooked discipline is edge cases: map every state — empty, loading, partial, full, error, disabled, double-tap — because an interaction that breaks at zero or on a repeated tap is exactly what erodes trust. > **Prompt** — Use the `microinteractions` skill to audit the five most-used interactions in our task app — completing a task, adding an item, switching views, receiving a notification, and reaching inbox zero — using Trigger, Rules, Feedback, Loops and Modes, and for each specify the feedback that fires within 100ms, every edge-case state we're currently missing, and which one deserves to become a signature moment > (https://skills.wondel.ai/skills/microinteractions/) Invest in one or two signature moments — a distinctive interaction that becomes part of your product's identity, like the moment a task completes or a goal is hit — but apply the removal test: if users wouldn't miss it, it's decoration, not signature, and it shouldn't slow down a frequent action. Use long loops to let interactions mature: show the "swipe to archive" hint for the first three sessions, then retire it through progressive reduction so power users aren't nagged forever. Have the agent implement the actual code for these, not just describe them. > **Prompt** — Use the `microinteractions` skill to design and implement the completion microinteraction for our running app's 'finish workout' button in our React component — an honest deterministic progress state between tap and confirmation, a celebratory but fast signature animation, haptic feedback as a supplementary channel, and a long loop that tones down the celebration after the user's twentieth workout > (https://skills.wondel.ai/skills/microinteractions/) ## Phase 8 — Sustain engagement with intrinsic motivation Everything above can be turned against the user, and if you do, growth reverses. **[Drive Motivation](https://skills.wondel.ai/skills/drive-motivation/)** brings Daniel Pink's synthesis of motivation science: for any task requiring even rudimentary cognitive effort, external "if-then" rewards either don't work or actively make things worse — they extinguish intrinsic motivation, crush creativity, and foster short-term thinking. Lasting engagement comes from Autonomy, Mastery, and Purpose (AMP), and this is the lens that keeps your habit loops and gamification from curdling into something users come to resent. Autonomy means choice over what, when, how, and with whom. The autonomy killers are exactly the patterns growth teams reach for under pressure: forced linear tutorials, unskippable steps, algorithm-only feeds with no user control, mandatory notifications. Audit your app for "you must complete X before Y" and replace it with chosen paths. Mastery means the desire to get better at something that matters — visible progress, immediate feedback, and challenge calibrated to skill so the user sits in flow between boredom and anxiety, with always a clear next step. Purpose is the context that makes the other two cohere: does the user know *why* this exists, and can they see their impact on something bigger than a vanity number? > **Prompt** — Use the `drive-motivation` skill to audit our language-learning app's gamification against Autonomy, Mastery, and Purpose — rate it 0-10, identify where our streaks and points have tipped from intrinsic mastery into extrinsic loss aversion, flag every autonomy violation like forced challenges or unskippable steps, and redesign the progression so it shows real skill development and connects daily practice to a purpose the learner cares about > (https://skills.wondel.ai/skills/drive-motivation/) The most common self-inflicted wound is awarding points for everything, which crowds out the intrinsic satisfaction that was driving your best users in the first place. Reserve rewards for genuinely meaningful milestones, prefer "now-that" recognition (an unexpected acknowledgment after the fact) over "if-then" bargains, and watch the line where a streak stops being a proud record of mastery and becomes a fear of loss you're exploiting. Sustainable growth runs on Type I behavior — fueled by AMP — because it's renewable and it promotes the user's well-being, which is the only kind of engagement that compounds for years instead of burning out in a quarter. > Engagement you have to manufacture every morning isn't a habit — it's a treadmill. The loops worth building are the ones users would choose even if you stopped reminding them. ## Your checklist - [ ] Map your app's core loop against the four Hook phases and fix the weakest one (Hooked UX) - [ ] Identify the internal trigger — the emotion — that should pull users back without a notification - [ ] Add honest variable reward to your most frequent screen, sequencing investment *after* reward - [ ] Run a B=MAP friction audit on activation and name the scarcest Ability Chain resource (Improve Retention) - [ ] Shrink your first-run flow to a Starter Step that delivers value in under 30 seconds, with a celebration - [ ] Switch re-engagement from time-based to event-based prompts that pass the "would I appreciate this?" test - [ ] Build an Opportunity Solution Tree for your retention outcome and keep it living (Continuous Discovery) - [ ] Establish a weekly story-based interview cadence with automated recruitment and one-page snapshots - [ ] Map the assumptions inside your next feature and test the riskiest one with a painted-door experiment - [ ] Convert your biggest internal design debate into a Lean UX hypothesis with a pre-committed metric (Lean UX) - [ ] Choose the lowest-fidelity experiment that answers the question; remove invalidated items from the backlog - [ ] Write an opportunity assessment for your top three backlog requests and kill the weakest (Inspired) - [ ] Replace your dated feature roadmap with outcome-based problems to solve and key results - [ ] Identify and retire vanity metrics; pick your One Metric That Matters for the Stickiness stage (Lean Analytics) - [ ] Draw a line in the sand — target, date, miss response — and pair the OMTM with a counter-metric - [ ] Rebuild your dashboard cohorted and segmented, OMTM big, six supporting metrics max - [ ] Audit your five most-used interactions and add sub-100ms feedback plus missing edge-case states (Microinteractions) - [ ] Implement one or two signature moments that pass the removal test - [ ] Audit gamification against Autonomy, Mastery, and Purpose; fix autonomy violations (Drive Motivation) - [ ] Replace "if-then" rewards with "now-that" recognition reserved for meaningful milestones ## Common mistakes **Buying growth before fixing retention.** The single most expensive error at this stage is spending on acquisition while cohorts still decay. Lean Analytics is explicit: virality and paid acquisition poured into a product that doesn't retain just multiply churn. Pass the Stickiness gate — a flattening retention curve — before you open the acquisition spigot. **Relying on external triggers forever.** If thirty days in your users still need a push to return, you have a notification dependency, not a habit. Hooked UX is clear that the goal is migrating users to internal triggers. Notifications are scaffolding to bridge the gap until the emotional cue forms — not the load-bearing wall. **Optimizing the wrong link in the Ability Chain.** Teams celebrate shaving a step off onboarding when the real bottleneck was mental effort or non-routineness, so the metric doesn't budge. Rate all six factors and fix the *scarcest* resource, not the most obvious one. **Prompting below the Action Line.** Sending "We miss you!" to a user with neither the motivation nor the ability to act is spam, and it degrades every future notification. Prompt only on real events, anchored to existing routines. **Jumping from outcome straight to solution.** "Retention is low, let's add streaks" skips the entire opportunity space. Build the Opportunity Solution Tree first; the streak might be the worst of five options you never considered. **Testing the easy assumption instead of the risky one.** It feels productive to validate something, so teams test what's convenient and leave the fatal assumption untouched. Map by importance versus evidence and test the leap-of-faith assumption first. **Measuring outputs, not outcomes.** Stories-shipped and features-launched feel like progress and change nothing. Both Inspired and Lean UX insist that success is a change in user behavior. Instrument every release so you can tell. **Gamifying with points for everything.** The fastest way to kill the intrinsic motivation driving your power users is to slap extrinsic rewards on every action. Drive warns that "if-then" rewards crowd out the very engagement you're trying to grow. Reserve rewards for meaningful milestones and protect autonomy. **Polishing microinteractions before the loop works.** Delightful animations on a product nobody returns to is rearranging deck chairs. Sequence matters: loop and activation first, discovery and metrics to steer, and only then the micro-moment polish that turns "fine" into "loved." ## Frequently asked questions ### In what order should I actually use these eight skills? Follow the phases as written — they're sequenced deliberately. Start with Hooked UX and Improve Retention because the loop and activation are the bucket you're trying to seal. Layer in Continuous Discovery and Lean UX next so you're steering with evidence instead of opinion, and use Inspired to fix how the team decides what to build. Bring in Lean Analytics early in parallel as your instrument panel — you'll want the baseline before and after every change. Microinteractions and Drive Motivation come last not because they're optional but because their payoff depends on a loop that already works and metrics that can prove the lift. That said, the skills compose freely; if your problem is clearly a measurement problem, lead with Lean Analytics. ### Do I need a team, or can a solo founder do this? A solo founder can do all of it — that's part of the point of having an AI agent execute alongside you. Continuous Discovery and Inspired describe a "product trio," but the underlying habits scale down: you can run one story-based interview a week, keep a personal Opportunity Solution Tree, and write your own opportunity assessments. The agent fills the gaps in skill you don't have — drafting the interview snapshot template, implementing the microinteraction in your component, building the cohort view. Where a real team helps is in collaborative design studios and dividing discovery from delivery, but none of these skills require headcount to start. ### How is this different from just A/B testing everything? A/B testing is one experiment type, and an expensive, slow one best reserved for tuning a concept you already know works. The Lean UX point is to match fidelity to risk: when the question is "do users even understand this?", five users and a paper prototype answer it in an afternoon and uncover most usability problems, whereas a coded A/B test needs traffic and weeks. More fundamentally, testing without discovery means you're optimizing solutions you never validated were worth building. Continuous Discovery and Inspired make sure you're testing the *right* things; Lean UX and Lean Analytics make sure you test them cheaply and read the results honestly. ### Isn't building habit loops manipulative? It can be, and Hooked UX takes this seriously with the Manipulation Matrix — a two-by-two of whether the maker uses the product themselves and whether it genuinely improves the user's life. Aim to be a "Facilitator": you use it, and it helps. Drive Motivation is the ethical backstop for the whole stack — if your engagement depends on autonomy violations, loss-aversion streaks, or rewards that crowd out genuine interest, you're building a treadmill users will come to resent and abandon. The durable version of growth makes staying the better choice through real value, not artificial switching costs or manufactured anxiety. ### How long before I see results? The fastest wins are usually in activation and microinteractions — a friction audit that finds the real Ability Chain bottleneck, or sub-100ms feedback on a dead-feeling core action, can move numbers within a single cohort. Habit formation is slower by nature: Hooked UX uses the "5% rule" — a habit has formed when at least 5% of users show unprompted return — and that takes weeks of loop iteration to read. The discovery and metrics habits are investments that compound: the first weekly interview teaches you little, but twelve of them rewire your intuition about what to build. Set lines in the sand with realistic dates so you're judging each change against a pre-committed bar, not a moving one. ## Start growing your app today Pick the phase that matches your sharpest pain — leaky activation, a loop that doesn't loop, a dashboard nobody trusts — and install the skill that owns it. Each one packages a definitive book into something your agent can apply directly to your code, your funnel, and your copy, today. Install the full stack with `npx skills add wondelai/skills --all --global` (or add them one at a time, e.g. `npx skills add wondelai/skills/hooked-ux --global`), then tell your agent which one to use and point it at a real artifact — your onboarding flow, your retention cohort, your most-used screen. When you've sealed the bucket and you're ready to make the product itself sharper — performance, accessibility, the quality of the experience — read [How to Improve an Existing App with AI Skills](https://skills.wondel.ai/guides/improve-an-existing-app-with-ai-skills/). And if growth depends as much on the business around the app as the app itself, see [How to Grow an Existing Business with AI Skills](https://skills.wondel.ai/guides/grow-an-existing-business-with-ai-skills/). --- # From Vibe-Coded Prototype to Production-Ready Product > A hands-on engineering playbook for turning an AI-generated prototype into something you can ship and operate — tests, structure, resilience, and scale — using AI agent skills from Clean Code, Refactoring, Release It!, and more. By Michał Jaskólski · Published 2026-06-25 · Updated 2026-08-08 · 20 min read Canonical: https://skills.wondel.ai/guides/vibe-coded-prototype-to-production/ Skills used: clean-code, pragmatic-programmer, refactoring-patterns, working-with-legacy-code, software-design-philosophy, clean-architecture, release-it, system-design, ddia-systems **TL;DR:** You take a vibe-coded prototype to production in nine sequenced moves: pin current behavior with characterization tests, clean names and functions, apply named refactorings, draw a Clean Architecture boundary around the business rules, then harden integrations with Release It! stability patterns and fix the data layer with Designing Data-Intensive Applications — because data outlives code. - Never clean untested code: cover it with characterization tests first, so any unintended change announces itself as a red test, not a support ticket. - Never refactor and add a feature in the same commit — a purely structural commit makes every red test trivially diagnosable. - The software that passes QA is not the software that survives production: every outbound call needs a timeout, every critical dependency a circuit breaker. - Install the stack with npx skills add wondelai/skills --all --global and treat anything below 8/10 on the resilience and boundary scorers as a launch blocker. You have a thing that works. You described what you wanted, an AI agent generated a few thousand lines, and now there's a running app: it logs you in, it saves data, the demo lands. On your machine, it is real. The problem is that "works on my machine" and "production-ready" are separated by a gap most founders discover at the worst possible moment — when a paying customer's data gets corrupted, when a third-party API hangs and takes the whole app down with it, when a single popular user's query melts the database, or when you open the codebase to fix a bug and cannot find the bug because nothing is where it should be and there are zero tests to tell you whether your fix broke anything else. That gap is not a character flaw and it is not a sign your prototype was bad. Fast-generated code is *tactical* code: it optimized for getting something running, not for surviving contact with reality. The good news is that the move from prototype to product is a well-trodden path with a real engineering literature behind it — and the same AI agent that generated the prototype can walk that path with you if you point it at the right principles. That is what this guide does. The approach here is sequenced, not scattered. You will pin the current behavior so you can change code without fear, clean the worst of the names and functions, restructure the design so logic stops bleeding into the framework, draw an architecture boundary around your business rules, harden every integration point against failure, and finally make the data and scaling decisions that let the thing grow. Each phase is driven by a specific [skill](https://skills.wondel.ai/skills/) — a packaged framework from a canonical engineering book — that you install once and invoke by telling the agent to use it. The skills stack: [Working with Legacy Code](https://skills.wondel.ai/skills/working-with-legacy-code/) gives you the safety net, [Clean Code](https://skills.wondel.ai/skills/clean-code/) and [Refactoring](https://skills.wondel.ai/skills/refactoring-patterns/) clean the surface, [Software Design](https://skills.wondel.ai/skills/software-design-philosophy/) and [Clean Architecture](https://skills.wondel.ai/skills/clean-architecture/) fix the structure, [Pragmatic Programmer](https://skills.wondel.ai/skills/pragmatic-programmer/) sets the engineering habits that hold it all together, and [Release It!](https://skills.wondel.ai/skills/release-it/), [System Design](https://skills.wondel.ai/skills/system-design/), and [Data-Intensive Apps](https://skills.wondel.ai/skills/ddia-systems/) make it operable at scale. > A prototype proves the idea can work. A product proves it keeps working when you are asleep. One sequencing note before we start. Counterintuitively, the *first* skill you reach for is the legacy-code one — even though your code was written last week. The reason is the definition that skill runs on: legacy code is not old code, it is **code without tests**. Your week-old prototype has no tests, so it is legacy code, and every edit you make to it is a gamble until you change that. So we begin by stopping the gambling. ## Phase 1 — Build a safety net before you touch anything The very first instinct after the demo is to start cleaning. Resist it. If you rename a variable, extract a function, or "just fix this one thing" in untested code, you have no way to know whether you preserved behavior or quietly broke a path you weren't even looking at. The Working with Legacy Code skill exists to break this exact trap. Its core move is **cover and modify, never edit and pray**: get the code you're about to change into a test harness, pin down what it actually does right now, and only then change it. The skill's central technique is the [**characterization test**](https://www.informit.com/store/working-effectively-with-legacy-code-9780131177055) from Michael Feathers' book. This is not a test of what the code *should* do — it's a test of what the code *actually does*, quirks included. The recipe is mechanical and oddly liberating: call the code, assert something you know is wrong (`expect(total).toBe(-1)`), run it, read the failure message to learn the real output, then change the assertion to pin that real value. You are not judging the behavior, you are photographing it, so that later, when you refactor, any unintended change announces itself as a red test on your machine instead of as a support ticket. The obstacle you will hit immediately is that vibe-coded prototypes love to instantiate their dependencies inline — a route handler that does `new Database()` in its own body, a service whose constructor opens a connection and news-up a payment client. That code can't be tested because you can't substitute a fake for the real database. The skill's answer is **seams**: places where you can change behavior without editing in that place. The least-invasive seam is almost always **Parameterize Constructor** with a production default — `constructor(db = new ProdDb())` — so every existing caller keeps compiling untouched while your tests pass in a fake. For a single dangerous call buried in a method, **Extract and Override** that call so a test subclass can stub it. > **Prompt** — Use the `working-with-legacy-code` skill to get my most critical untested class under test before I change it: identify the seams where it constructs its own dependencies, parameterize the constructor with production defaults so existing callers still compile, and write characterization tests that pin the current behavior > (https://skills.wondel.ai/skills/working-with-legacy-code/) When the change you need to make is genuinely urgent and you cannot get the whole area under test in time, the skill gives you two escape hatches that keep the risk contained to a single line. **Sprout Method / Sprout Class**: write the new behavior as fresh, fully tested code and call it from one line in the untested host. **Wrap Method**: rename the old function aside (`rawPay`) and add your new behavior — logging, validation, a feature gate — in a new wrapper that calls it. Both leave the old behavior byte-for-byte intact and let you test the new code properly, at the honest cost of leaving the host untested for now. Track those as debt and cover them on the next touch. > **Prompt** — Use the `working-with-legacy-code` skill to add a new feature to a large untested function without rewriting it: use Sprout Class to put the new logic in a fully tested class, call it from a single line in the existing flow, and leave the rest of the function untouched for now > (https://skills.wondel.ai/skills/working-with-legacy-code/) By the end of this phase you do not have a clean codebase. You have something more valuable: a codebase whose current behavior is *pinned*, so that everything you do from here is verifiable. ## Phase 2 — Make the code readable, function by function Now that changes are safe, attack legibility — because you (and your agent) are about to read this code far more than you write it, and the read-to-write ratio is well over 10:1. This is the [Clean Code](https://skills.wondel.ai/skills/clean-code/) skill's home turf. Its core principle is that **code is read more often than written, so optimize for the reader**, and it scores code 0–10 against six disciplines: meaningful names, small single-purpose functions, comments that explain *why* not *what*, clean error handling, clean tests, and a catalog of smells. Start with names and functions, because that's where generated code is weakest. AI-generated prototypes are full of `data`, `result`, `handleStuff`, `temp2`, and 120-line functions that validate, transform, call an API, format a response, and log — all in one breath. Clean Code's rules are specific and enforceable: names reveal intent (`elapsedTimeInDays`, not `d`); booleans read as predicates (`isActive`, `hasPermission`); functions do one thing at one level of abstraction, ideally a handful of lines, with zero to two arguments; flag arguments are a smell because a function taking `render(isPrint)` is really two functions. Command-Query Separation matters here too: a function either changes state or returns a value, never both, so a name never hides a side effect. > **Prompt** — Use the `clean-code` skill to review the orders module and score it 0-10 on Clean Code: flag every name that hides intent, every function over 20 lines or doing more than one thing, every flag argument, and every place a function both mutates state and returns a value, then give me the top ten fixes in priority order > (https://skills.wondel.ai/skills/clean-code/) The second front is error handling, where prototypes are often genuinely dangerous. Generated code tends to either swallow everything in a bare `catch` that hides real bugs, or return `null` on failure so that null-checks metastasize across every caller and one missing check crashes far from the source. Clean Code's prescriptions: prefer exceptions to return codes so the happy path stays uncluttered; catch *specific* exceptions and let the rest propagate; never return or pass `null` — use an empty collection, an `Optional`, or a Null Object with safe default behavior; and put context in every error you throw (`Failed to save invoice #1234 for customer Acme`) so debugging starts with a fact, not a hunt. > **Prompt** — Use the `clean-code` skill to audit error handling across our API layer: find every bare catch that swallows exceptions, every function that returns null on failure, and every error thrown without context, then refactor them to throw specific exceptions with operation and state details and replace null returns with Optionals or empty collections > (https://skills.wondel.ai/skills/clean-code/) A crucial discipline from this skill, reinforced by every other skill in the stack: **never refactor and add a feature in the same step.** Wear one hat at a time. Clean for clarity, run the characterization tests from Phase 1, commit. Then, separately, change behavior. When a commit is purely structural, a red test can only mean you broke something — which makes the failure trivial to diagnose. Mixing the two makes every failure ambiguous. ## Phase 3 — Apply named refactorings to the structure Clean Code tells you *what good looks like*; the [Refactoring](https://skills.wondel.ai/skills/refactoring-patterns/) skill gives you the [*named, mechanical transformations*](https://martinfowler.com/books/refactoring.html) from Martin Fowler's catalog to get there without breaking behavior. The distinction matters: this skill is a catalog. Each code smell maps to a specific refactoring with known mechanics, so instead of vaguely "cleaning up," you say "this is Feature Envy" or "this is a Long Method" and apply the prescribed move. That precision is exactly what makes an AI agent effective here — it can name the smell, cite the transformation, and execute it in small steps. The single most important transformation is **Extract Method**, and it's the one your prototype needs most. The heuristic is beautiful in its simplicity: if you feel the urge to write a comment explaining what a block of code does, extract that block into a method and use the comment as its name. A 100-line generated function becomes a short, readable sequence of named steps — `validateInput()`, `applyDiscounts()`, `persistOrder()` — each of which you can now understand, test, and reuse. From there the catalog branches: **Replace Magic Number with Symbolic Constant** for the bare `5` and `86400` scattered everywhere; **Decompose Conditional** and **Replace Nested Conditional with Guard Clauses** for the pyramids of `if/else` that generated code produces; **Replace Conditional with Polymorphism** when you see a `switch` on a type code; **Introduce Parameter Object** when the same three or four arguments travel together through every function. > **Prompt** — Use the `refactoring-patterns` skill to refactor the processOrder function in our billing service using named refactorings: name each smell you find, then apply Extract Method to break it into readable steps, Replace Nested Conditional with Guard Clauses to flatten the validation pyramid, and Replace Magic Number with Symbolic Constant for the hardcoded limits, running tests after each single transformation > (https://skills.wondel.ai/skills/refactoring-patterns/) The skill is strict about workflow, and you should hold your agent to it: run tests (green), apply *one* small transformation, run tests (green), commit. If the tests go red, you **revert** — you do not debug a half-finished refactoring. Small steps make the cause of any failure obvious (it was the last thing you did) and reverting costs seconds. Two patterns from the catalog are especially useful when prototype code is tangled: **Preparatory Refactoring** ("make the change easy, then make the easy change" — clean the insertion point *before* you add a feature there) and the **Rule of Three** (tolerate a duplication once, notice it twice, extract it on the third occurrence, so you don't abstract prematurely). > **Prompt** — Use the `refactoring-patterns` skill to do a preparatory refactoring before I add subscription pricing alongside our one-time pricing: restructure the existing pricing code to make the new path easy to add, extract the duplicated tax-calculation logic that already appears in three places, and keep every step behavior-preserving with tests green between transformations > (https://skills.wondel.ai/skills/refactoring-patterns/) ## Phase 4 — Reduce complexity: deep modules, not more classes At this point the code is readable and locally well-structured, but you may have a subtler problem — one that AI agents, left unsupervised, actively create. Asked to "clean up" or "make it modular," an agent will often shatter a function into a dozen tiny classes and interfaces, proud of the apparent decomposition. The [Software Design](https://skills.wondel.ai/skills/software-design-philosophy/) skill, from Ousterhout's [*A Philosophy of Software Design*](https://web.stanford.edu/~ouster/cgi-bin/book.php), is the antidote. Its governing principle: **complexity is the enemy, and the goal is to minimize the complexity a module imposes on the rest of the system.** The skill's most important idea is **deep vs. shallow modules**. A module's depth is the functionality it provides divided by the complexity of its interface. A *deep* module hides significant machinery behind a simple interface — Unix file I/O is the canonical example: `open`, `read`, `write`, `close` conceal disk blocks, buffering, caching, and encoding. A *shallow* module has an interface nearly as complex as its implementation, so it adds cognitive load without hiding much. The disease of producing too many small shallow classes even has a name: **"classitis."** The fix is to *merge* related shallow classes into deeper ones — a `RequestParser` plus `RequestValidator` plus `RequestProcessor` that always run in sequence and share state probably want to be one `RequestHandler`. > **Prompt** — Use the `software-design-philosophy` skill to analyze the notifications module for classitis: identify which classes are shallow (interface almost as complex as the implementation), where information is leaking across module boundaries, and which pass-through methods add indirection without value, then propose how to consolidate them into deeper modules with simpler interfaces > (https://skills.wondel.ai/skills/software-design-philosophy/) The second big idea is **information hiding** and its inverse red flag, **information leakage** — when a single design decision (a date format, a wire protocol, a database assumption) is reflected in multiple modules, so changing it means editing all of them. A common cause in prototypes is **temporal decomposition**: organizing code by the order things happen ("first read the config, then validate it, then apply it") instead of by knowledge, which forces every phase to share the same details. The skill's guidance is to organize modules around *knowledge* — one module owns config, one owns serialization — so each hides a decision the others don't need to know. Finally, this skill reframes the whole prototype-to-product effort as a choice between **tactical and strategic programming**. Tactical programming ships features fast and accumulates complexity with every shortcut; strategic programming invests an extra 10–20% to keep the design clean and treats every change as a chance to improve structure. Your prototype is the output of pure tactical programming. The point of this guide is to flip the mode — and the skill is emphatic that *startups need this most*, because early shortcuts compound into crippling debt exactly as the team and the codebase grow. ## Phase 5 — Draw the architecture boundary around your business rules Your modules are now deep and your functions clean, but there's a structural question that determines whether this product is a joy or a nightmare to evolve: **does your business logic depend on your framework and database, or do they depend on it?** In a vibe-coded prototype the answer is almost always backwards. Business rules live inside route handlers, ORM models *are* the domain objects, and pricing logic is interleaved with SQL. The [Clean Architecture](https://skills.wondel.ai/skills/clean-architecture/) skill fixes this with one rule. That rule is **the Dependency Rule: source code dependencies point inward**, toward higher-level policy. Picture concentric circles — Entities (enterprise business rules) at the center, then Use Cases (application-specific rules), then Interface Adapters (controllers, presenters, gateways), with Frameworks and Drivers (the web framework, the ORM, the message queue) on the outside. Nothing in an inner circle may name anything in an outer one. The database is a *detail*. The web is a *detail*. They are plugins to your business rules, not the skeleton of your application. The mechanism that enforces this is **Dependency Inversion**: a Use Case defines a `UserRepository` *interface*, and a `PostgresUserRepository` in the outer adapter layer *implements* it — so the business logic depends on an abstraction it owns, and Postgres depends on that abstraction, never the reverse. > **Prompt** — Use the `clean-architecture` skill to map the dependency graph of our Express app and find every violation of the Dependency Rule where business logic imports the ORM or the framework, then show me how to extract our order pricing rules into framework-free Use Cases that depend on repository interfaces, with the Prisma implementation moved out to an adapter layer > (https://skills.wondel.ai/skills/clean-architecture/) The practical payoff is enormous and immediate: once the boundary exists, you can test your business rules with no database, no web server, and no framework running — which makes the tests from Phase 1 fast and trustworthy — and you can swap Postgres for DynamoDB, or Express for Fastify, as a localized change instead of a rewrite. This skill pairs the Dependency Rule with the **SOLID** principles as its mid-level building blocks: Single Responsibility (a module has one reason to change because it serves one actor), Open-Closed (extend by adding code, not modifying existing code), and especially Dependency Inversion, which is how the boundary gets built in practice. > **Prompt** — Use the `clean-architecture` skill to apply Dependency Inversion to our PaymentService, which talks directly to the Stripe SDK throughout the codebase: define a PaymentGateway interface owned by our business layer, wrap Stripe behind a StripeGateway adapter that implements it, and wire the concrete choice in our composition root so we could swap to Braintree without touching business logic > (https://skills.wondel.ai/skills/clean-architecture/) A warning the skill is loud about, because it's a trap founders fall into: do not assume that splitting into microservices gives you good architecture for free. A set of services sharing one fat data model is just a **distributed monolith** — a monolith with network calls between its modules, which is strictly worse than a clean monolith. Apply the Dependency Rule *within* your service first. Services are deployment boundaries, not automatically architectural ones. ## Phase 6 — Lock in the engineering habits that keep it clean Architecture decays without discipline, and discipline is a set of habits. The [Pragmatic Programmer](https://skills.wondel.ai/skills/pragmatic-programmer/) skill supplies the meta-principles that hold every other phase together — it's less about any single line of code and more about *how to think* so the codebase stays easy to change, understand, and trust. Four of its principles matter most in the prototype-to-product transition. **DRY (Don't Repeat Yourself)** — but the skill is precise where most people are sloppy: DRY is about *knowledge*, not text. Two identical-looking blocks that encode *different* business rules are not duplication, and DRY-ing them couples concepts that should stay independent. The duplication that hurts is duplicated knowledge: the same validation rule in the client and the server, the same tax logic in three handlers. **Orthogonality**: components are orthogonal if changing one doesn't affect another — change the auth provider and billing shouldn't care — which is the design value the Clean Architecture boundary buys you. **The Broken Window Theory**: one unrepaired hack signals that nobody's minding the quality, and the threshold for the next hack drops to zero; fix problems immediately or "board them up" with a tracked ticket, never an untracked `// TODO: fix later`. And **reversibility**: abstract third-party vendors behind your own interfaces so no decision is permanent — the same move the architecture phase made for Stripe and Postgres. > **Prompt** — Use the `pragmatic-programmer` skill to audit our codebase for the kinds of duplicated knowledge that cause bugs (validation rules repeated on client and server, the same business calculation in multiple places) while ignoring coincidental code that merely looks similar, and flag any broken windows like untracked TODOs or quick hacks that need boarding up with a ticket > (https://skills.wondel.ai/skills/pragmatic-programmer/) This skill is also where you set up the **tracer bullet** habit for everything you build *after* the prototype. A tracer bullet is a thin but real end-to-end slice — UI to API to database to response — that you keep, as opposed to a prototype you throw away. Building the thinnest complete path first surfaces integration problems early and gives you a skeleton to flesh out, instead of building each layer in isolation and discovering at the end that they don't fit. For your next feature, that's the move: one real vertical slice, then expand. ## Phase 7 — Make it survive production: stability patterns Everything so far has made the code *good*. This phase makes it *survivable*, and it's the one prototypes ignore most completely. The [Release It!](https://skills.wondel.ai/skills/release-it/) skill opens with a sentence worth memorizing: **the software that passes QA is not the software that survives production.** Production is hostile. Its governing principle is that every system will eventually be pushed past its limits, and the only question is whether it degrades gracefully or collapses. The skill catalogs **stability anti-patterns**, and the number-one killer is **integration points** — every socket, HTTP call, and queue your prototype touches. The specific failure that destroys vibe-coded apps is that they call third-party APIs with *no timeout*. When that API slows down (not even fails — just slows), your request threads block waiting, the thread pool exhausts, and your entire app stops responding to *everyone*, because of a dependency you don't even control. The skill is blunt: **a slow response is worse than no response**, because it ties up resources and propagates delay up the whole call chain. Against each anti-pattern stands a **stability pattern**. **Timeouts** on every outbound call — connect *and* read — are non-negotiable. The **Circuit Breaker** wraps a failing dependency: after a threshold of failures it "trips" open and fails fast instead of waiting, then periodically tests recovery in a half-open state — a tripped breaker is the system working *correctly*, protecting itself. **Bulkheads** isolate resource pools so one drowning dependency can't drain the threads the rest of the app needs (a dedicated connection pool for the payment gateway, separate from search). **Retry with exponential backoff and jitter** so a recovering service isn't immediately flattened by a synchronized thundering herd. And **Steady State** — prototypes accumulate cruft (sessions, logs, temp files) until a disk fills at 3 a.m.; design the cleanup in from the start. > **Prompt** — Use the `release-it` skill to audit every outbound call in our app for stability: find external API calls and database queries with no timeout, add connect and read timeouts to all of them, wrap our payment and email provider calls in circuit breakers that trip after five failures in sixty seconds, and isolate their connection pools with bulkheads so one slow dependency cannot freeze the whole service > (https://skills.wondel.ai/skills/release-it/) Two more areas from this skill turn a prototype into something operable. **Deployment and release**: decouple *deploying* code from *releasing* it to users via feature flags, so you can ship dark, enable for 10%, and roll back a release in seconds without redeploying; make database migrations backward-compatible (expand-contract) so old and new code can run simultaneously during a rolling deploy. And **observability**, which prototypes have essentially none of: you cannot operate what you cannot see. Add **deep health checks** (the `/health` endpoint verifies the database, cache, and queue are reachable, not just that the process is alive), instrument the **RED metrics** for each endpoint (Rate, Errors, Duration), and **alert on symptoms users actually feel** — error rate and latency — not on causes like CPU. > **Prompt** — Use the `release-it` skill to add production observability to our service: implement a deep health check endpoint that verifies the database, Redis, and queue are reachable, instrument RED metrics (request rate, error rate, p50/p95/p99 latency) per endpoint, and design alerts that fire on user-facing symptoms like error rate above one percent rather than on CPU > (https://skills.wondel.ai/skills/release-it/) ## Phase 8 — Design for the scale you actually have (and the scale you'll reach) Resilient code can still fall over under load if the system around it was never sized. The [System Design](https://skills.wondel.ai/skills/system-design/) skill brings structured thinking to scaling, and its first principle is a corrective to how prototypes grow: **start with requirements, not solutions.** Before adding a cache or a queue or a second database, write down the numbers — daily active users, queries per second, storage growth, the latency and availability you're promising. Premature scaling machinery is as harmful as missing it. The skill's most immediately useful tool is **back-of-the-envelope estimation**: a two-minute calculation that prevents both over-provisioning and 3 a.m. outages. QPS is daily-active-users × actions-per-day ÷ 86,400 seconds, with peak typically 2–5× the average. Storage is records-per-day × record-size × retention. These order-of-magnitude numbers tell you which component bottlenecks first and roughly when — so you scale deliberately instead of reactively. From there the skill assembles systems from a standard toolkit of **building blocks** introduced *when the estimates justify them*: a CDN for static assets, a cache (cache-aside Redis with a defined TTL and explicit invalidation on writes) in front of read-heavy queries, a **message queue** to decouple slow work from the request path and absorb spikes (enqueue the image resize or the email send; let workers pull at their own pace), and read replicas before you ever consider sharding. > **Prompt** — Use the `system-design` skill to do back-of-the-envelope estimation for our app at 50k daily active users and tell me which component bottlenecks first: calculate average and peak QPS and yearly storage growth, then recommend in priority order where to add a cache, where to move slow work behind a message queue, and at what point we will need read replicas — without over-engineering for scale we do not have yet > (https://skills.wondel.ai/skills/system-design/) The skill is opinionated about the order of scaling moves, and it maps cleanly onto a maturing prototype: scale *vertically* first (a bigger box is simple), then add a *cache* for read-heavy paths, then *read replicas* for the database, and only *shard* as a last resort because of its operational complexity. It also gives you a library of common designs — rate limiter, news feed, notification system — so when you need to protect your API you reach for a known token-bucket pattern returning `429 Retry-After` at the gateway, rather than inventing one. ## Phase 9 — Get the data layer right, because data outlives code The last phase is the one with the longest shadow. The [Data-Intensive Apps](https://skills.wondel.ai/skills/ddia-systems/) skill, from Kleppmann's [*Designing Data-Intensive Applications*](https://dataintensive.net/), runs on a principle that should reframe every database decision you make: **data outlives code.** You will rewrite the application and swap frameworks several times, but the data persists for years — so the correctness, durability, and evolvability of the data layer deserve more care than anything else in the stack. A prototype that chose its database by familiarity ("it's what the agent generated") is carrying a decision it never actually made. Two of the skill's domains will bite a growing product first. **Transactions and isolation**: most databases do *not* default to serializable isolation — they default to read committed or snapshot isolation — which permits anomalies your prototype's naive code will trigger under concurrency. The classic is **write skew**: two transactions read the same data, each decides independently, and each writes a different row, with no single-row lock to stop them — think two requests both reading "inventory is 1" and both selling the last item. The fix is explicit (`SELECT ... FOR UPDATE` to take a lock, or a genuinely serializable transaction for a balance transfer), and the skill insists you *know your database's actual default* rather than assume safety. **Replication lag**: the moment you add the read replicas that System Design recommended, asynchronous replication means a user can write data and then read a stale replica that doesn't have it yet — so you implement read-your-writes and monotonic-read guarantees deliberately, not by hoping. > **Prompt** — Use the `ddia-systems` skill to review our database access for concurrency bugs our prototype will hit under real load: find places vulnerable to write skew like inventory decrements and balance updates that read-then-write without a lock, tell me our database's actual default isolation level and the anomalies it permits, and fix the risky paths with SELECT FOR UPDATE or a serializable transaction > (https://skills.wondel.ai/skills/ddia-systems/) The skill also gives you the vocabulary to choose datastores by *requirements* instead of habit, and to decouple them. Match the **data model** to the access pattern — relational for many-to-many and ad-hoc queries, document for self-contained aggregates, graph for relationship traversal — and recognize that **polyglot persistence** (different stores for different workloads) is often correct rather than a failure. Understand the **storage engine** trade-off: LSM-trees (Cassandra, RocksDB) for very high write throughput, B-trees (Postgres) for balanced read/write OLTP, columnar (ClickHouse) for analytics. And when you outgrow a single hot path, separate the **system of record from derived data** with change data capture or event sourcing, so a search index or a cache is something you can rebuild from the source of truth rather than a fragile second master. > **Prompt** — Use the `ddia-systems` skill to evaluate whether to stay single-database or go polyglot before we add full-text search and an activity feed to our Postgres-only app: assess each workload (relational profiles, write-heavy time-series feed, search across millions of documents) against data model fit and storage-engine characteristics, and if we add a search index show me how to keep it in sync with change data capture instead of dual writes > (https://skills.wondel.ai/skills/ddia-systems/) ## Your checklist - [ ] Treat the prototype as legacy code: write **characterization tests** that pin current behavior before changing anything. - [ ] Break dependencies with the **least-invasive seam** — Parameterize Constructor with a production default — so tests can inject fakes. - [ ] Use **Sprout/Wrap** to add urgent behavior safely when full coverage isn't possible yet, and track the untested host as debt. - [ ] Rename for intent; **Extract Method** every long function into named, single-purpose steps. - [ ] Replace swallowed exceptions and `null` returns with **specific exceptions, Optionals, and contextful error messages**. - [ ] Apply named refactorings one at a time, **tests green between each step**; revert (never debug) a red refactoring. - [ ] **Never refactor and change behavior in the same commit** — one hat at a time. - [ ] Merge shallow classes into **deep modules**; kill classitis and information leakage. - [ ] Enforce the **Dependency Rule**: business rules depend on interfaces they own, not on the framework or ORM. - [ ] Wrap every third-party vendor behind **your own interface** for reversibility. - [ ] Put a **timeout on every outbound call**; add **circuit breakers** and **bulkheads** on integration points. - [ ] Add **deep health checks**, **RED metrics**, and **symptom-based alerts** before launch. - [ ] Decouple deploy from release with **feature flags**; make migrations **backward-compatible**. - [ ] Do **back-of-the-envelope estimation** before adding scaling machinery; cache and queue only when numbers justify it. - [ ] Know your database's **actual isolation level**; fix **write skew** and **replication-lag** reads explicitly. ## Common mistakes **Cleaning up before writing a single test.** This is the cardinal sin and the reason this guide starts with the legacy-code skill. Renaming and extracting in untested code feels productive and is actually gambling — you cannot know you preserved behavior. Pin behavior first, *then* clean. **Letting the agent "modularize" into a swarm of tiny classes.** Ask an AI agent to make code modular and it will happily create fifteen shallow classes and call it architecture. That's classitis, and it raises complexity. The Software Design skill's deep-module principle is the corrective: hide real machinery behind simple interfaces; merge shallow classes that always travel together. **Refactoring and adding a feature in one commit.** When the commit does both, a failing test can't tell you which change broke things, and code review can't separate the structural diff from the behavioral one. Split every such change into a structure-only commit (tests stay green) and a behavior-only commit. **Calling external APIs with no timeout.** The most common cause of total prototype outages. A dependency doesn't have to fail to take you down — it only has to get slow while your threads block on it. Connect-and-read timeouts on every outbound call, plus a circuit breaker, are table stakes. **Scaling before you've sized anything.** Adding Kafka, sharding the database, and standing up five services because the prototype "needs to scale" is over-engineering that buys complexity you can't yet operate. Estimate first; the numbers usually say a cache and a read replica are years of runway. **Mistaking microservices for architecture.** Splitting a tangled prototype into services that share one database gives you a distributed monolith — all the coupling, plus network latency and partial failure. Apply the Dependency Rule *inside* the service before you split anything. **Assuming your database is serializable.** It almost certainly isn't by default. Code that reads-then-writes without a lock will corrupt data under concurrency through write skew, and it'll pass every single-user test you run. Check the actual default and lock the paths that need it. ## Frequently asked questions ### In what order should I install and apply these skills? Follow the phase order in this guide, which is deliberately not the order the books were written. Start with `working-with-legacy-code` because untested prototype code is legacy code and you need a safety net before anything else. Then `clean-code` and `refactoring-patterns` for surface legibility, `software-design-philosophy` and `clean-architecture` for structure, `pragmatic-programmer` to set durable habits, and finally `release-it`, `system-design`, and `ddia-systems` for resilience and scale. You don't have to do all nine before shipping — getting through Phase 3 (tested, readable, well-refactored) already puts you ahead of most prototypes, and Phases 7–9 can follow once you have real traffic. Install them all in one go with `npx skills add wondelai/skills --all --global` and pull each into a session as you reach its phase. ### Do I really need to write tests for AI-generated code I can just regenerate? Yes, and the regeneration argument is exactly why. The moment real users have data in your system, "just regenerate it" stops being an option — a regenerated module that behaves *slightly* differently can corrupt or lose customer data, and you'd have no test to catch the difference. Characterization tests are cheap insurance: they pin what the code does today so that any future change, whether you write it or an agent does, surfaces unintended behavior changes immediately. Tests are also what make the Clean Architecture boundary worth building — fast, framework-free tests on your business rules are only possible once that boundary exists. ### How do I keep my AI agent from over-engineering when it "improves" the code? Two guardrails. First, name the principle that fights over-engineering and put it in the prompt: the Software Design skill's deep-module / anti-classitis guidance, and the Pragmatic Programmer skill's YAGNI stance (don't build flexibility you have no evidence you need yet). Ask the agent to *reduce* the number of interfaces and merge shallow classes, not multiply them. Second, demand the small-step refactoring workflow — tests green between every transformation — which structurally prevents the agent from doing a sweeping rewrite under the banner of "cleanup." If a change can't be expressed as a sequence of named, behavior-preserving refactorings, that's a signal it's a rewrite in disguise. ### When is my prototype actually "production-ready"? Use a concrete bar drawn from the skills: your business rules have tests that run without a database or framework; every outbound call has a timeout and critical dependencies have circuit breakers; you have a deep health check and RED metrics wired to symptom-based alerts; you can deploy without downtime and roll back a release in under a minute; and you know your database's isolation level and have locked the read-then-write paths. The Release It! and Clean Architecture skills both score 0–10 against their principles — run those scorers on your codebase and treat anything below an 8 on the resilience and boundary dimensions as a launch blocker. "It works in the demo" is not on this list, because the demo was never the hard part. ### Should I do all of this before launching, or can I ship and harden in parallel? Ship earlier than you think, but in a specific order. Phases 1–3 (safety net, readability, refactoring) should be largely done before real users arrive, because they're cheapest now and they protect the data you're about to start collecting. The architecture boundary in Phase 5 pays off most when you do it before the codebase doubles again — retrofitting it later is real work. But the scale-oriented phases (8 and 9) are explicitly *requirements-driven*: don't build for 50K users while you have 50. The System Design skill's first principle — start with requirements, not solutions — applies to your own roadmap. Harden the resilience patterns in Phase 7 before launch (timeouts and a circuit breaker are not optional even at low traffic), and let the scaling work track your actual growth numbers. ## Start with the safety net The fastest way from "works on my machine" to a product you can operate is not a heroic rewrite — it's a sequence of small, verifiable moves, each backed by a framework that thousands of engineers have already proven. The skills in this stack turn that literature into something your AI agent can apply directly to *your* code. Install the whole stack with a single command: ``` npx skills add wondelai/skills --all --global ``` Then open your prototype and start at Phase 1: tell your agent to use the `working-with-legacy-code` skill to pin your current behavior with characterization tests. Once the net is in place, every other phase becomes safe. When you're ready to think bigger than incremental hardening, read the companion guides next: [Refactor a Codebase Buried in Technical Debt](https://skills.wondel.ai/guides/refactor-a-codebase-buried-in-technical-debt/) goes deeper on the refactoring and legacy-code workflow, and [Design the Best Architecture for a New App](https://skills.wondel.ai/guides/design-the-best-architecture-for-a-new-app/) shows how to get the structure right from the first line so your *next* project never becomes a prototype you have to rescue. --- # How to Refactor a Codebase Buried in Technical Debt > A safe, incremental plan for taming a legacy codebase — characterization tests, seams, named refactorings, and boundaries — using AI agent skills from Working Effectively with Legacy Code, Refactoring, Clean Architecture, and more. By Michał Jaskólski · Published 2026-06-25 · Updated 2026-08-08 · 18 min read Canonical: https://skills.wondel.ai/guides/refactor-a-codebase-buried-in-technical-debt/ Skills used: working-with-legacy-code, refactoring-patterns, clean-code, software-design-philosophy, clean-architecture, pragmatic-programmer, release-it, domain-driven-design **TL;DR:** You refactor a debt-buried codebase in place, never through a big-bang rewrite: pin behavior with characterization tests where you need to change code, apply Fowler's named refactorings in small verified steps, deepen modules with A Philosophy of Software Design, invert dependencies with Clean Architecture, then lock in Pragmatic Programmer habits so the debt never re-accumulates. - The big-bang rewrite is the most reliable way to turn a struggling-but-shipping product into a struggling-and-not-shipping one — refactor in place instead. - Legacy code is simply code without tests: cover and modify, never edit and pray. - Name the smell, cite the transformation: a catalog beats vague cleanup, for humans and AI agents alike. - Install the stack with npx skills add wondelai/skills --all --global and fix broken windows immediately — one tolerated hack resets the team's quality threshold to zero. You inherited it, or you wrote it three years ago, or it accreted while the company chased product-market fit — and now there is a codebase that everyone is afraid of. It has hundreds of thousands of lines, a handful of files that no one will open without a deep breath, a test suite that is either absent or so flaky that the team disabled it in CI, and a folklore of "don't touch the billing code, it works and we don't know why." Every estimate has a tech-debt tax baked in. Every new feature takes longer than the last. Onboarding a new engineer takes months because the only documentation is the code, and the code lies. The instinct, voiced in every such team eventually, is to rewrite it. Stop. The big-bang rewrite is the single most reliable way to turn a struggling-but-shipping product into a struggling-and-not-shipping one. The old system keeps moving while you rebuild — bugs get fixed, edge cases get handled, customers get onboarded onto behavior you don't even know exists — and the rewrite ships late, missing years of accumulated edge cases, having burned the runway you needed to actually fix things. This guide is the alternative: a sequenced, incremental plan to pay down technical debt *in place*, without ever stopping the world, where the worst-case blast radius of any single step is small and reversible. The core idea threaded through every phase is feedback over fear. Right now you change code and pray, because you have no way to know whether an edit preserved behavior. We will replace that with a discipline where the codebase tells you, on your own machine, the moment you break something. Then we clean what we can safely reach, reduce the complexity that makes the system hard to hold in your head, and carve durable boundaries so that the next change touches one place instead of fifteen. Each phase is driven by one [skill](https://skills.wondel.ai/skills/) — a packaged framework from a canonical engineering book that your AI agent applies directly to your code. You install the stack once with `npx skills add wondelai/skills --all --global` and pull each skill into a session as you reach its phase. > You do not pay down a mountain of debt by stopping to rebuild the mountain. You pay it down one safe, tested step at a time, along the paths you actually walk. The stack, in the order you will use it: [Working with Legacy Code](https://skills.wondel.ai/skills/working-with-legacy-code/) gives you the safety net and the comprehension tools to know where to even start. [Refactoring](https://skills.wondel.ai/skills/refactoring-patterns/) supplies the named, mechanical transformations to restructure safely. [Clean Code](https://skills.wondel.ai/skills/clean-code/) raises the legibility of what you touch. [Software Design](https://skills.wondel.ai/skills/software-design-philosophy/) attacks the complexity itself. [Clean Architecture](https://skills.wondel.ai/skills/clean-architecture/) draws the dependency boundaries that stop the rot. [Pragmatic Programmer](https://skills.wondel.ai/skills/pragmatic-programmer/) sets the habits that keep debt from re-accumulating. [Release It!](https://skills.wondel.ai/skills/release-it/) hardens the integration points that take legacy systems down in production. And [Domain-Driven Design](https://skills.wondel.ai/skills/domain-driven-design/) gives you the strategy to carve the big ball of mud into bounded contexts you can eventually extract. If you are rescuing a freshly AI-generated prototype rather than an aging system, the companion guide [From Vibe-Coded Prototype to Production-Ready Product](https://skills.wondel.ai/guides/vibe-coded-prototype-to-production/) covers that narrower case; this guide is about the large, old, tangled codebase where the central problem is scale and comprehension, not just polish. ## Phase 1 — Build a safety net and find where to start Before any cleanup, two questions dominate: how do I change anything without breaking it, and where in this enormous codebase do I even begin? The Working with Legacy Code skill, built on [Michael Feathers' book](https://www.informit.com/store/working-effectively-with-legacy-code-9780131177055), answers both. Its foundational redefinition reframes the whole problem: **legacy code is simply code without tests.** Not old code, not ugly code — *untested* code, because without tests you cannot know whether a change preserves behavior, so every edit is a gamble. The craft is to get tests in place *before* changing anything: **cover and modify, never edit and pray.** The skill's spine is the **Legacy Code Change Algorithm**, a fixed sequence you run for every change: identify the change points, find the test points, break dependencies, write characterization tests, then make the change and refactor. Notice that the actual edit happens *last*, inside a safety net you built first. The central technique for building that net is the **characterization test** — a test not of what the code *should* do but of what it *actually does* right now, quirks and bugs included. The recipe is mechanical: call the code in a harness, assert something you know is wrong (`expect(total).toBe(-1)`), run it, read the failure message to learn the real behavior, then change the assertion to pin that real value. You are photographing existing behavior, not judging it, so that later any unintended change shows up as a red test. But in a large codebase, before you can write that test you have to understand a region you don't understand — and that is the actual bottleneck, not typing. This skill is unusually strong here. **Effect sketches** trace what a change can affect: a bubble per variable or method, an arrow per "affects," traced forward from your change point until you have a finite list of everywhere behavior can leak out — turning "what could this break?" from free-floating anxiety into a bounded answer. **Pinch points** are narrowings in that sketch where a handful of tests cover a wide swath of behavior; find one and you can pin an entire cluster cheaply. **Scratch refactoring** is refactoring recklessly on a throwaway branch purely to *learn* the code, then reverting — the understanding survives the `git checkout`. And **feature sketches** reveal how methods and fields cluster inside a god class, showing you where a hidden class boundary wants to be drawn. > **Prompt** — Use the `working-with-legacy-code` skill to help me understand the scariest class in our codebase before I touch it: draw an effect sketch from its most-called method outward to find every place its changes can leak, identify pinch points where a few tests would cover the most behavior, and tell me the smallest set of characterization tests that would let me safely change its core logic > (https://skills.wondel.ai/skills/working-with-legacy-code/) The obstacle you hit the instant you try to write a test is that legacy classes resist instantiation: the constructor opens a real database connection, a singleton is consulted three calls deep, a static `Billing.charge()` is wired in everywhere. The skill's answer is **seams** — places where you can alter behavior without editing in that place — and a catalog of **dependency-breaking techniques** to create them. The rule is to use the *least invasive* technique that unblocks you, because these edits happen before tests exist. The workhorse is **Parameterize Constructor** with a production default (`def __init__(self, conn=None): self.conn = conn or connect()`), so every existing caller keeps compiling untouched while tests inject a fake. **Extract Interface** is the safest move in the book — introducing an interface cannot change behavior, only loosen a type. For pervasive statics and singletons, **Introduce Instance Delegator** hands callers an instance they can swap. > **Prompt** — Use the `working-with-legacy-code` skill to get our OrderProcessor under test: its constructor news up a Postgres pool, a Redis client, and a static EmailService, which makes it impossible to instantiate in a test, so identify the seams and break those dependencies with the least invasive techniques (Parameterize Constructor with production defaults, Extract Interface for the email static) so I can write characterization tests without changing behavior for existing callers > (https://skills.wondel.ai/skills/working-with-legacy-code/) When a change is genuinely urgent and you cannot get the surrounding area under test in time, the skill gives you two contained escape hatches. **Sprout Method / Sprout Class**: write the new behavior as fresh, fully tested code and call it from a single line in the untested host. **Wrap Method**: rename the old function aside (`rawPay`) and add behavior — logging, a feature gate, an audit hook — in a new wrapper that calls it, decorator-style. Both leave existing behavior byte-for-byte intact and let you test the new code, at the honest cost of leaving the host untested. The skill is firm that this is a *tactical* move: track every sprout as debt and cover the host the next time a change lands there. > **Prompt** — Use the `working-with-legacy-code` skill to add a new calculation to a large untested legacy function that we cannot get fully under test in time: use Sprout Class to put the new logic in a fully tested class, call it from one line in the existing code, and leave the rest untouched, then list what we should characterize next time we touch this file > (https://skills.wondel.ai/skills/working-with-legacy-code/) By the end of this phase you have not cleaned anything. You have something more valuable: along the paths you are about to change, the current behavior is *pinned*, and you have a map of where the change can reach. Everything from here is verifiable. ## Phase 2 — Restructure with named refactorings, one safe step at a time With behavior pinned at your change points, you can start improving structure — and the Refactoring skill, from [Martin Fowler's catalog](https://martinfowler.com/books/refactoring.html), is how you do it without breaking things. Its defining principle separates it cleanly from the rewrite you are avoiding: **refactoring is not rewriting; it is a sequence of small, behavior-preserving transformations, each backed by tests.** You never change *what* the code does, only *how* it is organized. The catalog is the point — each **code smell** maps to a specific named **refactoring** with known mechanics, so instead of vaguely "cleaning up," you say "this is Feature Envy" or "this is a Long Method" and apply the prescribed move. That precision is exactly what makes an AI agent reliable here: it can name the smell, cite the transformation, and execute it in disciplined small steps. In a debt-laden codebase the smells cluster predictably. **Long Method** is the most common and **Duplicate Code** the most expensive. You will see god classes with a dozen responsibilities (**Large Class**, **Divergent Change**), the same business rule copy-pasted across modules, **Primitive Obsession** where raw strings and ints stand in for domain concepts, and **Shotgun Surgery** where one logical change forces edits across many files. The single most important transformation is **Extract Method**, and the heuristic is elegant: if you feel the urge to write a comment explaining what a block does, extract that block into a method and use the comment as its name. A 300-line method becomes a readable sequence of named steps. From there the catalog branches: **Replace Magic Number with Symbolic Constant**; **Decompose Conditional** and **Replace Nested Conditional with Guard Clauses** for the pyramids of `if/else`; **Replace Conditional with Polymorphism** for `switch` statements on a type code; **Introduce Parameter Object** when the same cluster of arguments travels everywhere; **Extract Class** to split a god class along its axis of change. > **Prompt** — Use the `refactoring-patterns` skill to refactor the 600-line settleAccount method in our payments module using named refactorings: name each smell first, then apply Extract Method to break it into intention-revealing steps, Replace Nested Conditional with Guard Clauses to flatten the validation, and Replace Conditional with Polymorphism for the switch on account type, running the characterization tests after every single transformation > (https://skills.wondel.ai/skills/refactoring-patterns/) The skill is strict about the workflow, and you should hold your agent to it mechanically: run tests (green), apply *one* small transformation, run tests (green), commit. If the tests go red, you **revert** — you do not debug a half-finished refactoring. Small steps make any failure obviously attributable to the last thing you did, and reverting costs seconds; debugging a tangled multi-change refactoring costs days. Three workflow patterns are especially powerful against entrenched debt. **Preparatory Refactoring** — "make the change easy, then make the easy change" — means you clean the insertion point *before* adding a feature there, which is how you stop debt from compounding with every story. The **Rule of Three** keeps you from abstracting prematurely: tolerate a duplication once, notice it twice, extract on the third occurrence. And **Branch by Abstraction** lets you perform a large structural migration gradually in production: introduce an abstraction over the thing you want to replace, migrate callers behind it one at a time, then remove the old path — no long-lived feature branch, no big-bang merge. > **Prompt** — Use the `refactoring-patterns` skill to replace our hand-rolled date-handling utilities with a proper library across the codebase using Branch by Abstraction: introduce an interface that wraps our current date logic, migrate call sites to it incrementally with tests green at each step, swap in the new implementation behind the interface, and then remove the old utilities once nothing depends on them > (https://skills.wondel.ai/skills/refactoring-patterns/) A discipline this skill shares with the legacy-code skill and that is non-negotiable in debt work: **never refactor and change behavior in the same commit.** Wear one hat at a time. A structure-only commit that turns a test red can only mean you broke something mechanically, which makes the failure trivial to find. Mixing structural and behavioral change makes every failure ambiguous and every code review twice as hard. ## Phase 3 — Raise legibility where you touch the code Refactoring gives you the transformations; the Clean Code skill, from [Robert C. Martin's book](https://www.informit.com/store/clean-code-a-handbook-of-agile-software-craftsmanship-9780132350884), tells you *what good looks like* at the level of names, functions, and error handling. Its core principle is the one that justifies the whole effort: **code is read far more often than it is written — the ratio is well over 10:1 — so optimize for the reader.** In a codebase the team is afraid of, illegibility *is* the debt as much as bad structure is; every cryptic name is a tax paid by every future reader, human or agent. The skill scores code 0–10 across six disciplines and tells you the specific moves to climb the scale, which makes it ideal as a review lens for the team. The two fronts that pay off fastest in legacy code are naming and functions. Legacy systems are dense with `data`, `tmp`, `mgr`, `processData2`, and functions that validate, transform, persist, and notify all in one breath. Clean Code's rules are specific and enforceable: names reveal intent (`elapsedTimeInDays`, not `d`); booleans read as predicates (`isActive`, `hasPermission`, `canEdit`); one word per concept (don't mix `fetch`, `retrieve`, and `get` for the same idea); classes are nouns, methods are verbs; longer scope earns a longer, more descriptive name. Functions should do one thing at one level of abstraction, take zero to two arguments ideally, and never use a **flag argument** (a function taking `render(isPrint)` is really two functions). **Command-Query Separation** matters acutely in old code: a function either changes state or returns a value, never both, so a name can never hide a side effect that bites a caller later. > **Prompt** — Use the `clean-code` skill to review our user-management module and score it 0-10 on Clean Code: flag every name that hides intent, every function over twenty lines or doing more than one thing, every flag argument, and every function that both mutates state and returns a value, then give me the top ten fixes in priority order so I can apply them as behavior-preserving refactorings > (https://skills.wondel.ai/skills/clean-code/) The second front is error handling, which in long-lived systems is often genuinely dangerous and is where production incidents hide. Legacy code tends to swallow exceptions in bare `catch` blocks that hide real bugs, or return `null` on failure so null-checks metastasize across every caller and one missing check crashes far from the source. Clean Code's prescriptions: prefer exceptions to return codes so the happy path stays uncluttered; catch *specific* exceptions and let the rest propagate; never return or pass `null` — use an empty collection, an `Optional`, or a Null Object with safe defaults; wrap noisy third-party APIs behind a clean adapter that translates their exceptions into yours; and put context in every error (`Failed to save invoice #1234 for customer Acme`) so debugging starts from a fact. This pairs directly with the Boy Scout Rule the skill champions — **always leave the code cleaner than you found it** — which is how a large codebase improves continuously instead of waiting for a cleanup that never gets funded. > **Prompt** — Use the `clean-code` skill to audit error handling across our checkout and payments code: find every bare catch that swallows exceptions, every function that returns null on failure, and every error thrown without context, then refactor them to throw specific exceptions carrying the operation and the relevant state, replace null returns with Optionals or empty collections, and wrap the Stripe SDK behind an adapter that translates its errors into our domain exceptions > (https://skills.wondel.ai/skills/clean-code/) ## Phase 4 — Reduce the complexity that makes the system unholdable By now the regions you have touched are tested, restructured, and legible — but a debt-laden codebase has a deeper affliction that surface cleanup does not cure, and that AI agents left unsupervised will actually *worsen*. Asked to "modularize" or "clean up," an agent tends to shatter code into a swarm of tiny classes and interfaces and call it architecture. The Software Design skill, from John Ousterhout's [*A Philosophy of Software Design*](https://web.stanford.edu/~ouster/cgi-bin/book.php), is the corrective. Its governing principle names your real enemy precisely: **the greatest limitation in building software is our ability to understand the systems we create — complexity is the enemy.** Evaluate every change by asking whether it increases or decreases the overall complexity of the system. The skill gives you vocabulary to diagnose what "this code is a nightmare" actually means. Complexity shows three symptoms: **change amplification** (a simple change requires edits in many places), **cognitive load** (you must hold too much in mind to make a change), and **unknown unknowns** (it isn't even obvious what must change or what is relevant — the worst symptom, and the defining feature of a codebase buried in debt). Its central design idea is **deep versus shallow modules**: a module's depth is the functionality it provides divided by the complexity of the interface it imposes. A *deep* module hides significant machinery behind a simple interface (Unix file I/O — `open`, `read`, `write`, `close` — conceals disk blocks, buffering, caching, encoding). A *shallow* module has an interface nearly as complex as its implementation, adding cognitive load without hiding much. The disease of too many small shallow classes has a name — **classitis** — and the cure is to *merge* related shallow classes into deeper ones, which is the opposite of what an unsupervised agent does. > **Prompt** — Use the `software-design-philosophy` skill to analyze our notifications and messaging subsystem for classitis: identify which classes are shallow because their interface is nearly as complex as their implementation, find the pass-through methods that add indirection without value, and propose how to consolidate the shallow classes that always run together into deeper modules with simpler interfaces, telling me whether each change raises or lowers overall complexity > (https://skills.wondel.ai/skills/software-design-philosophy/) The second pillar is **information hiding** and its red-flag inverse, **information leakage** — when one design decision (a date format, a wire protocol, a database assumption) is reflected across multiple modules, so changing it means editing all of them. That is change amplification made concrete, and it is rampant in old codebases. A frequent cause is **temporal decomposition**: organizing code by *when* things happen ("read the config, then validate it, then apply it") rather than by *knowledge*, which forces every phase to share the same details. The fix is to organize modules around the knowledge they own — one module owns config, one owns serialization — so each hides a decision the others don't need. Finally, this skill reframes the entire debt-paydown effort as a shift from **tactical to strategic programming**. Tactical programming ships features fast and accumulates complexity with every shortcut; your codebase is the cumulative output of years of it. Strategic programming invests an extra 10–20% to keep the design clean and treats every change as an opportunity to improve structure — the "tactical tornado" who ships fast and leaves wreckage is the anti-pattern. This is the mindset that makes the Boy Scout Rule sustainable: a little improvement on every change, compounding, instead of a heroic rewrite that never comes. > **Prompt** — Use the `software-design-philosophy` skill to review how configuration and feature flags are read throughout our app for information leakage: find every place that knows the config file format or flag-resolution rules, show me where temporal decomposition has spread that knowledge across modules, and recommend a single deep config module that hides those decisions so a format change touches one place instead of twenty > (https://skills.wondel.ai/skills/software-design-philosophy/) ## Phase 5 — Draw the dependency boundary around your business rules Your modules are deeper and your functions cleaner, but the structural question that decides whether this codebase stays a swamp is bigger than any single module: **does your business logic depend on your framework and database, or do they depend on it?** In a codebase buried in debt the answer is almost always backwards — business rules live inside controllers, ORM models *are* the domain, pricing logic is interleaved with SQL, and you cannot test a business rule without standing up the whole framework. The [Clean Architecture](https://www.informit.com/store/clean-architecture-a-craftsmans-guide-to-software-structure-9780134494166) skill, from Robert C. Martin, fixes this with one rule and a great deal of leverage. The rule is **the Dependency Rule: source code dependencies must point inward**, toward higher-level policy. Picture concentric circles — Entities (enterprise business rules) at the center, then Use Cases (application-specific rules), then Interface Adapters (controllers, presenters, gateways), with Frameworks and Drivers (the web framework, the ORM, the queue) on the outside — and nothing in an inner circle may name anything in an outer one. The database is a *detail*. The web is a *detail*. They are plugins to your business rules, not the skeleton of your application. The mechanism that enforces the rule is **Dependency Inversion**: a Use Case defines a `UserRepository` *interface*, and a `PostgresUserRepository` in the outer layer *implements* it, so business logic depends on an abstraction it owns and the database depends on that abstraction, never the reverse. In a tangled monolith you do not retrofit this everywhere at once — that would be a rewrite. You do it module by module, starting where change is most frequent or most painful, and the SOLID principles are your mid-level tools. **Single Responsibility** (a module has one reason to change because it serves one actor) tells you where to split a god class; **Open-Closed** (extend by adding code, not modifying it) and **Dependency Inversion** are how you introduce a seam an adapter can plug into. The payoff is immediate and compounds: once the boundary exists for a module, you can test its business rules with no database and no framework — making the Phase 1 tests fast and trustworthy — and you can replace the framework or datastore behind it as a localized change. > **Prompt** — Use the `clean-architecture` skill to map the dependency graph of our Rails monolith and find every violation of the Dependency Rule where business logic reaches into ActiveRecord or the controller layer, then pick our order-pricing rules as the first module to fix: extract them into framework-free use cases that depend on a repository interface they own, and move the ActiveRecord implementation out to an adapter so we can unit-test pricing with no database > (https://skills.wondel.ai/skills/clean-architecture/) The skill is loud about a trap that debt-laden teams fall into when they finally decide to "modernize": do not assume that splitting into microservices buys you good architecture. A set of services sharing one fat data model is a **distributed monolith** — all the coupling of a monolith plus network latency and partial failure, which is strictly worse. Apply the Dependency Rule *within* your monolith first; services are deployment boundaries, not automatically architectural ones. Component principles like **Common Closure** (classes that change together belong together) and **Acyclic Dependencies** (break every cycle in the component graph) tell you where genuine boundaries are *before* you ever consider distributing them. > **Prompt** — Use the `clean-architecture` skill to check whether breaking our monolith into microservices would just create a distributed monolith given that everything still shares one database: analyze the component dependencies for cycles and shared data models, apply Common Closure to group classes that change together, and tell me which boundaries are real architectural seams versus which would only add network calls to existing coupling > (https://skills.wondel.ai/skills/clean-architecture/) ## Phase 6 — Lock in the habits that stop debt from re-accumulating Paying down debt is wasted if the codebase silently re-accrues it the moment your attention moves on. The Pragmatic Programmer skill, from Hunt and Thomas, supplies the meta-principles that hold every other phase together and keep the gains. Its ethos — **care about your craft** — is operationalized through habits that determine whether a large codebase stays easy to change. The most directly relevant to debt is the **Broken Window Theory**: one unrepaired hack signals that nobody is minding quality, and the threshold for the next hack drops to zero. This is the precise psychology that produced your current situation. The discipline is to fix problems immediately or "board them up" with a *tracked* ticket — never an untracked `// TODO: fix later`, which is itself a broken window — and to be intolerant of new debt in code review even as you pay down the old. Three more principles matter acutely here. **DRY (Don't Repeat Yourself)**, stated precisely where most people are sloppy: DRY is about *knowledge*, not text. Two identical-looking blocks encoding *different* business rules are not duplication, and DRY-ing them couples concepts that should stay independent; the duplication that hurts is duplicated *knowledge* — the same validation rule on client and server, the same tax logic in three handlers. **Orthogonality**: components are orthogonal if changing one doesn't affect another (change the auth provider and billing shouldn't care), which is the design value the Clean Architecture boundary buys you and the antidote to the shotgun surgery that plagues your codebase. And **reversibility**: abstract third-party vendors behind your own interfaces so no decision is permanent — there are no final decisions, only ones you've made expensive to change. > **Prompt** — Use the `pragmatic-programmer` skill to audit our codebase for duplicated knowledge that causes bugs (the same validation rule repeated on client and server, the same business calculation in several services) while explicitly ignoring code that merely looks similar but encodes different rules, then find the broken windows like untracked TODOs and quick hacks and tell me which to fix now versus board up with a tracked ticket > (https://skills.wondel.ai/skills/pragmatic-programmer/) This skill is also where you institute the practice that makes ongoing debt paydown affordable rather than a separate budget line: a debt budget, the Boy Scout Rule with teeth, and **Design by Contract** to make assumptions explicit so failures surface early instead of corrupting data quietly. **Crash early** — a dead program does far less damage than one limping along in an invalid state — is a particularly useful stance in a legacy system where silent corruption is a constant risk. Add preconditions and invariants as guard clauses at the boundaries you are hardening, so the system fails loudly at the point of the problem. > **Prompt** — Use the `pragmatic-programmer` skill to add Design by Contract guard clauses to the boundaries of our newly extracted billing use cases: define the preconditions each entry point requires, the postconditions it guarantees, and the invariants that must always hold (an account balance never goes negative), and make them fail fast and loudly so an invalid state crashes at the source instead of corrupting data downstream > (https://skills.wondel.ai/skills/pragmatic-programmer/) ## Phase 7 — Harden the integration points before they take you down Legacy systems do not usually fail in the demo; they fail in production, at 3 a.m., when a dependency you forgot about gets slow. The Release It! skill, from Michael Nygard, exists for exactly this, and its opening principle is worth memorizing: **the software that passes QA is not the software that survives production.** Production is hostile, and every system is eventually pushed past its design limits — the only question is whether it degrades gracefully or collapses. In an old codebase the danger is acute because the integration points have multiplied over years and almost none of them were hardened. The skill catalogs **stability anti-patterns**, and the number-one killer is **integration points** — every socket, HTTP call, and queue the system touches. The specific failure that takes down legacy apps is calling a third-party API or a sibling service with *no timeout*. When that dependency slows down — not even fails, just slows — request threads block waiting on it, the thread pool exhausts, and the entire app stops responding to everyone, because of something you don't control. The skill is blunt: **a slow response is worse than no response.** Two more anti-patterns are endemic to aging systems: **unbounded result sets** (a query that was fine when the table had a thousand rows becomes an out-of-memory crash at a million — add `LIMIT`, paginate every list endpoint) and **blocked threads** (the silent killer — contention and deadlocks that show no error until everything stops). Against each anti-pattern stands a **stability pattern**. **Timeouts** on every outbound call — connect *and* read — are non-negotiable. The **Circuit Breaker** wraps a failing dependency: after a threshold of failures it trips open and fails fast instead of waiting, then periodically tests recovery in a half-open state — a tripped breaker is the system working *correctly*, protecting itself from a downstream failure. **Bulkheads** isolate resource pools so one drowning dependency can't drain the threads the rest of the app needs (a dedicated connection pool for the payment gateway, separate from search). **Retry with exponential backoff and jitter** so a recovering service isn't immediately flattened by a synchronized thundering herd. And **Steady State** — legacy systems accumulate cruft (sessions, logs, temp files) until a disk fills — so design automatic cleanup. > **Prompt** — Use the `release-it` skill to audit every integration point in our legacy service for stability anti-patterns: find external API calls and database queries with no timeout and add connect and read timeouts to all of them, find list endpoints and queries with no LIMIT that will fall over as our tables grow and add pagination, then wrap our payment and email provider calls in circuit breakers that trip after five failures in sixty seconds and isolate their connection pools with bulkheads > (https://skills.wondel.ai/skills/release-it/) Two more areas from this skill make a legacy system operable rather than merely alive. **Deployment and release**: decouple *deploying* code from *releasing* it via feature flags, so you can ship dark, enable for a small percentage, and roll back a release in seconds without redeploying; make database migrations backward-compatible with **expand-contract** so old and new code can run simultaneously during a rolling deploy — essential when you are changing schemas a debt-laden app depends on in undocumented ways. And **observability**, which old systems are usually missing: you cannot operate what you cannot see. Add **deep health checks** (the `/health` endpoint verifies the database, cache, and queue are reachable, not just that the process is up), instrument the **RED metrics** per endpoint (Rate, Errors, Duration), and **alert on the symptoms users feel** — error rate and latency — not on causes like CPU. > **Prompt** — Use the `release-it` skill to design an expand-contract migration for the orders table schema that half our untested code depends on, keeping it backward-compatible at every step: add the new columns and write to both old and new, backfill existing rows, migrate readers behind a feature flag, then contract by dropping the old columns once nothing reads them, with a fast rollback at each stage > (https://skills.wondel.ai/skills/release-it/) ## Phase 8 — Carve the big ball of mud into bounded contexts You have made the codebase safe to change, legible, less complex, properly bounded at the module level, disciplined, and resilient. The final phase is strategic: how do you decompose a monolithic big ball of mud into parts the team can own and evolve — and eventually extract — without a rewrite? The Domain-Driven Design skill, from Eric Evans, provides the strategy. Its core principle reframes what "good structure" even means: **the model is the code; the code is the model.** The greatest risk in software is not technical failure but building a model that doesn't reflect how the business actually works — and in a legacy codebase that mismatch is usually the deepest debt of all, because the code's concepts and the business's concepts drifted apart years ago. The first and cheapest move is **Ubiquitous Language**: a shared, rigorous vocabulary between developers and domain experts, used consistently in conversation and *in the code*. Legacy codebases are littered with technical-only names — `DataManager`, `RequestProcessor`, `Helper`, `Utils` — that hide domain logic from the experts who could correct it. The skill treats naming difficulty as a *design signal*: if a concept is hard to name, the model is probably wrong. Renaming `process()` to `underwrite()` and `RequestHandler` to `LoanApplication` is not cosmetic; it surfaces the real domain and makes the next round of modeling possible. > **Prompt** — Use the `domain-driven-design` skill to build a ubiquitous language for our codebase, which is full of technical names like OrderManager, DataProcessor, and PaymentHelper that hide what the business actually does: go through the core billing and fulfillment modules, propose domain-meaningful names for the classes and methods based on how the business describes these operations, and flag any concept that is hard to name because it signals the model is probably wrong > (https://skills.wondel.ai/skills/domain-driven-design/) The strategic heart of decomposing the monolith is **Bounded Contexts and Context Mapping**. A bounded context is an explicit boundary within which one model applies — and crucially, the same word ("Customer," "Order") can legitimately mean different things in different contexts. Large systems that force a single unified model collapse into inconsistency; that one bloated `Customer` class serving billing, shipping, and marketing *is* a chunk of your debt. The skill's guidance is to **start by mapping what exists** (the Big Ball of Mud is itself a recognized pattern on the context map), then define target boundaries — often aligned with team boundaries, per Conway's Law. The single most important defensive pattern is the **Anti-Corruption Layer**: when one part of the system talks to another (or to the legacy core you haven't untangled yet), translate at the boundary so a foreign or outdated model never leaks into your clean one. This is what lets you build a clean new context *beside* the mud and protect it from contamination — the foundation of the **Strangler Fig** approach to incremental migration. > **Prompt** — Use the `domain-driven-design` skill to map the bounded contexts hiding inside our monolith: identify where the same term like Customer or Order means different things in billing versus shipping versus support, propose explicit context boundaries aligned with our team structure, and design an anti-corruption layer so a new cleanly modeled Billing context can talk to the legacy core without letting the old tangled model leak into it > (https://skills.wondel.ai/skills/domain-driven-design/) Inside each context, the **building blocks** give you the consistency rules that tame the tangle: **Entities** have identity that persists across change; **Value Objects** are defined entirely by their attributes and should be immutable (prefer them — most things people model as entities are really value objects); and **Aggregates** are small clusters with a single root that enforces invariants and is the only thing the outside references (by ID, never by object reference). Keeping aggregates small is how you fix the slow loads and concurrency conflicts a giant legacy object graph produces. **Domain Events** (`OrderPlaced`, `PaymentReceived`, named in past tense) let contexts react to each other asynchronously instead of through the synchronous spaghetti of direct calls — decoupling cause from effect and giving you a natural audit trail. And **strategic design** tells you *where to spend your limited effort*: identify the **Core Domain** where your competitive advantage lives and invest your best modeling there, while treating supporting and generic subdomains (auth, email, payments) as candidates to buy or wrap thinly rather than lovingly refactor. You do not pay down debt uniformly; you pay it down hardest where the business value is. > **Prompt** — Use the `domain-driven-design` skill to redesign our biggest god object — the one that loads dozens of related records and causes constant concurrency conflicts — using DDD aggregate rules: identify the true consistency boundary, shrink the aggregate to a small root plus only what must be immediately consistent, reference other aggregates by ID instead of loading them, and replace the synchronous cross-module calls with domain events that other contexts react to > (https://skills.wondel.ai/skills/domain-driven-design/) ## Your checklist - [ ] Stop the rewrite conversation. Commit to paying down debt **in place**, incrementally, with the old system always shipping. - [ ] Treat all untested code as **legacy code**: pin behavior with **characterization tests** at your change points before editing. - [ ] Use **effect sketches** and **pinch points** to map blast radius and find where a few tests cover the most behavior. - [ ] Break dependencies with the **least-invasive seam** — Parameterize Constructor with a production default — so tests can inject fakes. - [ ] Use **Sprout/Wrap** for urgent changes you can't fully cover yet, and track the untested host as debt. - [ ] Apply **named refactorings** one at a time, **tests green between each step**; revert (never debug) a red refactoring. - [ ] **Never refactor and change behavior in the same commit** — one hat at a time. - [ ] Use **Branch by Abstraction** and **Preparatory Refactoring** for large migrations and feature work in tangled code. - [ ] Rename for intent; **Extract Method** every monster function; replace swallowed exceptions and `null` returns with specific exceptions and contextful errors. - [ ] Merge shallow classes into **deep modules**; kill **classitis** and **information leakage**; shift from tactical to strategic. - [ ] Enforce the **Dependency Rule** module by module: business rules depend on interfaces they own, not the framework or ORM. - [ ] Don't split into services until you've proven the boundaries are real — avoid the **distributed monolith**. - [ ] Fix or **board up broken windows** with tracked tickets; DRY only **knowledge**, not coincidental code. - [ ] Put a **timeout on every outbound call**; add **circuit breakers**, **bulkheads**, and `LIMIT`s on integration points and queries. - [ ] Add **deep health checks**, **RED metrics**, and **symptom-based alerts**; decouple deploy from release with feature flags and expand-contract migrations. - [ ] Establish a **ubiquitous language**, map **bounded contexts**, and protect new clean contexts with **anti-corruption layers** as you strangle the mud. ## Common mistakes **Proposing the big-bang rewrite.** The cardinal error. The old system keeps accumulating fixes and edge cases while you rebuild; the rewrite ships late, missing years of hard-won behavior, and the business runs out of patience. Every skill in this stack assumes incremental change instead, because incremental change is the only kind that keeps shipping. **Cleaning before writing a single test.** Renaming and extracting in untested legacy code feels productive and is actually gambling — you cannot know you preserved behavior. Pin behavior with characterization tests at the change point first, *then* clean. Coverage grows along the paths you actually touch; that beats a dedicated "testing project" that never gets funded. **Trying to fix everything at once.** A codebase buried in debt has thousands of problems, and trying to address them globally produces a stalled, unmergeable mega-branch. Triage instead: a spot that changes once gets a sprout or a wrap; the same spot changing again has earned its tests and its refactor. Spend your effort where change is frequent and where the **Core Domain** value is. **Refactoring and changing behavior in one commit.** When a commit does both, a failing test can't tell you which change broke things and review can't separate structure from behavior. Split every such change into a structure-only commit (tests stay green) and a behavior-only commit. **Letting the agent "modularize" into a swarm of tiny classes.** Ask an AI agent to make legacy code modular and it will create fifteen shallow classes and call it architecture. That is classitis, and it raises complexity rather than lowering it. Hold the agent to the deep-module principle: hide real machinery behind simple interfaces, and merge shallow classes that always travel together. **Calling external services with no timeout.** The most common cause of legacy production outages. A dependency doesn't have to fail to take you down — it only has to get slow while your threads block on it. Connect-and-read timeouts on every outbound call, plus a circuit breaker, are table stakes before you trust the system in production. **Mistaking microservices for architecture.** Splitting a tangled monolith into services that share one database gives you a distributed monolith — all the coupling, plus network latency and partial failure. Apply the Dependency Rule and find the real bounded contexts *inside* the monolith before you distribute anything. **Silently fixing bugs you find while characterizing.** When a characterization test reveals the code does something wrong, you will be tempted to fix it on the spot. Don't — callers, reports, and customers may depend on the quirk. Pin the actual (wrong) behavior, document it with a ticket, and fix it later as a deliberate, separate, verifiable change. ## Frequently asked questions ### In what order should I install and apply these skills? Follow the phase order in this guide, which is deliberately not chronological by book. Start with `working-with-legacy-code` because untested code is legacy code and you need both a safety net and a comprehension map before anything else. Then `refactoring-patterns` for the safe transformations, `clean-code` for legibility, `software-design-philosophy` to attack complexity, and `clean-architecture` to draw module boundaries. `pragmatic-programmer` sets the habits that keep debt from returning, `release-it` hardens production, and `domain-driven-design` gives you the strategy to decompose the monolith. You don't need all eight before you see value — getting through Phase 3 on the regions you actively work in already changes the team's relationship with the code. Install the whole stack in one go with `npx skills add wondelai/skills --all --global` and pull each skill into a session as you reach its phase. ### Where do I even start in a codebase this large? Not with the worst file — with the file you have to *change next*. The legacy-code skill's discipline is that coverage and cleanup follow change: you invest comprehension and tests precisely where a feature or bug fix is taking you, never speculatively across the whole system. Use an effect sketch to bound what your change can affect, find the pinch point where a few tests cover the most behavior, pin that behavior, then make the change. The second heuristic is frequency: the files that show up in every other commit (your `git log` and churn metrics will tell you) are where debt costs the most, so they earn investment first. The Core Domain — where your competitive advantage lives — is the third axis. The intersection of "I'm changing it anyway," "it changes constantly," and "it's business-critical" is your starting point. ### How do I convince my team (or my manager) not to do the rewrite? Make the incremental path concrete and the rewrite's risk explicit. The rewrite asks the business to fund a second system that produces zero customer value until the day it fully replaces the first — during which the first keeps changing, so you're aiming at a moving target and will miss years of undocumented edge cases. The incremental path, by contrast, ships value continuously: every phase in this guide leaves the system better *and still running*, and the worst case of any single step is a fast revert. Frame it in the Software Design skill's terms — strategic programming invests 10–20% per change and compounds — and show a small, fast win first: pick one painful, frequently-changed module, put it under characterization tests, refactor it visibly, and let the reduced fear and faster next change speak for themselves. A demonstrated improvement on real code beats any slide about a rewrite. ### How do tests help when I don't even know what the correct behavior is supposed to be? That is exactly the situation characterization tests are built for, and the reason they're not called "specification tests." You are not asserting what the code *should* do — you're documenting what it *actually does* right now, because in a legacy system the actual behavior is the de facto spec that callers and customers depend on. The recipe sidesteps your ignorance: call the code, assert something obviously wrong, run it, and let the failure message *tell* you the real output, then pin that value. You don't need a spec; the running code is the spec. If, while doing this, you discover behavior that's clearly a bug, you still pin the current (wrong) value, file a ticket, and change it later as a separate deliberate step — because something downstream may quietly depend on the bug. ### Can I extract microservices from this monolith as part of the refactor? Eventually, and only after the boundaries are real. The most expensive mistake teams make when modernizing a debt-laden monolith is to carve it into services that still share one database and one fat data model — a distributed monolith, which keeps all the coupling and adds network latency and partial failure. The correct sequence is to find the genuine seams *inside* the monolith first: use the Domain-Driven Design skill to map bounded contexts, the Clean Architecture skill's Common Closure and Acyclic Dependencies to verify a candidate boundary has no cycles and groups things that change together, and an anti-corruption layer to decouple the new context from the legacy core. Once a context is cleanly bounded, well-tested, and communicating through explicit interfaces and domain events, *then* extracting it to a service is a deployment decision rather than an architectural gamble. The Strangler Fig pattern — grow the clean context beside the mud and gradually route traffic to it — is the low-risk path. ## Start with the safety net A codebase buried in technical debt did not get that way overnight, and it will not get fixed overnight either — but it does not need to. The way out is not a heroic rewrite that bets the company; it is a sequence of small, verifiable moves, each backed by a framework that thousands of engineers have already proven, each leaving the system better and still shipping. The skills in this stack turn that literature into something your AI agent can apply directly to *your* code, on *your* hardest files. Install the whole stack with a single command: ``` npx skills add wondelai/skills --all --global ``` Then open the file you have to change next and start at Phase 1: tell your agent to use the `working-with-legacy-code` skill to draw an effect sketch and pin the current behavior with characterization tests. Once the net is in place under the code you're about to touch, every subsequent step becomes safe — and the mountain starts coming down one verified step at a time. For the adjacent journeys, read [From Vibe-Coded Prototype to Production-Ready Product](https://skills.wondel.ai/guides/vibe-coded-prototype-to-production/) if your starting point is AI-generated rather than aged, and [Improve an Existing App With AI Skills](https://skills.wondel.ai/guides/improve-an-existing-app-with-ai-skills/) for the product-experience view — UX, copy, and in-app persuasion — once the code underneath is safe to change. --- # How to Design the Best Possible Architecture for a New App > Make the high-leverage architecture decisions right the first time — boundaries, domain model, data, and resilience — using AI agent skills from Clean Architecture, Domain-Driven Design, Designing Data-Intensive Applications, and more. By Michał Jaskólski · Published 2026-06-25 · Updated 2026-08-08 · 19 min read Canonical: https://skills.wondel.ai/guides/design-the-best-architecture-for-a-new-app/ Skills used: clean-architecture, domain-driven-design, system-design, ddia-systems, software-design-philosophy, release-it, pragmatic-programmer, 37signals-way **TL;DR:** You design the best architecture for a new app by making reversibility the goal: point dependencies inward with Clean Architecture, place boundaries where the business splits using Domain-Driven Design, size the system for the load you actually have, make data decisions with Designing Data-Intensive Applications, and keep modules deep — then cut scope until only the essential version ships. - The most leveraged decision is keeping business rules independent of the framework, database, and delivery mechanism — those change; the rules survive. - Boundaries fall where the business splits, not between every verb: DDD's ubiquitous language tells you where the seams really are. - Data outlives code — a careless schema or consistency model outlasts every framework you chose this week. - Install the stack with npx skills add wondelai/skills --all --global and test every design decision with one question: does it make the whole system simpler or more complex? "Architecture" is one of the most abused words in software. To one engineer it means a folder structure; to another, a diagram of microservices and Kafka topics that the app does not need and probably never will. The truth is narrower and more useful: architecture is the set of decisions that are expensive to reverse. Everything else is just code, and code is cheap to change. So the real skill of designing an architecture for a brand-new app is not drawing the most elaborate diagram. It is identifying the handful of decisions that will be costly to unwind later, making *those* well, and deliberately deferring everything else. That framing matters because a new app sits in a uniquely dangerous spot. You have the most freedom you will ever have — no legacy, no migrations, no users to keep online — and the least information you will ever have, because you do not yet know your real load, your real domain edges, or which features will matter. Over-commit now and you build a distributed system for a product that turns out to need a single database. Under-commit and your business logic fuses to your web framework, your domain model contradicts itself across three modules, and the "quick" prototype calcifies into something nobody can safely change. Both failures are avoidable, and they are avoided by the same move: get the boundaries and the model right, keep the volatile details swappable, and refuse to gold-plate. This guide gives you a sequenced workflow built from eight AI agent skills, each packaging a canonical book so your coding agent — Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw, Hermes Agent, or any other agentskills.io-compatible agent — applies the actual framework rather than a vague memory of it. You will establish dependency boundaries that keep frameworks and databases at arm's length ([Clean Architecture](https://skills.wondel.ai/skills/clean-architecture/)), model the business so the code reads like the domain and the boundaries fall where the business actually splits ([Domain-Driven Design](https://skills.wondel.ai/skills/domain-driven-design/)), size the system honestly with back-of-the-envelope math instead of cargo-culting scale ([System Design](https://skills.wondel.ai/skills/system-design/)), make deliberate data decisions about storage engines, replication, and consistency ([Data-Intensive Apps](https://skills.wondel.ai/skills/ddia-systems/)), treat complexity itself as the enemy at every step ([Software Design](https://skills.wondel.ai/skills/software-design-philosophy/)), design for the failures production will inevitably throw at you ([Release It!](https://skills.wondel.ai/skills/release-it/)), apply the meta-disciplines that keep the codebase reversible and orthogonal ([Pragmatic Programmer](https://skills.wondel.ai/skills/pragmatic-programmer/)), and ruthlessly cut scope so you build the essential version and ship it ([The 37signals Way](https://skills.wondel.ai/skills/37signals-way/)). > Architecture is the set of decisions that are expensive to reverse. Make those well; defer everything else. A note on order and dose. The phases below run from the most foundational and hardest-to-reverse (boundaries, domain) to the more tunable (data, resilience) to the cross-cutting disciplines (complexity, reversibility, scope-cutting) that you apply throughout. You do not need every skill at full strength on day one — a weekend project might use three of these lightly. A funded team building toward a real launch will want the whole stack. If you have not yet validated that anyone wants this app, start with the sibling guide on [how to create a new app with AI skills](https://skills.wondel.ai/guides/create-a-new-app-with-ai-skills/) and come back here once you have earned the right to build. And if you are hardening something you already vibe-coded, the guide on taking a [vibe-coded prototype to production](https://skills.wondel.ai/guides/vibe-coded-prototype-to-production/) is the better entry point. ## Phase 1: Draw the boundaries that make every other decision reversible Start here because this is the decision that buys back all the others. The single most leveraged thing you can do for a new app's architecture is to keep your business rules independent of the things most likely to change underneath them — the web framework, the database, the third-party APIs, the delivery mechanism. The [Clean Architecture](https://skills.wondel.ai/skills/clean-architecture/) skill, from [Robert C. Martin's book](https://www.informit.com/store/clean-architecture-a-craftsmans-guide-to-software-structure-9780134494166), distills this into one rule that is worth memorizing: **source code dependencies point inward**, from frameworks toward use cases toward entities. Nothing in an inner circle may know anything about an outer one. Why this is the highest-leverage move: every boundary you draw correctly is an option to defer or swap a decision later without a rewrite. If your business logic does not know whether data lives in SQLite or Postgres or DynamoDB, you can start with the simplest option and change your mind when you have evidence — which, for a new app, you always will. The database is a detail. The web framework is a detail. The payment provider is a detail. Details should be plugins to your business rules, not the skeleton your application is built around. The skill's diagnostic question is the one to keep asking yourself: *can you test your core business rules with no database running, no web server, and no framework loaded?* If the answer is no, your dependencies point the wrong way, and you will feel it as pain on every future change. The mechanism that enforces the rule is Dependency Inversion. Your use case defines an interface — say `InvoiceRepository` — and your infrastructure provides the implementation, `PostgresInvoiceRepository`. A controller translates an incoming HTTP request into a plain request object, calls the use case, and gets back a plain response object; an ORM entity or a framework type must never cross that boundary. Have your agent design this layering for a concrete feature in your actual app rather than in the abstract. > **Prompt** — Use the `clean-architecture` skill to design the Clean Architecture layering for my app's most business-critical flow — define the entities, the central use case with its request and response models, the repository and gateway interfaces it depends on, and show how the HTTP controller and the database adapter sit in the outer ring without leaking framework or ORM types into the core > (https://skills.wondel.ai/skills/clean-architecture/) The trap to avoid is treating the four concentric circles as sacred geometry. They are not. The number of layers is not fixed, and a small app can collapse interface adapters and frameworks into a single outer layer without sinning. What matters is the *direction* of dependencies, not the count of folders. Draw full boundaries — with interfaces on both sides — only at points of genuine volatility: the database, external services, the delivery mechanism. Everywhere else, a partial boundary or no boundary at all is the correct, simpler choice. Ask your agent to keep you honest about where a boundary earns its cost. > **Prompt** — Use the `clean-architecture` skill to review my proposed module layout for over-engineering — I have separate interface, adapter, and infrastructure layers for every single feature including a trivial settings page — and tell me which boundaries are pulling their weight at points of real volatility and which are ceremony I should collapse > (https://skills.wondel.ai/skills/clean-architecture/) One more decision belongs here because it is genuinely hard to reverse: the monolith-versus-services question. The skill is blunt about it — a microservice with a fat shared data model is just a distributed monolith, which is worse than a clean monolith in almost every way. Services are units of deployment, not units of architecture. For a new app, the right default is a well-structured modular monolith with clean internal boundaries; you can extract a service later precisely because the boundaries already exist. Splitting first, before you know where the seams are, is the expensive mistake. ## Phase 2: Model the domain so the boundaries fall where the business splits Clean Architecture tells you *that* you need boundaries and which way dependencies should flow. It does not tell you *where* to put the boundaries. For that you need to understand the business, and the [Domain-Driven Design](https://skills.wondel.ai/skills/domain-driven-design/) skill, from [Eric Evans's book](https://www.domainlanguage.com/ddd/), is how you turn that understanding into structure. Its foundational claim is that the model is the code and the code is the model: when the words your team says out loud are the exact words in the codebase — a Ubiquitous Language — an entire class of translation bugs simply ceases to exist. This is radically cheaper to do for a new app than at any later point, because you are inventing the vocabulary from a blank page. Name things after domain concepts, never technical roles. An `Order` that knows how to `place()` and `cancel()` is worlds better than an `OrderManager` with a `process()` method, because a domain expert can read the former and tell you precisely where it is wrong. The skill treats naming difficulty as a design signal in its own right: if a concept resists a clean name, your model is probably incorrect, and that is information, not an annoyance. The two strategic ideas that do the most architectural work are **bounded contexts** and **aggregates**, and they map directly onto the boundaries from Phase 1. A bounded context is a region within which a word means exactly one thing. "Customer" in your billing context and "Customer" in your support context can be — should be — different models with different attributes, and trying to unify them into one omniscient `Customer` class is a classic mistake that produces a bloated, self-contradicting object. Context boundaries are where you will eventually consider splitting services, so finding them now is the same work as deciding your future architecture. Have your agent map them from the language your team actually uses. > **Prompt** — Use the `domain-driven-design` skill to build the ubiquitous language and bounded contexts for my system — find where the team uses the same words to mean different things across features and integrations, and tell me exactly where the same word legitimately means different things in different contexts > (https://skills.wondel.ai/skills/domain-driven-design/) Aggregates are the other pillar, and they are where data consistency starts. An aggregate is a cluster of objects governed by a single root that enforces invariants — everything inside the aggregate boundary is immediately consistent, and everything outside it is eventually consistent. This is not a minor implementation detail; it is the decision that determines your transactional boundaries and, downstream, how the system behaves under concurrency and scale. The skill's hard rules: keep aggregates small (one root plus a minimal cluster), and reference other aggregates by ID rather than holding direct object references. The most common new-app failure here is the anemic domain model, where entities are passive data bags and all the real logic leaks into a swamp of service classes. Push the behavior back into the entities and value objects where it belongs. > **Prompt** — Use the `domain-driven-design` skill to design the Order aggregate for my checkout context — identify the aggregate root, which fields are value objects like Money and Address, what invariants the root must enforce such as total matching the sum of line items and an order never being confirmed without a payment reference, and which related concepts like Buyer and Listing should be referenced by ID instead of embedded > (https://skills.wondel.ai/skills/domain-driven-design/) Finally, apply strategic design so you do not spread your best thinking thin. Not every part of the app deserves a deep model. Identify your **core domain** — the thing that is genuinely your competitive advantage — and concentrate your modeling effort there. For supporting subdomains, build something serviceable without over-engineering it; for generic subdomains like authentication, email delivery, or payments, buy or use open source rather than lovingly hand-crafting what is already a commodity. This is where DDD and the anti-gold-plating theme of this guide converge: depth where it differentiates, thin adapters everywhere else. > **Prompt** — Use the `domain-driven-design` skill to classify the subdomains of my system into core, supporting, and generic — starting from what actually differentiates us — and tell me where to invest deep domain modeling versus where to buy or use an off-the-shelf component instead of building > (https://skills.wondel.ai/skills/domain-driven-design/) DDD and Clean Architecture are partners, not rivals. The DDD repository interface lives in the domain layer; its implementation lives in infrastructure — which is exactly where the Dependency Rule wants it. You are describing the same well-structured system from two angles: one gives you the direction of dependencies, the other gives you the location and meaning of the boundaries they cross. ## Phase 3: Size the system honestly — then build far less than you fear Now comes the discipline that cuts against every instinct you absorbed from reading architecture blog posts: prove how small your system can be before you build it big. The [System Design](https://skills.wondel.ai/skills/system-design/) skill, from Alex Xu's *System Design Interview*, is as valuable for telling you what *not* to build as for telling you what to build. Its first principle is to start with requirements, not solutions, and its estimation tools let you demonstrate, on the back of an envelope, that you almost certainly do not need sharding, a service mesh, or a multi-region deployment yet. Do the arithmetic before you provision anything. The skill hands you the formulas: queries per second is daily active users times actions per day divided by 86,400 seconds, with peak load typically two to five times the average; storage is records per day times record size times retention period. For a new app with a few hundred or a few thousand users, that calculation reliably says the same thing — a single well-indexed database with a cache in front of read-heavy paths will carry you comfortably for a long time. The skill names premature sharding as an explicit mistake: scale vertically first, then add read replicas, then cache aggressively, and shard last, only when an estimate or a real bottleneck demands it. Have your agent run the numbers and then tell you plainly which techniques you can skip. > **Prompt** — Use the `system-design` skill to do a back-of-the-envelope capacity estimate for my system — ask me for the usage numbers you need, then tell me honestly which scaling techniques — sharding, read replicas, CDN, message queues, multi-region — I do NOT need yet at this scale > (https://skills.wondel.ai/skills/system-design/) When you do hit a decision that the math justifies, the skill gives you the right building block for the specific problem rather than a kitchen sink. A read-heavy listing page wants a cache-aside layer with a sensible TTL and explicit invalidation on write. A spiky, slow background job — image processing, sending a batch of emails, generating a report — wants a message queue so the work is decoupled from the request path and the queue absorbs the spike. Global static assets want a CDN at the edge so your origin only serves the API. Reach for each block when a real bottleneck or a credible estimate points to it, and not a moment before. The skill's four-step process — scope, high-level design, deep-dive on the riskiest components, then tradeoffs — keeps you from either staying too abstract or drowning in premature detail. > **Prompt** — Use the `system-design` skill to design the asynchronous flow for my listing-image processing step, which takes 6 seconds per upload and currently blocks the create-listing request — use a message queue and a worker pool, and include how the client is notified when processing completes and how I keep the create-listing happy path fast and responsive > (https://skills.wondel.ai/skills/system-design/) The point of this phase is restraint backed by evidence. You are allowed to build for scale — once you can show, with numbers, that you are about to need it. Until then, the most professional architecture decision is the boring one. ## Phase 4: Make deliberate data decisions, because data outlives the code If Phase 3 is about how much system you need, this phase is about getting the part that lasts the longest correct. The [Data-Intensive Apps](https://skills.wondel.ai/skills/ddia-systems/) skill, from Martin Kleppmann's [*Designing Data-Intensive Applications*](https://dataintensive.net/), opens with the observation that should govern this entire phase: **data outlives code.** Applications get rewritten and frameworks come and go, but the data persists for years, sometimes decades. A careless schema or an unconsidered consistency model is the kind of mistake you live with long after the framework you chose this week is forgotten. Start with the data model and storage engine, chosen against your actual access patterns rather than habit or hype. The skill's framing: relational models excel at many-to-many relationships and ad-hoc queries; document models reduce impedance mismatch for self-contained aggregates with strong locality; graph models win for recursive traversals over densely connected data. Underneath, storage engines trade reads against writes — log-structured (LSM-tree) engines like Cassandra's give you excellent write throughput at the cost of read amplification, while page-oriented (B-tree) engines like Postgres's give predictable read latency. The mistake the skill calls out by name is choosing a database by popularity instead of by fit. Notice, too, how cleanly this phase rests on Phase 2: your DDD aggregates often map naturally to documents, while your relational integrity constraints map to foreign keys. Have your agent reason it through per workload. > **Prompt** — Use the `ddia-systems` skill to evaluate the right data model and storage-engine characteristics for the distinct data workloads in my system — identify which are relational and read-heavy, which are append-only streams, and which are graph-shaped — and tell me whether to start with one Postgres instance or introduce polyglot persistence > (https://skills.wondel.ai/skills/ddia-systems/) Then make the consistency and replication decisions explicit, because the defaults will surprise you. The skill is emphatic that most databases default to read committed or snapshot isolation, *not* serializable — which means anomalies like write skew can appear in production even though your code looks correct. For a new app this is exactly the moment to decide, per operation, where you need a serializable transaction or an explicit `SELECT ... FOR UPDATE`, and where eventual consistency is genuinely fine. The classic example is inventory: two buyers racing to purchase the last item of stock is a write-skew waiting to happen unless you lock the row. Replication has its own tradeoffs — single-leader with read replicas is the simple, strong-consistency default for a read-heavy app, but replication lag introduces read-your-writes anomalies you must design around (a user updates their profile, then sees the stale version served from a replica). > **Prompt** — Use the `ddia-systems` skill to walk through the concurrency and consistency design for my system's most contended write path — the place where two users race for the same resource — explain the write-skew risk under snapshot isolation, show me the correct locking or serializable-transaction approach, and tell me which other operations can safely tolerate eventual consistency > (https://skills.wondel.ai/skills/ddia-systems/) A final, durable idea from this skill that pays off enormously for a new app: separate your system of record from your derived data. Your source-of-truth tables are one thing; your search index, your caches, and your materialized analytics views are derived from them and should be rebuildable from source. The skill points to change data capture and event sourcing as the mechanisms. You do not have to adopt full event sourcing on day one — but designing so that derived data is always reconstructable from the system of record means a future requirement change does not force a terrifying one-way data migration. Reach for this when you have a real second read pattern (a search index, an analytics dashboard), not preemptively. ## Phase 5: Treat complexity as the enemy and keep modules deep Every phase so far has been adding structure. This one is the counterweight that keeps the structure from becoming its own disease. The [Software Design](https://skills.wondel.ai/skills/software-design-philosophy/) skill, from John Ousterhout's [*A Philosophy of Software Design*](https://web.stanford.edu/~ouster/cgi-bin/book.php), rests on a single sentence worth taping to your monitor: the greatest limitation in building software is our own ability to understand the systems we are creating. Complexity — anything about the structure that makes the system hard to understand and modify — is the enemy, and the right test for *every* design decision is simply: does this make the overall system simpler or more complex? The skill's most useful concept for a new app is **deep versus shallow modules**. A module's interface is the complexity it imposes on the rest of the system; its implementation is the functionality it provides. A deep module hides significant power behind a simple interface — think of how `file.read(path)` conceals disk blocks, buffering, caching, and encoding. A shallow module is the opposite: a complicated interface wrapping very little, so it adds more cognitive load than it removes. This is the precise corrective to a real risk in this guide — that you read Phases 1 and 2 and contract "classitis," the disease of splitting everything into a swarm of tiny single-method classes and interfaces, each one a new boundary the next developer must learn. Clean layering and deep modules are allies; clean layering and classitis are not. Have your agent judge whether your abstractions are actually pulling their weight. > **Prompt** — Use the `software-design-philosophy` skill to review my proposed design for the order-processing module against deep-versus-shallow module principles — I have split it into OrderValidator, OrderEnricher, OrderPersister, and OrderNotifier classes that each expose one method and mostly pass data to the next — and tell me whether I have created shallow pass-through modules I should consolidate into one deep module with a simple interface > (https://skills.wondel.ai/skills/software-design-philosophy/) Two more ideas from this skill sharpen the whole architecture. The first is **information hiding** and its evil twin, information leakage: when a single design decision is reflected in multiple modules, a change to it ripples everywhere, and that is one of the strongest red flags in all of software design. Each module should encapsulate a piece of knowledge — a data format, a protocol, a policy — that the rest of the system does not need to know. The second is the **strategic-versus-tactical** distinction, which is the deepest justification for this entire guide. Tactical programming optimizes for getting the next feature working right now and quietly accumulates complexity with every shortcut; strategic programming invests a steady ten to twenty percent extra effort to keep the design clean, and that investment compounds until the strategic codebase is *faster* to work in within months. The skill is pointed about startups specifically: early shortcuts compound into crippling debt exactly as the team grows and the cost of confusion multiplies. > **Prompt** — Use the `software-design-philosophy` skill to audit this module boundary for information leakage — my pricing logic reads a discount-rules format that is also parsed independently in the admin UI and the reporting job, so the same knowledge lives in three places — and show me how to encapsulate that knowledge in one deep module so a change to the rules format touches exactly one file > (https://skills.wondel.ai/skills/software-design-philosophy/) > Your primary job is a great design that happens to work, not working code that happens to have a design. ## Phase 6: Design for the failures production will absolutely send you A design that only works when every dependency is healthy is not finished — it is a demo. The [Release It!](https://skills.wondel.ai/skills/release-it/) skill, from Michael Nygard's book, starts from a premise every new-app builder underestimates: the software that passes QA is not the software that survives production, because production is actively hostile. Every system will eventually be pushed past its design limits; the only question is whether it degrades gracefully or collapses catastrophically. And the cheapest time to build in graceful degradation is now, in the architecture, not after your first 2 a.m. outage. The most important lesson is that integration points are the number-one killer, and the most dangerous failure is not a crash but a *slow* response. A dependency that returns an error quickly is survivable; a dependency that hangs ties up your threads, exhausts your connection pools, and propagates the delay up the entire call chain until the whole system freezes — with no error in the logs to tell you why. The non-negotiable architectural decision that follows is that **every outbound call gets a timeout** — both connect and read timeouts — and the critical ones get a circuit breaker that trips after a threshold of failures and periodically tests for recovery. A circuit breaker that has tripped is not a bug; it is the system correctly protecting itself from a downstream failure. Bulkheads complete the picture: isolate connection and thread pools per dependency so one failing integration cannot drain the resources the rest of the app needs. For a new app integrating a payment provider, an email service, and maybe an LLM API, these patterns are the difference between a contained blip and a total outage. Have your agent design them around your real integration points. > **Prompt** — Use the `release-it` skill to design the resilience layer for my app's outbound calls to third-party services — use timeouts, circuit breakers, and bulkheads, specify sensible connect and read timeout values and breaker thresholds for each dependency, and show how the critical flow degrades gracefully when a dependency is slow or down rather than hanging the whole request > (https://skills.wondel.ai/skills/release-it/) Two more Release It! ideas belong in the architecture from the start rather than bolted on later. The first is the pairing of unbounded result sets and steady-state hygiene: a list endpoint with no `LIMIT` is a harmless query in testing that becomes an out-of-memory crash once real data outgrows your assumptions, so paginate every list from day one and design automatic cleanup for the cruft that accumulates (old sessions, logs, temp files). The second is the decoupling of *deployment* from *release*: deploying code to servers and exposing it to users are separate operations, and separating them with feature flags and a fast rollback path means a bad change is a flag flip away from being undone rather than a thirty-minute roll-forward. Build your schema migrations to be backward-compatible (expand-contract) so old and new code can run side by side during a deploy. Have your agent design the readiness essentials. > **Prompt** — Use the `release-it` skill to design the production-readiness essentials for my new app before launch — pagination and result-set limits on every list endpoint, deep health checks that verify the database and queue are reachable rather than just that the process is alive, the RED metrics I should emit per endpoint, and a backward-compatible expand-contract migration plan so I can deploy without downtime > (https://skills.wondel.ai/skills/release-it/) Resist over-rotating here too. You do not need full chaos engineering, multi-region failover, and a service mesh for your first thousand users. You need timeouts on every call, circuit breakers and bulkheads on the critical ones, pagination everywhere, deep health checks, and a rollback you trust. That short list prevents the overwhelming majority of self-inflicted production disasters at a tiny fraction of the cost. ## Phase 7: Apply the meta-disciplines that keep the whole thing reversible The skills so far each govern a slice of the system. The [Pragmatic Programmer](https://skills.wondel.ai/skills/pragmatic-programmer/) skill, from Hunt and Thomas, operates one level up — the cross-cutting habits that determine whether the architecture stays easy to change over years rather than rotting into something nobody dares touch. Four of its ideas are load-bearing for a new app, and they tie the previous phases together. First, the **tracer bullet**. Rather than building the system layer by layer and praying the pieces connect at the end, build one thin but completely *real* vertical slice through every layer — from the HTTP entry point through the use case to the database and back — and keep it as production code. It gives you end-to-end feedback on day two instead of month two, and it proves the boundaries you designed in Phase 1 actually link up before you invest in fleshing them out. This is the single best first thing to build once your boundaries are drawn. > **Prompt** — Use the `pragmatic-programmer` skill to design the thinnest possible tracer bullet for my system — one real end-to-end slice from an authenticated request through the use case and repository to a saved row and back to a response — that exercises every architectural layer with minimal functionality so I can confirm the wiring and the boundaries actually connect before building any real features > (https://skills.wondel.ai/skills/pragmatic-programmer/) Second, **reversibility**: there are no final decisions, so abstract third-party dependencies behind your own interfaces and never let a vendor's API leak into your business logic. This is the same instinct as Clean Architecture's adapters, stated as a habit — the forking-road test asks whether you could switch from Postgres to a different store, or one LLM provider to another, in a week. If not, you are coupled, and you should fix it while it is still cheap. Third, **orthogonality**: changing the database should not break the UI; changing the auth provider should not touch billing. The test is to ask how many modules a dramatic change to one requirement would affect, and to aim for the answer "one." Fourth, **DRY for knowledge, not for coincidence** — two code blocks that look alike but encode different business rules are not duplication, and merging them couples concepts that should evolve independently. This is the subtle counterpoint to Phase 5's information-hiding: deduplicate knowledge ruthlessly, but do not deduplicate things that merely resemble each other. Ask your agent to audit a planned design against these. > **Prompt** — Use the `pragmatic-programmer` skill to audit my plan to call the OpenAI SDK directly from four different service classes against the reversibility and orthogonality principles — show me the adapter interface that would let me swap the model provider later without touching business logic, and flag anywhere I would be coupling unrelated modules to a single vendor's API shape > (https://skills.wondel.ai/skills/pragmatic-programmer/) The cultural glue is the Broken Window theory: the first hack is the most expensive because it grants permission for every hack after it. In a brand-new codebase, establishing zero tolerance for unexplained broken windows — fix it now, or board it up with a tracked ticket — is one of the cheapest high-leverage habits available, and it protects every architectural decision you made in the earlier phases from slow erosion. ## Phase 8: Cut scope ruthlessly so you build the essential version The final discipline is the one that decides whether any of the above ever ships. The [The 37signals Way](https://skills.wondel.ai/skills/37signals-way/) skill, distilled from *Getting Real*, *Rework*, and [*Shape Up*](https://basecamp.com/shapeup), exists to counterbalance the natural tendency of an architecture document to grow without limit. Its core principle is the perfect closing note for this guide: **build less.** The best products do fewer things exceptionally well, and simplicity is the destination you fight toward, not the place you start. Half a product beats a half-assed product. The mechanism is fixing time and flexing scope. Instead of estimating how long an open-ended architecture will take (an estimate that will balloon to fill whatever time you allow), set an *appetite* — how much time this work is genuinely worth — and then cut scope to fit it. For a new app, this is the antidote to architectural gold-plating: the message-queue infrastructure, the event-sourcing layer, the generic plugin system, the configurability for use cases you have invented in your head. The skill's framing of every preference as "a decision the team could not or would not make" applies directly to architecture — every speculative abstraction is a decision you are deferring to an imaginary future at the cost of present complexity. Have your agent shape the architectural work into something bounded. > **Prompt** — Use the `37signals-way` skill to shape the architecture work for the first version of my system into a six-week appetite — given the boundaries, domain model, data decisions, and resilience patterns I have planned, tell me what is genuinely essential for launch versus what is gold-plating I should cut or defer, and identify the rabbit holes that could blow the scope > (https://skills.wondel.ai/skills/37signals-way/) This is also where YAGNI — you aren't gonna need it — gets teeth. The skill's curator mindset says to say no by default so the great decisions can breathe, and to make tiny, reversible decisions rather than big irreversible ones. Notice how neatly that closes the loop with the opening principle of this guide: architecture is the set of decisions expensive to reverse, so the fewer of those you make speculatively, the better. Every abstraction you *don't* build is a decision you keep cheap. The discipline is not to avoid architecture — it is to do exactly enough of it, applied where it compounds, and to ship. > **Prompt** — Use the `37signals-way` skill to review my v1 technical plan for premature abstraction and feature creep — I have designed a generic event-sourcing system, a plugin architecture, and a configurable multi-tenant layer for an app that currently has zero users — and tell me which of these to delete from v1, which to replace with the simplest thing that could possibly work, and what the genuinely essential architecture is > (https://skills.wondel.ai/skills/37signals-way/) ## Your checklist - [ ] Identify the decisions that are genuinely expensive to reverse, and make only those carefully — defer the rest. - [ ] Draw dependency boundaries so source code dependencies point inward; keep frameworks, databases, and vendors in the outer ring ([clean-architecture](https://skills.wondel.ai/skills/clean-architecture/)). - [ ] Verify you can test core business rules with no database, web server, or framework running. - [ ] Default to a modular monolith with clean internal boundaries; do not split services before you know where the seams are. - [ ] Build a Ubiquitous Language and map bounded contexts from the words your team actually uses ([domain-driven-design](https://skills.wondel.ai/skills/domain-driven-design/)). - [ ] Design small aggregates with clear invariants; reference other aggregates by ID, not object reference. - [ ] Classify subdomains into core, supporting, and generic; invest deep modeling only in the core. - [ ] Run back-of-the-envelope QPS and storage estimates before provisioning anything ([system-design](https://skills.wondel.ai/skills/system-design/)). - [ ] Scale vertically first, then read replicas, then cache; shard last and only with evidence. - [ ] Choose each datastore against real access patterns and storage-engine fit, not popularity ([ddia-systems](https://skills.wondel.ai/skills/ddia-systems/)). - [ ] Decide consistency per operation; know your database's default isolation level and lock against write skew where it matters. - [ ] Separate system-of-record data from rebuildable derived data (indexes, caches, views). - [ ] Audit modules for depth; consolidate shallow pass-through classes and eliminate information leakage ([software-design-philosophy](https://skills.wondel.ai/skills/software-design-philosophy/)). - [ ] Put a timeout on every outbound call; add circuit breakers and bulkheads on critical integrations ([release-it](https://skills.wondel.ai/skills/release-it/)). - [ ] Paginate every list endpoint; add deep health checks and a rollback path you trust. - [ ] Build a tracer bullet through every layer before fleshing out features ([pragmatic-programmer](https://skills.wondel.ai/skills/pragmatic-programmer/)). - [ ] Abstract every vendor behind your own interface; keep the architecture orthogonal and reversible. - [ ] Set an appetite, cut scope to fit it, and delete speculative abstractions before launch ([37signals-way](https://skills.wondel.ai/skills/37signals-way/)). ## Common mistakes **Letting the framework be the architecture.** The fastest way to a rewrite is to scaffold your app from a framework's conventions and let its models, ORM entities, and request objects flow all the way into your business logic. The framework is a detail; when it dictates your structure, swapping or upgrading it becomes a rewrite. Keep it at the edges. Clean Architecture's Dependency Rule is the cure: framework calls inward, never the reverse. **Over-engineering for scale you cannot prove you need.** Sharding, microservices, event sourcing, a service mesh, and multi-region failover are all real tools — and all wrong for an app with a few hundred users. The System Design skill's estimation math almost always shows that a single indexed database plus a cache is enough for a long time. Premature sharding and premature service-splitting are among the most expensive mistakes a new team makes. Earn complexity with evidence. **Over-correcting into classitis.** The opposite failure is reading about clean layering and shattering the codebase into dozens of tiny single-method classes, each a shallow module that adds interface cost without hiding meaningful complexity. Ousterhout's deep-module principle is the corrective: a few deep modules with simple interfaces beat a swarm of shallow ones. Boundaries should fall at real volatility and real domain seams, not between every verb. **Ignoring the database's actual consistency guarantees.** Assuming your transactions are serializable when your database defaults to snapshot isolation leads to write-skew bugs — like two buyers each successfully purchasing the last unit of stock — that appear only under concurrent load and never in testing. Decide consistency per operation, know your default isolation level, and lock explicitly where invariants demand it. **Treating resilience as a post-launch concern.** Skipping timeouts, circuit breakers, and pagination because "we'll add them when we need them" means you add them during your first outage, under pressure, at 2 a.m. A slow dependency with no timeout can freeze your entire app with nothing in the logs. These patterns are architecture, not operations, and they are cheapest to design in from the start. **Anemic domain models.** When entities are passive data bags and all behavior lives in service classes, business rules scatter and duplicate, and the code stops resembling the domain. Push behavior into the entities and value objects that own the data. A domain expert should be able to read your core classes and tell you where they are wrong. **Confusing build-less with build-carelessly.** Cutting scope is not permission to ship something broken or to skip the boundaries that keep options open. The 37signals discipline is to build the *essential* version well — half a product, not a half-assed one. Cut features and speculative abstractions; never cut the small set of decisions that are expensive to reverse. ## Frequently asked questions ### Isn't this too much process for a small app or an MVP? No, because most of it is *subtraction*, not addition. The expensive-feeling phases — system design, data-intensive decisions, resilience — are largely about proving you can build *less*: a single database instead of a sharded cluster, eventual consistency where it is fine, timeouts and pagination instead of a full chaos-engineering practice. The genuinely additive work is concentrated in Phases 1 and 2 — boundaries and a domain model — and that work pays for itself almost immediately because it is what keeps every later decision cheap to change. For a true weekend project, lean on Clean Architecture's Dependency Rule, a quick Ubiquitous Language, timeouts on outbound calls, and the 37signals instinct to cut scope. That is a few hours of thinking that saves weeks. ### How do I know which decisions are actually "expensive to reverse"? Use the forking-road test from the Pragmatic Programmer skill: imagine the requirement changes, and ask how much of the system you would have to rewrite. Decisions that touch your data model, your transactional and consistency boundaries, and the seams between bounded contexts tend to be expensive, because data outlives code and migrations are painful. Decisions hidden behind an interface — which web framework, which database product, which payment provider, which queue — are cheap *if* you drew the boundary, because only the adapter changes. The whole strategy of this guide is to convert as many expensive decisions as possible into cheap ones by putting a boundary in front of them, so that the irreducibly expensive set is small enough to get right with care. ### Should I start with microservices or a monolith? A modular monolith, almost always. The Clean Architecture skill is explicit that services are units of deployment, not units of architecture, and that a microservice with a fat shared data model is a distributed monolith — strictly worse than a clean one, because you have added network calls, partial-failure modes, and operational overhead without gaining real independence. The right sequence is to build a well-structured monolith whose internal bounded contexts have clean boundaries, then extract a service later *if* a real need appears — a piece that must scale independently, a team that needs to deploy on its own cadence. Because the boundaries already exist, the extraction is mechanical rather than a redesign. Splitting first, before you know where the seams are, forces you to guess the boundaries and almost guarantees you guess wrong. ### How do these eight skills actually work together in practice? They form a dependency chain that mirrors the system you are building. Domain-Driven Design tells you *where* the boundaries belong (the bounded contexts and aggregate seams); Clean Architecture tells you *which way* dependencies cross them and how to keep details swappable. Data-Intensive Apps decides what lives inside those boundaries at the persistence layer, and System Design tells you how much infrastructure that actually requires — usually far less than you feared. Software Design is the quality gate that keeps all those modules deep and leak-free instead of multiplying into shallow ceremony. Release It! hardens the integration points between everything against real-world failure. Pragmatic Programmer supplies the cross-cutting habits — tracer bullets, reversibility, orthogonality — that hold the structure together over time. And the 37signals Way is the governor on the whole thing, fixing time and cutting scope so you build the essential version and ship. You invoke each one by telling your agent which skill to use for the decision in front of you. ### What if I already have a prototype I built fast and now need to make it solid? Then this guide is still the right map, but your entry point is different. Read the dedicated guide on taking a [vibe-coded prototype to production](https://skills.wondel.ai/guides/vibe-coded-prototype-to-production/), which is written for exactly that situation — characterizing the existing code, finding the seams, and hardening it without a rewrite. Come back to this guide for the target state: the boundaries you are refactoring toward (Phase 1), the domain model the code should express (Phase 2), and the resilience patterns to add at the integration points (Phase 6). The difference is sequencing — you will be introducing boundaries into existing code rather than drawing them on a blank page — but the destination is the same. ## Start designing your architecture The best architecture for a new app is not the most sophisticated one. It is the one that gets the small number of expensive-to-reverse decisions right — the boundaries, the domain model, the data and consistency choices, the resilience at the edges — and stays aggressively simple everywhere else. These eight skills give your AI agent the actual frameworks behind each of those decisions, so the guidance you get is grounded in the canonical books rather than improvised. Install the stack and start with the phase that matches your situation: ``` npx skills add wondelai/skills --all --global ``` Then open your agent and point it at the first decision in front of you — most teams should begin with Clean Architecture and Domain-Driven Design, since boundaries and the domain model are what make every later choice cheap. Work through the phases in order, pulling the data and resilience skills in as real bottlenecks and integration points appear. When you are ready to move from architecture to building it out feature by feature with clean, well-tested code, continue with the sibling guide on [how to create a new app with AI skills](https://skills.wondel.ai/guides/create-a-new-app-with-ai-skills/) — it picks up the validation, implementation, and shipping cadence around the architecture you have just designed. --- # Fix a Conversion Flow That Leaks > A step-by-step playbook for one flow that loses people — landing page, signup, checkout, or in-app onboarding — using AI agent skills from Lean Analytics, Making Websites Win, StoryBrand, $100M Offers, Influence, and The Design of Everyday Things. By Michał Jaskólski · Published 2026-08-30 · Updated 2026-08-30 · 18 min read Canonical: https://skills.wondel.ai/guides/fix-a-conversion-flow-that-leaks/ Skills used: lean-analytics, cro-methodology, storybrand-messaging, hundred-million-offers, influence-psychology, design-everyday-things **TL;DR:** You fix a leaking flow in one order: find the leak with numbers, learn the reason from customers in their own words, then repair message, offer, proof, and friction in that sequence — because cutting friction only pays once somebody wants the thing. Every fix ships as a test with a metric committed before you look. - A number tells you where the flow leaks; only research tells you why — and a fix without a reason behind it is a guess that costs you a test slot. - Motivation before friction: removing form fields from a page whose promise nobody understands moves nothing. - Commit the primary metric, the guardrail, and the sample size before the test runs, or you will find a winner in noise every time. - Install the stack with npx skills add wondelai/skills --all --global, or run the whole sequence with the conversion-optimization journey. There is one flow in your product that costs you more than all the others combined. People arrive at it with intent — they clicked the ad, they picked the plan, they started the signup — and then they leave. Traffic is not the problem, because they got there. The product is not the problem, because they never reached it. Something in the space between arriving and finishing is quietly taking a fraction of every visitor, every day, and unlike a bug it never shows up in an error log. The instinct is to redesign it. Someone suggests a shorter form, someone else wants a new headline, a third person is sure it is the price, and whichever opinion has the most seniority behind it becomes the change. Two weeks later the number is roughly what it was, or slightly worse, and nobody can say why — because four things changed at once and none of them were measured against a prediction. This guide runs the other way round. It fixes one flow, in a fixed order, where each step's output is the next step's input: a number tells you *where* the flow leaks, research tells you *why* people leave at that point, and only then do you touch anything — message first, then offer, then proof, then friction — with each change shipped as a test whose metric was committed before you looked at the result. Each phase is driven by a [skill](https://skills.wondel.ai/skills/): [Lean Analytics](https://skills.wondel.ai/skills/lean-analytics/) finds the leak, [CRO Methodology](https://skills.wondel.ai/skills/cro-methodology/) researches it and later designs the test, [StoryBrand](https://skills.wondel.ai/skills/storybrand-messaging/) fixes the promise, [$100M Offers](https://skills.wondel.ai/skills/hundred-million-offers/) fixes what is being promised, [Influence](https://skills.wondel.ai/skills/influence-psychology/) places the proof, and [The Design of Everyday Things](https://skills.wondel.ai/skills/design-everyday-things/) removes what remains in the way. > Cutting friction only pays once somebody wants the thing. Run the order backwards and you get a faster path to a decision nobody is making. One scoping rule before we start. The unit of work here is a **flow with one action at the end** — a landing page whose job is a demo request, a signup whose job is a created account, a checkout whose job is a paid order, an onboarding whose job is a first real use. If the page you are looking at has three competing calls to action, you do not have a flow yet, you have a menu, and the first fix is to decide what it is for. Everything below assumes that decision is made. ## Phase 1 — Find the leak with numbers, not opinions Start by refusing to guess. The [Lean Analytics](https://skills.wondel.ai/skills/lean-analytics/) skill exists to answer two questions before anyone proposes a change: which step actually loses people, and what single number are we trying to move. Its core discipline is the **One Metric That Matters** — not a dashboard, one number, chosen for the stage you are at and the decision you are about to make — and its sharpest tool is its intolerance for vanity metrics. Pageviews on the checkout page are a vanity metric. Step-to-step completion rate for the same session cohort is not. The output of this phase is a map of the flow with a real number on every transition: how many enter, how many reach each step, how many finish, and where the biggest absolute drop sits. Absolute matters more than percentage here — a step that loses 60% of the 200 people who reach it costs you less than a step that loses 25% of 4,000. Segment it at least once, because aggregate rates hide the interesting failure: mobile versus desktop, new versus returning, paid versus organic. A flow that converts fine on desktop and collapses on mobile is not a messaging problem. > **Prompt** — Use the `lean-analytics` skill to map my checkout funnel step by step from the analytics I'm pasting below, give me the completion rate and absolute drop at each transition, segment by device and traffic source, name the single biggest leak in absolute terms, and tell me which One Metric That Matters I should be moving > (https://skills.wondel.ai/skills/lean-analytics/) If the honest answer is that you have no instrumentation, this phase is where you add it, and that is not a delay — it is the phase. A flow you cannot measure cannot be optimized, only redecorated. Get event tracking on each step transition, wait for enough volume to be meaningful, and resist the temptation to start changing things while the data collects. The skill will also make you write down the current baseline, which matters more than it sounds: without a recorded before, every later claim of improvement is a memory. > **Prompt** — Use the `lean-analytics` skill to my signup flow has no step-level tracking — specify exactly which events I need to instrument to measure drop-off between each step, what properties each event should carry so I can segment later, and how much volume I need before the numbers mean anything > (https://skills.wondel.ai/skills/lean-analytics/) By the end of phase one you should be able to finish this sentence with a number in it: *we lose most people at ____, and the metric we are moving is ____.* Until you can, everything downstream is decoration. ## Phase 2 — Learn why people leave, in their words A number tells you where, never why, and the gap between those two is where most optimization work goes to die. This is the [CRO Methodology](https://skills.wondel.ai/skills/cro-methodology/) skill's first job. Drawn from Karl Blanks and Ben Jesson's *Making Websites Win*, it treats a conversion problem as a **diagnosis before prescription** discipline: the leak is a symptom, the objection is the cause, and you do not get to invent the objection. The method is to gather voice-of-customer evidence at or near the leak and read it for objections in the customer's own language. Exit surveys on the leaking step ("what stopped you from finishing today?"), session recordings of abandoned sessions, support tickets and chat logs mentioning the flow, sales-call notes, and reviews of you and your competitors. What you are looking for is the recurring sentence — the thing five different people said five different ways. That sentence is your objection, and its counter is your fix. > **Prompt** — Use the `cro-methodology` skill to here are 40 exit-survey responses and 15 support tickets about our checkout — cluster them into the distinct objections people actually have, quote the customer's own words for each, rank them by how often they appear and how close they sit to the leaking step, and write the counter-objection for the top three > (https://skills.wondel.ai/skills/cro-methodology/) The skill's second contribution here is the **friction and motivation audit** of the leaking step itself: what is being asked of the visitor at that moment, what they get in return, what they have to believe to continue, and what could go wrong for them if they do. That last one is the anxiety axis and it is chronically underweighted — people abandon checkouts over "will this auto-renew and can I get out" far more often than over one extra form field. > **Prompt** — Use the `cro-methodology` skill to audit the leaking step of my flow — I'll paste the page — for motivation, friction, and anxiety: list everything being asked of the visitor, everything they get, everything they must believe to continue, and every unanswered risk that would make a reasonable person stop, then rank the findings by likely impact > (https://skills.wondel.ai/skills/cro-methodology/) Phase two ends with a written list of ranked objections in customer language, not a list of proposed changes. Resist the urge to jump to fixes here; the next four phases each attack a different class of objection, and knowing which class yours falls into is what tells you where to spend the effort. ## Phase 3 — Make the promise the visitor's, not yours Now the fixes begin, and they begin with the message, because it is the cheapest thing to change and the most likely thing to be wrong. The [StoryBrand](https://skills.wondel.ai/skills/storybrand-messaging/) skill's core move is the one most product copy gets backwards: **the customer is the hero and you are the guide**. Your flow's copy should describe the visitor's desired outcome and what stands between them and it, not your product's cleverness and your team's journey. Apply it to the leaking step specifically, not the whole site. The test is a five-second one: if someone lands on this step cold, can they say what they get, what they have to do, and why it is worth doing? Most leaking steps fail on the first — they describe the mechanism ("connect your data source") instead of the outcome ("see which pages lose money, in about five minutes"). The skill's one-liner structure — character, problem, plan, success — is a useful forcing function for the step's headline and its button label, which should say what happens next rather than "Submit" or "Continue". > **Prompt** — Use the `storybrand-messaging` skill to rewrite the headline, subhead, and button label of my leaking checkout step using the StoryBrand structure — the visitor is the hero, name their desired outcome in their words not our feature language, state the plan in three steps, and make the button describe what happens when they click it > (https://skills.wondel.ai/skills/storybrand-messaging/) There is a second, quieter failure this phase catches: a promise that changes between steps. An ad promising a free trial that lands on a page asking for a card, a plan page saying "cancel anytime" and a checkout that never mentions it again. Every handoff in the flow is a place where the visitor re-evaluates, and an unexplained change of terms at a handoff reads as a bait and switch even when it is an oversight. > **Prompt** — Use the `storybrand-messaging` skill to check my flow for promise drift: here are the ad copy, landing page, plan selection, and checkout step in order — find every place where what we're promising changes, gets quieter, or gets contradicted between steps, and rewrite so the same promise survives to the end > (https://skills.wondel.ai/skills/storybrand-messaging/) ## Phase 4 — Make the offer worth acting on now If the message is clear and people still leave, the problem may not be how you said it — it may be what you are asking them to accept. The [$100M Offers](https://skills.wondel.ai/skills/hundred-million-offers/) skill works the **Value Equation**: perceived value rises with the dream outcome and the likelihood of achieving it, and falls with the time it takes and the effort and sacrifice required. Most weak offers are weak on the bottom half of that equation, and most teams try to fix them by discounting the top. At the conversion point specifically, four levers are available without touching your price. Shorten perceived time-to-value ("your first report in under ten minutes", not "get started"). Reduce effort and sacrifice ("import from your existing tool, no setup"). Raise likelihood of success with a guarantee that names the actual risk the visitor is carrying. And add a bonus that removes an adjacent obstacle rather than padding the box — for a B2B tool, the migration done for you beats a free ebook every time. > **Prompt** — Use the `hundred-million-offers` skill to score my current offer at the conversion point against the Value Equation — dream outcome, perceived likelihood, time delay, effort and sacrifice — then give me three ways to strengthen it that do not involve lowering the price, and write the guarantee that directly answers the top objection from my research > (https://skills.wondel.ai/skills/hundred-million-offers/) The honest caveat: sometimes the offer cannot change. Price is contractual, the guarantee is set by legal, the packaging is fixed for this quarter. That is a real constraint and it narrows this phase to presentation — the same offer described in terms of what the buyer gets rather than what they pay, the annual saving stated as a number rather than a percentage, the guarantee moved from the footer to beside the button. Presentation of a fixed offer is a smaller lever than a better offer, but it is not zero. > **Prompt** — Use the `hundred-million-offers` skill to our price and terms are fixed and cannot change — rewrite how the offer is presented at the conversion point so the same deal reads as stronger: lead with the outcome, quantify the saving, surface the guarantee next to the action, and name what the buyer avoids by acting now > (https://skills.wondel.ai/skills/hundred-million-offers/) ## Phase 5 — Put honest proof where the doubt is By this point the visitor understands the promise and finds the offer reasonable. What stops them now is a private question they are not going to ask you: *is this real, and will I regret it?* The [Influence](https://skills.wondel.ai/skills/influence-psychology/) skill supplies the answer with Cialdini's principles — social proof, authority, liking, commitment and consistency, reciprocity, scarcity, unity — used as a placement problem rather than a decoration problem. Placement is the whole trick. A testimonial wall on the homepage does nothing for someone hesitating at the payment step; the proof has to sit at the point of doubt, and it has to speak to *that* doubt. If the research in phase two said people fear the migration, the proof beside the button is a customer saying the migration took an afternoon — not a logo grid, not a star rating. Match each ranked objection to the specific form of evidence that answers it, and put it where the objection occurs. > **Prompt** — Use the `influence-psychology` skill to map my ranked objections to proof: for each one, tell me which Cialdini principle answers it and what specific evidence to place where — the exact testimonial to quote, the number to show, the credential or guarantee to surface — and mark anything I would need to go and acquire because we don't have it yet > (https://skills.wondel.ai/skills/influence-psychology/) The skill is equally clear about the limit, and this matters more in a checkout than anywhere else on your site. Manufactured scarcity, fake countdown timers, invented "12 people are viewing this" counters, and testimonials with stock photos are not persuasion — they are a short-term lift bought with long-term trust, and they are increasingly illegal in consumer contexts. The version that works is scarcity that is true, urgency with a real reason, and social proof from real named people. If you have little proof yet, the correct move is a plan to acquire it, not to fabricate it. > **Prompt** — Use the `influence-psychology` skill to audit my checkout for dishonest persuasion — fake urgency, invented scarcity, vague or unattributed social proof, pressure patterns — flag each one, explain the trust cost, and replace it with an honest equivalent that does the same job > (https://skills.wondel.ai/skills/influence-psychology/) ## Phase 6 — Remove what stands between deciding and doing Only now, with a visitor who wants the thing, does friction removal pay. The [Design of Everyday Things](https://skills.wondel.ai/skills/design-everyday-things/) skill governs this phase because the failures here are not aesthetic — they are gulfs of execution and evaluation. The gulf of execution is the distance between what the visitor wants to do and what the interface lets them do; the gulf of evaluation is the distance between what the system did and what the visitor can tell it did. In a leaking flow these show up as a small, boring, expensive list: a required field with no explanation of why it is required, an error message that says "invalid input" without saying which input or what would be valid, a card form that rejects spaces in the number, a submit button that gives no feedback so it gets clicked three times, a step with no visible progress so the visitor cannot tell whether they are two fields or twenty from finishing. Each one is worth a fraction of a percent, and there are usually a dozen of them. > **Prompt** — Use the `design-everyday-things` skill to walk my checkout flow as a first-time user and find every gulf of execution and evaluation: unexplained required fields, errors that don't say what would be valid, missing feedback after an action, invisible progress, controls whose affordance doesn't match what they do — then give me the fixes in order of how many people each one plausibly costs > (https://skills.wondel.ai/skills/design-everyday-things/) Two specific applications deserve their own pass because they carry disproportionate weight. **Error recovery**: errors should be prevented by constraints where possible (input masks, sensible defaults, forgiving parsing), and where they happen, the message should name the problem, name the fix, and preserve everything the user already typed. **Mobile reality**: run the flow on a real phone on a real connection, because the desktop version of a form is not the same artifact as the thumb-driven one, and phase one's segmentation probably already told you that. > **Prompt** — Use the `design-everyday-things` skill to redesign the error handling in my signup form: replace prevention-by-validation-message with constraints where possible, rewrite every error to name the problem and the fix in the user's language, make sure no error clears fields the user already filled, and tell me which errors should never have been possible to trigger > (https://skills.wondel.ai/skills/design-everyday-things/) ## Phase 7 — Prove the fix worked You now have a stack of changes. Shipping them together is how you learn nothing. The last phase returns to [CRO Methodology](https://skills.wondel.ai/skills/cro-methodology/) for test design, and its central rule is that **the metric is committed before the result is seen**. Write the hypothesis as a sentence — because research says *X*, changing *Y* should move *Z* by roughly *N* — then fix the primary metric, one guardrail metric, the sample size, and the stop date, and do not look before you get there. The guardrail is the part teams skip and regret. A change that lifts checkout completion while raising refunds has not worked; a signup change that lifts registrations while dropping activation has moved a number, not the business. Pick the downstream metric your change could plausibly damage and commit to watching it alongside the one you are trying to move. > **Prompt** — Use the `cro-methodology` skill to turn my prioritized fixes into a test plan: for each one write the hypothesis in because-changing-should form, name the primary metric and one guardrail, calculate the sample size and runtime I need at my traffic level, and order the tests so the highest-expected-value one runs first > (https://skills.wondel.ai/skills/cro-methodology/) If your traffic cannot reach significance — and for most flows below a few thousand entries a week, it cannot — the answer is not to run an underpowered test and believe the result. It is to switch evidence types honestly: pre-committed before-and-after windows of equal length, qualitative validation with five to eight users against a stated prediction, and a bias toward bold changes over small ones, because only a large effect is detectable at low volume. State which mode you are in, and stop calling it an A/B test when it is not. > **Prompt** — Use the `cro-methodology` skill to we get about 400 checkout starts a week, which is too few for a normal A/B test — design an honest evaluation plan instead: what before/after windows to use, which qualitative evidence to collect and from how many people, what effect size would be big enough to detect, and what would make me revert > (https://skills.wondel.ai/skills/cro-methodology/) ## Your checklist Work down this list in order. Each item assumes the one above it is done. - **Leak located.** You can name the step that loses the most people in absolute terms, segmented at least by device and source, with a recorded baseline. - **One metric named.** A single number defines success for this flow, and everyone working on it agrees what it is. - **Objections researched.** You have a ranked list of reasons people leave, quoted in customer language, from at least two evidence sources. - **Promise fixed.** The leaking step states the visitor's outcome in five seconds, and the promise does not change between steps. - **Offer strengthened.** The Value Equation has been worked at the conversion point, or presentation has been fixed where the offer is locked. - **Proof placed.** Every top objection has honest evidence sitting where that objection occurs, and no manufactured urgency survives. - **Friction removed.** Errors name the fix, feedback follows every action, progress is visible, and the flow has been completed on a real phone. - **Tests committed.** Each shipped change has a written hypothesis, a primary metric, a guardrail, a sample size, and a stop date fixed in advance. ## Common mistakes **Redesigning the whole page.** A redesign changes twenty things and teaches you nothing about which mattered. Worse, it usually reverts accumulated small wins nobody documented. Change what the research pointed at. **Cutting friction first.** It is the most satisfying phase and the least effective one when run early. A three-field form for something nobody wants converts about as badly as a nine-field one. **Copying a competitor's flow.** Their flow was shaped by their traffic, their price, their objections and their brand — and you are seeing the current version, not the tests that produced it. It is a source of hypotheses, never a source of answers. **Optimizing a step that is not the leak.** Teams work on the step they can see rather than the step that costs them, which is usually one they never look at because so few people reach it. **Peeking at running tests.** Checking a test daily and stopping when it looks good is a reliable way to ship noise. That is what the pre-committed stop date is protecting you from. **Fixing the flow and ignoring the traffic.** If a channel sends people who were never going to buy, the flow is not what is broken. Phase one's segmentation is what tells you the difference. ## Frequently asked questions ### How is this different from a general website audit? Scope. A site audit looks at everything — every page's message, speed, structure and search visibility — and returns a broad list. This guide takes one flow with one action at the end and works it to a measured result. Use [Improve an Existing Website](https://skills.wondel.ai/guides/improve-an-existing-website-with-ai-skills/) when the whole site needs a pass. Use this when you already know which flow is costing you and want it fixed properly rather than surveyed. ### Do I need real traffic for this to be worth running? You need enough to see where people drop, which is far less than you need to A/B test. Even a few hundred sessions through a flow will show you the step that loses the most people, and phases two through six are qualitative — objections, message, offer, proof, friction — so they work at any volume. What low traffic changes is the last phase: you evaluate with pre-committed before-and-after windows and user sessions instead of split tests, and you make bigger changes because only large effects are detectable. ### Why does message come before offer, and offer before proof? Because each answers a different question and they are asked in that sequence. Message answers "is this for me and what do I get" — if that fails, nothing later is even read. Offer answers "is what I get worth what it costs me" — a clear promise for a bad deal still loses. Proof answers "is this real" — which is only a question once someone wants the deal. Friction answers "can I actually do it", which only matters for someone who has decided. Reordering means fixing answers to questions the visitor never reached. ### What if the research says people leave because of the price? Take it seriously but read it carefully, because "too expensive" is the most common thing people say and the least reliable thing they mean. It usually means the value was not established, the risk was not removed, or the comparison was against the wrong alternative. Phase four is where you test that: strengthen the value side of the equation, add a guarantee that names the real risk, and see whether the objection survives. If it does after that work, you have a genuine pricing question, and [Monetizing Innovation](https://skills.wondel.ai/skills/monetizing-innovation/) is the skill for it. ### Can I run this on an in-product onboarding rather than a marketing page? Yes — the unit of work is any flow with one action at the end, and an onboarding qualifies. What changes is the evidence: product analytics and session recordings rather than page funnels, and phase six carries more weight because the friction lives in the interface rather than the form. If the concern is the whole product's engagement rather than one flow, [Improve an Existing App](https://skills.wondel.ai/guides/improve-an-existing-app-with-ai-skills/) is the better fit. ## Start with the number The temptation is to start with the fix, because the fix is the fun part and everyone has one in mind. Start with the number instead. An hour spent mapping the flow and reading forty exit surveys will tell you which of the next five phases actually applies to you, and will save you from the redesign that changes everything and moves nothing. Install the library with `npx skills add wondelai/skills --all --global` and work the phases in order — or hand the whole sequence to the [Conversion Optimization](https://skills.wondel.ai/skills/conversion-optimization/) journey, which asks you the decision questions at each phase and records the answers in your project's `docs/` folder so the work survives between sessions. --- # Make a Slow App Measurably Faster > An engineering playbook for a codebase that ships and earns but has grown slow and tangled — baseline, boundaries, hot paths, the real bottleneck, and the query layer — using AI agent skills from Working Effectively with Legacy Code, Clean Architecture, A Philosophy of Software Design, Refactoring, Release It!, and Designing Data-Intensive Applications. By Michał Jaskólski · Published 2026-08-30 · Updated 2026-08-30 · 20 min read Canonical: https://skills.wondel.ai/guides/make-a-slow-app-measurably-faster/ Skills used: working-with-legacy-code, clean-architecture, software-design-philosophy, refactoring-patterns, system-design, ddia-systems, release-it, pragmatic-programmer **TL;DR:** You make a working system faster in a fixed order: pin behavior and measure a baseline before touching anything, restore the boundaries that drifted, reshape the hot paths in named steps, then fix the measured bottleneck and the query layer. Every optimization cites its baseline and lands in a before/after ledger — anything that misses gets reverted, not kept. - Unmeasured optimization targets the wrong 97% of the code — the profiler decides what you work on, not intuition. - Never restructure unpinned code: characterization tests are what make a behavior-preserving change actually behavior-preserving. - Most latency you can control lives in the data layer — N+1 queries, missing indexes, and unbounded result sets beat clever algorithms. - Install the stack with npx skills add wondelai/skills --all --global, or run the whole sequence with the architecture-optimization journey. This is not the guide for a prototype. This is the guide for a system that works: it ships, it has customers, it makes money, and every quarter it is a little slower than the last. The p95 on the main endpoint has crept from 200ms to 900ms over eighteen months and no single commit did it. The database bill grows faster than the user count. A feature that would have taken two days last year takes a week now, because the code that used to be one thing has become four things wearing a trench coat. Nobody can point at the cause, because there isn't one — there are two hundred, and most of them were reasonable at the time. The reflex response is a rewrite, and the second reflex is a week of "performance work" where everybody optimizes the part of the code they personally find annoying. Both fail the same way: they spend real effort on code that was never the problem. Donald Knuth's line about premature optimization is quoted to death and usually misquoted — the point was never that optimization is bad. It is that you cannot know which 3% of the code matters until you measure, and unmeasured effort goes into the other 97% by default. So this guide runs on two rules that gate everything else: **measure before optimizing, pin before restructuring.** The profiler decides what you work on. The safety net decides what you are allowed to touch. Each phase is driven by a [skill](https://skills.wondel.ai/skills/): [Working with Legacy Code](https://skills.wondel.ai/skills/working-with-legacy-code/) builds the net and the baseline, [Clean Architecture](https://skills.wondel.ai/skills/clean-architecture/) and [A Philosophy of Software Design](https://skills.wondel.ai/skills/software-design-philosophy/) fix the structure that made it slow to change, [Refactoring](https://skills.wondel.ai/skills/refactoring-patterns/) reshapes the hot paths safely, [System Design](https://skills.wondel.ai/skills/system-design/) and [Data-Intensive Apps](https://skills.wondel.ai/skills/ddia-systems/) find and fix the real bottleneck, [Release It!](https://skills.wondel.ai/skills/release-it/) keeps it stable under stress, and [The Pragmatic Programmer](https://skills.wondel.ai/skills/pragmatic-programmer/) turns the result into budgets that hold. > A change that does not move the number it targeted is not an improvement you keep. It is a diff you revert. ## Phase 1 — Pin the behavior, then measure the baseline Two things have to exist before anything changes, and neither is a code change. The first is a **safety net**: characterization tests over the code you intend to touch. The [Working with Legacy Code](https://skills.wondel.ai/skills/working-with-legacy-code/) skill defines legacy code as code without tests, which makes a hot path with no coverage legacy code no matter how recently it was written. Its recipe is mechanical — call the code, assert something you know is wrong, run it, read the real output from the failure, pin that value. You are not judging the behavior, you are photographing it, so that when you restructure, an unintended change announces itself as a red test instead of as a 3am page. The obstacle is always the same: the hot path constructs its own dependencies, so you cannot substitute anything. The skill's answer is **seams** — the least invasive being Parameterize Constructor with a production default, so every existing caller compiles untouched while a test can pass in a fake. > **Prompt** — Use the `working-with-legacy-code` skill to get the three slowest endpoints in this codebase under characterization tests before I optimize them: find the seams where they construct their own dependencies, parameterize the constructors with production defaults so no caller changes, and pin the current behavior including the responses I might think are wrong > (https://skills.wondel.ai/skills/working-with-legacy-code/) The second thing is a **baseline with real numbers**. Not "it feels slow" — p50, p95 and p99 per endpoint under production-like load, the slow query log, an actual CPU or wall-clock profile of the worst offender, and the current infrastructure cost. Write them down with the date. Everything from here cites this document, and the single most common failure of performance work is that nobody recorded the before, so every later claim is a memory. > **Prompt** — Use the `working-with-legacy-code` skill to I need a performance baseline before optimizing: tell me exactly what to capture for each hot endpoint — latency percentiles, query counts and timings, allocation or CPU profile, throughput ceiling — how to capture it under production-like load rather than on my laptop, and what to record so a before/after comparison later is honest > (https://skills.wondel.ai/skills/working-with-legacy-code/) Phase one ends with two artifacts: a map of what is pinned and what is not, and a numbers document. Both gate everything after. If a later phase wants to touch code outside the safety net, it pins it first or it does not touch it. ## Phase 2 — Find where the boundary drifted With the net in place, look at structure before you look at speed — because in a system that grew, the structural drift and the slowness are usually the same fact seen from two angles. The [Clean Architecture](https://skills.wondel.ai/skills/clean-architecture/) skill's single rule is the **Dependency Rule**: source-code dependencies point inward, from frameworks and drivers toward use cases and entities, never outward. A system that once obeyed it and now does not will have business rules that import the ORM, entities that know about HTTP, and use cases that cannot be exercised without booting the framework. That drift has a direct performance cost, and it is not abstract. When business logic lives inside an ORM model, the code that decides *what* to fetch is tangled with the code that decides *how*, so nobody can see that a rule fires one query per item in a loop. When a use case can only run inside a request, you cannot profile it in isolation, so you profile the whole request and learn nothing specific. Restoring the boundary is what makes the next four phases possible. > **Prompt** — Use the `clean-architecture` skill to audit this codebase against the Dependency Rule: find every place a business rule imports the framework, ORM, or HTTP layer, mark the components whose dependencies point outward, and give me the smallest set of moves that restores an inward-pointing boundary around the business rules on my three hottest paths > (https://skills.wondel.ai/skills/clean-architecture/) The skill is also the right tool for deciding what *not* to do. A boundary is a cost as well as a benefit, and a system that grew slow does not need every module inverted behind an interface. Draw the boundary where the volatility is — around the things you have replaced or expect to replace — and leave the stable parts alone. Over-boundarying a system in the name of cleanliness is its own performance problem, paid in indirection. > **Prompt** — Use the `clean-architecture` skill to tell me where a boundary is worth paying for in this codebase and where it isn't: rank the candidate seams by how volatile the thing behind them actually is, and flag any existing abstraction that only has one implementation and has never changed, because that's indirection we're paying for and not using > (https://skills.wondel.ai/skills/clean-architecture/) ## Phase 3 — Check whether the structure itself is the complexity Structure has a second axis, and [A Philosophy of Software Design](https://skills.wondel.ai/skills/software-design-philosophy/) supplies it. John Ousterhout's central idea is **deep modules**: a module's value is its interface area divided by the functionality it hides. A deep module presents a small interface over substantial work. A shallow one presents an interface nearly as complicated as the thing it wraps, which means it adds cost without removing any. Codebases that grew under time pressure accumulate shallow modules — the pass-through service that calls one repository method, the "helper" that takes eight parameters and switches on three of them, the layer that exists because the previous architect said layers were good. Each one is a place where a caller must understand two things instead of one, and collectively they are why a two-day feature now takes a week. The skill's related idea, **information leakage**, catches the other half: when the same design decision appears in three modules, changing it means changing all three, and eventually someone changes two. > **Prompt** — Use the `software-design-philosophy` skill to find the shallow modules in this codebase: interfaces nearly as complex as their implementations, pass-through wrappers that add no abstraction, and helpers with more configuration parameters than behavior — then find the information leakage, where one design decision is duplicated across modules, and tell me which to collapse and which to deepen > (https://skills.wondel.ai/skills/software-design-philosophy/) Ousterhout's rule of **tactical versus strategic programming** is the one to internalize for the rest of this guide. Tactical programming optimizes for getting this change done; strategic programming spends a small, deliberate extra effort each time to keep the design good. Every slow, tangled codebase is a record of tactical decisions that were each individually correct. The point of this phase is not to atone for that but to decide, explicitly, which parts you are switching to strategic mode for — usually the hot paths, and usually only those. ## Phase 4 — Reshape the hot paths in named steps Now you may change the shape of the code the profiler pointed at, and the [Refactoring](https://skills.wondel.ai/skills/refactoring-patterns/) skill governs how. Martin Fowler's definition matters here more than usual: a refactoring is a **behavior-preserving transformation applied in small named steps with the tests green between each one**. Not "cleaning up". Not "while I'm in here". A named move, applied, tested, committed. For hot paths the useful catalogue is small. Extract Function to name a step so you can measure it separately. Replace Loop with Pipeline, or the reverse, when one allocates and the other does not. Introduce Parameter Object when a signature has grown to seven arguments and half the callers pass defaults. Replace Conditional with Polymorphism when a switch on type is executed a million times a day. Move Function when logic sits in the wrong module and forces a data round trip to get what it needs. > **Prompt** — Use the `refactoring-patterns` skill to here is our slowest request handler with its characterization tests — reshape it using named refactorings from the catalogue, one at a time, keeping behavior identical: name each refactoring you apply, show the code after each step, and stop before any change that would alter observable behavior so I can review it separately > (https://skills.wondel.ai/skills/refactoring-patterns/) The discipline that makes this safe is the **separate commits rule**: a commit either changes structure or changes behavior, never both. When a commit is purely structural and a test goes red, the test is telling you unambiguously that you broke something, and you can revert one small thing. When the two are mixed, every failure is a debate. Optimization commits are a third category — they change behavior only in timing, and they cite the baseline they target. > **Prompt** — Use the `refactoring-patterns` skill to review this branch and split it into separate commits by kind: pure structural refactorings with behavior identical, behavior changes, and optimizations that cite a baseline — tell me which changes are currently mixed together in one commit and how to separate them without losing the work > (https://skills.wondel.ai/skills/refactoring-patterns/) ## Phase 5 — Ask the measured load what the bottleneck is Now go back to the numbers. The [System Design](https://skills.wondel.ai/skills/system-design/) skill's contribution is **back-of-the-envelope honesty**: estimate before you architect, and compare the estimate to what you measured. Requests per second at peak, payload sizes, working-set size against available memory, the latency budget of a single request split across its components. Most "we need to scale" conversations end quietly when someone works out that the system handles 40 requests per second and a single modern machine handles thousands. The output of this phase is a ranked list of bottlenecks with the cheapest viable fix beside each. The order that usually falls out is unglamorous and correct: fix the query before you add a cache, add a cache before you add a queue, add a queue before you add a service. Each step up that ladder buys latency at the cost of a new failure mode and a new thing to operate — a cache introduces invalidation and staleness, a queue introduces ordering and retry semantics, a service introduces a network call that can hang. > **Prompt** — Use the `system-design` skill to here are my measured numbers — peak RPS, p95 per endpoint, payload sizes, data volume, and the current infrastructure — do the back-of-the-envelope math on where the ceiling actually is, rank the bottlenecks by how much latency each contributes, and for each one give me the cheapest fix that would work plus the operational cost it adds > (https://skills.wondel.ai/skills/system-design/) Caching deserves a specific warning because it is the most over-applied fix in this phase. A cache in front of a slow query hides the slow query; it does not remove it, and the first cold cache after a deploy or an eviction gives you the original latency at the worst possible moment, often with a thundering herd on top. Cache what is genuinely expensive and genuinely reusable, after the query itself is as fast as it reasonably gets — not instead of fixing it. > **Prompt** — Use the `system-design` skill to I'm about to add caching to hide a slow endpoint — talk me out of it or into it: what would the query cost after proper indexing, what's the realistic hit rate given our access pattern, what happens on cold start and eviction, and what invalidation would we owe? Then tell me whether to cache, and at which layer > (https://skills.wondel.ai/skills/system-design/) ## Phase 6 — Fix the data layer, where the latency actually lives In most applications that got slow, the answer is here, and [Data-Intensive Apps](https://skills.wondel.ai/skills/ddia-systems/) is the skill for it. Martin Kleppmann's material covers storage engines, indexing, replication, partitioning and transaction isolation — and the practical top of the list is short and boring. **N+1 queries** are the single most common cause of an endpoint that got slower as the product grew: one query for a list, then one per item, so latency scales with content and nobody notices until a customer has 500 of something. **Missing or wrong indexes** are the second: a query that scans a table which had 10,000 rows at launch and has 10 million now. **Unbounded result sets** are the third — an endpoint with no pagination that was fine when the biggest account had 40 records. **Over-fetching** is the fourth: selecting every column, including the large text one, to render a list that shows two fields. > **Prompt** — Use the `ddia-systems` skill to audit my data access on the three hottest endpoints: find every N+1 pattern and show the eager-loading or batched fix, list the queries doing full scans with the index each one needs and the write cost that index adds, flag every unbounded query that should be paginated, and find the selects fetching columns the response never uses > (https://skills.wondel.ai/skills/ddia-systems/) Then the correctness half, which matters the moment you start making things concurrent to make them fast. Isolation levels are not a detail: read-committed, the default in most databases, permits lost updates on read-modify-write cycles, which is exactly what a naive counter, a balance, or an inventory decrement is. If your fast new path lets two requests do that at once, you have traded latency for a data bug that appears under exactly the load you were optimizing for. > **Prompt** — Use the `ddia-systems` skill to review every read-modify-write in this codebase against our database's isolation level: find the ones that can lose updates or double-apply under concurrency, and for each show the fix — atomic update, SELECT FOR UPDATE, a compare-and-set with a version column, or a uniqueness constraint that makes the bad state impossible > (https://skills.wondel.ai/skills/ddia-systems/) ## Phase 7 — Stay fast when something else is slow A system tuned to be fast in the happy path can still fall over the first time a dependency degrades, and it usually fails worse than a slow system would. [Release It!](https://skills.wondel.ai/skills/release-it/) is the skill for this, and Michael Nygard's central observation is that **the worst failures come from things that are slow rather than down**. A dead dependency fails fast and you handle it. A dependency answering in 30 seconds holds every thread that called it, and the queue behind them, until your service is unavailable for reasons that have nothing to do with your code. The patterns are specific and cheap. Every outbound call gets a timeout — an unbounded call is a resource leak with a slow fuse. Every critical dependency gets a circuit breaker, so repeated failures stop being retried into the ground and start failing fast with a degraded response. Bulkheads keep one slow integration from consuming the whole thread or connection pool. And back-pressure with a bounded queue is what stops a burst from turning into an out-of-memory crash. > **Prompt** — Use the `release-it` skill to audit every outbound call in this service for stability: list the calls with no timeout or an unreasonable one, the retries with no backoff or jitter that would amplify an outage, the shared pools where one slow dependency can starve everything else, and the unbounded queues — then give me the fixes with concrete values for our traffic > (https://skills.wondel.ai/skills/release-it/) This phase is not judged on latency. Adding a circuit breaker will not make the p95 lower on a good day; it is what stops the p95 becoming a timeout on a bad one. Judge it by its own done-when: no unbounded call, no unbounded queue, no shared pool without a bulkhead, and a documented degraded mode for each critical dependency. ## Phase 8 — Turn the gains into budgets that hold Performance work that is not defended decays, because the next feature is written by someone who does not know what any of the numbers cost to earn. [The Pragmatic Programmer](https://skills.wondel.ai/skills/pragmatic-programmer/) supplies the habits that make the gains durable, and the mechanism that matters most here is turning a measurement into a gate. Write the budgets down as numbers — p95 per critical endpoint, maximum queries per request, maximum payload size — and enforce them in CI, so a regression fails a build instead of arriving as a support ticket in six weeks. Add the query-count assertion to the tests for hot endpoints, because that single check catches the N+1 that a future ORM relationship will reintroduce. Keep the optimization ledger: every change, its baseline, its after, and whether it was kept. > **Prompt** — Use the `pragmatic-programmer` skill to set up performance guardrails for this repo: define the budgets from our current measured numbers, write the CI checks that fail a build when p95 or query count regresses on the hot endpoints, add query-count assertions to the tests for those endpoints, and give me the ledger format for recording every optimization's before and after > (https://skills.wondel.ai/skills/pragmatic-programmer/) The skill's broader themes — DRY as being about knowledge rather than code, tracer bullets over big-bang delivery, orthogonality, and knowing what you actually own — are what stop the next eighteen months from recreating the situation you just spent a quarter fixing. ## Your checklist Work down in order; each item assumes the ones above it. - **Behavior pinned.** Every hot path you intend to change has characterization tests, and what is not pinned is written down as such. - **Baseline recorded.** Latency percentiles, query counts, a real profile, and current cost — dated, under production-like load. - **Boundary restored.** Business rules on the hot paths no longer depend on the framework, and you can exercise them without booting it. - **Shallowness removed.** Pass-through modules collapsed, leaked design decisions consolidated, hot paths readable enough to optimize. - **Hot paths reshaped.** Named refactorings only, tests green between steps, structural and behavioral changes in separate commits. - **Bottleneck identified.** A ranked list with the cheapest viable fix beside each, arrived at from measured load rather than intuition. - **Data layer fixed.** No N+1 on hot paths, indexes match the real queries, everything paginated, read-modify-write cycles safe under concurrency. - **Degradation handled.** Timeouts everywhere, circuit breakers on critical dependencies, bulkheads on shared pools, a documented degraded mode. - **Budgets enforced.** Numbers in CI, query-count assertions on hot endpoints, and a ledger where every optimization shows its before and after. ## Common mistakes **Optimizing without a profile.** The intuition about which code is slow is wrong far more often than it is right, and the code that looks worst is rarely the code that costs most. **Caching instead of fixing.** A cache over a bad query is a bad query that now also has an invalidation problem and a cold-start cliff. **Rewriting instead of measuring.** A rewrite reproduces the old system's behavior imperfectly at enormous cost, and the new one is slow in different places you have not measured yet. **Restructuring unpinned code.** "Behavior-preserving" is a claim, and without tests it is an unverified one. This is how a performance sprint produces an incident. **Mixing structure, behavior, and optimization in one commit.** Every subsequent failure becomes ambiguous and every revert becomes surgery. **Keeping a change that missed its number.** If it did not beat the baseline it cited, it is complexity you are now maintaining for nothing. Revert it and write down what you learned. **Scaling out before scaling the query.** Adding machines to hide a full table scan is the most expensive way to not fix a problem. ## Frequently asked questions ### How is this different from the technical-debt guide? Aim. [Refactor a Codebase Buried in Technical Debt](https://skills.wondel.ai/guides/refactor-a-codebase-buried-in-technical-debt/) is for a codebase that people are afraid to change: the goal is making it safe to touch again, module by module, while the team keeps shipping. This guide assumes the code broadly works and asks a narrower question — where is the time actually going, and what is the cheapest thing that removes it. Structure work appears here as a means to speed, not as the goal. If your complaint is "it is slow", start here. If it is "we cannot change it", start there. ### Do I need all eight phases, or can I go straight to the database? You can go straight there, and sometimes it is right — if the profile says one unindexed query is 80% of your p95, fix it today. What phase one is non-negotiable about is having that profile and having the path pinned before you change it. The structural phases earn their place when the same slow pattern keeps coming back: an N+1 is usually a boundary problem, and a hot path nobody can read is a hot path nobody can safely change. Defer them if time is short; record that you deferred them and why. ### What does "measure before optimizing" mean in practice for a small team? Less than you think. It means production-like load rather than your laptop, latency percentiles rather than an average, a query count per request, and one real profile of the worst endpoint — captured once, written down with the date. That is an afternoon, not a project. The average is the part worth insisting on: a mean latency of 300ms can hide a p99 of nine seconds, and the p99 is what your loudest customers experience every day. ### Why is the resilience work judged differently from the rest? Because it is not supposed to make anything faster. Timeouts, circuit breakers and bulkheads change what happens when something else fails, so measuring them against a latency delta on a healthy day would score them as useless. They are judged by their own condition: no unbounded call, no unbounded queue, no shared pool without a bulkhead, and a stated degraded mode for each critical dependency. The same applies to CI budgets, which exist to protect gains rather than produce them. ### Our slowness is in the front end, not the server. Does this apply? Partly. The measure-first and pin-first rules transfer directly, and [High Performance Browser Networking](https://skills.wondel.ai/skills/high-perf-browser/) is the skill for the transport side — connection setup, protocol overhead, what actually blocks a first render. But if the complaint is a marketing site's page-load score rather than an application's endpoint latency, [Improve an Existing Website](https://skills.wondel.ai/guides/improve-an-existing-website-with-ai-skills/) covers Core Web Vitals as part of a broader pass and is the better starting point. ## Start with the baseline The quarter of performance work that produces nothing always starts the same way: with a change. Somebody had a theory, the theory was plausible, and by the time anyone asked what it was supposed to move there was no before to compare against. An afternoon spent capturing percentiles, query counts and one honest profile is what separates that quarter from the one where every change has a number beside it. Install the library with `npx skills add wondelai/skills --all --global` and work the phases in order — or hand the whole sequence to the [Architecture Optimization](https://skills.wondel.ai/skills/architecture-optimization/) journey, which asks you the decision questions at each phase and keeps the baseline, the ledger and the safety-net map in your project's `docs/` folder so the work survives between sessions.