Kowalah

View saved version →

---
name: ai-estate
description: Review and maintain the organisation's AI estate — which AI tools and platforms it actually has, what people have built and switched on in them (connectors, skills, plugins, projects, agents), how each is held (licences, seats, contracts, DPAs), which are unsanctioned or risky, what renews soon, and where each is used in the business. Use for "what AI tools do we have", "what's our shadow AI", "which tools train on our data", "what renews this quarter", "is ChatGPT approved", "add Granola to the register", or any audit of AI tools and licences.
---

# AI estate

For the AI Ops lead, the core team, the CIO or whoever is accountable for which AI the
organisation uses. The first question they have to answer is **what have we actually got**,
and the second is **what should we worry about**. This skill answers both from the systems
register, and keeps the register true.

## Read the register before you ask

**`kowalah_get_systems`** returns the register: every system, whether it has AI in it,
how the organisation holds it (arrangements), how many live process steps use it, and a
`flags` block. Pass `ai_only: true` for the AI Register view. Read it first, and ask the
user only about what it doesn't hold.

A register that looks short is usually a finding in itself. If the organisation plainly
uses tools that aren't recorded (the ones you can see connected in this session are a good
first check), say so before reviewing what is there.

## Read the flags in this order

1. **`risks`**, highest severity first. `employee_contracted` is the one that matters most:
   a personal plan used for work means no DPA, no admin control and no audit trail. That is
   shadow AI, and it is the headline. `trains_on_data` without `dpa_in_place` comes next.
   `prohibited_in_use` means a tool the organisation banned is still held.
2. **`unreviewed`** — arrangements nobody has made a decision on. Unreviewed is not
   approved. Count them and say so.
3. **`ai_without_arrangement`** — AI the organisation uses with no record of how it holds
   it. Each one is a question: who pays, on what plan, under what terms?
4. **`not_in_model`** — systems in the register that no process step runs on. Either the
   work that uses them hasn't been mapped, or it's shelfware. Both are worth saying.
5. **`renewals_due`** (admins and core team only) — renewals in the next 90 days. Pair each
   with its risks and its usage: a renewal is the moment to fix an arrangement, and a tool
   used in no step is a candidate not to renew.

**A null is "not assessed", never "no".** `dpa_in_place: null` means nobody has checked,
which is different from `false`. Report unassessed fields as gaps to fill, not as passes.

## What's been built and switched on

The systems register says which products the organisation holds. **`kowalah_get_ai_estate`**
says what's deployed inside them: connectors, skills, plugins, projects, agents, automations
and apps, who uses each, and the process steps they run. Read its `gaps` first:

- **`unsanctioned`** — assets on a platform the organisation hasn't approved or has
  prohibited, personal ones first. This is the shadow-AI list, and it joins the two
  registers: a personal Gmail connector on an unreviewed Claude plan is one line here.
- **`personal`** — one person's own tools used for work, with their platform's standing.
- **`undecided`**, **`no_owner`**, **`scope_unknown`** — what nobody has decided. Admins and
  core team settle these with `kowalah_record_ai_assets` (by `id`: owner, status, scope).
- **`not_in_model`** — agents, skills, automations and apps that run no process step. Either
  the step hasn't been mapped or the tool isn't earning its keep.
- **`needs_auth`** — connectors installed but never connected, or disconnected.
- **`stale`** — nobody has shared it from their session for 90 days: likely retired.
- **`suggested_step_links`** — steps whose text names an agent, skill, automation or app
  that isn't linked

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: kowalah-setup
description: Connect the Kowalah MCP server and work out what the signed-in account can see. Use when the Kowalah plugin has just been installed, when Kowalah tools return nothing or error, when the user asks how to connect Kowalah, or when someone wants to start mapping an AI operating model from scratch.
---

# Setting up the Kowalah connection

The Kowalah plugin talks to `https://mcp.kowalah.com/api/mcp` over authenticated HTTP.
Every tool is scoped to the organisations the signed-in user belongs to — there is no
anonymous or read-only mode.

You do not need an existing Kowalah engagement. Signing in creates an account, and if
nobody from the user's company is here yet it creates an organisation for them too, with
them as its admin and an empty operating model to fill.

## Connecting

1. **Installing the plugin doesn't connect it.** The plugin bundles the `kowalah` MCP
   server, but the user still has to connect it. In Claude: open the plugin from
   **Customize → Plugins** and go to its **Connectors** tab.
   - **Not connected** — connect it there.
   - **Not added** — add it there, then connect. On a Claude Team or Enterprise plan a
     workspace owner usually has to add it for the organisation first, under
     **Organization settings → Connectors** with the URL `https://mcp.kowalah.com/api/mcp`.
     If the user can't add it, that's who to ask.

   In Microsoft 365 Copilot: in Cowork, turn the Kowalah plugin on under
   **Customize → Plugins**, then sign in when the Kowalah connector asks. In Copilot Chat,
   add the Kowalah agent, and it asks you to sign in the first time it uses Kowalah. If
   Kowalah isn't listed in either, the organisation's Microsoft 365 admin has to make it
   available first.

   In another assistant, connect the Kowalah app or connector the way that assistant asks.
