cleveragents-core/docs/adr/ADR-012-skill-system.md

---
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 <Jeffrey.Freeman@CleverThis.com>
    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: `<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.