Authoring Orchestration Skills

Descriptor Surface

The source file for this skill family is oskill.md. The subsystem reads the descriptor through the generic skill document parser and then looks only for a bounded set of section families. In the current implementation, these section families are instructions, preparation, allowed skills, allowed preparation skills, description, and session type. Several aliases are accepted for some headings, but the underlying contract remains the same.

The optional Help section is not part of the orchestration prompt contract. It exists for user-facing invocation guidance, such as autocomplete panels that need to show when and how a person should call the orchestrator.

Unlike DBTable Skills, this family does not derive a generated runtime module. The descriptor remains the central maintained artifact. For that reason, authoring quality matters directly. The headings should not be decorative. They should correspond to execution choices that the subsystem actually uses.

The most important practical consequence concerns omission. If Allowed Skills is omitted or left empty, the subsystem does not block execution. Instead, it exposes all discovered skills except the orchestrator itself. If tighter control is intended, the allowlist should therefore be declared explicitly.

Declared allowlists also define top-level ownership. Skills named in Allowed Skills or Allowed-Prep-Skills remain callable by the orchestrator, but MainAgent does not expose them as separate top-level tools during ordinary prompt sessions.

The behavior of Allowed-Prep-Skills is more specific. If this section is absent, preparation falls back to the same allowlist used for normal execution. If the section exists but contains no entries, then no preparation skills are available. This distinction should be authored deliberately, because it changes the bounded capability surface of the preparation stage.

Minimal Template

A practical minimal template is shown below. It is intentionally short, but it already exercises the parser and the main orchestration contract in a disciplined way.

# document-review

## Instructions

1. Determine which downstream skill should be used first.
2. Keep the execution path bounded to the declared allowlist.
3. Return a concise result after the delegated work is completed.

## Allowed Skills
- context-loader
- spec-reviewer

## Description
Coordinate a small document-review workflow through a bounded set of skills.

## Help
Invoke this orchestrator with the review task and the documents or scope to inspect.
Example input: review the architecture specs

This template does not declare a session type, so the subsystem will execute it through the SOP path. It also omits a preparation stage, so no separate preparation block will run before the main session starts.

Extended Example

When a workflow requires preparation and a loop-based session, the descriptor can be expanded as follows.

# review-specs

## Preparation

1. Load files that are mentioned in the user request. If none are mentioned,
   load all spec files under `./docs/specs` using context-loader.
2. Always load `./AGENTS.md`.

## Allowed-Prep-Skills
- context-loader

## Instructions

1. Determine which specification files contain problems.
2. For each problematic file, call backlog-expert to produce task text.
3. Store the generated tasks through backlog-api.
4. Enrich each task with bounded numbered options.

## Description
Analyze specification files, create backlog tasks for the detected problems,
and enrich those tasks with bounded solution options.

## Help
Invoke this orchestrator with the spec review request and any files or folders to inspect.
Example input: review docs/specs for stale contracts

## Session
loop

## Allowed Skills
- context-loader
- backlog-api
- backlog-expert

This version makes three operational choices explicit. The preparation stage is separated from the main session. The preparation stage is restricted to a narrower allowlist than the main workflow. The session type is fixed to loop rather than being left to the default SOP path.