Create a new skill-based program for the PostHog wizard. Use when adding a program type (like revenue analytics, audit, error tracking) that installs a context-mill skill and runs an agent against it. Covers the createSkillProgram factory for the common case, customization via ProgramRun, and advanced patterns for custom screens or detection.
Create a new skill-based program for the PostHog wizard. Use when adding a program type (like revenue analytics, audit, error tracking) that installs a context-mill skill and runs an agent against it. Covers the createSkillProgram factory for the common case, customization via ProgramRun, and advanced patterns for custom screens or detection.
compatibility
Designed for Claude Code working on the PostHog wizard codebase.
metadata
{"author":"posthog","version":"2.0"}
Adding a Skill-Based Program
A skill-based program installs a context-mill skill and runs the agent against it. Examples in the codebase: the audit program (clean factory call), the revenue-analytics program (factory + custom intro screen + detect step).
Before reading this, read wizard-development/SKILL.md for the architectural context — particularly principle 4 ("New capability is a new program, not a new branch").
Architecture
The wizard's runner pipeline is fixed. What varies between programs is a ProgramRun configuration object that controls the skill ID, prompt, success message, abort cases, and post-run hooks. A ProgramConfig ties together: the CLI command, the step list, and the ProgramRun. The program registry derives all downstream wiring — CLI subcommands, TUI programs, the router — from a single array. Adding a program is configuration, not code.
The common case:
createSkillProgram
For programs that just install a skill and let the agent run it (most programs), use the factory in agent-skill/index.ts:
// src/lib/programs/error-tracking/index.tsimport { createSkillProgram } from'../agent-skill/index.js';
exportconst errorTrackingConfig = createSkillProgram({
skillId: 'error-tracking-setup',
command: 'errors',
flowKey: 'error-tracking',
description: 'Set up PostHog error tracking',
integrationLabel: 'error-tracking',
successMessage: 'Error tracking configured!',
reportFile: 'posthog-error-tracking-report.md',
docsUrl: 'https://posthog.com/docs/error-tracking',
spinnerMessage: 'Setting up error tracking...',
estimatedDurationMinutes: 5,
requires: ['posthog-integration'], // optional: prior programs that must run first
});
Then register it in one place:
src/lib/programs/program-registry.ts — add to PROGRAM_REGISTRY array
That's the entire program. bin.ts, the store, the agent runner, the router, and the screen sequences (src/ui/tui/screen-sequences.ts) all derive their wiring from the registry automatically. Don't add a yargs command. Don't add a runner function. Don't touch bin.ts. The ProgramId union type updates itself from the registry contents.
The audit program (src/lib/programs/audit/) is the cleanest example of this pattern.
Customizing the agent run
createSkillProgram accepts these optional fields on SkillProgramOptions, all of which flow through to the ProgramRun:
Option
Purpose
customPrompt
Extra prompt instructions appended after the default project prompt
Array of { match: RegExp, message, body, docsUrl? } that match [ABORT] <reason> signals from the skill
requires
Other program flowKeys that must be satisfied first
For more complex post-agent work (env var upload, dashboard creation, anything that needs to run after the agent completes but before the outro), drop the factory and build the ProgramConfig directly so you can set ProgramRun.postRun. See posthog-integration for that pattern.
Dynamic run configuration
If your program needs to inspect the session before building the run config (read framework context, seed state on disk, set per-session prompt fragments), pass an async function as the program's run:
The audit program uses this pattern to seed a checks ledger on disk before the agent run.
Custom screens
Skill-based programs default to the generic step list in agent-skill/steps.ts (intro → auth → run → outro → keep-skills). To use program-specific screens (a custom intro that displays detection results, a custom outro with program-specific bullets), override the relevant step's screen field:
Add the screen IDs to the ScreenId enum in src/ui/tui/screen-sequences.ts
Create the React component(s) under src/ui/tui/screens/
Register them in src/ui/tui/screen-registry.tsx
The screen reads from the store (via useWizardStore), renders error states from frameworkContext.detectError if present, and calls store.completeSetup() (or equivalent) when the user advances. The router resolves the active screen from session state — see wizard-development/references/ARCHITECTURE.md for the full screen resolution flow. Never call console.error or imperatively navigate from inside the TUI.
Detection / prerequisite checking
If your program needs to verify prerequisites before showing the intro screen (e.g. PostHog must already be installed, certain SDKs must be present), add a headless detect step at the top of the program with an onReady hook:
{
id: 'detect',
label: 'Detecting prerequisites',
// No screen — this step is headlessonReady: async (ctx) => {
// ctx.session.installDir is the user's project dir// On success: ctx.setFrameworkContext('skillPath', '...')// On failure: ctx.setFrameworkContext('detectError', { kind: '...', ... })
},
},
Use onReady, not onInit — onInit fires during store construction before session is assigned, so it can't read installDir. The custom intro screen reads frameworkContext.detectError and renders an error view (with an Exit option) when present, or the welcome view otherwise.
The revenue-analytics program is the canonical example of this pattern (detect step + custom intro + abort cases).
Verification
pnpm build
pnpm test
pnpm fix
Then run end-to-end against a real test app:
pnpm try --install-dir=<path> <your-command>
Test failure cases too — missing prerequisites, bad install directories, network errors during skill download. The wizard should render structured error outros, not stack traces.
Canonical examples in the codebase
src/lib/programs/audit/ — clean createSkillProgram call with abort cases, custom screens, and a dynamic run function for per-session seeding
