Browse
Core Concepts
Reasoning
Memory & Retrieval
Agent Types
Design Patterns
Training & Alignment
Frameworks
Tools
Safety
Meta
User Tools
Sidebar
three_layer_architecture
Table of Contents
Three-Layer Architecture (Skill, Persona, Command)
The Three-Layer Architecture represents a modular organizational framework for AI agent design and implementation, decomposing complex agent behaviors into three distinct, composable layers: Skills, Personas, and Commands 1)). This architecture enables systematic composition of agent capabilities, facilitating both maintainability and extensibility in agent-based systems.2)
Skills Layer
The foundational layer of the architecture consists of Skills, which represent discrete, reusable workflows encapsulated as markdown-based specifications. Each skill is defined within a dedicated directory structure following the pattern `skills/<name>/SKILL.md` 3)), where the markdown document contains the complete workflow definition, parameters, execution logic, and success criteria for that particular skill.
Skills function as atomic units of capability that can be invoked independently or composed together to achieve more complex objectives. This modular approach parallels the layering principles found in multi-agent systems research, where decomposition of tasks into specialized components improves both reliability and interpretability 4)). By maintaining skills as self-contained markdown documents, the architecture enables version control, documentation, and straightforward testing of individual capabilities without requiring modification to higher-layer components.
Personas Layer
The Personas layer provides orchestration capabilities through markdown-based agents positioned in the `agents/` directory structure. Personas function as decision-making entities that invoke and coordinate multiple skills to accomplish user objectives 5)). Rather than implementing skill logic directly, personas act as compositional wrappers that select appropriate skills, manage execution order, and handle conditional logic based on task requirements and context.
This organizational pattern reflects established agent architecture principles from cognitive science and AI research, where personas represent distinct behavioral profiles or decision-making strategies 6)). A persona might specialize in particular domains (such as code review, documentation, or system design) and delegate to skills that provide the actual execution mechanisms. This separation enables agents to reason about which skills to apply without embedding task-specific logic at the orchestration level.
Commands Layer
The Commands layer provides explicit user-facing interfaces through slash command syntax, with implementation varying by platform. For Claude Code environments, commands are defined in `.claude/commands/*.md` files, while Gemini implementations use `.gemini/commands/*.toml` configuration files 7)).
Commands serve as the entry points through which users trigger personas or invoke skills directly. This layer abstracts the underlying complexity of skill and persona composition, exposing a clean command-line-style interface for interaction. The dual-format approach (markdown for Claude, TOML for Gemini) reflects platform-specific preferences while maintaining architectural consistency across different AI service providers.
Architectural Composition and Benefits
The three-layer design enables several important properties in agent systems. Reusability is achieved through skills that can be invoked across multiple personas and commands without duplication. Maintainability improves through clear separation of concerns, where skill modifications do not require changes to orchestration logic. Extensibility becomes straightforward—new skills can be added without modifying existing personas or commands, following the open-closed principle from software engineering 8).
The architecture also supports platform agnosticism, enabling the same skill and persona definitions to be deployed across different AI provider ecosystems through platform-specific command implementations. This separation allows organizations to maintain consistent agent behaviors while adapting to varying provider APIs and interface conventions.
Implementation Patterns
In practice, this architecture typically manifests as follows: A developer defines a skill (such as “code-review” or “architecture-analysis”) as a detailed workflow markdown document specifying input requirements, processing steps, and output formatting. A persona then composes multiple skills—for example, a “senior-engineer” persona might invoke “code-review”, “performance-analysis”, and “design-feedback” skills in sequence or conditionally. Finally, commands expose these personas to end-users: `/review-pr` might trigger the senior-engineer persona to analyze a pull request, while `/suggest-optimization` might invoke the performance-analysis skill directly.
This layering facilitates the creation of sophisticated multi-step agent workflows that remain manageable and debuggable. Teams can develop and test skills in isolation, design persona behaviors independent of specific implementation details, and expose varying command surfaces without replicating underlying logic.
See Also
References
1)
, 3)
, 5)
, 7)
[https://alphasignalai.substack.com/p/how-ai-agents-follow-senior-engineer|AlphaSignal - How AI Agents Follow Senior Engineer Patterns (2026)]
4)
[https://arxiv.org/abs/2308.00352|Sap et al. - Coordination and Strategy in Multi-Agent RL (2023)]
6)
[https://arxiv.org/abs/2309.16935|Wang et al. - Cognitive Architectures for Language Agents (2023)]
8)
[https://arxiv.org/abs/2006.16236|Andreas et al. - Modular Compositionality Through Language Models (2020)]
three_layer_architecture.txt · Last modified: (external edit)
Page Tools
