# AI Skills Are Not Just Prompts: A Practical Architecture for Building, Evaluating, Shipping, and Maintaining Agent Skills 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: ```text 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: ```text .claude/ └── skills/ └── code-review/ └── SKILL.md ``` But conceptually the runtime does something like: ```text 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: ```text 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: ```text 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 ```text SKILL.md ────────────── 3000 lines 50 examples 20 rules 10 workflows 15 edge cases ``` #### Design B — Layered knowledge ```text 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: ```text Skill Rule Agent Hook Script Plugin ``` They are not interchangeable. ### Skill A skill describes **how to perform a class of task**. Example: ```text database-migration ``` It might define: ```text 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: ```text 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: ```text Main Agent ├── Research Agent ├── Security Agent └── Testing Agent ``` ### Hook A hook responds to an event: ```text Before tool call ↓ Security check ``` or: ```text After file modification ↓ Formatter ``` ### Script A script performs deterministic computation: ```text 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: ```markdown 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: ```text database migration ``` Then adds: ```text database design query optimization backup strategy production deployment ``` Eventually the skill becomes: ```text 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: ```text 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: ```text 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: ```text 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 ```text "Write a blog about PostgreSQL" → security skill activates ``` #### False negative ```text "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: ```text Request ↓ classify / | / | Bug Feature Refactor ↓ ↓ ↓ Debug Implement Refactor ``` ### Pipeline A pipeline is sequential: ```text Research ↓ Analyze ↓ Plan ↓ Implement ↓ Test ↓ Review ↓ Report ``` This is particularly useful for engineering skills. ### Loop A loop supports iteration: ```text Implement ↓ Test ↓ Failed? / Yes No ↓ ↓ Fix Complete ↓ Test again ``` For coding agents, this is natural: ```text 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: ```text Research repository │ ┌─────────────┼─────────────┐ ↓ ↓ ↓ Frontend Backend Database ↓ ↓ ↓ Findings Findings Findings └─────────────┼─────────────┘ ↓ Synthesis ``` ### Combining Shapes Real skills often combine these patterns: ```text 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: ```text 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: ```text 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 ```text SKILL.md / | / | ↓ ↓ ↓ References Scripts Templates ``` The hub provides orchestration. The spokes provide specialized resources. ### Data vs Instructions vs Code Separate them: #### Instructions ```text SKILL.md ``` Tell the agent what to do. #### Data ```text references/ ``` Provide knowledge. #### Code ```text 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 ```text Prefer TypeScript. ``` #### Requirement ```text Use TypeScript for new files. ``` #### Hard constraint ```text Do not create JavaScript files. New implementation files must use TypeScript. ``` Important rules should be unambiguous. ### Present-Tense Instructions Instead of: ```text The agent should inspect the repository. ``` write: ```text Inspect the repository before making changes. ``` Instead of: ```text The agent will run the tests after implementation. ``` write: ```text 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: ```text 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: ```text Always run Prettier. ``` The agent might comply. But it might also forget. A stronger design is: ```text 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: ```text RULE: Never commit API keys. ``` But a stronger architecture is: ```text Agent ↓ git commit ↓ secret scanner ↓ Secret found? ├── Yes → Block commit └── No → Continue ``` ### Enforcement Hierarchy A useful model is: ```text 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: ```text 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: ```text Prompt: "Create a PostgreSQL migration for the users table." Expected: database-migration → activated ``` You can maintain an evaluation set: ```text ┌────────────────────────────────────┐ │ Activation Evaluation │ ├────────────────────────────────────┤ │ Prompt │ │ Expected skill │ │ Should activate? │ │ Actual skill │ │ Result │ └────────────────────────────────────┘ ``` ### Behavior Evaluation Once activated, did the skill behave correctly? Suppose the migration skill requires: ```text Inspect schema Check migration history Create migration Validate SQL Test migration Test rollback ``` Behavior evaluation checks those requirements. ```text Skill ↓ ┌────────┴────────┐ ↓ ↓ Activation Behavior ↓ ↓ Correct skill? Correct workflow? ``` A skill could have: ```text 90% activation accuracy 40% behavior accuracy ``` and still be a poor skill. ### Measuring Skills Like Software Useful metrics include: #### Activation accuracy ```text correct activations / total activation tests ``` #### False positive rate ```text incorrect activations / total tests ``` #### False negative rate ```text missed activations / applicable tests ``` #### Task success rate ```text successful executions / total executions ``` #### Rule compliance ```text required behaviors satisfied / required behaviors ``` #### Regression rate ```text 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: ```text deep-research ``` Before declaring it complete, ask: ```text 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: ```text Development ↓ Repository ↓ Package / Plugin ↓ Distribution ↓ Installation ↓ Skill available ``` ### Plugin Binding A plugin can act as a distribution container: ```text 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: ```text research-skill@1.0.0 research-skill@1.1.0 research-skill@2.0.0 ``` Changing: ```text "prefer X" ``` to: ```text "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: ```text 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: ```text 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: ```text Tool v1 ↓ Skill v1 ``` Later: ```text 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: ```text external methodology ↓ copy ↓ your skill ``` The external source changes. Your copy doesn't. Now: ```text Upstream ↓ Version 3 Your skill ↓ Version 1 ``` You have a maintenance obligation. ### Review Gate A good update flow is: ```text Upstream changes ↓ Detect change ↓ Review ↓ Update skill ↓ Run evaluation suite ↓ Check regressions ↓ Release ``` Not: ```text 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: ```text 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: ```text 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: ```text 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: ```text software-engineering ``` with everything inside it. Too narrow: ```text read-file write-file check-import check-variable run-test ``` You don't want hundreds of microscopic skills. A better structure might be: ```text Engineering │ ├── Research ├── Implementation ├── Testing ├── Security └── Deployment ``` Each skill owns a meaningful capability. ### Router Families A router can first identify the broad family: ```text 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: ```text 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: ```text 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: ```text ┌──────────────────────────────────────┐ │ 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: ```text prompt → answer ``` It is closer to: ```text intent ↓ routing ↓ context ↓ workflow ↓ tools ↓ validation ↓ feedback ↓ result ``` * * * ## 16\. Example: Building a Deep Research Skill Suppose you want: ```text deep-research ``` Its directory could be: ```text 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 ```text 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: ```text "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: ```text "Fix this React bug." "Run the tests." "Format this file." ``` ### Step 3 — Define the Workflow ```text 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: ```text Source A → Claim X Source B → Claim Y ``` then: ```text Conflict detected ↓ Investigate ↓ Find additional sources ↓ Re-evaluate evidence ↓ Resolve / report uncertainty ``` Now the skill combines: ```text Pipeline + Loop ``` ### Step 5 — Add Mechanical Validation Instead of only telling the AI: > "Make sure every claim has a citation." build a validator: ```text Report ↓ Citation validator ↓ Missing citation? ├── Yes → fail └── No → pass ``` ### Step 6 — Evaluate Activation Example: ```text Prompt: "Do a deep investigation into DuckDB vs PostgreSQL for analytics." Expected: deep-research → YES ``` And: ```text Prompt: "Fix the DuckDB connection bug." Expected: deep-research → NO ``` ### Step 7 — Evaluate Behavior For a research request: ```text ✓ 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: ```text 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: ```text Code ↓ Execution ↓ Result ``` AI software: ```text Intent ↓ Skill ↓ Reasoning ↓ Tools ↓ Result ``` But production AI systems need another layer: ```text 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: ```text Interpretation Planning Hypothesis generation Trade-offs Synthesis Creative reasoning ``` Let software handle: ```text Formatting Validation Testing Schema checking Permissions Secret detection Deterministic calculations Policy enforcement ``` For example: ```text 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: ```text Activation Context Permissions Workflow Tools Memory Policies Evaluation Regression Versioning Distribution ``` These are systems problems. That is why skill engineering starts resembling: ```text 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: ```text 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: ```text ┌───────────────────────────────────┐ │ SKILL LIFECYCLE │ │ │ │ Version → Ship → Observe → │ │ Maintain → Update → Deprecate │ │ │ └───────────────────────────────────┘ ``` * * * ## Conclusion: From Prompt Files to AI Engineering The simplest way to build an AI skill is: ```text Write SKILL.md ``` The professional way is: ```text 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.**