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.
Design prompt-native agents where features are defined in prompts, not code. Use when building autonomous agents, MCP servers, or self-modifying systems that figure out HOW to achieve outcomes using primitive tools.
/plugin marketplace add RBozydar/rbw-claude-code/plugin install core@rbw-claude-codeThis skill inherits all available tools. When active, it can use any tool Claude has access to.
references/action-parity-discipline.mdreferences/agent-native-testing.mdreferences/architecture-patterns.mdreferences/dynamic-context-injection.mdreferences/mcp-tool-design.mdreferences/mobile-patterns.mdreferences/refactoring-to-prompt-native.mdreferences/self-modification.mdreferences/shared-workspace-architecture.mdreferences/system-prompt-design.md<essential_principles>
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.
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.
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 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 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:
Wait for response before proceeding. </intake>
<routing> | 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. </routing>
<architecture_checklist>
When designing an agent-native system, verify these before implementation:
z.string() inputs when the API validates, not z.enum()refresh_context tool)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>
All references in references/:
Core Patterns:
Agent-Native Disciplines:
<anti_patterns>
THE CARDINAL SIN: Agent executes your code instead of figuring things out
This is the most common mistake. You fall back into writing workflow code and having the agent call it, instead of defining outcomes and letting the agent figure out HOW.
// WRONG - You wrote the workflow, agent just executes it
tool("process_feedback", async ({ message }) => {
const category = categorize(message); // Your code
const priority = calculatePriority(message); // Your code
await store(message, category, priority); // Your code
if (priority > 3) await notify(); // Your code
});
// RIGHT - Agent figures out how to process feedback
tool("store_item", { key, value }, ...); // Primitive
tool("send_message", { channel, content }, ...); // Primitive
// Prompt says: "Rate importance 1-5 based on actionability, store feedback, notify if >= 4"
Don't artificially limit what the agent can do
If a user could do it, the agent should be able to do it.
// WRONG - limiting agent capabilities
tool("read_approved_files", { path }, async ({ path }) => {
if (!ALLOWED_PATHS.includes(path)) throw new Error("Not allowed");
return readFile(path);
});
// RIGHT - give full capability, use guardrails appropriately
tool("read_file", { path }, ...); // Agent can read anything
// Use approval gates for writes, not artificial limits on reads
Don't encode decisions in tools
// Wrong - tool decides format
tool("format_report", { format: z.enum(["markdown", "html", "pdf"]) }, ...)
// Right - agent decides format via prompt
tool("write_file", ...) // Agent chooses what to write
Don't over-specify in prompts
// Wrong - micromanaging the HOW
When creating a summary, use exactly 3 bullet points,
each under 20 words, formatted with em-dashes...
// Right - define outcome, trust intelligence
Create clear, useful summaries. Use your judgment.
Context Starvation Agent doesn't know what resources exist in the app.
User: "Write something about Catherine the Great in my feed"
Agent: "What feed? I don't understand what system you're referring to."
Fix: Inject available resources, capabilities, and vocabulary into the system prompt at runtime.
Orphan Features UI action with no agent equivalent.
// UI has a "Publish to Feed" button
Button("Publish") { publishToFeed(insight) }
// But no agent tool exists to do the same thing
Fix: Add corresponding tool and document in system prompt for every UI action.
Sandbox Isolation Agent works in separate data space from user.
Documents/
├── user_files/ ← User's space
└── agent_output/ ← Agent's space (isolated)
Fix: Use shared workspace where both agent and user operate on the same files.
Silent Actions Agent changes state but UI doesn't update.
// Agent writes to database
await db.insert("feed", content);
// But UI doesn't observe this table - user sees nothing
Fix: Use shared data stores with reactive binding, or file system observation.
Capability Hiding Users can't discover what agents can do.
User: "Help me with my reading"
Agent: "What would you like help with?"
// Agent doesn't mention it can publish to feed, research books, etc.
Fix: Include capability hints in agent responses or provide onboarding.
Static Tool Mapping (for agent-native apps) Building individual tools for each API endpoint when you want the agent to have full access.
// You built 50 tools for 50 HealthKit types
tool("read_steps", ...)
tool("read_heart_rate", ...)
tool("read_sleep", ...)
// When glucose tracking is added... code change required
// Agent can only access what you anticipated
Fix: Use Dynamic Capability Discovery - one list_* tool to discover what's available, one generic tool to access any type. See mcp-tool-design.md. (Note: Static mapping is fine for constrained agents with intentionally limited scope.)
Incomplete CRUD Agent can create but not update or delete.
// ❌ User: "Delete that journal entry"
// Agent: "I don't have a tool for that"
tool("create_journal_entry", ...)
// Missing: update_journal_entry, delete_journal_entry
Fix: Every entity needs full CRUD (Create, Read, Update, Delete). The CRUD Audit: for each entity, verify all four operations exist. </anti_patterns>
<success_criteria> You've built a prompt-native agent when:
Core Prompt-Native Criteria:
Tool Design Criteria:
list_*, discover_*)Agent-Native Criteria:
refresh_context tool exists)Mobile-Specific Criteria (if applicable):
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.