2. **Sign in, or sign up — with a work email address.** An email Kowalah doesn't already
   know is fine; an account is created automatically and you do not need to be invited
   first. The email domain decides where you land, so a personal address (gmail, outlook)
   will not reach a company's organisation even if one exists.
3. Approve the connection.

## Then work out which organisation they landed in

Every Kowalah account belongs to an organisation — there are no personal accounts. On
sign-up the user is placed in one of two, and the difference changes what you should do
next:

- **Their company's organisation**, if its email domain is already registered with
  Kowalah. They join it, usually as a `member`.
- **A new organisation created for them**, if it isn't. They are its sole admin, and it
  contains nothing but an automatically-created root unit.

Both authenticate identically and both are legitimate. Establish which one before doing
anything else, because the same empty result means opposite things in each.

Run **`kowalah_get_update`** with no query. A working connection returns `kind: "home"`
with the user's identity, their `organizations` (each with `id`, `name` and `role`), and a
role-appropriate rollup.

### Read three things off it

**Which organisations they belong to.** If more than one, several tools need an explicit
`organization_id` — ask which one each time rather than guessing.

**Their role.** This gates `kowalah_get_update` only: `admin` and `core_team` see
everything in the organisation, `member` sees their own opportunities plus items they are a
stakeholder on. It does **not** gate the operating model, vision map, accelerator library
or process detail — anyone in the organisation can read all of those. Writes are
permission-checked separately, and where a user cannot edit something the tools route them
to a proposal rather than refusing. An admin is a cross-cutting editor in their own
organisation, so a sole admin in a new organisation can author the whole model.

**Which of the two organisations they landed in.** Check this by *shape*, never by name.

**The organisation's name pro

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: my-ai-tools
description: See which AI tools you use in your assistant (Claude, ChatGPT, Codex and others) — connectors, apps, skills, plugins, projects — check they're set up properly, and share them with your organisation's AI register. Use for "what AI tools do I have", "what's connected", "is my setup right", "add my tools to the register", "my AI lead asked everyone to share their tools", or when someone has been asked to take part in an AI tools review.
---

# My AI tools

For anyone in the organisation. Most people's AI setup has grown one connector and one skill
at a time, and nobody, including them, has the full picture. This skill shows them theirs,
fixes what's half set up, and, with their say-so, adds it to the organisation's AI register
so the AI lead can see what's actually in use.

**What this skill sends, and when.** Only what the user approves leaves the conversation,
and only to their own organisation's AI register in Kowalah, with the
`kowalah_record_ai_assets` tool: first a list of tool names, kinds and ids, and then, if they
choose to do part two, their own answers about each tool. Nothing is sent before the user
has seen exactly what will be saved and said yes. If they say no, or say nothing, nothing is
sent.

## 1. Say what you'll do, and what you won't

Before looking at anything, tell them in two or three sentences:

- You'll list the connectors, skills, plugins and projects **this session** can see, in
  whichever assistant they're using.
- Only **names and ids** get recorded. You won't read or record what's inside a skill, a
  project or a conversation.
- They'll see the list first and choose what to share. Anything personal stays out unless
  they say otherwise.

Then ask whether to go ahead. If they'd rather just see their setup without sharing
anything, do step 2 and step 6 and send nothing.

## 2. List what this session uses

Work from what you can actually see in this session, not from memory or guesses. Each
assistant shows different things; list what yours shows and nothing it doesn't:

- **Connectors** (called apps in some assistants) — each one's name, and its id when the
  assistant shows one. Note its state: connected, needs authorising, disconnected, setup
  not finished.
- **Plugins** — name and id as the assistant shows it (in Claude, `plugin_…`), and the
  skills inside each.
- **Skills** — name, and id where there is one (in Claude, `skill_…`). Skills built into
  the assistant by its maker are recorded by name.
- **Projects** — you will usually see an id but not a name.
- **Custom GPTs aren't recorded.** They are being retired; if the work matters, record what
  replaces it.

If you can't tell what something is, or the assistant shows you very little of its own
setup, say so plainly and record only what you're sure of. A short honest list beats a
long guessed one.

**Leave out** built-in and local tools: memory, the file system, the browser, widgets,
anything running on their own computer. They aren't the organisation's AI estate.

**Never describe or send what's in a project, a skill or a chat.** For a project, record its
id and ask the user what it's called. If you can tell a project is personal, don't list it
for sharing at all.

Show the list grouped by kind, with anything that needs attention marked. Keep it scannable:
a table per kind, or a short list, not a paragraph per item.

## 3. Let them choose

Ask which to share. Make it easy: "all of these, except …" is the usual answer.

- **Personal things are out by default.** A connector to their own Gmail, a personal
  project, a skill they wrote for home. Offer once, plainly: sharing a personal tool as
  *personal* helps the AI lead see where people are using their own accounts for work, but
  it is their call.
