--- adr_number: 12 title: Skill System status_history: - - '2026-02-16' - Proposed - Jeffrey Phillips Freeman - - '2026-02-16' - Accepted - Jeffrey Phillips Freeman tier: 2 authors: - Jeffrey Phillips Freeman superseded_by: null related_adrs: - number: 2 title: Namespace System relationship: Skills use namespaced names and resolve tool conflicts via qualified names - number: 10 title: Actor and Agent Architecture relationship: Skills are assigned to actors to provide their tool capabilities - number: 11 title: Tool System relationship: Skills compose tools into reusable, hierarchical collections - number: 13 title: Validation Abstraction relationship: Validation tools can be included in skills alongside regular tools - number: 28 title: Agent Skills Standard (AgentSkills.io) relationship: Agent Skills are composed and exposed through the skill system - number: 29 title: Model Context Protocol (MCP) Adoption relationship: MCP tools are exposed through skills for actor access - number: 30 title: Skill Abstraction Definition relationship: Formalizes the canonical definition of what a skill is acceptance: votes_for: - voter: Jeffrey Phillips Freeman comment: Composable skill collections with hierarchical inclusion keep actor configuration manageable votes_against: [] abstentions: [] --- ## Context Actors need curated sets of tools to perform their roles — a code execution actor needs file operations, git tools, and test runners; a DevOps actor needs infrastructure provisioning and deployment tools. Assigning tools individually to each actor would be repetitive, error-prone, and difficult to maintain. The system needs an organizational unit that groups related tools into reusable, composable collections. ## Decision Drivers - Must compose tool collections from four distinct sources (MCP, Agent Skills, built-in, custom) - Skills must be reusable across different actors without duplication of tool assignments - Need hierarchical inclusion with automatic flattening for LLM tool binding - Tool name conflicts across composed skills must be resolvable without manual renaming - Actors performing similar roles should share common tool sets without redundant configuration - Skill access must be restrictable per-actor to enforce capability boundaries ## Decision A **skill** is a namespaced, reusable collection of tools that serves as the organizational layer between individual tools and actors. Skills are defined in YAML, support hierarchical composition through skill-includes, and are flattened into a unified tool set when referenced by an actor. ## Design ### Skill Definition Skills are defined in YAML configuration files and managed via `agents skill` CLI commands. A skill configuration includes: - **`name`**: Namespaced identifier (e.g., `local/devops-toolkit`). - **`tools`**: Named tool references (by namespace/name from the Tool Registry), with optional metadata overrides. - **`includes`**: References to other skills, with optional per-tool overrides. - **`mcp_servers`**: MCP server configurations, with optional per-tool overrides. - **`agent_skills`**: Agent Skills (SKILL.md) references. - **`builtins`**: Built-in tool group references (e.g., `file_operations`, `git_operations`). - **`anonymous_tools`**: Inline tool definitions scoped to this skill only. ### Skill / Tool Distinction **Tools** are independently registered atomic operations with their own name, YAML, source, capability metadata, and lifecycle. **Skills** are organizational units. They group named tool references, anonymous inline tools, child skill includes, and source-specific tool collections (MCP, Agent Skills, builtins). A skill has no execution logic of its own — it is purely a composition mechanism. When an actor references a skill, it gains the **flattened set** of all tools from that skill and its transitive includes. ### Hierarchical Composition Skills can include other skills, forming a hierarchy: ``` local/full-stack-dev ├── local/file-ops (builtins: file_operations, directory_operations) ├── local/code-analysis (MCP: semgrep-server, custom: local/ast-parser) ├── local/testing (custom: local/run-pytest, local/coverage-check) └── local/devops-toolkit ├── local/docker-tools (MCP: docker-server) └── local/deploy (custom: local/helm-deploy) ``` The flattened tool set is the union of all tools across the entire hierarchy. ### Name Conflict Resolution When the same tool name appears in multiple included skills, conflicts are resolved by qualification: `.`. This ensures unambiguous tool references even in complex composition hierarchies. ### Metadata Overrides at Inclusion When a skill includes another skill or references a named tool, it can override `capability` and `description` metadata at the point of inclusion. Overrides are shallow-merged, never persist back to the source, and cannot override schema or built-in metadata. ### Tool Source Integration Skills integrate tools from all four sources: - **Named tools**: Reference registered tools by name from the Tool Registry. - **MCP servers**: Declare MCP server configurations; all tools exposed by the server are included. - **Agent Skills**: Reference SKILL.md files; tools described in frontmatter are included. - **Built-ins**: Reference built-in tool groups by name (e.g., `file_operations`). - **Anonymous tools**: Define inline tools scoped to this skill only. ### Skill Access Policy Actors specify a `skill_access_policy` that controls which skills they can use. This enables restricting an actor to a specific set of capabilities (e.g., a read-only review actor should not have access to write-capable skills). ## Constraints - Circular skill includes are forbidden. The include graph must be a DAG. - Tool name conflicts across included skills must be resolved by qualification. - Skills do not have execution logic — they are purely organizational. - Anonymous tools defined in a skill are scoped to that skill only and are not registered in the Tool Registry. - Skill names follow the namespace system (`[[server:]namespace/]name`). ## Consequences ### Positive - Reusable skill definitions eliminate repetitive tool assignment across actors. - Hierarchical composition enables building complex capability sets from simple, focused skills. - The flattening model ensures actors always see a flat tool set, regardless of how deeply the skill hierarchy is nested. - MCP, Agent Skill, built-in, and custom tools are composed uniformly through the skill layer. ### Negative - Deep skill hierarchies can make it difficult to determine which tools an actor actually has access to without inspecting the full transitive closure. - Metadata overrides at multiple inclusion points can create confusion about the effective metadata for a tool. - The qualification mechanism for name conflicts (`.`) produces verbose tool names. ### Risks - Large flattened tool sets may exceed LLM context window limits, degrading tool-calling accuracy. - Skill hierarchy changes (adding or removing tools from a shared skill) have cascading effects on all actors that reference it. ## Alternatives Considered **Direct tool assignment to actors (no skill layer)** — Simpler but does not scale. Actors performing similar roles would have redundant tool lists, and changes to tool sets would require updating every affected actor individually. **Dynamic tool selection (LLM chooses tools from the full registry)** — Removes the curation benefit. Without curated skill sets, the LLM must choose from the entire tool registry, which is both a security risk (access to tools it should not have) and a quality risk (too many irrelevant tools in the prompt). ## Compliance - **Cycle detection**: Skill registration validates that includes do not introduce cycles. - **Flattening tests**: Unit tests verify that hierarchically composed skills produce the correct flattened tool set, including conflict resolution. - **Override tests**: Tests verify that metadata overrides at inclusion points are applied correctly and do not persist back to the source. - **Access policy tests**: Tests verify that actor skill access policies correctly restrict the available tool set. - **BDD scenarios**: Behave features exercise actors using hierarchically composed skills across all tool sources.