cleveragents-core/docs/adr/ADR-030-skill-abstraction-definition.md

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	Actor and Agent Architecture	Actors reference skills to acquire tool capabilities; skills are the binding mechanism
ADR-011	Tool System	Tools are the atomic operations that skills collect and present to actors
ADR-012	Skill System	Implements the skill abstraction: composition, inclusion, registry, and flattening
ADR-028	Agent Skills Standard (AgentSkills.io)	Agent Skills are one of the four tool sources unified under the skill abstraction
ADR-029	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