- **Anything they haven't seen, you don't send.**
- **Confirm the final list.** Show exactly what will be sent (each item's name, kind and id)
  and ask "Send these to your organisation's AI register?" Only a clea

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: outcomes
description: Record and report the value AI has actually delivered — time saved, cost reduced, revenue won, adoption milestones — on any work (a process step, a process, a unit, an opportunity, the whole organisation, a Kowalah deliverable), with what produced it and which vision measure it counts towards. Use for "we're saving 5 hours a week on this", "log that win", "what value have we got from AI", "what has this agent delivered", "how are we tracking against our success measures", or verifying a claimed outcome.
---

# Outcomes

An outcome is value that has actually happened, not value a use case is expected to
deliver. Expected value belongs on the opportunity's ICE score. This skill records the real
thing when someone reports it, and reports what's been realised when someone asks.

The reader who matters is whoever has to stand behind the number: the AI lead reporting to
the board, or the sponsor deciding whether to fund the next phase. So record in a way that
survives their questions.

## Recording one

**`kowalah_save_outcome`** records an outcome. Anyone in the organisation can record one.

**Put it on the work it happened in.** `on` is what the value is on:
- `process_step`: "Koko's triage saves two hours a month" is on the triage step. This is the
  most useful place, because the process then shows what it has delivered.
- `process`, `org_unit` or `opportunity` when the value is wider than one step.
- `organization` only for organisation-wide milestones ("80% of staff active weekly").
- `deliverable` or `expert_request` for value from a piece of Kowalah's work.

Find the id first: `kowalah_get_process` for steps, `kowalah_get_operating_model` for
units. Members can only record on a deliverable or expert request they're a stakeholder on.

**Link what produced it and what it counts towards.** If an agent, skill or automation
delivered the value, set `ai_asset_id` (from `kowalah_get_ai_estate`). That's how the estate
can say which tools are earning their keep. If it moves one of the vision's success
measures, set `vision_measure_id` (from `kowalah_get_vision`).

**Ask for a figure, and make it comparable.** With a number, always set:
- `value_unit`: hours, count, percent or currency
- `currency` for money, in any ISO currency: record euros as EUR, not converted
- `period`: `one_off`, or how often it recurs

Without these, the outcome is counted but can't be added up. "Saves two hours a month" is
`value: 2, value_unit: hours, period: monthly`. With no figure at all, still record it: a
milestone with a good narrative is an outcome.

**Ask how they know, and record the answer as `basis`.**
- `estimated`: a judgement
- `sampled`: timed on a few cases
- `measured`: from a system

Don't upgrade a guess. "About five hours, I reckon" is `estimated`, however confident the
user sounds. An honest estimate is worth more than a measurement nobody can reproduce. Put
the evidence in `evidence_url` if there is some.

**Write the narrative in their words:** what changed, for whom, and how they know. One
paragraph is plenty. `source` is `client` for the organisation's own work (the default),
`kowalah` for Kowalah's, and `joint` for both.

## Claimed and verified

Every outcome starts as a **claim**. Admins and core team can **verify** one (`verify:
true`), and it's recorded in their name. That's the organisation standing behind the
number. Anyone else who wants a claim verified should ask an admin or core team member.

- Changing a verified figure (value, unit, period, basis, or what it's on) makes it a claim
  again, and the tool says so. Tell the user it needs verifying again.
- Only the person who recorded an outcome, or an admin or core team member, can edit or
  remove it. Removing keeps it in history. Give a `reason`.
- Never verify on someone's behalf, and never describe a claim as verified.

## Reporting what's been realised

- **One process:** `kowalah_get_process` returns `outcomes` for the process and its s

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: process-diagnostic
description: Read one business process honestly — where its cycle time actually goes, how many handoffs it has, and what has never been measured. Use for "walk me through this process", "why does this take so long", "where are the bottlenecks in X", or before proposing any change to a process.
---

# Process diagnostic

For the person who owns a process and has to decide what to do about it. This is the read
that comes before any redesign. Run it first — `process-redesign` assumes it.

## Read the model before you ask

The operating model already holds the owners, the steps, the timings, the constraints, the
quality bars and the work in flight. **Ask the user only for what it doesn't have.**
Questioning someone about a process the model already describes wastes their time and
tells them you didn't look.

Where the model is missing something, that absence is usually the finding — say what isn't
recorded rather than quietly filling the gap from conversation.

## Sequence

1. **`kowalah_get_process`** with the process UUID. If you do not have the UUID, get it
   from `kowalah_get_operating_model_unit` (the unit's process list) or
   `kowalah_get_update`.
2. **Read the `diagnosis` block first** — before the steps, before the roll-up. It is the
   derived read of how well the process is actually captured, and it decides whether the
   rest of the data can be trusted.
3. **Check `access`** before offering to change anything.
4. Narrate the chain: steps in order, current→target dispositions, gap and constraint
   markers, the DEFINE contract on each step, and the ranked `backlog`.

## The counting rule that governs everything

**A null is "can't say". It is never "none".**

This is the single most important thing to get right, and the easiest to get wrong, because
a null renders as an absence and an absence reads as a clean bill of health.

- `handoff_count` is null whenever *any* step lacks an owner. A partial count would
  understate the handoffs — and the handoffs are where the waiting is. When it is null,
  say so and ask for the missing owners. Do not describe the process as though it flowed
  straight through.
- `cycle.ratio` is null unless *every* step is both timed and costed. A ratio built from
  three of twelve steps makes a process look tighter than it is.
- `touch_minutes_total` is a **floor**, not a total. Read it alongside
  `steps_missing_touch`. "At least 40 minutes, across the eight steps anyone has timed" is
  honest; "40 minutes" is not.

## Work is measured in minutes. Processes are measured in days.

`cycle.ratio` is touch time over elapsed time across the whole chain. **When it is there,
lead with it.**

A process that is 0.4% work and 99.6% waiting cannot be fixed by making the work faster.
That is usually the entire finding, and it reframes the conversation from "can AI do this
step quicker" to "why does this sit for six days between steps". Automating a step inside a
process that is 99% waiting moves nothing.

**When `cycle.ratio` is null, the missing timings are the finding.** Do not skip past it to
the parts you can measure. `cycle.steps_untimed` gives you the sentence: *"nine of twelve
steps have never been timed end to end — we cannot say where this process spends its
time, and that is the first thing to fix."* That is a more useful output than a confident
read of the three steps that happen to have data.

## The rest of the diagnosis block

- `constraint_steps` — steps marked as constraining the whole chain. These rank highest in
  the redesign backlog and are where effort actually pays.
- `steps_missing_output` and `steps_missing_acceptance_criteria` — the DEFINE contract
  gaps. A step with no defined output artifact or no acceptance criteria cannot be handed
  to AI, because there is no bar to hold it to. Route these to `quality-bar`.
- `steps_with_exception_notes` — where the documented process and the real one diverge.
  Worth reading aloud; exception notes are usually w

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: process-redesign
description: Take a process from as-is to a proposed to-be — mark up what gets eliminated, merged or kept, then generate the redesign beside the original so the two can be compared. Use for "redesign this process", "how would we do this with AI", "these ten steps should be three", or when a diagnostic shows the process needs restructuring rather than automating.
---

# Process redesign

For a process owner who has diagnosed a process and concluded it needs restructuring. Run
`process-diagnostic` first — this skill assumes you have the diagnosis and have checked
`access`.

## Read the model before you ask

The operating model already holds the owners, the steps, the timings, the constraints, the
quality bars and the work in flight. **Ask the user only for what it doesn't have.**
Questioning someone about a process the model already describes wastes their time and
tells them you didn't look.

Where the model is missing something, that absence is usually the finding — say what isn't
recorded rather than quietly filling the gap from conversation.

## Why this is not a disposition change

A step's disposition — `human`, `ai_assisted`, `automated`, `ai_autonomous` — says **who
runs the step**. Every one of those values *keeps the step*.

Editing dispositions can only ever produce the same process with better paint. If the
answer is "these ten steps become three", no amount of disposition editing gets you there.
`kowalah_propose_redesign` is the tool that can.

So the first question is always: **is this a redesign, or is this automation?** If the
shape of the chain is right and individual steps should be run differently, use
`kowalah_save_process_step` to set target dispositions and stop. If the chain itself is
wrong, continue here.

## The order matters

**Mark up the real process first. Generate the redesign second.**

`kowalah_propose_redesign` *seeds* the to-be from the as-is and from the redesign decisions
already recorded on the steps. Call it before doing the thinking and you get a copy you
then have to prune by hand. Do the thinking first and you get a redesign that already
reflects it.

### 1. Mark each step

`kowalah_save_process_step` with the step `id`, setting `redesign_decision` and
`redesign_rationale`.

- Steps marked **`eliminate`** or **`merge`** do not carry across.
- Everything else carries.
- **A step with no decision is CARRIED, and reported back in `undecided_count`.** Silently
  dropping work nobody decided to drop would be the worst possible default — so an
  unmarked step survives. The count is your check that you covered the chain.

Always write `redesign_rationale`. The decision is what happens; the rationale is what
someone six weeks from now needs in order to argue with it. "Eliminate — this approval only
existed because the previous system couldn't enforce the limit" is defensible. "Eliminate"
alone is not.

Work through the chain in order and put a decision on every step, including the ones you
are keeping. An explicit "keep" and an unmarked step produce the same to-be but a very
different review.

### 2. Generate the to-be

`kowalah_propose_redesign` with the as-is `process_id`.

You get back a real process — status `draft`, `redesign_status` `proposed`, its own process
number — with `step_count`, `carried_count`, `dropped_count` and `undecided_count`.
**Nothing about the as-is changes.**

Check `undecided_count` immediately. If it is not zero, name the steps that carried without
a decision and ask whether that was intended.

## Two things are deliberately cleared on the to-be

Both are easy to read as bugs. Neither is.

**Target disposition is cleared.** The redesign is a new design question. Inheriting the
old target would pre-answer it — you would be deciding how to run step 4 of the new process
based on a judgement made about step 4 of a process that no longer exists.

**Elapsed time is cleared.** It is the number the redesign exists to *move*. Carrying it
over would mak

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: programme-review
description: Review the state of an AI operating model programme — coverage, where constraints concentrate, and whether the work in flight is aimed at the actual gaps. Use for "how is our AI programme going", "where are we with AI", "what should we do next", "prep me for the steering group", or any org-wide or divisional read of AI progress.
---

# Programme review

For the person accountable for AI across an organisation or a division: the AI programme
lead, the core team, the exec sponsor. The job is to say where the programme actually is
and what should happen next — not to recite a dashboard.

## Read the model before you ask

The operating model already holds the owners, the steps, the timings, the constraints, the
quality bars and the work in flight. **Ask the user only for what it doesn't have.**
Questioning someone about a process the model already describes wastes their time and
tells them you didn't look.

Where the model is missing something, that absence is usually the finding — say what isn't
recorded rather than quietly filling the gap from conversation.

## The one failure mode this skill exists to prevent

**A portfolio of initiatives aimed at places that had no gap.** It is the most common
finding and the least comfortable one. Coverage climbs, everyone reports green, and none
of the work is pointed at where the business is actually constrained. Every review must
end by testing the in-flight work against the gaps — not by reporting them on separate
slides.

## Sequence

1. **`kowalah_get_operating_model`** — the world view. Returns the unit tree with coverage
   roll-ups on every node, org-wide totals, and a `vision` block if one has been authored.
2. **Read the totals properly** (see below). Pick the two or three units where the
   constraints and redesign gaps actually concentrate.
3. **`kowalah_get_operating_model`** with `view: "rows"` — the whole model in one call:
   every unit with its subtree roll-up, every process with its `readiness`, the
   organisation's ranked redesign backlog (each item naming its process and unit) and the
   open questions. Read the units you picked from it, rather than opening them one at a
   time. If the connector doesn't accept `view: "rows"`, it's an older version: call
   `kowalah_get_operating_model_unit` on each of those units instead.
4. **`kowalah_get_update`** with no query — the portfolio of what is actually in flight:
   projects, deliverables, expert requests, opportunities, client-visible risks.
5. **Cross-reference.** For each significant in-flight item, name the unit and process it
   is aimed at. Then name the top-backlog items with nothing pointed at them.

Steps 4 and 5 are not optional. A review that stops at step 3 is a coverage report.

## Reading coverage honestly

**Coverage % is the vanity metric.** It says how much of the mapped business has processes
recorded against it. It says nothing about whether those processes are any good, whether
anyone is working on them, or whether the ones that matter are covered. Never lead with it.

**Lead with where constraints concentrate.** The roll-ups carry `constraint count` and
`redesign-gap count` across each unit's whole subtree. A unit at 80% coverage with fifteen
constraints is in worse shape than one at 40% with two. Say that plainly.

**Mind the denominator.** Roll-ups cover what has been *mapped*. A division with no
processes recorded shows no constraints — not because it has none, but because nobody has
looked. If a unit's process count is zero or near it, that absence is the finding. Do not
let an unmapped unit read as a healthy one.

**Coverage moving is not progress.** Mapping more processes raises coverage without
changing anything about how the business runs. Progress is constraints closing and
redesigns landing. If coverage rose and the constraint count did not fall, say so.

## Using the vision map

When a `vision` block comes back, it carries the vision statement, the guid

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: programme-views
description: Design and build something the person can share about their AI programme — a dashboard, a slide deck, a document, a one-page visual or a short animated walkthrough — from their Kowalah operating model plus any other sources they choose. Works out who they are and who it's for, then designs it with them rather than filling a template. Use for "build our AI programme dashboard", "make me a board deck on our AI progress", "write up the steering group update", "I need something to show my team", "turn this review into slides", or any request to present the operating model to someone else.
---

# Programme views

Someone needs to show the AI programme to someone else: a steering group, a board, their
own team, a new joiner. This skill helps their AI assistant design and build that with them. It
is a design partner, not a template. The operating model is the backbone, and the person
decides what else goes in.

Three steps, in order. Don't start building until step 3 has an agreed outline.

## 1. Who they are, and who it's for

**Read before you ask.** Call `kowalah_get_update` with no query. It says who the person is,
their role in the organisation (admin, core team or member) and, where set, their home
unit. If they belong to more than one organisation, ask which one this is for.

Then ask the two questions the model can't answer:

- **Who is it for?** The reader matters more than the author. A board reads differently
  from a steering group, and a team reads differently from both.
- **What should the reader do or decide after seeing it?** A view with no decision behind
  it turns into a status report nobody acts on.

Their role suggests what they probably need. Use it as a first guess to check, never as a
box to put them in. An admin might run the programme or sponsor it, so ask which. Read the
matching guide in `references/roles/`:

| Usually | Guide |
|---|---|
| Runs the AI programme day to day | `references/roles/ai-programme-lead.md` |
| Sponsors it: accountable to the board or leadership team | `references/roles/executive-sponsor.md` |
| Owns a business process or function | `references/roles/process-owner.md` |
| Does the work in a process | `references/roles/team-member.md` |

## 2. What else they've got

The operating model holds processes, steps, coverage, the redesign backlog, open questions
and the vision. It doesn't hold everything a good view might need.

- **Look at what's connected.** Check which other tools are available in this conversation:
  a CRM, a data warehouse, a finance system, a document store. Suggest the ones that would
  add something real, such as pipeline value beside the sales processes or actual close
  dates beside the finance close. Say why each would help.
- **Use what's already known.** If memories or project files describe their priorities,
  their board's questions or a previous update, use them, and say that you did.
- **The person chooses.** Suggest, never pull in a source unasked. Some data shouldn't go
  in front of every reader, and they know which.

Keep a note of where each figure will come from. Every number in the finished piece has to
show its source.

## 3. Design it together, then build

**Agree the format.** Read the guide for the one that fits:

| Format | Good for | Guide |
|---|---|---|
| Dashboard | A view people come back to, with live figures | `references/formats/dashboard.md` |
| Slides | A meeting or a board pack; travels as a file | `references/formats/slides.md` |
| Doc | A written update people read, comment on and edit | `references/formats/doc.md` |
| Design | A one-page visual: a summary, a poster, a process on a page | `references/formats/design.md` |
| Motion | A short animated walkthrough of a process or a change | `references/formats/motion.md` |

Not every format is available everywhere. What you can make depends on the assistant
you're running in, the person's plan and what their administrator has switched on. In
Claude

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 10 — file references are metadata, not package contents.

View saved version →

---
name: quality-bar
description: Define what "good" means for a process step and set the checks that hold it there — acceptance criteria, gates and monitors, target scores. Use for "how do we know the AI is doing this right", "set up evals for this step", "what counts as a good output here", or before handing any step to AI.
---

# Quality bar

For a process owner who is about to let AI run part of a process, or who already has and
cannot say whether it is working. This is where a business owner sets the bar in their own
terms — *"what counts as a good forecast category call"*, *"what a compliant response looks
like"* — rather than delegating it to whoever builds the thing.

## Read the model before you ask

The operating model already holds the owners, the steps, the timings, the constraints, the
quality bars and the work in flight. **Ask the user only for what it doesn't have.**
Questioning someone about a process the model already describes wastes their time and
tells them you didn't look.

Where the model is missing something, that absence is usually the finding — say what isn't
recorded rather than quietly filling the gap from conversation.

## The rule this enforces

**A step with no acceptance criteria cannot be handed to AI, because there is no bar to
hold it to.** Not "should not" — cannot, meaningfully. You can wire it up, but you will
have no way to say whether it works, and no way to notice when it stops.

`kowalah_get_process` reports `steps_missing_acceptance_criteria` and
`steps_missing_output` in its `diagnosis` block. Those two counts are the backlog this
skill works through.

## Sequence

1. **`kowalah_get_process`** — read the steps, their DEFINE contract
   (`acceptance_criteria`, `input_artifact`, `output_artifact`), and any evals already
   attached. Check `access`.
2. **Fix the contract first** with `kowalah_save_process_step`. A step needs a defined
   `output_artifact` before an acceptance criterion means anything — you cannot say what
   good looks like until you have said what the thing *is*.
3. **Then attach evals** with `kowalah_save_process_step_eval`.

Doing 3 before 2 produces evals that check something nobody has defined.

## Writing acceptance criteria that work

The test of a criterion: **could two people independently apply it and agree?**

- *"The response is accurate and helpful"* — fails. Nothing to disagree with, nothing to
  check.
- *"Every figure quoted traces to a row in the source ledger, and no figure appears that
  isn't in it"* — passes. Checkable by anyone, and it names the failure mode that actually
  happens.

Write criteria against the **failure you are afraid of**, not the success you are hoping
for. Ask the owner: what would a bad output look like, and who would be harmed by it? That
question produces better criteria than "what does good look like" in about nine cases out
of ten.

## Gate or monitor

`mode` is the decision that matters most, and it is a business decision, not a technical
one.

- **`gate`** — blocks the step until it passes. All-or-nothing. It **must not** carry a
  `sampling_pct`; setting one is rejected, because a gate that only checks 20% of cases is
  not a gate.
- **`monitor`** — observes a sample and reports. May set `sampling_pct` (0–100).

Choose a gate when a single bad output is unacceptable — a payment released, a regulated
communication sent, a customer commitment made. Choose a monitor when you need to know the
error rate but individual errors are recoverable.

Most steps want both: a narrow gate on the thing that must never go wrong, plus a monitor
on overall quality. They are separate eval rows on the same step.

## The other eval fields

- **`method`** — `human_review` (default) | `llm_judge` | `programmatic` | `golden_set`.
  Start at `human_review` unless there is a reason not to; a human-reviewed eval that
  actually runs beats an automated one nobody built. `golden_set` is the strongest option
  where you have a set of known-correct cas

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: raise-opportunity
description: Take an idea or an ask to the Kowalah team properly — check what already exists, test it against the AI vision, score it, and submit it. Use for "I need help with", "raise this with Kowalah", "we should look into", "I've got an idea about", or when a review turns up a gap somebody wants to act on.
---

# Raise an opportunity

`kowalah_create_opportunity` is the single entry point for everything a client might want
help with — a quick question, a piece of work for the Kowalah team, a new initiative, a
project to scope. **The user does not need to decide in advance which it is.** They
describe what they are trying to do; Kowalah triages from there. Anyone in the organisation
can raise one, at any role.

This skill is the four things to do before submitting. Skipping them is how thin,
unscoreable opportunities end up in the queue.

## Read the model before you ask

The operating model already holds the owners, the steps, the timings, the constraints, the
quality bars and the work in flight. **Ask the user only for what it doesn't have.**
Questioning someone about a process the model already describes wastes their time and
tells them you didn't look.

Where the model is missing something, that absence is usually the finding — say what isn't
recorded rather than quietly filling the gap from conversation.

## 1. Check the library first

**`kowalah_find_accelerator`** before anything else. The library holds proven skills,
plugins, prompts, guides and templates: the organisation's own accelerators plus Kowalah's
library, each result tagged with a `scope` of `organization` or `kowalah`.

Each result lists an edition per AI platform, with how to get it (download, read or
watch, open a link, copy a prompt), how to use it, and a `url` to its page in the Kowalah
app, where files are downloaded. If the ask is about a step in their operating model, pass
its `process_step_id` to find what fits that step. A result with `access: "preview"` is
one their plan shows only in outline: say what it does and pass on the note about the
full library, rather than guessing at its contents. **If there is a
match, the right outcome is the user using it today — not an opportunity raised for
something that already exists.** Say what you found, offer it, and only continue if it
genuinely does not fit.

Search on the problem, not the solution. Someone asking for "an AI tool to summarise
supplier contracts" should be searched as "contract review" and "supplier" separately —
the useful match is rarely phrased the way the ask is.

## 2. Get the description to something real

The server enforces a minimum length, but the bar that matters is higher than the one it
checks. A one-line opportunity wastes everyone's time and is slower to triage.

If the first message is thin, ask:

- What is the goal — what changes if this works?
- What would good look like?
- What context should Kowalah know that isn't obvious? Systems, constraints, who is
  involved, what has already been tried.

Write it up as a paragraph or more. Keep the user's own words for the goal; they are
usually more precise than a tidied-up version.

## 3. Test it against the vision

If the organisation has a vision map — the `vision` block on
`kowalah_get_operating_model`, or `kowalah_get_vision` — **name in the `content` which
guiding principle this serves and which KPI it moves.**

Several clients make this their own programme success measure: *every use case names the
KPI it moves before it starts.* This tool is where that gets enforced, so do it properly.

Each principle carries its defining attributes as an assertion plus a counter-clause — *"It
moves a business KPI." / "Not a good idea in search of one."* **Apply both halves.** The
counter-clause is the useful one; it is what lets you tell the user their idea is a good
idea in search of a problem without it being your opinion.

**If it does not obviously serve any principle, say so to the user before submitting.

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: scheduled-tasks
description: Help someone set up a scheduled task in their AI assistant that brings them something useful from Kowalah on a regular basis — what's new in their accelerator library, a draft of their weekly programme update, the week in their area, progress against their vision, or ideas from their own work. Suggests ideas that fit their role, lets them choose, then writes the task. Use for "set me up a weekly update", "keep me posted on new accelerators", "can this run every Friday", "remind me each week", "automate my steering update", or "what could I schedule?".
---

# Scheduled tasks

A scheduled task is a prompt the person's assistant runs on a timetable, on its own: every
Monday morning, every Friday afternoon, the first of the month. Set up well, it brings
them something they'd otherwise have to remember to ask for. This skill suggests tasks
that fit them, lets them choose, and writes the task so it works without this
conversation.

**The person chooses and creates the task.** You suggest; they decide what runs, how
often and where the results go. Nothing is set up without their yes.

## 1. Who they are

Call `kowalah_get_update` with no query. It gives their role in the organisation (admin,
core team or member) and, where set, their home unit. If they belong to more than one
organisation, ask which one this is for.

Then ask, in one go:

- **What would they like to hear about, or stop doing by hand?** Their answer beats any
  suggestion.
- **When?** Which day and time suits them, and how often.
- **Where should the result go?** A message in their assistant is the default. If they
  have email, chat or a document store connected, they may want it there instead.

## 2. Suggest a few ideas

Read `references/ideas.md` and suggest two or three ideas that fit their role and what
they told you. Say in a sentence what each would give them, and let them pick one. One
good task they keep beats four they switch off.

Ideas fall into two kinds:

- **Ones that tell them something:** what's new in their library, the week in their area,
  progress against the vision. Read only. A good first task for anyone.
- **Ones that draft something for them:** their programme update, ideas from their own
  work. The task prepares a draft; the person reviews it and decides what happens next.

## 3. Write the task, then create it

Write the task prompt from the matching idea's template, filled in for this person. A
scheduled run starts fresh, with none of this conversation, so the prompt must stand on
its own:

- **Name the organisation and, if it applies, the unit**, by name, so the run doesn't
  have to ask.
- **Say what to call and how to read it**, including "use the date of the previous run as
  `since`; on the first run, use seven days ago".
- **Say exactly what to report and in what form,** including what to say when there's
  nothing new. A short "nothing new this week" is better than padding.
- **Include the rules below** that apply to the idea.

Show them the prompt, the timing and where the result goes. Change anything they want.
Then, once they say yes, ask the assistant to create a scheduled task with that prompt and
timing. If their assistant can't create scheduled tasks, or they'd rather do it
themselves, give them the prompt and timing to set it up in their assistant's settings.

## Rules for every scheduled task

1. **Nothing is shared or saved on its own.** A scheduled run reads and drafts. Anything
   that would be written to Kowalah (an opportunity, a process change, an outcome) is put
   to the person to approve, never submitted by the run.
2. **Report what was checked.** The "what's new" answer lists what it `covers`. Report
   those, and don't suggest anything else was looked at.
3. **Steps, not people.** When a task describes work, delays or constraints, it describes
   steps in a process, never named colleagues.
4. **Their own work stays theirs.** A task that looks at the person's own calendar or
 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: spot-opportunities
description: Talk through your own work and find where AI could actually help — grounded in your organisation's AI vision and what already exists, not generic advice. Use for "where could AI help me", "what should I be using AI for", "I'm not sure what to automate", "help me think about my job", or when someone has been told to look for AI opportunities and doesn't know where to start.
---

# Spot opportunities in your own work

For anyone in a client organisation, whatever their role. Most people who install this
plugin have no formal position in the operating model — they were told "have a look at your
work and log anything worth doing". This is that conversation.

The job is to get from *"here's what I do all day"* to either **something they can use
today** or **one well-formed opportunity**. Not a list of twelve ideas.

## Read the model before you ask

The operating model already holds the owners, the steps, the timings, the constraints, the
quality bars and the work in flight. **Ask the user only for what it doesn't have.**
Questioning someone about a process the model already describes wastes their time and
tells them you didn't look.

Where the model is missing something, that absence is usually the finding — say what isn't
recorded rather than quietly filling the gap from conversation.

## Ground it first — this is what stops it being generic AI advice

Before asking anything about their work:

1. **`kowalah_get_vision`** — the organisation's AI vision map, in its own words: the vision
   statement, the guiding principles with their defining attributes, the success measures.
2. **`kowalah_get_operating_model`** — the unit tree. You are looking for one thing: **is
   their part of the business already mapped?** If it is, their work is probably already a
   process with steps and an owner, and the conversation is different.

Anyone can read both of these regardless of role. If either returns `kind: "empty"`, carry
on without it — just don't invent a vision that hasn't been written.

If the model comes back with **one unit and no processes**, and they are the sole `admin`
of a single organisation with no vision authored, the account is in a new organisation
created at sign-up rather than their company's existing one. Say so before going further,
because it means two different things. For someone starting fresh it is the normal state:
what they log is theirs, in their own organisation, and the conversation carries on. For
someone whose company already works with Kowalah it is the wrong place, and what they log
will not reach the colleagues they expect. Ask which it is. Don't be reassured by the
organisation's name — it is derived from their email domain, so it may well be their
employer's name. See the `kowalah-setup` skill.

Having the vision in hand changes the conversation from "what could AI do" to "what would
move the things we said mattered". Use the principles' own wording when you get to the
test; do not paraphrase them into generic AI-strategy language.

## Then talk about their actual work

Not a questionnaire. Ask what they do, then follow the friction.

**Their first answer will usually be a tool** — *"we should have a chatbot for this"*,
*"could AI write our reports"*. That is a solution, not a problem, and solutions offered
first are usually the ones that don't survive scrutiny. Take it, then go underneath it:
what makes the current way painful?

Questions that actually surface things:

- **What do you wait for?** Not what takes you time — what sits there while you can't move.
  Waiting is invisible on any time sheet and it is usually most of the elapsed time.
- **What do you redo?** Rework means something upstream isn't right.
- **What do you chase?** Chasing is pure coordination cost and nobody counts it.
- **Where do you copy between systems?** Re-keying is the most common real finding and
  almost nobody volunteers it — it feels too small to mention.
- **What's the bit you dr

Preview of the first 4,000 characters. Read full instructions →