Service Design

Service Design Skill

Build visual Business Process Models from conversation. Describe your service, answer questions, and get a real diagram you can see in your browser — updated as you go.

What you get

  • A guided conversation that turns domain knowledge into process diagrams
  • Standard BPMN 2.0 files that work in any compatible tool
  • A built-in browser viewer — no extra software needed
  • Progressive refinement: start simple, add detail over time

How it works

  1. Name your service

    What does it do in one sentence? What comes in, and what goes out? After two answers, you see your first diagram.

  2. Add people and roles

    Who initiates the service? Who does the work? Who receives the output? The diagram adds swim lanes for each actor.

  3. Describe artifacts and decisions

    What documents flow through? What decisions branch the process? Data objects and gateways appear in the diagram.

  4. Walk through the sequence

    Step by step, from start to finish. Where are the handoffs? Where does work wait for approval? The full flow takes shape.

  5. Connect services together

    Map how services depend on each other. Build an organizational view that shows the whole picture.

Getting started

You need Claude Code installed (claude runs in your terminal) and a web browser. No coding experience required.

Install globally

Add the skill to your Claude Code commands directory: 

mkdir -p ~/.claude/commands

curl -o ~/.claude/commands/service-model.md \
  https://raw.githubusercontent.com/civicstudio/service-modeling-skill/main/service-model.md

Then open any project in Claude Code and run: 

/service-model

Or add per-project

Copy the file into your project's .claude/commands/ directory and commit it. Everyone on the team gets the skill. 

mkdir -p .claude/commands

curl -o .claude/commands/service-model.md \
  https://raw.githubusercontent.com/civicstudio/service-modeling-skill/main/service-model.md

git add .claude/commands/service-model.md
git commit -m "add service-model skill for Claude Code"

Start a session

Create a fresh directory and launch Claude: 

mkdir my-service-design
cd my-service-design
claude

Type /service-model and answer the questions. After two rounds, open service-model/viewer.html in your browser and load the generated .bpmn file.

Working as a team

Async contributions

Each team member runs /service-model from a shared repo on their own time. Claude sees what exists and asks questions to fill in gaps. Commit the .bpmn files and the team shares one evolving model.

Live facilitated sessions

Project the terminal and browser viewer side by side. One person drives while the team discusses. The diagram updates after each round — keeping conversation focused and producing a concrete artifact.

Who contributes what

Perspective Contribution
Frontline staff Describe what they actually do day-to-day
Managers Describe decisions, approval steps, and business rules
Leadership Describe how services connect and where friction exists

Progressive refinement

The skill builds your model in layers. You don't need to know these levels — Claude walks you through them.

Round Claude asks about Diagram shows
1 Name, inputs, outputs A single box with arrows in and out
2 People and roles Swim lanes for each person or team
3 Documents and data Document icons attached to steps
4 Decisions and rules Diamond shapes where the flow branches
5 Step-by-step walkthrough Full task sequence with handoffs
6 Other services Multi-service map showing dependencies

Open standard

The generated .bpmn files follow the BPMN 2.0 open standard. They work in any BPMN-compliant tool — not just the built-in viewer. Your process models are portable and never locked in.