MCP Skills Tutorial

Repository Layout

MCP skills sit under the same .AchillesSkills root as other skill types. The recursive agent fixtures ship with:

tests/recursiveAgent/recursiveAgentFixtures/
└── .AchillesSkills/
    ├── orchestrationSuite/
    │   └── data/
    │       └── mskill.md
    └── llmSuite/
        └── llmData/
            └── mskill.md

Each directory can optionally include companion LightSOPLang scripts or JavaScript helpers, but the descriptor alone is sufficient for planning.

Descriptor Example

# Inventory Data Retrieval

Plan MCP tool usage to gather inventory records for downstream tasks.

## Instructions

- Select tools that fetch stock or movement data.
- Avoid pricing or unrelated finance tools unless explicitly mentioned.
- Provide clear reasoning for each tool invocation.

## Allowed Tools

- inventoryLookup

The Instructions section feeds the planner prompt, while Allowed Tools constrains which MCP commands may be scheduled. Even if the runtime advertises additional tools, the skill will ignore those not listed here.

Adding LightSOPLang (Optional)

When you want a fully deterministic plan, add a LightSOPLang section to the descriptor. The fallback orchestrator in the test suite demonstrates this pattern:

## LightSOPLang

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

The command registry exposes only metricScanner and inventoryLookup because they were declared in Allowed Tools. Each command becomes a plan step persisted in the MCP execution log.

Execution Output

Whether the plan comes from LightSOPLang or the LLM, the skill returns a structured payload:

{
  skill: 'inventory-data-retrieval',
  result: {
    type: 'mcp',
    prompt: 'Collect current stock levels for review.',
    plan: [
      { tool: 'inventoryLookup', arguments: 'Collect current stock levels for review.', why: 'Default stub selection' }
    ],
    notes: ''
  }
}

Tests such as tests/recursiveAgent/orchestration.test.mjs assert that the plan respects the allow-list and that each step records the rationale string (why) sourced from the descriptor or LLM response.

Creating New MCP Skills

1. Create .AchillesSkills/<domain>/<skill_name>/mskill.md.
2. Populate Instructions with precise guidance for the planner.
3. List all permitted tools under Allowed Tools.
4. Add an optional LightSOPLang block when deterministic sequencing is required.
5. Register the repository (or let tests auto-discover it) and execute via RecursiveSkilledAgent.executePrompt supplying available tool metadata.