| name | agent-native-architecture |
| description | This skill should be used when building AI agents using prompt-native architecture where features are defined in prompts, not code. Use it when creating autonomous agents, designing MCP servers, implementing self-modifying systems, or adopting the "trust the agent's intelligence" philosophy. |
> See [EXAMPLES.md](./EXAMPLES.md) for ❌/✅ pairs illustrating every
> anti-pattern named below.
<essential_principles>
The Prompt-Native Philosophy
Agent native engineering inverts traditional software architecture. Instead of writing code that the agent executes, you 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. Many things the developer can do, the agent can do.
Don't artificially limit the agent. If a user could read files, write code, browse the web, deploy an app—the agent should be able to do those things too. The agent figures out HOW to achieve an outcome; it doesn't just call your pre-written functions.
Features Are Prompts
Each feature is a prompt that defines an outcome and gives the agent the tools it needs. The agent then figures out how to accomplish it.
Traditional: Feature = function in codebase that agent calls
Prompt-native: Feature = prompt defining desired outcome + primitive tools
The agent doesn't execute your code. It uses primitives to achieve outcomes you describe.
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 your workflow
Right: read_file, write_file, list_files — agent figures out how to build a dashboard
Pure primitives are better, but domain primitives (like store_feedback) are OK if they don't encode logic—just storage/retrieval.
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
Self-Modification (Advanced)
The advanced tier: agents that can evolve their own code, prompts, and behavior. Not required for every app, but a big part of the future.
When implementing:
- Approval gates for code changes
- Auto-commit before modifications (rollback capability)
- Health checks after changes
- Build verification before restart
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
- High security - though this is overblown for most apps
</essential_principles>
What aspect of agent native architecture do you need help with?
- 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
- API integration - Connect to external APIs (HealthKit, HomeKit, GraphQL)
Wait for response before proceeding.
| Response | Action |
|----------|--------|
| 1, "design", "architecture", "plan" | Read [architecture-patterns.md](./references/architecture-patterns.md), then apply Architecture Checklist below |
| 2, "tool", "mcp", "primitive" | Read [mcp-tool-design.md](./references/mcp-tool-design.md) |
| 3, "prompt", "system prompt", "behavior" | Read [system-prompt-design.md](./references/system-prompt-design.md) |
| 4, "self-modify", "evolve", "git" | Read [self-modification.md](./references/self-modification.md) |
| 5, "review", "refactor", "existing" | Read [refactoring-to-prompt-native.md](./references/refactoring-to-prompt-native.md) |
| 6, "context", "inject", "runtime", "dynamic" | Read [dynamic-context-injection.md](./references/dynamic-context-injection.md) |
| 7, "parity", "ui action", "capability map" | Read [action-parity-discipline.md](./references/action-parity-discipline.md) |
| 8, "workspace", "shared", "files", "filesystem" | Read [shared-workspace-architecture.md](./references/shared-workspace-architecture.md) |
| 9, "test", "testing", "verify", "validate" | Read [agent-native-testing.md](./references/agent-native-testing.md) |
| 10, "mobile", "ios", "android", "background" | Read [mobile-patterns.md](./references/mobile-patterns.md) |
| 11, "api", "healthkit", "homekit", "graphql", "external" | Read [mcp-tool-design.md](./references/mcp-tool-design.md) (Dynamic Capability Discovery section) |
After reading the reference, apply those patterns to the user's specific context.
<architecture_checklist>
Architecture Review Checklist (Apply During Design)
When designing an agent-native system, verify these before implementation:
Tool Design
Action Parity
UI Integration
Context Injection
Mobile (if applicable)
When designing architecture, explicitly address each checkbox in your plan.
</architecture_checklist>
<quick_start>
Build a prompt-native agent in three steps:
Step 1: Define primitive tools
const tools = [
tool("read_file", "Read any file", { path: z.string() }, ...),
tool("write_file", "Write any file", { path: z.string(), content: z.string() }, ...),
tool("list_files", "List directory", { path: z.string() }, ...),
];
Step 2: Write behavior in the system prompt
## Your Responsibilities
When asked to organize content, you should:
1. Read existing files to understand the structure
2. Analyze what organization makes sense
3. Create appropriate pages using write_file
4. Use your judgment about layout and formatting
You decide the structure. Make it good.
Step 3: Let the agent work
query({
prompt: userMessage,
options: {
systemPrompt,
mcpServers: { files: fileServer },
permissionMode: "acceptEdits",
}
});
</quick_start>
<reference_index>
Domain Knowledge
All references in references/:
Core Patterns:
Agent-Native Disciplines:
<anti_patterns>
What NOT to Do
The positive rules above (essential principles + architecture checklist)
already state what to do. For the inverse — what each rule looks like when
violated, with a paired ❌/✅ code or prose example for each — see
EXAMPLES.md.
The pairs cover: the cardinal sin (agent executes your workflow), artificial
capability limits, encoding decisions in tools, over-specifying in prompts,
context starvation, orphan features, sandbox isolation, silent actions,
capability hiding, static tool mapping, and incomplete CRUD.
</anti_patterns>
<success_criteria>
You've built a prompt-native agent when:
Core Prompt-Native Criteria:
Tool Design Criteria:
Agent-Native Criteria:
Mobile-Specific Criteria (if applicable):
