How to use the Process Mapper agent skill: map and measure a process

What the process-mapper skill makes the agent do

The skill turns a rough description of a business process into a structured analysis in five steps: capture the stages as JSON, map them into a text swim-lane diagram with lanes by owner, measure cycle time, detect bottlenecks, and recommend one fix. Each step is backed by a deterministic Python script that uses only the standard library, so the ranking and verdicts come from fixed rules rather than the model's guesses.

The skill focuses on three things: how much of total elapsed time is waiting rather than work, which stage is the constraint, and how the value-add ratio (VA%) compares with typical ranges. It is tactical process documentation for internal operations and explicitly excludes sales-pipeline and system-uptime (SLO) work.

• Produces a text swim-lane diagram and a normalized JSON artifact.
• Computes total P50 and P90 cycle time, VA%, wait %, rework % and a Little's-Law throughput estimate.
• Returns a ranked bottleneck list with severity (CRITICAL / HIGH / MEDIUM), a root-cause hypothesis and one action per finding.

Install the process-mapper skill

Download the ZIP for process-mapper from this page and unzip it. For a personal install, place the folder in ~/.claude/skills/. To scope it to one project, place it in that project's .claude/skills/ folder instead.

If you use the Claude apps rather than Claude Code, you can upload the skill under Settings → Capabilities → Skills.

• Personal install: ~/.claude/skills/process-mapper/
• Project install: .claude/skills/process-mapper/ inside your project
• Claude apps: Settings → Capabilities → Skills, then upload the skill

Check the requirements before you start

You need Python 3. The scripts use only the standard library, so there are no packages to install. The skill runs scripts, and it does not use the network.

The most important requirement is data. You must supply stage-level timing as JSON with a name, owner, type, and P50 and P90 durations for each stage. The skill's own assumptions say that if you have no timing data, you should first instrument the process, not map it.

• Python 3 (standard library only)
• Per-stage data: name, owner, type (value-add, wait or rework), duration_minutes_p50, duration_minutes_p90
• Rough estimates are acceptable, but the output is only as good as the input numbers

Trigger the skill with a natural request

You do not need special syntax. Describe a process you want documented or a slowdown you want explained, and mention the process type. The skill's description targets requests from a BizOps lead, COO or process-improvement owner about end-to-end processes such as procurement, employee onboarding, incident handoff, customer onboarding or claims adjudication.

Good requests name the process, the problem and the data you have. Before running the tools, the skill walks you through its forcing questions one at a time, such as whether your cycle times are measured or estimated, and whether you are mapping the current (as-is) process or the intended (to-be) one.

• "Map our employee onboarding process and tell me where the time goes. Here are the stage timings."
• "Our procurement intake feels slow but nobody knows which step is the bottleneck. Use process-mapper on this JSON."
• "Check whether our incident handoff is waste-heavy and recommend one fix for the constraint."

Run the tools on your process JSON

Write your stages into a JSON file. The process template in assets/process_template.md includes a JSON skeleton and a stage table to fill in first. Then run the three tools against that file. The documenter draws the diagram, the analyzer computes cycle time and the detector ranks bottlenecks. The --profile option (saas, services, manufacturing or healthcare) changes what counts as normal waiting.

To see the output format before using your own data, run the built-in example. It renders a diagram and JSON for a six-stage procurement-intake process.

• python3 scripts/process_documenter.py --input my-process.json
• python3 scripts/bottleneck_detector.py --input my-process.json --profile saas
• python3 scripts/cycle_time_analyzer.py --input my-process.json --profile saas
• python3 scripts/process_documenter.py --sample (built-in six-stage example)

Read the verdict and the bottleneck list

The analyzer labels value-add ratio as HEALTHY above 25%, TYPICAL between 10% and 25%, and WASTE-HEAVY below 10%. The source notes that most non-manufacturing processes land in the TYPICAL band. The detector applies three rules: a stage whose P50 is more than twice the mean of value-add stages, wait-state share above 40% of total cycle, and rework share above 15%.

The skill then pairs the bottleneck list with the verdict and recommends a single intervention aimed at the constraint. It deliberately does not recommend speeding up non-constraint stages, because that only builds queues in front of the constraint.

• HEALTHY: VA% above 25%
• TYPICAL: VA% from 10% to 25%
• WASTE-HEAVY: VA% below 10%
• Little's-Law throughput is estimated as WIP divided by cycle time

Safety notes: scripts and network

The skill runs bundled Python scripts, so review the scripts in the scripts/ folder before you run them on sensitive data. The skill does not use the network, according to its requirements. Process JSON files may contain internal staffing or performance information, so keep them in a location you control.

• Scripts run locally: scripts/process_documenter.py, scripts/bottleneck_detector.py, scripts/cycle_time_analyzer.py
• Network use: none listed
• Check the type labels you enter: mislabelling waiting as value-add is the most common data error