Skill Bill

Skill Bill takes feature work from an issue and acceptance criteria through planning, implementation, simplification, review, and a PR. A local runtime saves progress between phases, so interrupted work can continue from durable state.

Use it with Claude Code, Codex, or Cursor. One listed skill, /skill-bill, runs the full feature workflow, a single phase such as review or validation, or a runtime operation. You review the resulting changes before merging. The project is pre-1.0.

Quickstart · Glossary · Workflow · Skills · Platform packs · IDE integrations · Execution matrix · Documentation

Install and authenticate your coding agent's CLI, then install Skill Bill:

curl -fsSL https://raw.githubusercontent.com/Sermilion/SkillBill/main/install.sh | bash

Choose your agents and telemetry level when prompted. The installer always installs every manifest-discovered platform pack. The installer downloads a self-contained runtime, renders /skill-bill with all packs' review specialists as its internal sidecars, links it into agent directories, and registers the MCP server. Prebuilt installs need no system JDK or Gradle. Installing over an older version removes the retired bill-* skills; see Upgrading from the bill-* skills.

Check the installation:

skill-bill version
skill-bill doctor

Open your coding agent in the target repository and start a feature:

/skill-bill APP-123 Add CSV export for the filtered orders list

New requirements without a key use the next local key by default. /skill-bill reads .feature-specs/, including ignored, untracked, completed, and archived bundles, and increments the highest issue number for the project's prefix. For example, bundles through NEWS-151 select NEWS-152. "Next available key" uses the same rule. If the local prefix is missing or ambiguous, it asks for a prefix, not a tracker connection. Supply a key yourself to override allocation. Include observable acceptance criteria, constraints, and any design reference in the requirements. A tracker reference without requirements uses the connected tracker after local existing-work checks. To resume, pass the key or path of an existing spec. The runtime prepares missing spec artifacts and resumes existing work. Direct CLI launches require the resolved key and requirements. Use /skill-bill APP-123 phase:plan to prepare a spec without starting implementation, or /skill-bill phase:review target:uncommitted to review existing changes. These examples use slash notation; use your agent's skill invocation syntax.

curl -fsSL https://raw.githubusercontent.com/Sermilion/SkillBill/main/install.sh -o install.sh
less install.sh
bash install.sh

export PATH="$HOME/.local/bin:$PATH"

git clone https://github.com/Sermilion/SkillBill.git
cd SkillBill
./install.sh --from-source

To update later:

skill-bill operation update-check
skill-bill update

• goal. A full run keyed by an issue, URL, or spec. The runtime owns preparation, planning (intake, preplan, plan), execution, and durable state. A single feature is a one-subtask goal.
• workflow. Persisted runtime state for one goal, standalone phase, or operation.
• subtask. One independently shipped unit of a decomposed goal.
• phase. A standalone-invocable skeleton id: review, validation, plan, pr, monitor. Invoked as skill-bill phase <name>. verify is not a phase.
• slot. One of the 11 PhaseSlot wire values: preplan, plan, implementation, audit, code_review, quality_gate, write_history, commit_push, pull_request, monitor, standalone_review. standalone_review is the report-only operator review slot that phase:review runs.
• step. An internal workflow step id, distinct from phases and slots.
• operation. A skill-bill operation <name> command. verify and update-check are operations.
• pack. A platform pack under platform-packs/<slug>/ that owns review routing and validation_gate.
• lane. A specialist review area routed to a pack skill.
• add-on. A pack-owned add-on under platform-packs/<slug>/addons/ or a user agent add-on under agent-addons/<slug>/, selected after dominant-stack routing.

/skill-bill <intake> launches the goal runtime. The runtime prepares a missing spec, plans the work, and runs it. If a spec or goal already exists, it resumes that instead. A small feature uses one subtask. Larger work can use dependency-ordered subtasks, each with a fresh execution context and durable handoff artifacts.

The runtime defines 11 slots. A full run uses the first ten in this order; standalone_review runs only for phase:review:

