cleveragents-core/docs/reference/skill_resolution.md

Skill Resolution Reference

The SkillResolver flattens a skill's tool set by recursively resolving includes, collecting tool refs, inline tools, MCP sources, and agent skill sources into an ordered list of ResolvedToolEntry objects.

Resolution Algorithm

1. Cycle detection -- Before descending into includes, check if the current skill has already been visited in this resolution path. If so, raise a ValueError with the full cycle path trace.
2. Depth-first include resolution -- Process each SkillInclude by recursively resolving the included skill first. Tools from deeper includes appear earlier in the final order.
3. Tool ref collection -- Add tool_refs from the current skill.
4. Inline tool collection -- Anonymous tools are keyed as {skill_name}/_anon_{index}.
5. MCP source collection -- Each tool is added as mcp:{server}/{tool_name}.
6. Agent skill collection -- Each agent skill path is added as agent_skill:{path}.

De-duplication

When the same tool name appears multiple times (e.g., from overlapping includes), the last occurrence wins for entry metadata. The tool's position in the ordered list is preserved from its first appearance.

Robot Smoke Tests

A Robot Framework smoke suite validates core resolver behavior:

robot/skill_resolution.robot
robot/helper_skill_resolution.py

Running the Robot smoke suite

# Via nox (recommended -- uses the correct virtualenv automatically)
nox -s integration_tests -- robot/skill_resolution.robot

# Directly with robot (ensure dependencies are installed)
robot --outputdir build/reports/robot robot/skill_resolution.robot

What the suite covers

Test Case	What it validates
Resolve Skill With Flat Includes Preserves Depth-First Order	Included tools appear before the root skill's own refs
Resolve Skill With Overlapping Includes De-Duplicates	Shared tools appear once; last-wins semantics for metadata
Resolve Skill With Inline Tools And MCP Sources	Anonymous tools keyed as _anon_N, MCP tools keyed correctly
Resolve Skill With Cycle Raises Error	Circular includes produce a clear cycle-detection error

Behave BDD Tests

The Behave feature file features/skill_resolution.feature contains comprehensive scenarios for the Skill model and resolver. The scenarios mirror the Robot smoke expectations and cover additional edge cases including override application, capability summary computation, and from_config loading.

Run the Behave suite via:

nox -s unit_tests -- features/skill_resolution.feature

ASV Benchmarks

Performance benchmarks live in benchmarks/skill_resolution_bench.py and track construction, serialization, and resolution throughput. Run via:

nox -s benchmark