====== 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 (([https://alphasignalai.substack.com/p/how-ai-agents-follow-senior-engineer|AlphaSignal - How AI Agents Follow Senior Engineer Patterns (2026)]))). This architecture enables systematic composition of agent capabilities, facilitating both maintainability and extensibility in agent-based systems.(([[https://alphasignalai.substack.com/p/how-ai-agents-follow-senior-engineer|AlphaSignal (2026]]))



===== 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` (([https://alphasignalai.substack.com/p/how-ai-agents-follow-senior-engineer|AlphaSignal - How AI Agents Follow Senior Engineer Patterns (2026)]))), 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 (([https://arxiv.org/abs/2308.00352|Sap et al. - Coordination and Strategy in Multi-Agent RL (2023)]))). 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 (([https://alphasignalai.substack.com/p/how-ai-agents-follow-senior-engineer|AlphaSignal - How AI Agents Follow Senior Engineer Patterns (2026)]))). 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 (([https://arxiv.org/abs/2309.16935|Wang et al. - Cognitive Architectures for Language Agents (2023)]))). 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 (([https://alphasignalai.substack.com/p/how-ai-agents-follow-senior-engineer|AlphaSignal - How AI Agents Follow Senior Engineer Patterns (2026)]))).

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 (([https://arxiv.org/abs/2006.16236|Andreas et al. - Modular Compositionality Through Language Models (2020)])).

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 =====
  * [[runtime_layer_architecture|Runtime Layer Architecture for AI Agents]]
  * [[skill_based_agent_modularity|Skill-Based Agent Modularity]]
  * [[agent_team_architecture|Agent Team Architecture]]
  * [[ai_agent_skills|AI Agent Skills]]
  * [[three_layer_memory_system|Three-Layer Memory System]]

===== References =====