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
    └── fallbackSuite/
        └── plannerFallback/
            └── 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 skill only exposes the permitted skills (report, data) to LightSOPLang command registries and downstream plan prompts.

Fallback Descriptor

You can provide an alternative orchestration playbook that runs when the scripted flow fails or when the orchestrator is invoked explicitly as a fallback.

# Fallback Planner

Handles ad-hoc investigations when no predefined skill fits.

## Instructions

- Evaluate whether existing skills cover the request.
- If no skill is suitable, pivot to the fallback playbook.

## Allowed Skills

- nonexistent-placeholder

## Fallback

Intent: investigation
Gather detailed transactional records and summarise discrepancies for the operator.

Allowed Tools:
- invoiceLookup
- ledgerSearch

## LightSOPLang

@prompt prompt
@attempt nonexistent-placeholder $prompt "Attempt non-existent skill" investigation

During execution, a failure to execute any scripted steps triggers the Fallback section. The agent composes a ReAct-style MCP plan using the provided instructions and tool allow-list.

Execution Flow

1. Discovery: The orchestration skill loader parses oskill.md, extracting instructions, allowed skills, intents, and optional scripts.
2. Code Generation (if specs exist): If the skill includes a specs directory, the RecursiveSkilledAgent automatically generates executable code from the specifications before any script execution. This generated code takes precedence over LightSOPLang scripts.
3. Scripted Execution: If the descriptor includes a LightSOPLang block and no specs directory exists, the interpreter runs those commands first via a command registry that respects the allow-list.
4. LLM Planning: When no script is provided and no specs directory exists, the skill asks the LLMAgent for a JSON-formatted plan constrained to the allowed skills.
5. Fallback: If all steps fail or are skipped, the optional fallback descriptor generates a recovery plan, usually by scheduling MCP tools.

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.

Code Generation from Specifications

For complex orchestration scenarios, you can define specifications in natural language and let the agent generate the implementation.

Creating a Specification-Based Orchestration Skill

1. Create the skill descriptor: Start with a basic oskill.md file.

   # Disk Manager Orchestrator
   
   This skill manages disk operations using generated code.
   
   ## Instructions
   Plan and execute disk operations.
   
   ## LightSOPLang
   # This script will be IGNORED because a 'specs' folder exists.
   @doomed skill-that-does-not-exist "This should never run"

2. Add specification files: Create a specs directory and add specification files for each module.

   # specs/index.mjs.md
   # Main Module Specification
   
   ## Input Format
   - context: Object containing prompt string
   
   ## Output Format
   - Returns an object with status, operation, and path
   
   ## Constraints
   - Must handle file operations asynchronously
   - Must validate file paths before operations
   
   ## Examples
   - createFile('/path/to/file', 'content') -> {status: 'success', operation: 'createFile', path: '/path/to/file'}
   - deleteFile('/path/to/file') -> {status: 'success', operation: 'deleteFile', path: '/path/to/file'}

3. Run the agent: When you create a RecursiveSkilledAgent, it automatically detects the specs directory and generates the code.

   const agent = new RecursiveSkilledAgent({
       llmAgent: new LLMAgent({ name: 'MyAgent' }),
       startDir: '/path/to/project',
   });
   
   // The agent will automatically generate code during initialization
   await Promise.all(agent.pendingPreparations);
   
   // Now you can use the generated skill
   const result = await agent.executePrompt('createFile /tmp/test.txt hello', {
       skillName: 'disk-manager'
   });

Note: The generated code is written to the src directory. You should not edit these files directly. Instead, update the specification files in the specs directory and let the agent regenerate the code.