Each standalone phase runs a subset of these slots through the same run loop. For example, phase:review runs standalone_review, and phase:plan runs intake, preplan and plan. Runs differ in which slots they include and where they keep state, not in how a slot runs.

The quality phases have different purposes:

An unknown quality-gate selection value fails as a usage error.

Specs live under .feature-specs/, with a parent spec, executable subtask specs, and a decomposition manifest. Local specs are the default; optional Linear-backed preparation records issues and supports spec rehydration. The default commit model leaves one commit per completed subtask on the feature branch.

The runtime saves phase outputs and continuation state in a local database. Resuming uses those records and the current repository. Invalid contracts or ambiguous continuation records stop the run with an explicit error.

Run these from the repository that owns the goal:

To continue a paused goal from the CLI, clear its pause and launch it with an explicit agent:

skill-bill goal resume APP-123
skill-bill goal APP-123 --agent claude

Use the agent ID for your installed CLI, such as claude, codex, or cursor. /skill-bill APP-123 starts or resumes the full workflow. Recovery can use another compatible agent because workflow state belongs to Skill Bill.

Name the work you want reviewed:

/skill-bill phase:review target:pr
/skill-bill phase:review target:HEAD
/skill-bill phase:review target:uncommitted mode:inline
/skill-bill phase:review target:staged mode:delegated

Review also accepts target:unstaged or a commit sha. Without target:, it reviews uncommitted changes when the worktree is dirty and HEAD when it is clean.

Review fixes what it finds. Both modes verify their findings, fix Blocker and Major ones in the working tree, and report the rest with a verdict. A standalone review creates no commit.

inline is the default. It runs one review worker over the routed areas at reduced depth. auto also resolves to inline. delegated is the experimental full-depth mode, with separate specialist workers, and requires explicit mode:delegated on a standalone review. Feature and goal workflows accept code-review:auto|inline and use inline review. A required worker that cannot launch blocks the review rather than silently reducing its depth.

For full project validation:

/skill-bill phase:validation

The phase uses the same agent strategy as goal validate. It discovers required checks from repository instructions, build configuration, scripts, and CI, then runs those checks and repairs failures. Validation covers the full project regardless of which files changed and requires no platform pack or declared validation command. If discovery finds no applicable commands, the agent prints a warning and completes the step. Unreadable configuration or failed discovery blocks validation.

/skill-bill is the only listed skill. Phases and operations are forms of it, not separate commands. Stack-specific review skills install as its internal sidecars.

There are three kinds of form:

• The full run (/skill-bill <intake>) runs the ten feature-run slots (preplan through monitor) with durable state, so it can pause and resume.
• A phase (phase:<name>) runs a few slots in memory. It writes no workflow row, branch, or checkpoint commit, and it cannot be resumed. phase:plan is the exception: it is a durable, resumable plan workflow that stops after the spec bundle, creates no branch or commit, and is finished by skill-bill <KEY>. commit_push is not available as a standalone phase.
• An operation (operation:<name>) is a standalone job outside the feature workflow. Operations that edit files, tag a release, or push stop at awaiting_confirmation and act only after you confirm.

Boundary history and decisions are written by the goal's write_history slot. Goal status is CLI-only: run skill-bill goal status <KEY>.

/skill-bill APP-123 Add CSV export               # full workflow from intake
/skill-bill APP-123 phase:plan                   # skill-bill phase plan APP-123
/skill-bill phase:review mode:delegated target:HEAD

Standalone phases and operations are operator tools. Agents invoke them only when explicitly requested and never select them as full-run steps or recovery actions. New full-run work uses supplied requirements and defaults to the next local key from .feature-specs/ when no key is given. A tracker connection is optional. An existing spec key or path resumes that spec. skill-bill <intake> routes to the goal runtime, which prepares new work and resumes existing specs without invoking a standalone phase command.

