wizard: Skill for Claude Code

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.