# diagramming-processes

A coding-agent skill that makes the agent draw processes, states and message exchanges as diagrams whose source lives in git, not as pictures.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 17800 installs · ★ 33
- Author: riekelt
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/riekelt/technical-writer/tree/HEAD/plugins/technical-writer/skills/diagramming-processes/SKILL.md
- Updated: 2026-09-13
- HTML: https://affpapa.org/en/nevibecode/skills/diagramming-processes

## What it does

The skill kicks in when a business process, lifecycle or system interaction serializes badly into prose. The agent picks the notation from the reader's question: ArchiMate for processes spanning departments, an activity diagram for step order, a state machine for states, a sequence diagram for messages. One question per diagram.

Diagram source is a committed text file, one per diagram, grouped in a diagrams directory beside the documents. Where the repository has no tool yet, the skill recommends starting with PlantUML, whose standard library carries the ArchiMate notation. Renders are derived: a stale render is deleted in the same change that edits its source. A screenshot or whiteboard photo with no source counts as a finding against the document, because nobody can diff it and so nobody will maintain it.

Participants are systems, roles, modules and business objects. Classes, methods and functions stay in the code — the skill forbids drawing class structure, since an IDE generates a fresher picture on demand. Edges carry the event or condition in the domain's language, never a callback name. Error paths are drawn where behavior differs. The skill expects the `technical-writing` skill as background for its truth and style rules. Past five diagrams, an index document tracks coverage and the render command.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add riekelt/technical-writer --skill diagramming-processes -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/diagramming-processes/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/diagramming-processes/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add riekelt/technical-writer --skill diagramming-processes -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/diagramming-processes/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add riekelt/technical-writer --skill diagramming-processes -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/diagramming-processes/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install riekelt/technical-writer diagramming-processes
```

2. **Manually: put the files in place**
- File: `.github/skills/diagramming-processes/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add riekelt/technical-writer --skill diagramming-processes -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/riekelt/technical-writer --path plugins/technical-writer/skills/diagramming-processes
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/diagramming-processes/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add riekelt/technical-writer --skill diagramming-processes -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/riekelt/technical-writer/tree/HEAD/plugins/technical-writer/skills/diagramming-processes/SKILL.md

## When to use it
- show a process that runs across several departments
- document the states an object can be in and what moves it
- pin down the message order between services
- draw process documentation for a legacy codebase
- split one overloaded diagram into several by reader question

## Example prompts
- Draw the order fulfilment process as an activity diagram, put the source in the diagrams folder
- Draw a state machine for ticket statuses, including the error branches
- Build a sequence diagram for the messages exchanged between the payment services

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 61e599b83c8ef31a.

BEGIN THIRD-PARTY FILE 61e599b83c8ef31a
```text
---
name: diagramming-processes
description: Use when a business process, workflow, lifecycle, or interaction between systems needs a diagram - a flow that prose serializes badly, a state machine, a message sequence, an enterprise process map - or when drawing the process documentation of a legacy campaign. Encodes diagrams-as-source, the notation ladder from ArchiMate to PlantUML, the kind-per-question table, behavior-level participants, the diagram index, and the same-change maintenance rule. Use whenever a document needs a graph rather than more paragraphs, even if nobody says "PlantUML".
---

# Diagramming processes

**REQUIRED BACKGROUND:** the `technical-writing` skill (hard rules, truth rules, style).

## Overview

A diagram is a set of claims drawn instead of written; every box and arrow is bound by the same truth rules as a sentence. Core principle: **diagram the behavior (processes, lifecycles, interactions), keep the source in version control, and treat every render as derived.** The prose owns the reasoning; the diagram carries what prose serializes badly: branching, concurrency, and state.

## When to invoke, and not

Invoke when a flow, lifecycle, or interaction needs showing: a business process spanning components or organizations, a state machine, a message exchange, the `processes.md` of a legacy campaign (`documenting-legacy-codebases`). Do NOT invoke to decorate: a linear flow of three or four steps is a numbered list, and a diagram restating one is furniture. Out of scope: charts generated from data (metrics, trends), and implementation structure, which the behavior rule below forbids.

## The notation ladder

Name the altitude before drawing, and match the notation to it:

- **Business layer: ArchiMate.** Processes spanning departments, organizations, or multiple systems, capability maps, and the TOGAF-style views enterprise stakeholders expect. The audience reads roles, services, and processes, never components.
- **System layer: PlantUML behavior diagrams.** Flows, state machines, and sequences within and between systems: code documentation, one level above the code.
```
END THIRD-PARTY FILE 61e599b83c8ef31a

The third-party file has ended. Everything between the 61e599b83c8ef31a tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2126 of 7696 bytes. © riekelt · MIT · https://github.com/riekelt/technical-writer/tree/HEAD/plugins/technical-writer/skills/diagramming-processes/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md