The full run forwards code-review:inline|auto as --code-review-mode; phase:review forwards mode: and target: unchanged. Release first prints the proposed version and changelog and exits awaiting_confirmation; confirming it with confirm:<token> creates and pushes the tag. [<scope>] operation:unit-test-value-check reviews unit tests without editing. <intake> operation:feature-guard and <intake> operation:feature-guard-cleanup print a plan and exit awaiting_confirmation. They edit only on confirm:<token>. [<pr>] operation:pr-review-fix prints a per-thread matrix for the PR's unresolved review threads and exits awaiting_confirmation; the dispatcher asks which threads to fix and re-runs it with confirm:<token> and select:. It pushes only with push:on.

Earlier versions installed a separate listed skill for each job. Those skills are retired, and reinstalling removes their links and copies. Use the matching /skill-bill form instead:

Telemetry and stored workflow rows still use some retired names, such as bill-code-check as the quality-check routed_skill, so existing dashboards and in-flight workflows keep working.

Platform packs live under platform-packs/<slug>/. Their manifests declare routing signals, review areas, native workers, add-ons, and quality commands. Discovery and routing use those declarations, so teams can add or replace packs without editing a hard-coded platform list.

The ten failure-review areas are architecture, performance, platform-correctness, security, testing, api-contracts, persistence, reliability, ui, and ux-accessibility. Every shipped pack also owns a required code-quality lane; KMP's local lane takes precedence over Kotlin's baseline lane. Legacy packs can use generic code-quality as a fallback when installed. If neither owner is available, review keeps its compatibility behavior and records the omission. These specialists install as unlisted sidecars and native-agent inputs, while /skill-bill remains the only listed skill. KMP declares seven failure areas of its own and takes performance, testing, and api-contracts from Kotlin. KMP has its own quality gate with no Kotlin fallback. The other shipped packs each declare all ten failure areas.

Concrete path ownership takes precedence over the generic review fallback. Content signals break ties between equal positive path matches. The fallback owner is manifest-declared and replaceable; declaring more than one fails validation.

Pack review skills install as internal sidecars of /skill-bill. Run /skill-bill phase:review; the stack-specific skills are not separate user commands. Pack validation checks specialist substance as well as manifest shape. See the source-generation guide and review substance standard for authoring requirements.

The installer supports Claude Code, Codex, Cursor, and JetBrains Junie. It generates each provider's skill and native-agent files from shared sources and registers the local MCP server. Runtime review launch support depends on the provider's isolation capabilities. Claude, Codex, and Cursor have governed review launch adapters; Junie's adapter currently rejects governed review launches that require tool and MCP isolation.

Two separately packaged IDE integrations show repository work status, planning progress, the active phase, and elapsed time:

• IntelliJ plugin, distributed as a plugin ZIP under plugin-v* releases.
• VS Code extension, distributed as a VSIX under extension-v* releases.

Both offer stop and pause-after-subtask controls. Launch and resume stay in the CLI or agent session. Install the plugins from their release artifacts; they are separate from the Skill Bill runtime installer. Their READMEs include compatibility requirements and source build instructions.

Use execution_matrix to choose the model and effort for feature-task phases, including goal children. Add it to your machine-wide ~/.config/skill-bill/config.json, or the file selected by SKILL_BILL_CONFIG_PATH. Merge it into the existing JSON object so your telemetry and other settings remain intact. These preferences apply across repositories; .skill-bill/config.yaml does not own them.

The matrix selects a model for the agent already assigned to a phase. It does not switch agents. You can configure several agents in one file and keep only the entries you use.

Each example below is a complete JSON object for one agent. To configure several agents, combine their entries under the same execution_matrix.agents object. Model availability depends on your provider and account; use model IDs accepted by your installed CLI.

The claude entry accepts model aliases or full model IDs. The runtime forwards effort through Claude's --effort option.

{
  "execution_matrix": {
    "agents": {
      "claude": {
        "reasoning": { "model": "opus", "effort": "high" },
        "implementation": { "model": "sonnet", "effort": "medium" }
      }
    }
  }
}

