# ADR-030: Skill Abstraction Definition

**Status:** Proposed  
**Date:** 2026-02-17  
**Supersedes:** None  
**Author(s):** CleverAgents Team  
**Approver(s):**

## Context

CleverAgents integrates tools from four heterogeneous sources — MCP servers, Agent Skills (AgentSkills.io) folders, built-in tool groups, and custom Python implementations. Without a unifying abstraction, actors would need to understand each source's discovery mechanism, lifecycle, and metadata format individually. The system needs a single, well-defined concept that bridges the gap between individual tools (which are atomic, independently registered operations) and actors (which need coherent bundles of capabilities to perform their roles). The term "skill" is used throughout the specification, CLI, and configuration but its precise definition — what it is, what it is not, and how it relates to the four tool sources — must be formalized as an architectural commitment.

## Decision

CleverAgents defines a **skill** as a **composable, namespaced collection of tools** that serves as the unit of capability assignment to actors. A skill is not a tool; it is a container that assembles tools from any combination of the four supported sources into a coherent, reusable bundle. Actors never reference individual tools directly for capability assignment — they reference skills, and through skills gain access to a flattened set of tools.

## Design

### Canonical Definition

A **skill** is a YAML-configured, namespaced entity registered in the Skill Registry that:

1. **Aggregates tools from four sources** into a single collection:

   | Source | How Referenced in Skill YAML | Discovery Mechanism |
   |--------|----------------------------|---------------------|
   | **Built-in tool groups** | `builtin_groups:` section | Pre-registered by the runtime |
   | **Custom Python tools** | `tools:` section (named references or inline anonymous tools) | Tool Registry lookup or inline definition |
   | **MCP server tools** | `mcp_servers:` section | MCPToolAdapter `discover()` via JSON-RPC `tools/list` |
   | **Agent Skills folders** | `agent_skill_folders:` section | AgentSkillAdapter `discover()` via SKILL.md parsing |

2. **Produces a flattened tool set** — when resolved, a skill yields a flat list of `ToolRecord` entries regardless of their original source. All tools in the set share the same four-stage lifecycle (`discover`, `activate`, `execute`, `deactivate`) and are indistinguishable to the actor runtime.

3. **Is the unit of capability assignment** — actors reference skills by fully-qualified namespaced name in their `skills:` list. The actor's graph gains access to the union of all tools from all referenced skills.

### What a Skill Is Not

| Skill is... | Skill is not... |
|-------------|----------------|
| A **container** of tools | A single executable operation |
| **Named and registered** in the Skill Registry | An anonymous or inline concept |
| **Defined in its own YAML file** | Defined inline in an actor configuration |
| **Source-agnostic** after flattening | Tied to a specific tool source |
| The **assignment unit** for actors | Directly callable by end users |

A skill never executes — tools execute. A skill organizes, composes, and presents tools to actors as a coherent capability surface.

### Tool Source Unification

The skill abstraction is the architectural seam where four distinct tool ecosystems converge into a uniform interface:

- **MCP tools** (schema-driven, low-latency, deterministic) enter through `mcp_servers:` and are individually registered with inferred or overridden capability metadata.
- **Agent Skills** (instruction-driven, multi-step, knowledge-rich) enter through `agent_skill_folders:` and appear as tool records whose execution loads SKILL.md instructions into the LLM context.
- **Built-in tools** (bundled with the runtime) enter through `builtin_groups:` and require no external process.
- **Custom tools** (user-authored Python) enter through `tools:` either as named references to registered tools or as anonymous inline definitions.

After flattening, the actor runtime does not distinguish between these sources. A tool node in an actor graph referencing a skill-provided tool behaves identically whether the underlying source is MCP, Agent Skills, built-in, or custom.

### Hierarchical Composition

Skills compose hierarchically through the `includes:` mechanism:

```
Skill: local/full-stack-ops
  includes:
    - local/file-ops          (5 tools)
    - local/git-ops           (3 tools)
    - local/github            (8 MCP tools)
  tools:
    - local/run-migrations    (1 custom tool)
  agent_skill_folders:
    - deploy-to-staging       (1 Agent Skill)
                              ─────────────
                              18 tools total (flattened)
```

When a child skill is included, all of its tools (including those from its own includes) are merged into the parent's flattened set. Per-tool metadata overrides can be applied at the inclusion point to adjust capability flags (e.g., marking a tool as `human_approval_required` in a specific skill context).

### Skill Registry

The Skill Registry is the persistent catalog that stores all registered skills and their resolved tool sets. Key operations:

