# ADR-012: Skill System

**Status:** Accepted  
**Date:** 2026-02-16  
**Supersedes:** None  
**Author(s):** Jeffrey Phillips Freeman <Jeffrey.Freeman@CleverThis.com>  
**Approver(s):** Jeffrey Phillips Freeman <Jeffrey.Freeman@CleverThis.com>

## 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

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: `<skill_name>.<tool_name>`. 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 (`<skill_name>.<tool_name>`) 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.

## Related ADRs

| ADR | Title | Relationship |
|-----|-------|-------------|
| [ADR-002](ADR-002-namespace-system.md) | Namespace System | Skills use namespaced names and resolve tool conflicts via qualified names |
| [ADR-010](ADR-010-actor-and-agent-architecture.md) | Actor and Agent Architecture | Skills are assigned to actors to provide their tool capabilities |
| [ADR-011](ADR-011-tool-system.md) | Tool System | Skills compose tools into reusable, hierarchical collections |
| [ADR-013](ADR-013-validation-abstraction.md) | Validation Abstraction | Validation tools can be included in skills alongside regular tools |
| [ADR-028](ADR-028-agent-skills-standard.md) | Agent Skills Standard (AgentSkills.io) | Agent Skills are composed and exposed through the skill system |
| [ADR-029](ADR-029-model-context-protocol.md) | Model Context Protocol (MCP) Adoption | MCP tools are exposed through skills for actor access |
| [ADR-030](ADR-030-skill-abstraction-definition.md) | Skill Abstraction Definition | Formalizes the canonical definition of what a skill is |

## Acceptance

### Votes For

| Voter | Comment |
|-------|---------|
| Jeffrey Phillips Freeman <Jeffrey.Freeman@CleverThis.com> | Composable skill collections with hierarchical inclusion keep actor configuration manageable |

**Total: 1**

### Votes Against

| Voter | Comment |
|-------|---------|

**Total: 0**

### Abstentions

| Voter | Comment |
|-------|---------|

**Total: 0**