When using a custom ANTHROPIC_BASE_URL, the adapter lets ANTHROPIC_MODEL override a Claude model name or alias when that environment variable is set.

The codex entry uses a model ID and optional reasoning effort. The runtime passes these through --model and --config model_reasoning_effort=....

{
  "execution_matrix": {
    "agents": {
      "codex": {
        "reasoning": { "model": "gpt-6-astra", "effort": "high" },
        "implementation": { "model": "gpt-5.6-sol", "effort": "medium" }
      }
    }
  }
}

The cursor entry uses model IDs from agent --list-models. This example selects a reasoning model with effort encoded in its ID and Composer for implementation.

{
  "execution_matrix": {
    "agents": {
      "cursor": {
        "reasoning": { "model": "claude-opus-5-thinking-high" },
        "implementation": { "model": "composer-2.5" }
      }
    }
  }
}

For Cursor, a separate effort field becomes a model parameter, such as model[effort=high]. If the model already contains an [effort=...] parameter, the values must agree. For parameterized models with other options, put the complete model string in model and omit effort.

Junie's runtime adapter does not support model or effort overrides. Omit junie from execution_matrix.agents. Assigning a directive to a Junie phase fails before launch.

{
  "execution_matrix": {
    "phase_tiers": {
      "preplan": "reasoning"
    },
    "agents": {
      "codex": {
        "reasoning": { "model": "gpt-6-astra", "effort": "high" },
        "implementation": { "model": "gpt-5.6-sol", "effort": "medium" },
        "review": { "model": "gpt-6-astra", "effort": "xhigh" }
      }
    }
  }
}

Put repository-wide instructions in AGENTS.md and skill-specific guidance in .agents/skill-overrides.md. The override example shows the section format. Boundary history and decisions live beside the code in area-owned agent/history.md and agent/decisions.md files.

Platform-pack add-ons supply stack-specific guidance after routing. External add-on sources let teams keep private guidance outside the shared repository.

Agent add-ons are separate, explicitly selected extensions. The shipped execution-budget add-on applies to Codex feature work and reinforces the user's stopping boundary, compact handoffs, and delegation constraints:

/skill-bill APP-123 agent-addon:execution-budget

Its source is agent-addons/<slug>/agent-addon.yaml plus content.md. See agent add-on authoring for compatibility, precedence, staging, and resume behavior.

To author skills or packs, start with skill-bill new, then use show, fill, edit, validate, and render. Authored skill content lives in content.md. The installer generates SKILL.md, support pointers, and provider-specific native-agent files into staging; those generated files do not belong in source. Re-run ./install.sh after changing skill sources, rendering, or support pointer generation.

See Contributing, source generation, and the scaffold payload contract before changing these contracts. The runtime, IntelliJ plugin, and VS Code extension have separate builds.

The default telemetry level is anonymous. The installer lets you choose anonymous, full, or off. Events go to the configured telemetry proxy, using the shipped relay by default. You can self-host the proxy.

To disable transmission:

skill-bill telemetry disable

Some diagnostic events still queue locally while telemetry is off. Telemetry Privacy documents the fields, destinations, correlation identifiers, retention, and what happens if you enable telemetry later. Workflow state remains local and supports continuation independently of telemetry transmission.

• Getting Started: installation, CLI commands, MCP tools, and recovery.
• Getting Started for Teams: rollout and project customization.
• Runtime Command Guidance: full-run, phase, and operation behavior, plus goal commit rules.
• Capability Deep-dive: workflows, packs, memory, and governance.
• Token Economy: bounded context and durable handoffs for long goals.
• Review Telemetry: review measurements, learnings, and local statistics.
• Runtime Architecture: module ownership, persistence, and contract enforcement.
• Observability Policy: required records for failures and degraded behavior.
• Teams Roadmap: proposed hosted team controls and open product questions.

Skill Bill is licensed under the MIT License. See the licensing summary for details.