# 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

```bash
# 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:

```bash
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:

```bash
nox -s benchmark
```