The current generation of AI coding agents makes it surprisingly easy to create a "skill." Write a Markdown file. Add instructions. Give it a name. Put it inside .claude/skills/. Done. Except it isn't. As soon as you build more than a handful of skills, a different set of problems appears: Which skill should activate? Why did two skills activate at the same time? Why did the agent ignore an important instruction? What belongs in a skill versus a rule, agent, hook, or script? How much context should the skill load? How do you test whether the skill actually works? What happens when the underlying framework changes? How do you distribute skills? How do you retire obsolete skills? How do you prevent dozens of skills from becoming an unmaintainable mess? At that point, AI skills stop looking like prompts and start looking like software systems. A production-grade AI skill is not merely a Markdown prompt. It is a versioned, testable, routable, enforceable software component with a defined lifecycle. 1. The Skill Lifecycle A useful way to understand an AI skill is to look at its entire lifecycle: Runtime ↓ Scope / Fit ↓ Triggers ↓ Architecture ↓ Anatomy ↓ Content ↓ Enforcement ↓ Measurement ↓ Shipping ↓ Maintenance ↓ Portfolio Each stage answers a different question: Stage Core question Runtime How does the skill load and execute? Fit & scope Should this be a skill at all? Typing & triggers When should it activate? Architecture How should the workflow operate? Anatomy What files make up the skill? Content How should instructions be written? Enforcement What can be enforced mechanically? Measurement How do we know it works? Shipping How do users receive it? Maintenance How does it survive change? Portfolio How do many skills coexist? The important insight is that skill engineering covers the entire lifecycle, not just the writing of SKILL.md. 2. Chapter 00 — How Skills Load and Run Before designing a skill, understand the runtime. A skill may look simple on disk: .claude/ └── skills/ └── code-review/ └── SKILL.md But conceptually the runtime does something like: User request ↓ Skill discovery ↓ Trigger evaluation ↓ Skill activation ↓ Instruction loading ↓ Reference/tool loading ↓ Agent execution ↓ Result The important question is: What does the agent actually see, and when does it see it? This matters because context is limited. A skill might contain: SKILL.md references/ database.md security.md examples.md architecture.md scripts/ validate.js check.sh templates/ report.md You usually don't want every file loaded for every request. Instead: Request ↓ SKILL.md ↓ Determine relevant task ↓ Load relevant reference ↓ Execute required script This is progressive context loading. The main skill file acts as an entry point rather than a giant knowledge dump. Context Is a Resource One of the biggest mistakes in AI skill design is treating context as free. It isn't. Design A — Everything in one file SKILL.md ────────────── 3000 lines 50 examples 20 rules 10 workflows 15 edge cases Design B — Layered knowledge SKILL.md ↓ Routing ↓ references/ ├── workflow.md ├── security.md └── examples.md The second design gives you more control over what enters the model's context. Design skills around context boundaries, not just file boundaries. 3. Chapter 01 — Fit and Scope The next question is: Should this behavior be implemented as a skill? AI development environments often provide multiple primitives: Skill Rule Agent Hook Script Plugin They are not interchangeable. Skill A skill describes how to perform a class of task. Example: database-migration It might define: 1. Inspect schema 2. Inspect migration history 3. Design migration 4. Implement migration 5. Validate migration 6. Test rollback Rule A rule is a constraint: Never modify production data directly. That is policy, not a workflow. Agent An agent is useful when you need a distinct reasoning or execution role: Main Agent ├── Research Agent ├── Security Agent └── Testing Agent Hook A hook responds to an event: Before tool call ↓ Security check or: After file modification ↓ Formatter Script A script performs deterministic computation: validate-schema.js The AI may decide when to run it. The script determines how validation works. 4. The Boundary Is More Important Than the Skill A good skill should explicitly state what it does not do. For example: This skill handles: - PostgreSQL schema migrations - Migration generation - Migration validation - Rollback testing This skill does not handle: - Application architecture - Production deployment - Database backups - Infrastructure provisioning Why? Because skills tend to grow. A developer starts with: database migration Then adds: database design query optimization backup strategy production deployment Eventually the skill becomes: database-engineering-everything and becomes difficult to reason about. Scope is a defense against skill inflation. 5. Chapter 02 — Typing and Triggers Once you know what a skill does, you need to answer: When should it activate? Imagine: frontend-review backend-review security-review performance-review database-review The user says: "Review my authentication API." Multiple skills may be relevant. You now have a routing problem: User request │ ┌─────────────┼─────────────┐ ↓ ↓ ↓ Backend Security Performance If everything activates, the system becomes noisy. If nothing activates, the skill is useless. Activation Is a Classification Problem Think of activation as: User request ↓ Intent classification ↓ Skill candidates ↓ Relevance evaluation ↓ Activation Example: Request Expected skill "Create a PostgreSQL migration" Database migration "Fix this React component" Frontend "Audit authentication" Security "Why is this query slow?" Database performance "Write a technical article" Documentation A good skill therefore needs a clear activation signature. False Positives and False Negatives False positive "Write a blog about PostgreSQL" → security skill activates False negative "Why is my PostgreSQL migration failing?" → database migration skill does not activate Both are important. Therefore, evaluate activation separately from execution. 6. Chapter 03 — Shape and Architecture Once a skill activates, what does it actually do? There are several useful workflow shapes. Route A route chooses a path: Request ↓ classify / | / | Bug Feature Refactor ↓ ↓ ↓ Debug Implement Refactor Pipeline A pipeline is sequential: Research ↓ Analyze ↓ Plan ↓ Implement ↓ Test ↓ Review ↓ Report This is particularly useful for engineering skills. Loop A loop supports iteration: Implement ↓ Test ↓ Failed? / Yes No ↓ ↓ Fix Complete ↓ Test again For coding agents, this is natural: Write implementation ↓ Run tests ↓ Read failure ↓ Modify implementation ↓ Run tests again Failure becomes an expected workflow state rather than an exceptional event. Map A map splits a problem into independent pieces: Research repository │ ┌─────────────┼─────────────┐ ↓ ↓ ↓ Frontend Backend Database ↓ ↓ ↓ Findings Findings Findings └─────────────┼─────────────┘ ↓ Synthesis Combining Shapes Real skills often combine these patterns: Route ↓ Pipeline ↓ Map ↓ Loop ↓ Final report This is where AI skills start looking like workflow engines rather than prompts. 7. Chapter 04 — Anatomy A mature skill might look like: skills/ └── deep-research/ │ ├── SKILL.md │ ├── references/ │ ├── research-methodology.md │ ├── source-evaluation.md │ └── evidence.md │ ├── scripts/ │ ├── validate-sources.js │ └── generate-report.js │ ├── templates/ │ └── report.md │ └── examples/ ├── example-1.md └── example-2.md Each part has a job. SKILL.md Is the Hub Think of SKILL.md as the router and operating manual. It should explain: What this skill does When it activates What it must accomplish What references to load What workflow to follow What constraints apply How to validate the result It should not necessarily contain every piece of knowledge. Hub-and-Spoke Architecture SKILL.md / | / | ↓ ↓ ↓ References Scripts Templates The hub provides orchestration. The spokes provide specialized resources. Data vs Instructions vs Code Separate them: Instructions SKILL.md Tell the agent what to do. Data references/ Provide knowledge. Code scripts/ Perform deterministic operations. This separation makes skills easier to maintain and test. 8. Chapter 05 — Writing the Content Now we reach the instruction layer. Compare: Weak You might want to check whether tests pass. Strong Run the test suite before declaring the task complete. Stronger Do not declare the task complete until the test suite passes. The difference is binding strength. Instructions Have Different Authority Preference Prefer TypeScript. Requirement Use TypeScript for new files. Hard constraint Do not create JavaScript files. New implementation files must use TypeScript. Important rules should be unambiguous. Present-Tense Instructions Instead of: The agent should inspect the repository. write: Inspect the repository before making changes. Instead of: The agent will run the tests after implementation. write: Run the tests after implementation. Direct instructions are easier to interpret. Don't Overload the Skill With Philosophy Avoid thousands of words explaining philosophy. Prefer operational instructions: 1. Inspect X. 2. Determine Y. 3. Run Z. 4. If Z fails, investigate. 5. Do not proceed until Y is verified. The skill should be operational. 9. Chapter 06 — Enforcement This is one of the most important ideas. Don't rely on the model to enforce something that software can enforce. Suppose your skill says: Always run Prettier. The agent might comply. But it might also forget. A stronger design is: AI modifies file ↓ Hook ↓ Prettier ↓ Formatted file Formatting no longer depends entirely on model memory. AI Instructions vs Mechanical Enforcement Consider: Never commit secrets. A prompt can say: RULE: Never commit API keys. But a stronger architecture is: Agent ↓ git commit ↓ secret scanner ↓ Secret found? ├── Yes → Block commit └── No → Continue Enforcement Hierarchy A useful model is: Human judgment ↓ AI instruction ↓ Automated validation ↓ Mechanical enforcement The further down the stack you go, the less you rely on model compliance. Examples of good candidates for automation: Formatting Linting Type checking Schema validation Tests Secret detection File naming Generated artifacts SQL safety Permission boundaries The AI should focus on tasks requiring judgment. 10. Chapter 07 — Measurement Now ask: How do we know the skill works? A skill should ideally be evaluated, not merely read and trusted. There are two major dimensions. Activation Evaluation Did the correct skill activate? Example: Prompt: "Create a PostgreSQL migration for the users table." Expected: database-migration → activated You can maintain an evaluation set: ┌────────────────────────────────────┐ │ Activation Evaluation │ ├────────────────────────────────────┤ │ Prompt │ │ Expected skill │ │ Should activate? │ │ Actual skill │ │ Result │ └────────────────────────────────────┘ Behavior Evaluation Once activated, did the skill behave correctly? Suppose the migration skill requires: Inspect schema Check migration history Create migration Validate SQL Test migration Test rollback Behavior evaluation checks those requirements. Skill ↓ ┌────────┴────────┐ ↓ ↓ Activation Behavior ↓ ↓ Correct skill? Correct workflow? A skill could have: 90% activation accuracy 40% behavior accuracy and still be a poor skill. Measuring Skills Like Software Useful metrics include: Activation accuracy correct activations / total activation tests False positive rate incorrect activations / total tests False negative rate missed activations / applicable tests Task success rate successful executions / total executions Rule compliance required behaviors satisfied / required behaviors Regression rate previously passing cases now failing This turns skill development into an engineering discipline. 11. Auditing Against Prior Art Another useful activity is comparing your skill against existing approaches. Suppose you create: deep-research Before declaring it complete, ask: What existing research workflows already exist? What evaluation techniques do they use? What source-quality rules are common? What am I missing? Which practices are unnecessarily complicated? This is prior-art auditing. You don't need to reinvent every workflow. 12. Chapter 08 — Shipping A skill isn't useful if nobody can install it. A typical flow is: Development ↓ Repository ↓ Package / Plugin ↓ Distribution ↓ Installation ↓ Skill available Plugin Binding A plugin can act as a distribution container: Plugin │ ├── Skills │ ├── research │ ├── testing │ └── code-review │ ├── Hooks ├── Commands └── Configuration This lets users install a cohesive collection rather than manually copying individual files. Versioning Once users depend on a skill, versioning matters: research-skill@1.0.0 research-skill@1.1.0 research-skill@2.0.0 Changing: "prefer X" to: "must use X" can change agent behavior significantly. Therefore skill versions should be treated as meaningful behavioral versions. Dormancy A skill may sit unused for months. Then: Developer ↓ invokes old skill ↓ framework changed ↓ skill behaves differently This is skill dormancy. Skills need lifecycle states and maintenance expectations. 13. Chapter 09 — Maintenance AI skills exist inside rapidly changing ecosystems. Things change: AI models Agent runtimes APIs CLI tools Frameworks Repository structures Tool interfaces Best practices Security requirements Therefore: A skill is software, and software drifts. Drift Suppose: Tool v1 ↓ Skill v1 Later: Tool v2 ↓ behavior changed Your skill still assumes the old behavior. That is drift. Vendored Knowledge Suppose your skill contains a copy of external documentation: external methodology ↓ copy ↓ your skill The external source changes. Your copy doesn't. Now: Upstream ↓ Version 3 Your skill ↓ Version 1 You have a maintenance obligation. Review Gate A good update flow is: Upstream changes ↓ Detect change ↓ Review ↓ Update skill ↓ Run evaluation suite ↓ Check regressions ↓ Release Not: Upstream changed ↓ blindly copy everything 14. Chapter 10 — The Skill Portfolio One skill is easy. Two are manageable. Ten are interesting. Fifty become an architecture problem. You may eventually have: skills/ ├── research/ ├── frontend/ ├── backend/ ├── database/ ├── security/ ├── testing/ ├── performance/ ├── deployment/ ├── documentation/ ├── architecture/ ├── debugging/ └── code-review/ Now you need portfolio management. Skill Collision Suppose the user says: "Review my API." Potential matches: api-review backend-review security-review performance-review Which one activates? This is a collision. If multiple skills activate, their instructions may conflict. For example: Skill A: "Keep the implementation minimal." Skill B: "Add extensive validation." Skill C: "Refactor the architecture." A skill portfolio therefore needs routing and priority policies. Skill Granularity How large should a skill be? Too broad: software-engineering with everything inside it. Too narrow: read-file write-file check-import check-variable run-test You don't want hundreds of microscopic skills. A better structure might be: Engineering │ ├── Research ├── Implementation ├── Testing ├── Security └── Deployment Each skill owns a meaningful capability. Router Families A router can first identify the broad family: User request ↓ Main Router ↓ ┌───────────────┼───────────────┐ ↓ ↓ ↓ Research Engineering Operations ↓ ↓ ↓ Research Backend Deployment skill Security Monitoring Testing Instead of asking: "Which of these 100 skills should run?" you ask: Which family? ↓ Which subcategory? ↓ Which skill? Retirement A healthy portfolio needs a retirement policy. A skill may become obsolete because: the underlying tool disappeared the workflow became part of another skill the framework changed the skill is redundant another skill superseded it nobody uses it anymore A lifecycle might be: Experimental ↓ Active ↓ Stable ↓ Deprecated ↓ Retired This prevents the skill directory from becoming a graveyard. 15. The Deeper Architecture: Instructions + Tools + Enforcement + Evaluation A mature skill can be viewed as four major layers: ┌──────────────────────────────────────┐ │ SKILL │ │ │ │ ┌────────────────────────────────┐ │ │ │ Instructions │ │ │ │ What the agent should do │ │ │ └────────────────────────────────┘ │ │ ↓ │ │ ┌────────────────────────────────┐ │ │ │ Workflow │ │ │ │ Route / Pipeline / Loop / Map │ │ │ └────────────────────────────────┘ │ │ ↓ │ │ ┌────────────────────────────────┐ │ │ │ Enforcement │ │ │ │ Hooks / Scripts / Tests │ │ │ └────────────────────────────────┘ │ │ ↓ │ │ ┌────────────────────────────────┐ │ │ │ Evaluation │ │ │ │ Activation / Behavior / QA │ │ │ └────────────────────────────────┘ │ └──────────────────────────────────────┘ This is the important shift in thinking. A skill is not merely: prompt → answer It is closer to: intent ↓ routing ↓ context ↓ workflow ↓ tools ↓ validation ↓ feedback ↓ result 16. Example: Building a Deep Research Skill Suppose you want: deep-research Its directory could be: deep-research/ ├── SKILL.md ├── references/ │ ├── research-methodology.md │ ├── source-quality.md │ ├── evidence-evaluation.md │ └── synthesis.md ├── scripts/ │ ├── validate-sources.js │ └── generate-report.js ├── templates/ │ └── research-report.md └── evals/ ├── activation.json └── behavior.json Step 1 — Define Scope This skill performs structured research. It handles: - multi-source research - source evaluation - evidence synthesis - contradiction analysis - structured reporting It does not handle: - software implementation - deployment - generic writing Step 2 — Define Activation Potential activation prompts: "Research this topic deeply." "Investigate the current state of..." "Compare these technologies using external sources." "Find evidence for and against this claim." Non-activation examples: "Fix this React bug." "Run the tests." "Format this file." Step 3 — Define the Workflow Understand question ↓ Decompose question ↓ Identify evidence requirements ↓ Search ↓ Evaluate sources ↓ Extract evidence ↓ Cross-check claims ↓ Synthesize ↓ Write report ↓ Validate citations Step 4 — Add a Loop If two sources disagree: Source A → Claim X Source B → Claim Y then: Conflict detected ↓ Investigate ↓ Find additional sources ↓ Re-evaluate evidence ↓ Resolve / report uncertainty Now the skill combines: Pipeline + Loop Step 5 — Add Mechanical Validation Instead of only telling the AI: "Make sure every claim has a citation." build a validator: Report ↓ Citation validator ↓ Missing citation? ├── Yes → fail └── No → pass Step 6 — Evaluate Activation Example: Prompt: "Do a deep investigation into DuckDB vs PostgreSQL for analytics." Expected: deep-research → YES And: Prompt: "Fix the DuckDB connection bug." Expected: deep-research → NO Step 7 — Evaluate Behavior For a research request: ✓ question decomposition ✓ multiple sources ✓ source quality assessment ✓ evidence extraction ✓ conflicting evidence analysis ✓ synthesis ✓ citations ✓ final report Now regressions can be detected. 17. Applying This to an AI Engineering Harness This model becomes especially interesting when building a larger AI development harness. Imagine: AI HARNESS │ ↓ Intent Router │ ┌───────────────┼───────────────┐ ↓ ↓ ↓ Research Engineering Operations │ │ │ ↓ ↓ ↓ Skills Skills Skills │ │ │ └───────────────┼───────────────┘ ↓ Tools ↓ Enforcement ↓ Evaluation ↓ Reporting This is much more powerful than simply having a folder full of Markdown files. 18. Skills as a Policy Execution Layer Traditional software: Code ↓ Execution ↓ Result AI software: Intent ↓ Skill ↓ Reasoning ↓ Tools ↓ Result But production AI systems need another layer: Intent ↓ Skill ↓ Reasoning ↓ Tools ↓ Policy ↓ Validation ↓ Result The skill becomes a bridge between natural-language intent and deterministic engineering systems. 19. The Most Important Design Principle If there is one idea to take away from all of this, it is: Use AI for judgment. Use software for certainty. Let the model handle: Interpretation Planning Hypothesis generation Trade-offs Synthesis Creative reasoning Let software handle: Formatting Validation Testing Schema checking Permissions Secret detection Deterministic calculations Policy enforcement For example: AI: "These three files probably need to change." Software: "Does the resulting code compile?" AI: "This migration should be safe." Software: "Does the migration actually execute successfully?" AI: "These sources support the conclusion." Software: "Are the required citations present?" That division produces more reliable systems. 20. Why Skill Engineering Will Become Important As AI agents become more capable, the bottleneck increasingly shifts away from: "Can the model write code?" toward: "Can we reliably control how the model works?" That is a different engineering problem. We need to reason about: Activation Context Permissions Workflow Tools Memory Policies Evaluation Regression Versioning Distribution These are systems problems. That is why skill engineering starts resembling: software architecture + prompt engineering + workflow orchestration + testing + policy enforcement + package management 21. Practical Checklist for Building a Skill Scope [ ] Is this actually a skill? [ ] Could this be a rule? [ ] Could this be a hook? [ ] Could this be a script? [ ] What does the skill explicitly refuse to do? Activation [ ] When should it activate? [ ] When should it not activate? [ ] What are the ambiguous prompts? [ ] Can it collide with another skill? Architecture [ ] Is the workflow a route? [ ] Pipeline? [ ] Loop? [ ] Map? [ ] Combination of these? Context [ ] Is SKILL.md concise? [ ] Can supporting information be loaded progressively? [ ] Are references separated from instructions? Enforcement [ ] Which rules can be automated? [ ] Which checks should be hooks? [ ] Which checks should be scripts? [ ] Which requirements belong in CI? Evaluation [ ] Does the skill activate correctly? [ ] Does it perform the correct workflow? [ ] Are there regression tests? [ ] Are failure cases tested? Shipping [ ] Is the skill versioned? [ ] Can another developer install it? [ ] Is plugin/package integration defined? Maintenance [ ] What external dependencies can drift? [ ] Are vendored references tracked? [ ] Is there a review process? [ ] Can the skill become deprecated? Portfolio [ ] Does it overlap with another skill? [ ] Is the granularity appropriate? [ ] Does the router know where it belongs? [ ] What happens when the skill is obsolete? 22. Final Architecture Putting everything together: USER INTENT │ ▼ ┌────────────────┐ │ ROUTER │ └───────┬────────┘ │ ▼ ┌──────────────────┐ │ SKILL │ │ │ │ Scope │ │ Instructions │ │ Workflow │ │ References │ └────────┬─────────┘ │ ▼ ┌─────────────────────┐ │ AI REASONING │ └──────────┬──────────┘ │ ┌──────────┴──────────┐ ↓ ↓ Tools / APIs Scripts │ │ └──────────┬──────────┘ ↓ ┌─────────────────┐ │ ENFORCEMENT │ │ │ │ Hooks │ │ Policies │ │ Validators │ └────────┬────────┘ ↓ ┌─────────────────┐ │ EVALUATION │ │ │ │ Activation │ │ Behavior │ │ Regression │ └────────┬────────┘ ↓ RESULT And around the whole system: ┌───────────────────────────────────┐ │ SKILL LIFECYCLE │ │ │ │ Version → Ship → Observe → │ │ Maintain → Update → Deprecate │ │ │ └───────────────────────────────────┘ Conclusion: From Prompt Files to AI Engineering The simplest way to build an AI skill is: Write SKILL.md The professional way is: Define scope ↓ Define activation ↓ Design workflow ↓ Structure context ↓ Write instructions ↓ Add tools ↓ Mechanically enforce critical rules ↓ Evaluate activation ↓ Evaluate behavior ↓ Version ↓ Ship ↓ Monitor drift ↓ Maintain ↓ Retire when necessary That is the fundamental shift. AI skills should be treated less like prompts and more like software components. A prompt tells an AI what you would like it to do. A well-engineered skill defines: when it should act, what it should do, what context it should consume, how it should execute, which rules are mandatory, what software can enforce, how success is measured, and how the component evolves over time. Once you start thinking this way, .claude/skills/ stops being a collection of Markdown files. It becomes an AI-native software architecture layer. The future of agent engineering is not just better prompts — it is better systems around prompts.