How to use the Commercial Forecaster agent skill

What is an agent skill?

An agent skill is a folder of instructions, reference material and scripts that an AI agent can load when a task matches the skill's description. The skill tells the agent when to use it, what steps to follow and which scripts to run.

The commercial-forecaster skill is licensed under MIT. Its main instruction file is SKILL.md, and it includes an intake template, three Python scripts and reference notes.

What the skill makes the agent do

The skill is built around three questions a forecast has to answer: what the commit, best-case and pipe-only numbers are; which cohorts are leaking and whether the consolidated NRR hides that; and which funnel stages are reliable.

Instead of one number, the agent organizes pipeline into commit, best-case and pipe-only tiers. Each output names the conversion rate used, the data window and the weighting choice, so the assumptions are visible to the people reading the forecast.

• bookings_forecaster.py: a 3-tier bookings forecast (commit, best-case, pipe-only) with the conversion rate, data window and weighting disclosed. The data window blends last-4-quarter and last-12-quarter history at 70/30.
• cohort_arr_projector.py: per-cohort NRR and GRR projection over the horizon, with a callout for leaky cohorts whose NRR is declining against the trailing-cohort average.
• funnel_confidence_scorer.py: per-stage confidence bands based on coefficient of variation (HIGH below 10%, MEDIUM 10-25%, LOW 25-50%, VERY LOW above 50%), with a suggested treatment for each stage.

How to install the skill

Option 1: personal install. Download the ZIP for this skill from this page and unzip it into ~/.claude/skills/ so the skill folder sits there.

Option 2: project install. Download the same ZIP and unzip it into the .claude/skills/ folder of a specific project.

Option 3: Claude apps. Upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

What you need before you start

The skill needs Python 3. Its scripts use only the Python standard library, according to the file headers, so there are no packages to install beyond Python itself.

The scripts read a JSON intake file. Build it from assets/forecast_intake_template.md, which asks for four inputs: opportunities with stage, amount, close date, age and last activity; historical stage-to-stage conversion over the last 4 and last 12 quarters; per-cohort starting ARR with per-quarter retention and expansion; and per-stage funnel conversion across the last 12 quarters. The template takes about 20 minutes to fill in for a Head of Commercial, RevOps or VP Sales.

• The skill does not work well without historical pipeline and cohort data. Its outputs depend on that input, so forecasts built without it would be weak or misleading.
• The skill is not for backward-looking financial close or reporting, which the skill routes to finance/financial-analysis.

How to trigger the skill with natural requests

You do not need special syntax. Describe the forecasting task in plain language and mention the artifact you need. The skill's description lists the triggers it responds to: a quarterly bookings forecast, an ARR projection, a pipeline forecast, an NRR projection, or a commit, best-case or pipe-only board number.

Requests that should match the skill include asking for a three-tier commit, best-case and pipe-only forecast for the board, asking whether a recent cohort is hiding a leak behind the consolidated NRR, or asking which funnel stages are reliable enough to commit to.

Run the three steps of a forecast

The workflow in SKILL.md runs in steps. Step 2 runs the bookings forecaster, Step 3 projects cohort ARR and Step 4 scores funnel confidence. Each command reads the same intake.json file. The skill's Step 2 command shows the bookings forecaster with the saas profile and markdown output.

The intake template lists profiles for the bookings forecaster: saas, api, enterprise-software, marketplace and services. The profile shifts default stage-conversion rates by industry, but your historical data overrides those defaults.

• Step 1: fill in the intake template and save it as intake.json.
• Step 2: run the bookings forecaster to get commit, best-case and pipe-only numbers with the assumption block.
• Step 3: run the cohort projector to get the NRR and GRR trajectory, cohort heatmap and any leaky-cohort callout.
• Step 4: run the funnel confidence scorer to get per-stage bands and treatments.
• Step 5: put the number, the heatmap and the confidence bands into the board deck, with the assumption block on the same slide as the number.

Examples of what you can ask for

The skill is most useful when you ask for the whole structured answer rather than one figure. A useful request names the forecast period, the data you have and the output you need for the board.

• Build a Q3 bookings forecast from my intake.json with commit, best-case and pipe-only tiers and the conversion rates and data windows used.
• Check my cohort retention for the last four quarters and tell me whether any recent cohort is leaking revenue that the consolidated NRR hides.
• Score each funnel stage in intake.json by coefficient of variation and tell me which ones should be treated as soft floors.
• Project ARR for the next four quarters from my cohort data and show the assumptions behind it.

Safety notes: scripts and network

The skill runs scripts. The bookings forecaster, cohort projector and funnel confidence scorer are Python scripts that the agent executes against your intake file. Review the scripts in the skill folder before you run them on sensitive data.

The skill does not use the network, according to its listing. Your intake file stays with the local scripts as described in the source.

• Read the scripts in scripts/ before running them on real revenue data.
• All three scripts support --help and --sample, which you can use to check behaviour before using your own data.

Tips for better forecasts

The skill is designed so the assumptions travel with the number. Keep them there, and use the variance between commit and pipe-only as a pipeline-risk signal.

• Do not remove the assumption block. The skill is built so that a forecast without one is theatre, and the CLI is described as refusing to omit it.
• Do not report NRR without the cohort breakdown. A consolidated number can look flat while a recent cohort is leaking.
• Do not treat best-case as commit. Commit should only include commit-grade stages.
• Do not re-up stalled late-stage opportunities by hand. The bookings forecaster downweights stalled opps automatically.
• Check the coefficient of variation for each stage. The same average conversion can hide very different reliability.