brent.edwards
f0815dd126
CI / lint (pull_request) Has been cancelled
CI / typecheck (pull_request) Has been cancelled
CI / security (pull_request) Has been cancelled
CI / quality (pull_request) Has been cancelled
CI / unit_tests (pull_request) Has been cancelled
CI / integration_tests (pull_request) Has been cancelled
CI / coverage (pull_request) Has been cancelled
CI / build (pull_request) Has been cancelled
CI / docker (pull_request) Has been cancelled
79 lines
2.8 KiB
Markdown
79 lines
2.8 KiB
Markdown
# 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
|
|
```
|