Orchestration Skills

Inside the Descriptor

Every orchestration skill is documented in .AchillesSkills/<domain>/<skill_name>/oskill.md. The descriptor breaks the plan into human-readable pieces:

• Instructions: How the planner should interpret the user’s request.
• Allowed Skills: The catalogue of downstream skills this planner may call.
• Intents: ReAct-style shorthand that explains the purpose of each step.
• Fallback: Recovery guidance when scripted steps fail.
• LightSOPLang: An optional deterministic script that runs before any LLM planning.

# Planner Orchestrator

## Instructions
- Analyse the request and split it into intents.
- Prefer the reporting skill for summarisation tasks.

## Allowed Skills
- report
- data

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

## Fallback
Intent: investigation
Allowed Tools:
- invoiceLookup

## LightSOPLang
@prompt prompt
@report report $prompt "Primary summary" reporting
@data data $prompt "Collect supporting facts" data-fetch

Scripts make the skill deterministic; LightSOPLang variables such as @report or @data read almost like prose, keeping the intent legible to non-technical reviewers.

Code Generation from Specifications

When an orchestration skill includes a specs directory containing specification files (e.g., index.mjs.md, DiskManager.js.md), the RecursiveSkilledAgent automatically generates executable code from these specifications.

Important: If a specs directory exists, the generated code takes precedence over any existing LightSOPLang script or other source code. The agent will:

1. Parse all specification files in the specs directory
2. Send them to the LLM for code generation
3. Write the generated code to the src directory
4. Execute the generated code when the skill is invoked

This allows you to define complex orchestration logic using natural language specifications while maintaining the flexibility to regenerate the implementation as requirements evolve.

.AchillesSkills/disk-manager/
├── oskill.md                  # Orchestration descriptor
└── specs/                     # Specification directory
    ├── index.mjs.md           # Main module specification
    └── DiskManager.js.md      # Helper class specification

# After code generation:
.AchillesSkills/disk-manager/
├── oskill.md                  # Orchestration descriptor
├── specs/                     # Specification directory
│   ├── index.mjs.md           # Main module specification
│   └── DiskManager.js.md      # Helper class specification
└── src/                       # Generated code directory
    ├── index.mjs              # Generated main module
    └── DiskManager.js         # Generated helper class

Execution Styles

Orchestration skills execute in one of two modes. If a LightSOPLang block is present, the skill runs those commands immediately, invoking the named skills with shared context and intent tags. If there is no script, the skill requests a plan from the language model, constrained by the allowed list. Either way, the result is a structured itinerary that downstream components can replay step-by-step.

Fallback Thinking

Real processes rarely run perfectly. Fallback sections capture how the team wants to respond when data is missing or a tool fails. Some skills define investigative LightSOPLang scripts, while others instruct the planner to seek help from MCP tools. Because the fallback follows the same descriptor format, it stays auditable and predictable.

Design Tips

• Keep the allowed skills list focused so plans remain easy to reason about.
• Write instructions as if coaching a teammate; the clearer the story, the better the plan.
• Use intent labels consistently to explain why each step exists.
• Pair orchestration skills with tutorials or test fixtures to show how they behave under pressure.