MCP Skills

MCP skills let Achilles Agents choreograph external tools that speak the Model Context Protocol. They decide which tool to call, capture why the step matters, and return an auditable plan that other skills can build upon. Use them for telemetry sweeps, document hunts, or compliance checks where a predictable toolchain is essential.

Descriptor Overview

Each skill lives in .AchillesSkills/<domain>/<skill_name>/mskill.md. The descriptor tells the agent:

Instructions: How to approach the task and what evidence to collect.
Allowed Tools: A whitelist that constrains the plan to approved MCP commands.
LightSOPLang: Optional deterministic scripts for sequences that should never vary.
Notes or Limits: Optional guidance that caps adaptive plan length or adds review tips.

# LLM Data Lookup

## Instructions
- Prefer tools that extract current metrics.
- Explain why each tool is selected so the reporter can summarise later.

## Allowed Tools
- metricScanner
- inventoryLookup

## LightSOPLang
@prompt prompt
@scan metricScanner $prompt "Collect freshness metrics"
@lookup inventoryLookup $prompt "Fetch inventory snapshots"

The allowed list keeps execution safe, while LightSOPLang provides a deterministic fall-back when you need one.

Planning Styles

MCP skills run in two styles. Scripted mode executes the LightSOPLang program exactly as written, producing a plan of tool calls with attached rationales. Adaptive mode asks the LLM for a JSON plan that honours the allowed-tool list and any plan limits. Both outputs show the tool name, arguments, and justification so reviewers can trust the result.

Telling the Story

Descriptors work best when they read like coaching notes for a teammate. Describe what success means, when to skip a tool, and how to present the findings. The tutorials and fixtures under tests/recursiveAgent/recursiveAgentFixtures/.AchillesSkills include working MCP skills that you can use as blueprints.

Authoring Checklist

Create .AchillesSkills/<domain>/<skill_name>/mskill.md with clear instructions and an explicit allowed-tool list.
Add a LightSOPLang block when a deterministic sequence is required.
State how success is reported so downstream consumers know what to expect.
Register the repository or wire it into tests to exercise the workflow end-to-end.

Focus on the outcome—Achilles Agents handle the protocol mechanics while your descriptor guards intent and scope.