- **Register**: Parse skill YAML, resolve all tool references and includes, store the `SkillRecord` with its flattened tool list.
- **Resolve**: Given a skill name, return the complete flattened tool set (used during actor activation).
- **Validate**: Ensure all referenced tools exist in the Tool Registry, all included skills are registered, and no circular includes exist.
- **Refresh**: When a tool's metadata changes (e.g., MCP tool list refresh), update all skills that include that tool.

### Actor Binding

When an actor is activated, the runtime:

1. Reads the actor's `skills:` list.
2. Resolves each skill name through the Skill Registry.
3. Merges all flattened tool sets into the actor's available tool surface.
4. Makes these tools available both for LLM tool-calling and as named tool nodes in the actor's graph.

This binding is the only path through which actors acquire tool capabilities. There is no mechanism for an actor to reference a tool without going through a skill.

## Constraints

- A skill must be defined in its own YAML configuration file — inline skill definitions in actor YAML are not permitted.
- A skill's flattened tool set must contain only valid, registered tools (or valid inline anonymous tool definitions).
- Circular skill includes are prohibited and must be detected at registration time.
- All four tool sources must produce `ToolRecord` entries with the same interface — source-specific behavior is encapsulated in the respective adapter.
- Actors must reference skills by fully-qualified namespaced name; glob patterns or wildcards are not supported in skill references.

## Consequences

### Positive
- A single abstraction unifies four heterogeneous tool ecosystems, eliminating source-specific logic in actor and graph code.
- Hierarchical composition enables DRY skill definitions — common tool bundles are defined once and included everywhere.
- The strict skill-as-container / tool-as-operation distinction prevents conceptual confusion in configuration and documentation.
- Actors gain capabilities declaratively through skill references, making actor configurations readable and auditable.
- New tool sources can be added in the future without changing the skill abstraction or actor binding model.

### Negative
- An extra layer of indirection (skill) sits between actors and tools, requiring configuration even for simple single-tool use cases.
- Flattening large skill hierarchies with many MCP servers could have non-trivial startup cost during actor activation.
- Tool name collisions across included skills must be resolved via fully-qualified names, adding configuration verbosity.

### Risks
- If the skill abstraction is bypassed (e.g., actors directly referencing tools outside skills), the uniform capability model breaks down.
- Overly deep skill inclusion hierarchies could become difficult to reason about and debug.
- Stale skill registrations (referencing removed tools or unreachable MCP servers) could cause silent capability degradation at actor activation time.

## Alternatives Considered

**Direct tool assignment to actors** — Actors reference individual tools by name instead of skills. Simpler for trivial cases but scales poorly (actors with 20+ tools become unwieldy), eliminates reuse (common tool sets duplicated across actors), and loses the organizational abstraction that makes configurations readable. Rejected.

**Implicit skill creation from tool groups** — Automatically create a skill for each tool source (one skill per MCP server, one per built-in group, etc.). Removes user control over composition, prevents cross-source bundling, and makes the abstraction invisible rather than explicit. Rejected.

**Skills as executable workflows** — Define skills as multi-step procedures rather than tool collections. Conflates skills with Agent Skills (which are instruction-driven workflows) and with actor graphs (which are the execution model). The current design correctly separates organization (skills) from execution (tools) from orchestration (actors/graphs). Rejected.

## Compliance

- **Skill YAML validation tests**: Verify that skill configurations correctly parse all four tool source sections and produce valid flattened tool sets.
- **Flattening tests**: Ensure hierarchical skill includes correctly merge tools, apply overrides, and detect circular references.
- **Actor binding tests**: Verify that actor activation resolves all skill references and produces the correct merged tool surface.
- **Source uniformity tests**: Confirm that tools from all four sources are indistinguishable after flattening (same `ToolRecord` interface, same lifecycle).
- **Registry consistency tests**: Validate that skill registration fails gracefully when referenced tools or included skills do not exist.

## Related ADRs

| ADR | Title | Relationship |
|-----|-------|-------------|
| [ADR-010](ADR-010-actor-and-agent-architecture.md) | Actor and Agent Architecture | Actors reference skills to acquire tool capabilities; skills are the binding mechanism |
| [ADR-011](ADR-011-tool-system.md) | Tool System | Tools are the atomic operations that skills collect and present to actors |
| [ADR-012](ADR-012-skill-system.md) | Skill System | Implements the skill abstraction: composition, inclusion, registry, and flattening |
| [ADR-028](ADR-028-agent-skills-standard.md) | Agent Skills Standard (AgentSkills.io) | Agent Skills are one of the four tool sources unified under the skill abstraction |
| [ADR-029](ADR-029-model-context-protocol.md) | Model Context Protocol (MCP) Adoption | MCP tools are one of the four tool sources unified under the skill abstraction |

## Acceptance

### Votes For

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

**Total: 0**

### Votes Against

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

**Total: 0**

### Abstentions

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

**Total: 0**
