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

adr_number, title, status_history, tier, authors, superseded_by, related_adrs, acceptance

adr_number	title	status_history	tier	authors	superseded_by	related_adrs	acceptance
12	Skill System	2026-02-16 Proposed Jeffrey Phillips Freeman 2026-02-16 Accepted Jeffrey Phillips Freeman	2	Jeffrey Phillips Freeman	null	number title relationship 2 Namespace System Skills use namespaced names and resolve tool conflicts via qualified names number title relationship 10 Actor and Agent Architecture Skills are assigned to actors to provide their tool capabilities number title relationship 11 Tool System Skills compose tools into reusable, hierarchical collections number title relationship 13 Validation Abstraction Validation tools can be included in skills alongside regular tools number title relationship 28 Agent Skills Standard (AgentSkills.io) Agent Skills are composed and exposed through the skill system number title relationship 29 Model Context Protocol (MCP) Adoption MCP tools are exposed through skills for actor access number title relationship 30 Skill Abstraction Definition Formalizes the canonical definition of what a skill is	votes_for votes_against abstentions voter comment Jeffrey Phillips Freeman <Jeffrey.Freeman@CleverThis.com> Composable skill collections with hierarchical inclusion keep actor configuration manageable

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.