{"slug": "ai-skills-are-not-just-prompts-a-practical-architecture-for-building-evaluating", "title": "AI Skills Are Not Just Prompts: A Practical Architecture for Building, Evaluating, Shipping, and Maintaining Agent Skills", "summary": "A developer outlines a practical architecture for building, evaluating, shipping, and maintaining AI agent skills, arguing that production-grade skills are versioned, testable, routable software components with a defined lifecycle. The post emphasizes progressive context loading and distinguishes skills from other primitives like rules, agents, hooks, and scripts.", "body_md": "The current generation of AI coding agents makes it surprisingly easy to create a \"skill.\"\n\nWrite a Markdown file. Add instructions. Give it a name. Put it inside `.claude/skills/`\n\n. Done.\n\nExcept it isn't.\n\nAs soon as you build more than a handful of skills, a different set of problems appears:\n\nAt that point, **AI skills stop looking like prompts and start looking like software systems**.\n\nA production-grade AI skill is not merely a Markdown prompt. It is a versioned, testable, routable, enforceable software component with a defined lifecycle.\n\nA useful way to understand an AI skill is to look at its entire lifecycle:\n\n```\nRuntime\n   ↓\nScope / Fit\n   ↓\nTriggers\n   ↓\nArchitecture\n   ↓\nAnatomy\n   ↓\nContent\n   ↓\nEnforcement\n   ↓\nMeasurement\n   ↓\nShipping\n   ↓\nMaintenance\n   ↓\nPortfolio\n```\n\nEach stage answers a different question:\n\n| Stage | Core question |\n|---|---|\n| Runtime | How does the skill load and execute? |\n| Fit & scope | Should this be a skill at all? |\n| Typing & triggers | When should it activate? |\n| Architecture | How should the workflow operate? |\n| Anatomy | What files make up the skill? |\n| Content | How should instructions be written? |\n| Enforcement | What can be enforced mechanically? |\n| Measurement | How do we know it works? |\n| Shipping | How do users receive it? |\n| Maintenance | How does it survive change? |\n| Portfolio | How do many skills coexist? |\n\nThe important insight is that **skill engineering covers the entire lifecycle, not just the writing of SKILL.md.**\n\nBefore designing a skill, understand the runtime.\n\nA skill may look simple on disk:\n\n```\n.claude/\n└── skills/\n    └── code-review/\n        └── SKILL.md\n```\n\nBut conceptually the runtime does something like:\n\n```\nUser request\n     ↓\nSkill discovery\n     ↓\nTrigger evaluation\n     ↓\nSkill activation\n     ↓\nInstruction loading\n     ↓\nReference/tool loading\n     ↓\nAgent execution\n     ↓\nResult\n```\n\nThe important question is:\n\nWhat does the agent actually see, and when does it see it?\n\nThis matters because context is limited.\n\nA skill might contain:\n\n```\nSKILL.md\nreferences/\n    database.md\n    security.md\n    examples.md\n    architecture.md\nscripts/\n    validate.js\n    check.sh\ntemplates/\n    report.md\n```\n\nYou usually don't want every file loaded for every request.\n\nInstead:\n\n```\nRequest\n   ↓\nSKILL.md\n   ↓\nDetermine relevant task\n   ↓\nLoad relevant reference\n   ↓\nExecute required script\n```\n\nThis is **progressive context loading**.\n\nThe main skill file acts as an entry point rather than a giant knowledge dump.\n\nOne of the biggest mistakes in AI skill design is treating context as free.\n\nIt isn't.\n\n```\nSKILL.md\n──────────────\n3000 lines\n50 examples\n20 rules\n10 workflows\n15 edge cases\nSKILL.md\n   ↓\nRouting\n   ↓\nreferences/\n   ├── workflow.md\n   ├── security.md\n   └── examples.md\n```\n\nThe second design gives you more control over what enters the model's context.\n\nDesign skills around context boundaries, not just file boundaries.\n\nThe next question is:\n\nShould this behavior be implemented as a skill?\n\nAI development environments often provide multiple primitives:\n\n```\nSkill\nRule\nAgent\nHook\nScript\nPlugin\n```\n\nThey are not interchangeable.\n\nA skill describes **how to perform a class of task**.\n\nExample:\n\n```\ndatabase-migration\n```\n\nIt might define:\n\n```\n1. Inspect schema\n2. Inspect migration history\n3. Design migration\n4. Implement migration\n5. Validate migration\n6. Test rollback\n```\n\nA rule is a constraint:\n\n```\nNever modify production data directly.\n```\n\nThat is policy, not a workflow.\n\nAn agent is useful when you need a distinct reasoning or execution role:\n\n```\nMain Agent\n   ├── Research Agent\n   ├── Security Agent\n   └── Testing Agent\n```\n\nA hook responds to an event:\n\n```\nBefore tool call\n      ↓\nSecurity check\n```\n\nor:\n\n```\nAfter file modification\n      ↓\nFormatter\n```\n\nA script performs deterministic computation:\n\n```\nvalidate-schema.js\n```\n\nThe AI may decide **when** to run it. The script determines **how** validation works.\n\nA good skill should explicitly state what it does not do.\n\nFor example:\n\n```\nThis skill handles:\n\n- PostgreSQL schema migrations\n- Migration generation\n- Migration validation\n- Rollback testing\n\nThis skill does not handle:\n\n- Application architecture\n- Production deployment\n- Database backups\n- Infrastructure provisioning\n```\n\nWhy?\n\nBecause skills tend to grow.\n\nA developer starts with:\n\n```\ndatabase migration\n```\n\nThen adds:\n\n```\ndatabase design\nquery optimization\nbackup strategy\nproduction deployment\n```\n\nEventually the skill becomes:\n\n```\ndatabase-engineering-everything\n```\n\nand becomes difficult to reason about.\n\nScope is a defense against skill inflation.\n\nOnce you know what a skill does, you need to answer:\n\nWhen should it activate?\n\nImagine:\n\n```\nfrontend-review\nbackend-review\nsecurity-review\nperformance-review\ndatabase-review\n```\n\nThe user says:\n\n\"Review my authentication API.\"\n\nMultiple skills may be relevant.\n\nYou now have a routing problem:\n\n```\n                 User request\n                      │\n        ┌─────────────┼─────────────┐\n        ↓             ↓             ↓\n    Backend       Security       Performance\n```\n\nIf everything activates, the system becomes noisy.\n\nIf nothing activates, the skill is useless.\n\nThink of activation as:\n\n```\nUser request\n      ↓\nIntent classification\n      ↓\nSkill candidates\n      ↓\nRelevance evaluation\n      ↓\nActivation\n```\n\nExample:\n\n| Request | Expected skill |\n|---|---|\n| \"Create a PostgreSQL migration\" | Database migration |\n| \"Fix this React component\" | Frontend |\n| \"Audit authentication\" | Security |\n| \"Why is this query slow?\" | Database performance |\n| \"Write a technical article\" | Documentation |\n\nA good skill therefore needs a clear **activation signature**.\n\n```\n\"Write a blog about PostgreSQL\"\n\n→ security skill activates\n\"Why is my PostgreSQL migration failing?\"\n\n→ database migration skill does not activate\n```\n\nBoth are important.\n\nTherefore, evaluate **activation separately from execution**.\n\nOnce a skill activates, what does it actually do?\n\nThere are several useful workflow shapes.\n\nA route chooses a path:\n\n```\n                 Request\n                    ↓\n                 classify\n              /     |                   /      |                  Bug    Feature   Refactor\n            ↓        ↓         ↓\n         Debug    Implement  Refactor\n```\n\nA pipeline is sequential:\n\n```\nResearch\n   ↓\nAnalyze\n   ↓\nPlan\n   ↓\nImplement\n   ↓\nTest\n   ↓\nReview\n   ↓\nReport\n```\n\nThis is particularly useful for engineering skills.\n\nA loop supports iteration:\n\n```\nImplement\n    ↓\nTest\n    ↓\nFailed?\n  /    Yes     No\n ↓       ↓\nFix    Complete\n ↓\nTest again\n```\n\nFor coding agents, this is natural:\n\n```\nWrite implementation\n        ↓\nRun tests\n        ↓\nRead failure\n        ↓\nModify implementation\n        ↓\nRun tests again\n```\n\nFailure becomes an expected workflow state rather than an exceptional event.\n\nA map splits a problem into independent pieces:\n\n```\n                 Research repository\n                        │\n          ┌─────────────┼─────────────┐\n          ↓             ↓             ↓\n       Frontend      Backend       Database\n          ↓             ↓             ↓\n       Findings      Findings      Findings\n          └─────────────┼─────────────┘\n                        ↓\n                     Synthesis\n```\n\nReal skills often combine these patterns:\n\n```\nRoute\n  ↓\nPipeline\n  ↓\nMap\n  ↓\nLoop\n  ↓\nFinal report\n```\n\nThis is where AI skills start looking like **workflow engines rather than prompts**.\n\nA mature skill might look like:\n\n```\nskills/\n└── deep-research/\n    │\n    ├── SKILL.md\n    │\n    ├── references/\n    │   ├── research-methodology.md\n    │   ├── source-evaluation.md\n    │   └── evidence.md\n    │\n    ├── scripts/\n    │   ├── validate-sources.js\n    │   └── generate-report.js\n    │\n    ├── templates/\n    │   └── report.md\n    │\n    └── examples/\n        ├── example-1.md\n        └── example-2.md\n```\n\nEach part has a job.\n\n`SKILL.md`\n\nIs the Hub\nThink of `SKILL.md`\n\nas the router and operating manual.\n\nIt should explain:\n\n```\nWhat this skill does\nWhen it activates\nWhat it must accomplish\nWhat references to load\nWhat workflow to follow\nWhat constraints apply\nHow to validate the result\n```\n\nIt should not necessarily contain every piece of knowledge.\n\n```\n                   SKILL.md\n                  /   |                    /    |                    ↓     ↓     ↓\n          References Scripts Templates\n```\n\nThe hub provides orchestration.\n\nThe spokes provide specialized resources.\n\nSeparate them:\n\n```\nSKILL.md\n```\n\nTell the agent what to do.\n\n```\nreferences/\n```\n\nProvide knowledge.\n\n```\nscripts/\n```\n\nPerform deterministic operations.\n\nThis separation makes skills easier to maintain and test.\n\nNow we reach the instruction layer.\n\nCompare:\n\nYou might want to check whether tests pass.\n\nRun the test suite before declaring the task complete.\n\nDo not declare the task complete until the test suite passes.\n\nThe difference is **binding strength**.\n\n```\nPrefer TypeScript.\nUse TypeScript for new files.\nDo not create JavaScript files. New implementation files must use TypeScript.\n```\n\nImportant rules should be unambiguous.\n\nInstead of:\n\n```\nThe agent should inspect the repository.\n```\n\nwrite:\n\n```\nInspect the repository before making changes.\n```\n\nInstead of:\n\n```\nThe agent will run the tests after implementation.\n```\n\nwrite:\n\n```\nRun the tests after implementation.\n```\n\nDirect instructions are easier to interpret.\n\nAvoid thousands of words explaining philosophy.\n\nPrefer operational instructions:\n\n```\n1. Inspect X.\n2. Determine Y.\n3. Run Z.\n4. If Z fails, investigate.\n5. Do not proceed until Y is verified.\n```\n\nThe skill should be **operational**.\n\nThis is one of the most important ideas.\n\nDon't rely on the model to enforce something that software can enforce.\n\nSuppose your skill says:\n\n```\nAlways run Prettier.\n```\n\nThe agent might comply.\n\nBut it might also forget.\n\nA stronger design is:\n\n```\nAI modifies file\n      ↓\nHook\n      ↓\nPrettier\n      ↓\nFormatted file\n```\n\nFormatting no longer depends entirely on model memory.\n\nConsider:\n\nNever commit secrets.\n\nA prompt can say:\n\n```\nRULE:\nNever commit API keys.\n```\n\nBut a stronger architecture is:\n\n```\nAgent\n  ↓\ngit commit\n  ↓\nsecret scanner\n  ↓\nSecret found?\n  ├── Yes → Block commit\n  └── No  → Continue\n```\n\nA useful model is:\n\n```\nHuman judgment\n      ↓\nAI instruction\n      ↓\nAutomated validation\n      ↓\nMechanical enforcement\n```\n\nThe further down the stack you go, the less you rely on model compliance.\n\nExamples of good candidates for automation:\n\n```\nFormatting\nLinting\nType checking\nSchema validation\nTests\nSecret detection\nFile naming\nGenerated artifacts\nSQL safety\nPermission boundaries\n```\n\nThe AI should focus on tasks requiring judgment.\n\nNow ask:\n\nHow do we know the skill works?\n\nA skill should ideally be evaluated, not merely read and trusted.\n\nThere are two major dimensions.\n\nDid the correct skill activate?\n\nExample:\n\n```\nPrompt:\n\"Create a PostgreSQL migration for the users table.\"\n\nExpected:\ndatabase-migration → activated\n```\n\nYou can maintain an evaluation set:\n\n```\n┌────────────────────────────────────┐\n│ Activation Evaluation              │\n├────────────────────────────────────┤\n│ Prompt                             │\n│ Expected skill                     │\n│ Should activate?                   │\n│ Actual skill                       │\n│ Result                             │\n└────────────────────────────────────┘\n```\n\nOnce activated, did the skill behave correctly?\n\nSuppose the migration skill requires:\n\n```\nInspect schema\nCheck migration history\nCreate migration\nValidate SQL\nTest migration\nTest rollback\n```\n\nBehavior evaluation checks those requirements.\n\n```\n                    Skill\n                      ↓\n             ┌────────┴────────┐\n             ↓                 ↓\n       Activation          Behavior\n             ↓                 ↓\n        Correct skill?    Correct workflow?\n```\n\nA skill could have:\n\n```\n90% activation accuracy\n40% behavior accuracy\n```\n\nand still be a poor skill.\n\nUseful metrics include:\n\n```\ncorrect activations / total activation tests\nincorrect activations / total tests\nmissed activations / applicable tests\nsuccessful executions / total executions\nrequired behaviors satisfied / required behaviors\npreviously passing cases now failing\n```\n\nThis turns skill development into an engineering discipline.\n\nAnother useful activity is comparing your skill against existing approaches.\n\nSuppose you create:\n\n```\ndeep-research\n```\n\nBefore declaring it complete, ask:\n\n```\nWhat existing research workflows already exist?\n\nWhat evaluation techniques do they use?\n\nWhat source-quality rules are common?\n\nWhat am I missing?\n\nWhich practices are unnecessarily complicated?\n```\n\nThis is **prior-art auditing**.\n\nYou don't need to reinvent every workflow.\n\nA skill isn't useful if nobody can install it.\n\nA typical flow is:\n\n```\nDevelopment\n    ↓\nRepository\n    ↓\nPackage / Plugin\n    ↓\nDistribution\n    ↓\nInstallation\n    ↓\nSkill available\n```\n\nA plugin can act as a distribution container:\n\n```\nPlugin\n│\n├── Skills\n│   ├── research\n│   ├── testing\n│   └── code-review\n│\n├── Hooks\n├── Commands\n└── Configuration\n```\n\nThis lets users install a cohesive collection rather than manually copying individual files.\n\nOnce users depend on a skill, versioning matters:\n\n```\nresearch-skill@1.0.0\nresearch-skill@1.1.0\nresearch-skill@2.0.0\n```\n\nChanging:\n\n```\n\"prefer X\"\n```\n\nto:\n\n```\n\"must use X\"\n```\n\ncan change agent behavior significantly.\n\nTherefore skill versions should be treated as meaningful behavioral versions.\n\nA skill may sit unused for months.\n\nThen:\n\n```\nDeveloper\n   ↓\ninvokes old skill\n   ↓\nframework changed\n   ↓\nskill behaves differently\n```\n\nThis is **skill dormancy**.\n\nSkills need lifecycle states and maintenance expectations.\n\nAI skills exist inside rapidly changing ecosystems.\n\nThings change:\n\n```\nAI models\nAgent runtimes\nAPIs\nCLI tools\nFrameworks\nRepository structures\nTool interfaces\nBest practices\nSecurity requirements\n```\n\nTherefore:\n\nA skill is software, and software drifts.\n\nSuppose:\n\n```\nTool v1\n ↓\nSkill v1\n```\n\nLater:\n\n```\nTool v2\n ↓\nbehavior changed\n```\n\nYour skill still assumes the old behavior.\n\nThat is drift.\n\nSuppose your skill contains a copy of external documentation:\n\n```\nexternal methodology\n       ↓\ncopy\n       ↓\nyour skill\n```\n\nThe external source changes.\n\nYour copy doesn't.\n\nNow:\n\n```\nUpstream\n   ↓\nVersion 3\n\nYour skill\n   ↓\nVersion 1\n```\n\nYou have a maintenance obligation.\n\nA good update flow is:\n\n```\nUpstream changes\n       ↓\nDetect change\n       ↓\nReview\n       ↓\nUpdate skill\n       ↓\nRun evaluation suite\n       ↓\nCheck regressions\n       ↓\nRelease\n```\n\nNot:\n\n```\nUpstream changed\n       ↓\nblindly copy everything\n```\n\nOne skill is easy.\n\nTwo are manageable.\n\nTen are interesting.\n\nFifty become an architecture problem.\n\nYou may eventually have:\n\n```\nskills/\n├── research/\n├── frontend/\n├── backend/\n├── database/\n├── security/\n├── testing/\n├── performance/\n├── deployment/\n├── documentation/\n├── architecture/\n├── debugging/\n└── code-review/\n```\n\nNow you need portfolio management.\n\nSuppose the user says:\n\n\"Review my API.\"\n\nPotential matches:\n\n```\napi-review\nbackend-review\nsecurity-review\nperformance-review\n```\n\nWhich one activates?\n\nThis is a **collision**.\n\nIf multiple skills activate, their instructions may conflict.\n\nFor example:\n\n```\nSkill A:\n\"Keep the implementation minimal.\"\n\nSkill B:\n\"Add extensive validation.\"\n\nSkill C:\n\"Refactor the architecture.\"\n```\n\nA skill portfolio therefore needs routing and priority policies.\n\nHow large should a skill be?\n\nToo broad:\n\n```\nsoftware-engineering\n```\n\nwith everything inside it.\n\nToo narrow:\n\n``` python\nread-file\nwrite-file\ncheck-import\ncheck-variable\nrun-test\n```\n\nYou don't want hundreds of microscopic skills.\n\nA better structure might be:\n\n```\nEngineering\n│\n├── Research\n├── Implementation\n├── Testing\n├── Security\n└── Deployment\n```\n\nEach skill owns a meaningful capability.\n\nA router can first identify the broad family:\n\n```\n                  User request\n                       ↓\n                  Main Router\n                       ↓\n       ┌───────────────┼───────────────┐\n       ↓               ↓               ↓\n   Research        Engineering      Operations\n       ↓               ↓               ↓\n   Research        Backend         Deployment\n   skill           Security        Monitoring\n                   Testing\n```\n\nInstead of asking:\n\n\"Which of these 100 skills should run?\"\n\nyou ask:\n\n```\nWhich family?\n     ↓\nWhich subcategory?\n     ↓\nWhich skill?\n```\n\nA healthy portfolio needs a retirement policy.\n\nA skill may become obsolete because:\n\nA lifecycle might be:\n\n```\nExperimental\n     ↓\nActive\n     ↓\nStable\n     ↓\nDeprecated\n     ↓\nRetired\n```\n\nThis prevents the skill directory from becoming a graveyard.\n\nA mature skill can be viewed as four major layers:\n\n```\n┌──────────────────────────────────────┐\n│              SKILL                   │\n│                                      │\n│  ┌────────────────────────────────┐  │\n│  │ Instructions                    │  │\n│  │ What the agent should do       │  │\n│  └────────────────────────────────┘  │\n│                  ↓                   │\n│  ┌────────────────────────────────┐  │\n│  │ Workflow                       │  │\n│  │ Route / Pipeline / Loop / Map │  │\n│  └────────────────────────────────┘  │\n│                  ↓                   │\n│  ┌────────────────────────────────┐  │\n│  │ Enforcement                    │  │\n│  │ Hooks / Scripts / Tests       │  │\n│  └────────────────────────────────┘  │\n│                  ↓                   │\n│  ┌────────────────────────────────┐  │\n│  │ Evaluation                     │  │\n│  │ Activation / Behavior / QA    │  │\n│  └────────────────────────────────┘  │\n└──────────────────────────────────────┘\n```\n\nThis is the important shift in thinking.\n\nA skill is not merely:\n\n```\nprompt → answer\n```\n\nIt is closer to:\n\n```\nintent\n  ↓\nrouting\n  ↓\ncontext\n  ↓\nworkflow\n  ↓\ntools\n  ↓\nvalidation\n  ↓\nfeedback\n  ↓\nresult\n```\n\nSuppose you want:\n\n```\ndeep-research\n```\n\nIts directory could be:\n\n```\ndeep-research/\n├── SKILL.md\n├── references/\n│   ├── research-methodology.md\n│   ├── source-quality.md\n│   ├── evidence-evaluation.md\n│   └── synthesis.md\n├── scripts/\n│   ├── validate-sources.js\n│   └── generate-report.js\n├── templates/\n│   └── research-report.md\n└── evals/\n    ├── activation.json\n    └── behavior.json\nThis skill performs structured research.\n\nIt handles:\n- multi-source research\n- source evaluation\n- evidence synthesis\n- contradiction analysis\n- structured reporting\n\nIt does not handle:\n- software implementation\n- deployment\n- generic writing\n```\n\nPotential activation prompts:\n\n```\n\"Research this topic deeply.\"\n\n\"Investigate the current state of...\"\n\n\"Compare these technologies using external sources.\"\n\n\"Find evidence for and against this claim.\"\n```\n\nNon-activation examples:\n\n```\n\"Fix this React bug.\"\n\n\"Run the tests.\"\n\n\"Format this file.\"\nUnderstand question\n       ↓\nDecompose question\n       ↓\nIdentify evidence requirements\n       ↓\nSearch\n       ↓\nEvaluate sources\n       ↓\nExtract evidence\n       ↓\nCross-check claims\n       ↓\nSynthesize\n       ↓\nWrite report\n       ↓\nValidate citations\n```\n\nIf two sources disagree:\n\n```\nSource A → Claim X\nSource B → Claim Y\n```\n\nthen:\n\n```\nConflict detected\n       ↓\nInvestigate\n       ↓\nFind additional sources\n       ↓\nRe-evaluate evidence\n       ↓\nResolve / report uncertainty\n```\n\nNow the skill combines:\n\n```\nPipeline + Loop\n```\n\nInstead of only telling the AI:\n\n\"Make sure every claim has a citation.\"\n\nbuild a validator:\n\n```\nReport\n  ↓\nCitation validator\n  ↓\nMissing citation?\n  ├── Yes → fail\n  └── No  → pass\n```\n\nExample:\n\n```\nPrompt:\n\"Do a deep investigation into DuckDB vs PostgreSQL for analytics.\"\n\nExpected:\ndeep-research → YES\n```\n\nAnd:\n\n```\nPrompt:\n\"Fix the DuckDB connection bug.\"\n\nExpected:\ndeep-research → NO\n```\n\nFor a research request:\n\n```\n✓ question decomposition\n✓ multiple sources\n✓ source quality assessment\n✓ evidence extraction\n✓ conflicting evidence analysis\n✓ synthesis\n✓ citations\n✓ final report\n```\n\nNow regressions can be detected.\n\nThis model becomes especially interesting when building a larger AI development harness.\n\nImagine:\n\n```\n                    AI HARNESS\n                        │\n                        ↓\n                  Intent Router\n                        │\n        ┌───────────────┼───────────────┐\n        ↓               ↓               ↓\n     Research       Engineering      Operations\n        │               │               │\n        ↓               ↓               ↓\n     Skills           Skills          Skills\n        │               │               │\n        └───────────────┼───────────────┘\n                        ↓\n                     Tools\n                        ↓\n                  Enforcement\n                        ↓\n                    Evaluation\n                        ↓\n                    Reporting\n```\n\nThis is much more powerful than simply having a folder full of Markdown files.\n\nTraditional software:\n\n```\nCode\n ↓\nExecution\n ↓\nResult\n```\n\nAI software:\n\n```\nIntent\n ↓\nSkill\n ↓\nReasoning\n ↓\nTools\n ↓\nResult\n```\n\nBut production AI systems need another layer:\n\n```\nIntent\n ↓\nSkill\n ↓\nReasoning\n ↓\nTools\n ↓\nPolicy\n ↓\nValidation\n ↓\nResult\n```\n\nThe skill becomes a bridge between **natural-language intent and deterministic engineering systems**.\n\nIf there is one idea to take away from all of this, it is:\n\nUse AI for judgment. Use software for certainty.\n\nLet the model handle:\n\n```\nInterpretation\nPlanning\nHypothesis generation\nTrade-offs\nSynthesis\nCreative reasoning\n```\n\nLet software handle:\n\n```\nFormatting\nValidation\nTesting\nSchema checking\nPermissions\nSecret detection\nDeterministic calculations\nPolicy enforcement\n```\n\nFor example:\n\n```\nAI:\n\"These three files probably need to change.\"\n\nSoftware:\n\"Does the resulting code compile?\"\n\nAI:\n\"This migration should be safe.\"\n\nSoftware:\n\"Does the migration actually execute successfully?\"\n\nAI:\n\"These sources support the conclusion.\"\n\nSoftware:\n\"Are the required citations present?\"\n```\n\nThat division produces more reliable systems.\n\nAs AI agents become more capable, the bottleneck increasingly shifts away from:\n\n\"Can the model write code?\"\n\ntoward:\n\n\"Can we reliably control how the model works?\"\n\nThat is a different engineering problem.\n\nWe need to reason about:\n\n```\nActivation\nContext\nPermissions\nWorkflow\nTools\nMemory\nPolicies\nEvaluation\nRegression\nVersioning\nDistribution\n```\n\nThese are systems problems.\n\nThat is why skill engineering starts resembling:\n\n```\nsoftware architecture\n        +\nprompt engineering\n        +\nworkflow orchestration\n        +\ntesting\n        +\npolicy enforcement\n        +\npackage management\n```\n\n`SKILL.md`\n\nconcise?Putting everything together:\n\n```\n                         USER INTENT\n                              │\n                              ▼\n                     ┌────────────────┐\n                     │     ROUTER     │\n                     └───────┬────────┘\n                             │\n                             ▼\n                    ┌──────────────────┐\n                    │      SKILL       │\n                    │                  │\n                    │ Scope            │\n                    │ Instructions     │\n                    │ Workflow         │\n                    │ References       │\n                    └────────┬─────────┘\n                             │\n                             ▼\n                  ┌─────────────────────┐\n                  │   AI REASONING      │\n                  └──────────┬──────────┘\n                             │\n                  ┌──────────┴──────────┐\n                  ↓                     ↓\n             Tools / APIs          Scripts\n                  │                     │\n                  └──────────┬──────────┘\n                             ↓\n                    ┌─────────────────┐\n                    │   ENFORCEMENT   │\n                    │                 │\n                    │ Hooks           │\n                    │ Policies        │\n                    │ Validators      │\n                    └────────┬────────┘\n                             ↓\n                    ┌─────────────────┐\n                    │   EVALUATION    │\n                    │                 │\n                    │ Activation      │\n                    │ Behavior        │\n                    │ Regression      │\n                    └────────┬────────┘\n                             ↓\n                         RESULT\n```\n\nAnd around the whole system:\n\n```\n          ┌───────────────────────────────────┐\n          │           SKILL LIFECYCLE         │\n          │                                   │\n          │ Version → Ship → Observe →       │\n          │ Maintain → Update → Deprecate    │\n          │                                   │\n          └───────────────────────────────────┘\n```\n\nThe simplest way to build an AI skill is:\n\n```\nWrite SKILL.md\n```\n\nThe professional way is:\n\n```\nDefine scope\n     ↓\nDefine activation\n     ↓\nDesign workflow\n     ↓\nStructure context\n     ↓\nWrite instructions\n     ↓\nAdd tools\n     ↓\nMechanically enforce critical rules\n     ↓\nEvaluate activation\n     ↓\nEvaluate behavior\n     ↓\nVersion\n     ↓\nShip\n     ↓\nMonitor drift\n     ↓\nMaintain\n     ↓\nRetire when necessary\n```\n\nThat is the fundamental shift.\n\n**AI skills should be treated less like prompts and more like software components.**\n\nA prompt tells an AI what you would *like* it to do.\n\nA well-engineered skill defines:\n\nOnce you start thinking this way, `.claude/skills/`\n\nstops being a collection of Markdown files.\n\nIt becomes an **AI-native software architecture layer**.\n\nThe future of agent engineering is not just better prompts — it is better systems around prompts.", "url": "https://wpnews.pro/news/ai-skills-are-not-just-prompts-a-practical-architecture-for-building-evaluating", "canonical_source": "https://dev.to/nishikantaray/ai-skills-are-not-just-prompts-a-practical-architecture-for-building-evaluating-shipping-and-540h", "published_at": "2026-09-03 19:13:59+00:00", "updated_at": "2026-09-03 19:55:31.212547+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "artificial-intelligence"], "entities": [], "alternates": {"html": "https://wpnews.pro/news/ai-skills-are-not-just-prompts-a-practical-architecture-for-building-evaluating", "markdown": "https://wpnews.pro/news/ai-skills-are-not-just-prompts-a-practical-architecture-for-building-evaluating.md", "text": "https://wpnews.pro/news/ai-skills-are-not-just-prompts-a-practical-architecture-for-building-evaluating.txt", "jsonld": "https://wpnews.pro/news/ai-skills-are-not-just-prompts-a-practical-architecture-for-building-evaluating.jsonld"}}