Adding Skill Program

Adding a Skill-Based Program

Read wizard-development for the shared design policy. Use Pi for new agent work and prefer an orchestrator flow. Linear runs are for very simple work and existing flows. The Anthropic SDK remains a supported legacy fallback, deprecated as the default for new work; the shared guide owns the fallback criteria and gateway model/effort/system-prompt contract.

These are contribution defaults. A program whose config sets no binding runs on DEFAULT_BINDING, Pi and linear.

Choose the contribution surface

• Content-only capability: use the existing skill command machinery when it can express the workflow. Context-mill owns skill content and cliEntries. A new skill-backed child of an existing family ships through context-mill; inspect family dispatch. Unpromoted skills run through the skill command.
• Native program: use a ProgramConfig when the wizard needs its own flow, screens, detection, composition, or other native behavior. Keep product instructions in context-mill.

Command names, program id, context-mill agentFlow, and skillId have different roles. Use the full product name for public commands. The config field is id.

Build a native orchestrator program

Use metrics as the current Pi/orchestrator example and read the runner architecture when changing execution behavior.

1. Add the program folder src/programs/<id>/. Its index.ts is the only entry: it exports the ProgramConfig as config, and any detectors or keys the TUI and CLI need. No other file in the folder is named index.ts. Copy a sibling's tsconfig.json into the folder, unchanged, and add { "path": "<id>" } to references in src/programs/tsconfig.json. The folder is one project, its tests included, and pnpm typecheck (tsc -b) builds it. Without the reference, the registry's import fails with TS6307. Keep tests in <id>/__tests__; they reach other layers through their entries only. Shared program code goes in src/programs/shared/, detection/, warehouse-sources/, frameworks/ or oauth/, never in another program's folder, and has no index.ts. A program imports its own files and the shared program code by relative path, such as ../shared/skill-program. Set agentFlow when its context-mill flow differs from id; setting it explicitly also documents the content dependency. Keep a run definition so runProgram executes agent work.
2. Supply the flow's seed and task prompts in context-mill, including the task dependencies and applicable skill variants. The orchestrator loads agentFlow ?? id, requires a seed prompt, and checks task-skill variants before running. run.skillId alone does not define this flow.
3. Register the config: import it as import { config as <name> } from '@programs/<id>' in program-registry.ts and add it to PROGRAM_REGISTRY. Set the config's binding to Pi and the orchestrator. ProgramId is a string.
4. For a standalone native command, create a command module in src/cli/commands with nativeCommandFactory and register it in runCli in src/cli/index.ts. A native family child uses the handlers in family dispatch. Program registration derives screen sequences and store lookup, not the top-level CLI .use() chain.
5. Check the program's OAuth scopes against the tools it needs. Add oauthScopeAdditions to the config only when the base set is insufficient. Keep a program's own set in its folder, as replay-vision does; sets several programs share live in program-scopes.ts.

Model and effort selections in flow frontmatter must be supported by the wizard and gateway. Follow the cross-repo procedure in wizard-development before introducing a model or changing gateway-required prompt material.

Simple linear programs and existing flows

For a very simple linear flow, use createSkillProgram to configure installation of one skill. Register the native program as above. The factory sets no binding, so the program runs on DEFAULT_BINDING unless you add one to the config it returns. Read SkillProgramOptions for required fields; audit demonstrates factory customization and a dynamic run(session) that seeds a ledger. Revenue analytics builds its config directly and adds prerequisite detection.

ProgramRun.customPrompt, abortCases, postRun, and buildOutroData are consumed by the linear sequence. postRun runs after success; buildOutroData receives session and credentials, with host information inside credentials. The orchestrator currently uses its own task prompts, failure handling, and outro, and does not invoke those hooks. Check this limitation before migrating a linear flow; setting an orchestrator binding does not preserve these behaviors automatically.