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

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	Namespace System	Skills use namespaced names and resolve tool conflicts via qualified names
ADR-010	Actor and Agent Architecture	Skills are assigned to actors to provide their tool capabilities
ADR-011	Tool System	Skills compose tools into reusable, hierarchical collections
ADR-013	Validation Abstraction	Validation tools can be included in skills alongside regular tools
ADR-028	Agent Skills Standard (AgentSkills.io)	Agent Skills are composed and exposed through the skill system
ADR-029	Model Context Protocol (MCP) Adoption	MCP tools are exposed through skills for actor access
ADR-030	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