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. Current runtime bindings still default many programs to Anthropic plus linear; documentation changes do not migrate them.

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, content-mill agentFlow, and skillId have different roles. Use the full product name for public commands. The config field is id, not the retired flowKey.

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 config under src/programs/<name>/. Set agentFlow when its content-mill flow differs from id; setting it explicitly also documents the content dependency. Keep a run definition so the outer runner 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 in PROGRAM_REGISTRY and add its Pi/orchestrator entry to PROGRAM_BINDINGS. Existing binding checks enforce coverage; ProgramId currently widens to string.
4. For a standalone native command, create a command module with nativeCommandFactory and register it in main.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 program OAuth scopes against the tools the program needs; add scopes only when the base set is insufficient.

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 with an explicit Pi/linear binding; the factory does not select a sequence. 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.

Screens, prerequisites, and composition

Reuse AGENT_SKILL_STEPS: intro, health check, auth, run, outro, and keep-skills. Auth also applies the shared AI opt-in gate for agent programs. Override screenId, not screen, when adapting a step. New screens need an entry in ScreenId, a component, and registration in screen-registry. Follow ink-tui for rendering and store usage.

Use a headless step's onReady for session-dependent detection, then render structured frameworkContext.detectError data in the intro. onInit runs when the TUI starts rendering with its initial session; onReady runs after the real session is assigned. See store hooks and run-wizard. The noninteractive runner also walks onReady by default; set ciPreRun only when it needs a different prerequisite strategy.

requires currently records metadata; it does not execute or enforce prior programs. Compose real work through ProgramStep.run, with onRunPrep and targetDir when needed. The integration run step and self-driving demonstrate this. Composed sub-runs are structurally linear; orchestrators cannot nest. A host run step without run can also set targetDir and onRunPrep to scope the program's own agent to a picked project and keep its sequence, as error-tracking does.

Validate the affected path

Reuse the relevant registry, binding, detection, or routing checks. Add a focused behavioral test only for a meaningful gap; avoid tests that repeat configuration fields. Check that the selected CLI route resolves the intended program and that its content-mill flow is available. Use the exploration guide for a warranted end-to-end run against a disposable app. Follow wizard-development for proportionate checks; documentation-only changes need source/link verification.