Orchestration Skills Tutorial

Repository Layout

Orchestration skills live alongside other assets inside .AchillesSkills. The planner scenario in the test suite uses the following structure:

tests/recursiveAgent/recursiveAgentFixtures/
└── .AchillesSkills/
    └── orchestrationSuite/
        └── planner/
            └── oskill.md

Primary Descriptor

oskill.md defines the instructions, allow-lists, and intents consumed by the orchestration skill.

# Planner Orchestrator

This orchestrator coordinates logistics reporting and MCP lookups.

## Instructions

- Analyse the request and split it into intents.
- Prefer the reporting skill for summarisation tasks.
- Use the data MCP skill when raw records are required before reporting.
- Reorder or drop steps when they do not help the user.

## Allowed Skills

- report
- data

## Intents

- reporting: Prepare human readable summaries or status updates.
- data-fetch: Retrieve underlying inventory or operational records.

The allowed skills (report, data) become the toolbelt for whichever agentic session the subsystem launches. Each command issued by the session maps back to one of these concrete skills.

Selecting a Session Type

The descriptor can opt into loop execution by declaring a loop block:

## Loop
true

Leaving the section out keeps the orchestrator in SOP mode (deeper planning). Adding it switches to the loop agent session, which is faster and more iterative.

Loop Session Walkthrough

1. Toolbelt creation: The subsystem resolves the allowed skills and exposes each one as a callable command.
2. Prompting: The loop agent receives the descriptor's instructions as its system prompt.
3. Iterative execution: The agent calls tools until the request is met or a step limit is reached, returning the final answer as result.

SOP Session Walkthrough

1. Toolbelt creation: Same as loop sessions—allowed skills become commands.
2. Plan generation: The SOP agent assembles a LightSOPLang-style plan internally, executing it through a commands registry backed by the toolbelt.
3. Trace capture: The session returns variables alongside the final output for auditing.

Execution Flow

1. Discovery: The loader parses oskill.md, extracting instructions, allowed skills, intents, and optional loop metadata.
2. Toolbelt Assembly: Each allowed skill becomes a callable handler plus a short description.
3. Agentic Session: The subsystem launches executeSOPAgentSession by default or executeLoopAgentSession when ## Loop is set.
4. Delegation: Session commands call back into RecursiveSkilledAgent with explicit skillName values.
5. Result Packaging: Responses include the raw result, session label (loop or sop), and SOP variables when applicable.

The regression tests under tests/recursiveAgent/orchestration.test.mjs exercise these flows end-to-end and are an excellent reference when authoring new orchestration skills.