The Prompt-Native Philosophy
Agent native engineering inverts traditional software architecture. Instead of writing code that the agent executes, define outcomes in prompts and let the agent figure out HOW to achieve them.
The Foundational Principle
Whatever the user can do, the agent can do.
Avoid artificially limiting the agent. If a user can read files, write code, browse the web, deploy an app -- the agent should be able to do those things too.
Features Are Prompts
Each feature is a prompt that defines an outcome and gives the agent the tools it needs.
Traditional: Feature = function in codebase that agent calls
Prompt-native: Feature = prompt defining desired outcome + primitive tools
Tools Provide Capability, Not Behavior
Tools should be primitives that enable capability. The prompt defines what to do with that capability.
Wrong: generate_dashboard(data, layout, filters) -- agent executes a predefined workflow
Right: read_file, write_file, list_files -- agent figures out how to build a dashboard
The Development Lifecycle
- Start in the prompt -- new features begin as natural language defining outcomes
- Iterate rapidly -- change behavior by editing prose, not refactoring code
- Graduate when stable -- harden to code when requirements stabilize AND speed/reliability matter
- Many features stay as prompts -- not everything needs to become code
When NOT to Use This Approach
- High-frequency operations (thousands of calls per second)
- Deterministic requirements (exact same output every time)
- Cost-sensitive scenarios (when API costs would be prohibitive)
What aspect of agent native architecture is needed?
- Design architecture -- plan a new prompt-native agent system
- Create MCP tools -- build primitive tools following the philosophy
- Write system prompts -- define agent behavior in prompts
- Self-modification -- enable agents to safely evolve themselves
- Review/refactor -- make existing code more prompt-native
- Context injection -- inject runtime app state into agent prompts
- Action parity -- ensure agents can do everything users can do
- Shared workspace -- set up agents and users in the same data space
- Testing -- test agent-native apps for capability and parity
- Mobile patterns -- handle background execution, permissions, cost
Wait for response before proceeding.
| Response |
Action |
| 1, "design", "architecture" |
Read architecture-patterns.md, apply Architecture Checklist |
| 2, "tool", "mcp", "primitive" |
Read mcp-tool-design.md |
| 3, "prompt", "system prompt" |
Read system-prompt-design.md |
| 4, "self-modify", "evolve" |
Read self-modification.md |
| 5, "review", "refactor" |
Read refactoring-to-prompt-native.md |
| 6, "context", "inject" |
Read dynamic-context-injection.md |
| 7, "parity", "capability" |
Read action-parity-discipline.md |
| 8, "workspace", "shared" |
Read shared-workspace-architecture.md |
| 9, "test", "testing" |
Read agent-native-testing.md |
| 10, "mobile", "ios" |
Read mobile-patterns.md |
After reading the reference, apply those patterns to the specific context.
Architecture Review Checklist
When designing an agent-native system, verify before implementation:
Tool Design
Action Parity
UI Integration
Context Injection
Mobile (if applicable)
Common Anti-Patterns
| Anti-Pattern |
Problem |
Fix |
Reference |
| Cardinal Sin |
Agent executes predefined workflow code instead of figuring things out |
Define outcomes in prompts, provide primitive tools |
architecture-patterns.md |
| Context Starvation |
Agent doesn't know what resources exist |
Inject available resources into system prompt at runtime |
dynamic-context-injection.md |
| Orphan Features |
UI action with no agent equivalent |
Add tool + document in system prompt for every UI action |
action-parity-discipline.md |
| Sandbox Isolation |
Agent works in separate data space from user |
Use shared workspace |
shared-workspace-architecture.md |
| Silent Actions |
Agent changes state but UI doesn't update |
Use shared data stores with reactive binding |
architecture-patterns.md |
| Capability Hiding |
Users can't discover what agents can do |
Include capability hints, provide onboarding |
action-parity-discipline.md |
| Static Tool Mapping |
Individual tools for each API endpoint |
Use Dynamic Capability Discovery (list_* + generic access tool) |
mcp-tool-design.md |
| Incomplete CRUD |
Agent can create but not update/delete |
Every entity needs all four CRUD operations |
mcp-tool-design.md |
See the referenced files for detailed examples and solutions.
References
All in references/:
Core Patterns:
Agent-Native Disciplines:
Success Criteria
A prompt-native agent is complete when:
1---2name: agent-native-architecture3description: This skill should be used when building AI agents using prompt-native architecture where features are defined in prompts, not code. It covers creating autonomous agents, designing MCP servers, implementing self-modifying systems, and adopting the "trust the agent's intelligence" philosophy.4---5
6<essential_principles>
7
8## The Prompt-Native Philosophy
9
10Agent native engineering inverts traditional software architecture. Instead of writing code that the agent executes, define outcomes in prompts and let the agent figure out HOW to achieve them.
11
12### The Foundational Principle
13
14**Whatever the user can do, the agent can do.**
15
16Avoid artificially limiting the agent. If a user can read files, write code, browse the web, deploy an app -- the agent should be able to do those things too.
17
18### Features Are Prompts
19
20Each feature is a prompt that defines an outcome and gives the agent the tools it needs.
21
22**Traditional:** Feature = function in codebase that agent calls
23**Prompt-native:** Feature = prompt defining desired outcome + primitive tools
24
25### Tools Provide Capability, Not Behavior
26
27Tools should be primitives that enable capability. The prompt defines what to do with that capability.
28
29**Wrong:** `generate_dashboard(data, layout, filters)` -- agent executes a predefined workflow
30**Right:** `read_file`, `write_file`, `list_files` -- agent figures out how to build a dashboard
31
32### The Development Lifecycle
33
341. **Start in the prompt** -- new features begin as natural language defining outcomes
352. **Iterate rapidly** -- change behavior by editing prose, not refactoring code
363. **Graduate when stable** -- harden to code when requirements stabilize AND speed/reliability matter
374. **Many features stay as prompts** -- not everything needs to become code
38
39### When NOT to Use This Approach
40
41- High-frequency operations (thousands of calls per second)
42- Deterministic requirements (exact same output every time)
43- Cost-sensitive scenarios (when API costs would be prohibitive)
44
45</essential_principles>
46
47<intake>
48
49What aspect of agent native architecture is needed?
50
511. **Design architecture** -- plan a new prompt-native agent system
522. **Create MCP tools** -- build primitive tools following the philosophy
533. **Write system prompts** -- define agent behavior in prompts
544. **Self-modification** -- enable agents to safely evolve themselves
555. **Review/refactor** -- make existing code more prompt-native
566. **Context injection** -- inject runtime app state into agent prompts
577. **Action parity** -- ensure agents can do everything users can do
588. **Shared workspace** -- set up agents and users in the same data space
599. **Testing** -- test agent-native apps for capability and parity
6010. **Mobile patterns** -- handle background execution, permissions, cost
61
62Wait for response before proceeding.
63
64</intake>
65
66<routing>
67
68| Response | Action |
69|----------|--------|
70| 1, "design", "architecture" | Read [architecture-patterns.md](./references/architecture-patterns.md), apply Architecture Checklist |
71| 2, "tool", "mcp", "primitive" | Read [mcp-tool-design.md](./references/mcp-tool-design.md) |
72| 3, "prompt", "system prompt" | Read [system-prompt-design.md](./references/system-prompt-design.md) |
73| 4, "self-modify", "evolve" | Read [self-modification.md](./references/self-modification.md) |
74| 5, "review", "refactor" | Read [refactoring-to-prompt-native.md](./references/refactoring-to-prompt-native.md) |
75| 6, "context", "inject" | Read [dynamic-context-injection.md](./references/dynamic-context-injection.md) |
76| 7, "parity", "capability" | Read [action-parity-discipline.md](./references/action-parity-discipline.md) |
77| 8, "workspace", "shared" | Read [shared-workspace-architecture.md](./references/shared-workspace-architecture.md) |
78| 9, "test", "testing" | Read [agent-native-testing.md](./references/agent-native-testing.md) |
79| 10, "mobile", "ios" | Read [mobile-patterns.md](./references/mobile-patterns.md) |
80
81After reading the reference, apply those patterns to the specific context.
82
83</routing>
84
85<architecture_checklist>
86
87## Architecture Review Checklist
88
89When designing an agent-native system, verify before implementation:
90
91### Tool Design
92- [ ] External APIs with full agent access use Dynamic Capability Discovery
93- [ ] Every entity has full CRUD tools
94- [ ] Tools are primitives, not workflows
95- [ ] API validates inputs (use `z.string()` not `z.enum()` when API validates)
96
97### Action Parity
98- [ ] Every UI action has a corresponding agent tool
99- [ ] Edit and delete operations are available, not just create/read
100- [ ] The "write something to [app location]" test passes for all locations
101
102### UI Integration
103- [ ] Agent changes reflect in UI immediately (shared service, file watching, or event bus)
104- [ ] Users can discover what the agent can do (onboarding, capability hints)
105
106### Context Injection
107- [ ] System prompt includes available resources and capabilities
108- [ ] Context refreshes for long sessions (or `refresh_context` tool exists)
109
110### Mobile (if applicable)
111- [ ] Background execution uses checkpoint/resume pattern
112- [ ] Just-in-time permission requests in tools
113- [ ] Cost-aware model tier selection
114
115</architecture_checklist>
116
117<anti_patterns>
118
119## Common Anti-Patterns
120
121| Anti-Pattern | Problem | Fix | Reference |
122|---|---|---|---|
123| **Cardinal Sin** | Agent executes predefined workflow code instead of figuring things out | Define outcomes in prompts, provide primitive tools | architecture-patterns.md |
124| **Context Starvation** | Agent doesn't know what resources exist | Inject available resources into system prompt at runtime | [dynamic-context-injection.md](./references/dynamic-context-injection.md) |
125| **Orphan Features** | UI action with no agent equivalent | Add tool + document in system prompt for every UI action | [action-parity-discipline.md](./references/action-parity-discipline.md) |
126| **Sandbox Isolation** | Agent works in separate data space from user | Use shared workspace | [shared-workspace-architecture.md](./references/shared-workspace-architecture.md) |
127| **Silent Actions** | Agent changes state but UI doesn't update | Use shared data stores with reactive binding | [architecture-patterns.md](./references/architecture-patterns.md) |
128| **Capability Hiding** | Users can't discover what agents can do | Include capability hints, provide onboarding | [action-parity-discipline.md](./references/action-parity-discipline.md) |
129| **Static Tool Mapping** | Individual tools for each API endpoint | Use Dynamic Capability Discovery (`list_*` + generic access tool) | [mcp-tool-design.md](./references/mcp-tool-design.md) |
130| **Incomplete CRUD** | Agent can create but not update/delete | Every entity needs all four CRUD operations | [mcp-tool-design.md](./references/mcp-tool-design.md) |
131
132See the referenced files for detailed examples and solutions.
133
134</anti_patterns>
135
136<reference_index>
137
138## References
139
140All in `references/`:
141
142**Core Patterns:**
143- [architecture-patterns.md](./references/architecture-patterns.md) -- system architecture
144- [mcp-tool-design.md](./references/mcp-tool-design.md) -- Dynamic Capability Discovery, CRUD Completeness
145- [system-prompt-design.md](./references/system-prompt-design.md) -- prompt structure
146- [self-modification.md](./references/self-modification.md) -- safe self-evolution
147- [refactoring-to-prompt-native.md](./references/refactoring-to-prompt-native.md) -- migration guide
148
149**Agent-Native Disciplines:**
150- [dynamic-context-injection.md](./references/dynamic-context-injection.md)
151- [action-parity-discipline.md](./references/action-parity-discipline.md)
152- [shared-workspace-architecture.md](./references/shared-workspace-architecture.md)
153- [agent-native-testing.md](./references/agent-native-testing.md)
154- [mobile-patterns.md](./references/mobile-patterns.md)
155
156</reference_index>
157
158<success_criteria>
159
160## Success Criteria
161
162A prompt-native agent is complete when:
163
164- [ ] The agent figures out HOW to achieve outcomes, not just calls predefined functions
165- [ ] Features are prompts defining outcomes, not code defining workflows
166- [ ] Tools are primitives enabling capability, not encoding logic
167- [ ] Changing behavior means editing prose, not refactoring code
168- [ ] Every UI action has a corresponding agent tool (action parity)
169- [ ] Agent and user operate in the same data space (shared workspace)
170- [ ] System prompt includes dynamic context about app state
171
172</success_criteria>
majiayu000