{"id":"3dafb709-652f-431e-acd5-cb561c6149e8","shortId":"Cj2vw9","kind":"skill","title":"agent-native-architecture","tagline":">-","description":"# Agent-Native Architecture\n\n## Core Principles\n\nFive principles govern agent-native design. For detailed explanations, examples, and test criteria, see [core-principles.md](./references/core-principles.md).\n\n| Principle | One-line test |\n|-----------|--------------|\n| **Parity** | Can the agent achieve every outcome the UI allows? |\n| **Granularity** | To change behavior, do you edit prose or refactor code? |\n| **Composability** | Can you add a feature by writing a new prompt, without new code? |\n| **Emergent Capability** | Can the agent handle open-ended requests you didn't design for? |\n| **Improvement Over Time** | Does the app work better after a month, even without code changes? |\n\n## Focus Area Selection\n\n1. **Design architecture** - Plan a new agent-native system from scratch\n2. **Files & workspace** - Use files as the universal interface, shared workspace patterns\n3. **Tool design** - Build primitive tools, dynamic capability discovery, CRUD completeness\n4. **Domain tools** - Know when to add domain tools vs stay with primitives\n5. **Execution patterns** - Completion signals, partial completion, context limits\n6. **System prompts** - Define agent behavior in prompts, judgment criteria\n7. **Context injection** - Inject runtime app state into agent prompts\n8. **Action parity** - Ensure agents can do everything users can do\n9. **Self-modification** - Enable agents to safely evolve themselves\n10. **Product design** - Progressive disclosure, latent demand, approval patterns\n11. **Mobile patterns** - iOS storage, background execution, checkpoint/resume\n12. **Testing** - Test agent-native apps for capability and parity\n13. **Refactoring** - Make existing code more agent-native\n14. **Anti-patterns** - Common mistakes and how to avoid them\n15. **Success criteria** - Verify your architecture is agent-native\n16. **Hooks patterns** - Hook events, decision control, MCP matchers, async hooks\n\n**Wait for response before proceeding.**\n\n## Reference Routing\n\n| Response | Action |\n|----------|--------|\n| 1, \"design\", \"architecture\", \"plan\" | Read [architecture-patterns.md](./references/architecture-patterns.md), then apply Architecture Checklist below |\n| 2, \"files\", \"workspace\", \"filesystem\" | Read [files-universal-interface.md](./references/files-universal-interface.md) and [shared-workspace-architecture.md](./references/shared-workspace-architecture.md) |\n| 3, \"tool\", \"mcp\", \"primitive\", \"crud\" | Read [mcp-tool-design.md](./references/mcp-tool-design.md) |\n| 4, \"domain tool\", \"when to add\" | Read [from-primitives-to-domain-tools.md](./references/from-primitives-to-domain-tools.md) |\n| 5, \"execution\", \"completion\", \"loop\" | Read [agent-execution-patterns.md](./references/agent-execution-patterns.md) |\n| 6, \"prompt\", \"system prompt\", \"behavior\" | Read [system-prompt-design.md](./references/system-prompt-design.md) |\n| 7, \"context\", \"inject\", \"runtime\", \"dynamic\" | Read [dynamic-context-injection.md](./references/dynamic-context-injection.md) |\n| 8, \"parity\", \"ui action\", \"capability map\" | Read [action-parity-discipline.md](./references/action-parity-discipline.md) |\n| 9, \"self-modify\", \"evolve\", \"git\" | Read [self-modification.md](./references/self-modification.md) |\n| 10, \"product\", \"progressive\", \"approval\", \"latent demand\" | Read [product-implications.md](./references/product-implications.md) |\n| 11, \"mobile\", \"ios\", \"android\", \"background\", \"checkpoint\" | Read [mobile-patterns.md](./references/mobile-patterns.md) |\n| 11a, \"icloud\", \"storage\", \"documents\", \"file state\", \"entitlement\" | Read [mobile-storage.md](./references/mobile-storage.md) |\n| 11b, \"background task\", \"battery\", \"on-device\", \"cloud routing\" | Read [mobile-execution.md](./references/mobile-execution.md) |\n| 11c, \"model tier\", \"token budget\", \"cost-aware\", \"batch\", \"caching\" | Read [mobile-cost.md](./references/mobile-cost.md) |\n| 12, \"test\", \"testing\", \"verify\", \"validate\" | Read [agent-native-testing.md](./references/agent-native-testing.md) |\n| 13, \"review\", \"refactor\", \"existing\" | Read [refactoring-to-prompt-native.md](./references/refactoring-to-prompt-native.md) |\n| 14, \"anti-pattern\", \"mistake\", \"wrong\" | Read [anti-patterns.md](./references/anti-patterns.md) |\n| 15, \"success\", \"criteria\", \"verify\", \"checklist\" | Read [success-criteria.md](./references/success-criteria.md) |\n| 16, \"hook\", \"hooks\", \"PreToolUse\", \"decision control\", \"async hook\" | Read [hooks-patterns.md](./references/hooks-patterns.md) |\n| 0, \"quick start\", \"getting started\", \"overview\", \"introduction\" | Read [quick-start.md](./references/quick-start.md) |\n\n**After reading the reference, apply those patterns to the user's specific context.**\n\n## Architecture Review Checklist\n\nWhen designing an agent-native system, verify these **before implementation**:\n\n### Core Principles\n- [ ] **Parity:** Every UI action has a corresponding agent capability\n- [ ] **Granularity:** Tools are primitives; features are prompt-defined outcomes\n- [ ] **Composability:** New features can be added via prompts alone\n- [ ] **Emergent Capability:** Agent can handle open-ended requests in your domain\n\n### Tool Design\n- [ ] **Dynamic vs Static:** For external APIs where agent should have full access, use Dynamic Capability Discovery\n- [ ] **CRUD Completeness:** Every entity has create, read, update, AND delete\n- [ ] **Primitives over Workflows:** Tools expose atomic capabilities; compose workflows in prompts\n- [ ] **API as Validator:** Use `z.string()` inputs when the API validates, not `z.enum()`\n- [ ] **Eval Gate:** 10 Q/A pairs in CI (read-only, multi-hop, closed-data), 9/10 pass threshold. See [mcp-tool-design.md](./references/mcp-tool-design.md) Evaluation section.\n\n### Files & Workspace\n- [ ] **Shared Workspace:** Agent and user work in same data space\n- [ ] **context.md Pattern:** Agent reads/updates context file for accumulated knowledge\n- [ ] **File Organization:** Entity-scoped directories with consistent naming\n- [ ] **Context Durability:** Incremental progress writes (WAL pattern) so interrupted tasks resume from last checkpoint\n\n### Agent Execution\n- [ ] **Completion Signals:** Agent has explicit `complete_task` tool (not heuristic detection)\n- [ ] **Partial Completion:** Multi-step tasks track progress for resume\n- [ ] **Context Limits:** Designed for bounded context from the start\n- [ ] **Validate-Before-Run:** Agent previews planned actions before executing destructive operations\n\n### Context Injection\n- [ ] **Available Resources:** System prompt includes what exists (files, data, types)\n- [ ] **Available Capabilities:** System prompt documents tools with user vocabulary\n- [ ] **Dynamic Context:** Context refreshes for long sessions (or provide `refresh_context` tool)\n- [ ] **Trust levels for loaded content:** System prompt distinguishes trusted (developer-authored) from untrusted (user input, retrieved docs, tool outputs); untrusted text is data, never instructions. See [dynamic-context-injection.md](./references/dynamic-context-injection.md) Trust Levels section for the prompt-injection defense details.\n\n### UI Integration\n- [ ] **Agent -> UI:** Agent changes reflect in UI (shared service, file watching, or event bus)\n- [ ] **No Silent Actions:** Agent writes trigger UI updates immediately\n- [ ] **Capability Discovery:** Users can learn what agent can do\n\n### Governance\n- [ ] **Approval Gates:** Destructive or irreversible actions require user confirmation\n- [ ] **Audit Trail:** Agent actions logged with timestamp, tool, and outcome\n- [ ] **Scope Boundaries:** Agent cannot access resources outside its designated workspace\n\n### Hooks & Governance Automation\n- [ ] **Event Coverage:** Only 6 hook events fire in agent context (PreToolUse, PostToolUse, PermissionRequest, PostToolUseFailure, Stop/SubagentStop); session lifecycle logic lives in the orchestrator\n- [ ] **Decision Gates:** PreToolUse hooks enforce tool-level policy (allow/deny/ask/defer) instead of hardcoded checks\n- [ ] **Completion Gating:** SubagentStop hooks block premature completion when verification steps remain\n- [ ] **MCP Matchers:** Regex patterns target tools by server and operation for capability-based security\n- [ ] **Two-Tier Config:** Shared policy committed, personal overrides git-ignored, per-hook disable toggles\n\n### Mobile (if applicable)\n- [ ] **Checkpoint/Resume:** Handle iOS app suspension gracefully\n- [ ] **iCloud Storage:** iCloud-first with local fallback for multi-device sync\n- [ ] **Cost Awareness:** Model tier selection (Haiku/Sonnet/Opus)\n\n**When designing architecture, explicitly address each checkbox in your plan.**","tags":["agent","native","architecture","skills","iliaal","agent-skills","ai-coding-assistant","ai-tools","claude-code"],"capabilities":["skill","source-iliaal","skill-agent-native-architecture","topic-agent-skills","topic-ai-coding-assistant","topic-ai-tools","topic-claude-code","topic-skills"],"categories":["ai-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/iliaal/ai-skills/agent-native-architecture","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add iliaal/ai-skills","source_repo":"https://github.com/iliaal/ai-skills","install_from":"skills.sh"}},"qualityScore":"0.456","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 13 github stars · SKILL.md body (8,591 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:07:01.506Z","embedding":null,"createdAt":"2026-05-09T01:05:34.437Z","updatedAt":"2026-05-18T19:07:01.506Z","lastSeenAt":"2026-05-18T19:07:01.506Z","tsv":"'/references/action-parity-discipline.md':347 '/references/agent-execution-patterns.md':322 '/references/agent-native-testing.md':417 '/references/anti-patterns.md':433 '/references/architecture-patterns.md':283 '/references/core-principles.md':27 '/references/dynamic-context-injection.md':338,756 '/references/files-universal-interface.md':295 '/references/from-primitives-to-domain-tools.md':315 '/references/hooks-patterns.md':452 '/references/mcp-tool-design.md':306,604 '/references/mobile-cost.md':409 '/references/mobile-execution.md':396 '/references/mobile-patterns.md':374 '/references/mobile-storage.md':384 '/references/product-implications.md':365 '/references/quick-start.md':462 '/references/refactoring-to-prompt-native.md':424 '/references/self-modification.md':356 '/references/shared-workspace-architecture.md':298 '/references/success-criteria.md':441 '/references/system-prompt-design.md':330 '0':453 '1':101,277 '10':199,357,585 '11':208,366 '11a':375 '11b':385 '11c':397 '12':216,410 '13':227,418 '14':236,425 '15':247,434 '16':257,442 '2':113,289 '3':125,299 '4':136,307 '5':149,316 '6':158,323,837 '7':168,331 '8':178,339 '9':189,348 '9/10':599 'access':545,825 'accumul':626 'achiev':37 'action':179,276,342,495,690,785,807,814 'action-parity-discipline.md':346 'ad':516 'add':57,142,312 'address':945 'agent':2,6,15,36,72,108,162,176,182,194,220,234,255,483,499,522,541,611,621,651,655,687,769,771,786,798,813,823,842 'agent-execution-patterns.md':321 'agent-n':5,14,107,219,233,254,482 'agent-native-architectur':1 'agent-native-testing.md':416 'allow':42 'allow/deny/ask/defer':865 'alon':519 'android':369 'anti':238,427 'anti-pattern':237,426 'anti-patterns.md':432 'api':539,571,579 'app':88,173,222,919 'appli':285,467 'applic':915 'approv':206,360,802 'architectur':4,8,103,252,279,286,476,943 'architecture-patterns.md':282 'area':99 'async':266,448 'atom':565 'audit':811 'author':739 'autom':833 'avail':697,707 'avoid':245 'awar':404,936 'background':213,370,386 'base':894 'batch':405 'batteri':388 'behavior':46,163,327 'better':90 'block':874 'bound':678 'boundari':822 'budget':401 'build':128 'bus':782 'cach':406 'cannot':824 'capability-bas':892 'capabl':69,132,224,343,500,521,548,566,708,792,893 'chang':45,97,772 'check':869 'checkbox':947 'checklist':287,438,478 'checkpoint':371,650 'checkpoint/resume':215,916 'ci':589 'close':597 'closed-data':596 'cloud':392 'code':53,67,96,231 'commit':902 'common':240 'complet':135,152,155,318,551,653,658,665,870,876 'compos':54,511,567 'config':899 'confirm':810 'consist':635 'content':732 'context':156,169,332,475,623,637,674,679,695,717,718,726,843 'context.md':619 'control':263,447 'core':9,490 'core-principles.md':26 'correspond':498 'cost':403,935 'cost-awar':402 'coverag':835 'creat':555 'criteria':24,167,249,436 'crud':134,303,550 'data':598,617,705,751 'decis':262,446,856 'defens':765 'defin':161,509 'delet':559 'demand':205,362 'design':17,81,102,127,201,278,480,533,676,829,942 'destruct':693,804 'detail':19,766 'detect':663 'develop':738 'developer-author':737 'devic':391,933 'didn':79 'directori':633 'disabl':911 'disclosur':203 'discoveri':133,549,793 'distinguish':735 'doc':745 'document':378,711 'domain':137,143,308,531 'durabl':638 'dynam':131,335,534,547,716 'dynamic-context-injection.md':337,755 'edit':49 'emerg':68,520 'enabl':193 'end':76,527 'enforc':860 'ensur':181 'entiti':553,631 'entitl':381 'entity-scop':630 'eval':583 'evalu':605 'even':94 'event':261,781,834,839 'everi':38,493,552 'everyth':185 'evolv':197,352 'exampl':21 'execut':150,214,317,652,692 'exist':230,421,703 'explan':20 'explicit':657,944 'expos':564 'extern':538 'fallback':929 'featur':59,505,513 'file':114,117,290,379,607,624,628,704,778 'files-universal-interface.md':294 'filesystem':292 'fire':840 'first':926 'five':11 'focus':98 'from-primitives-to-domain-tools.md':314 'full':544 'gate':584,803,857,871 'get':456 'git':353,906 'git-ignor':905 'govern':13,801,832 'grace':921 'granular':43,501 'haiku/sonnet/opus':940 'handl':73,524,917 'hardcod':868 'heurist':662 'hook':258,260,267,443,444,449,831,838,859,873,910 'hooks-patterns.md':451 'hop':595 'icloud':376,922,925 'icloud-first':924 'ignor':907 'immedi':791 'implement':489 'improv':83 'includ':701 'increment':639 'inject':170,171,333,696,764 'input':576,743 'instead':866 'instruct':753 'integr':768 'interfac':121 'interrupt':645 'introduct':459 'io':211,368,918 'irrevers':806 'judgment':166 'know':139 'knowledg':627 'last':649 'latent':204,361 'learn':796 'level':729,758,863 'lifecycl':850 'limit':157,675 'line':31 'live':852 'load':731 'local':928 'log':815 'logic':851 'long':721 'loop':319 'make':229 'map':344 'matcher':265,882 'mcp':264,301,881 'mcp-tool-design.md':305,603 'mistak':241,429 'mobil':209,367,913 'mobile-cost.md':408 'mobile-execution.md':395 'mobile-patterns.md':373 'mobile-storage.md':383 'model':398,937 'modif':192 'modifi':351 'month':93 'multi':594,667,932 'multi-devic':931 'multi-hop':593 'multi-step':666 'name':636 'nativ':3,7,16,109,221,235,256,484 'never':752 'new':63,66,106,512 'on-devic':389 'one':30 'one-lin':29 'open':75,526 'open-end':74,525 'oper':694,890 'orchestr':855 'organ':629 'outcom':39,510,820 'output':747 'outsid':827 'overrid':904 'overview':458 'pair':587 'pariti':33,180,226,340,492 'partial':154,664 'pass':600 'pattern':124,151,207,210,239,259,428,469,620,643,884 'per':909 'per-hook':908 'permissionrequest':846 'person':903 'plan':104,280,689,950 'polici':864,901 'posttoolus':845 'posttoolusefailur':847 'prematur':875 'pretoolus':445,844,858 'preview':688 'primit':129,148,302,504,560 'principl':10,12,28,491 'proceed':272 'product':200,358 'product-implications.md':364 'progress':202,359,640,671 'prompt':64,160,165,177,324,326,508,518,570,700,710,734,763 'prompt-defin':507 'prompt-inject':762 'prose':50 'provid':724 'q/a':586 'quick':454 'quick-start.md':461 'read':281,293,304,313,320,328,336,345,354,363,372,382,394,407,415,422,431,439,450,460,464,556,591 'read-on':590 'reads/updates':622 'refactor':52,228,420 'refactoring-to-prompt-native.md':423 'refer':273,466 'reflect':773 'refresh':719,725 'regex':883 'remain':880 'request':77,528 'requir':808 'resourc':698,826 'respons':270,275 'resum':647,673 'retriev':744 'review':419,477 'rout':274,393 'run':686 'runtim':172,334 'safe':196 'scope':632,821 'scratch':112 'section':606,759 'secur':895 'see':25,602,754 'select':100,939 'self':191,350 'self-modif':190 'self-modifi':349 'self-modification.md':355 'server':888 'servic':777 'session':722,849 'share':122,609,776,900 'shared-workspace-architecture.md':297 'signal':153,654 'silent':784 'skill' 'skill-agent-native-architecture' 'source-iliaal' 'space':618 'specif':474 'start':455,457,682 'state':174,380 'static':536 'stay':146 'step':668,879 'stop/subagentstop':848 'storag':212,377,923 'subagentstop':872 'success':248,435 'success-criteria.md':440 'suspens':920 'sync':934 'system':110,159,325,485,699,709,733 'system-prompt-design.md':329 'target':885 'task':387,646,659,669 'test':23,32,217,218,411,412 'text':749 'threshold':601 'tier':399,898,938 'time':85 'timestamp':817 'toggl':912 'token':400 'tool':126,130,138,144,300,309,502,532,563,660,712,727,746,818,862,886 'tool-level':861 'topic-agent-skills' 'topic-ai-coding-assistant' 'topic-ai-tools' 'topic-claude-code' 'topic-skills' 'track':670 'trail':812 'trigger':788 'trust':728,736,757 'two':897 'two-tier':896 'type':706 'ui':41,341,494,767,770,775,789 'univers':120 'untrust':741,748 'updat':557,790 'use':116,546,574 'user':186,472,613,714,742,794,809 'valid':414,573,580,684 'validate-before-run':683 'verif':878 'verifi':250,413,437,486 'via':517 'vocabulari':715 'vs':145,535 'wait':268 'wal':642 'watch':779 'without':65,95 'work':89,614 'workflow':562,568 'workspac':115,123,291,608,610,830 'write':61,641,787 'wrong':430 'z.enum':582 'z.string':575","prices":[{"id":"852d713a-1d38-467a-8450-273e1bd276b2","listingId":"3dafb709-652f-431e-acd5-cb561c6149e8","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"iliaal","category":"ai-skills","install_from":"skills.sh"},"createdAt":"2026-05-09T01:05:34.437Z"}],"sources":[{"listingId":"3dafb709-652f-431e-acd5-cb561c6149e8","source":"github","sourceId":"iliaal/ai-skills/agent-native-architecture","sourceUrl":"https://github.com/iliaal/ai-skills/tree/master/skills/agent-native-architecture","isPrimary":false,"firstSeenAt":"2026-05-09T01:05:34.437Z","lastSeenAt":"2026-05-18T19:07:01.506Z"}],"details":{"listingId":"3dafb709-652f-431e-acd5-cb561c6149e8","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"iliaal","slug":"agent-native-architecture","github":{"repo":"iliaal/ai-skills","stars":13,"topics":["agent-skills","ai-coding-assistant","ai-tools","claude-code","skills"],"license":"mit","html_url":"https://github.com/iliaal/ai-skills","pushed_at":"2026-05-16T13:15:17Z","description":"Curated collection of agent skills for AI coding assistants.","skill_md_sha":"9f991f6baf2f2a33c4d8ca075c63688860e14f22","skill_md_path":"skills/agent-native-architecture/SKILL.md","default_branch":"master","skill_tree_url":"https://github.com/iliaal/ai-skills/tree/master/skills/agent-native-architecture"},"layout":"multi","source":"github","category":"ai-skills","frontmatter":{"name":"agent-native-architecture","description":">-"},"skills_sh_url":"https://skills.sh/iliaal/ai-skills/agent-native-architecture"},"updatedAt":"2026-05-18T19:07:01.506Z"}}