workflow to skill conversion

SKILL.md

---
description: convert an ad-hoc workflow into a reusable skill via demonstration plus structured interview. when to do it, how to scope it, how to handle branches and error paths. trigger when the user notices they have done the same thing 3+ times and want to systematize it.
---

# workflow to skill conversion

the playbook for turning "i keep doing this manually" into "claude does it for me". not a recording tutorial - the skill-graph mechanics around what to record and how to scope it so the result is durable.

## intent

convert tacit workflow into a structured skill that survives editing, scales across the team, and improves with use. the conversion is about scoping and structure, not about hitting record. a badly-scoped recording produces a skill no one uses.

## inputs

- a workflow you have done by hand at least 3 times in the last 30 days
- the willingness to demo it once more, this time with intent
- 15 minutes for the demo plus interview

## procedure

### step 1, name the workflow precisely

before recording, write the workflow's name in one sentence with verb plus object plus context. examples:

  - "send weekly status email to manager every friday with this-week-shipped plus blockers"
  - "triage incoming bug report into linear with duplicate-check"
  - "research a target account before a sales call"

if you cannot name it in one sentence, you are looking at two skills, not one.

### step 2, decide skill vs orchestration

a skill is a single coherent procedure. an orchestration is a sequence of skills. signs you have an orchestration:
  - the workflow has 4+ distinct phases that could each stand alone
  - each phase produces a discrete artifact that gets passed to the next
  - you can imagine wanting to run just one phase in isolation

if it is an orchestration, split before recording. record each phase as its own skill. then compose them later via the orchestrator.

### step 3, pick the canonical happy path

most workflows have branches. for the recording, demo the most common path (the one that runs 70%+ of the time). do not try to demo every branch. capture the others as decision points in the interview.

### step 4, record with narration

start recording. as you work, narrate decisions:
  - "checking the slack channel first because the alert usually surfaces there"
  - "if the customer id is not in the alert, look it up in the crm by email"
  - "skipping the screenshot step because this customer does not have a dashboard"

the narration shows the interviewer where the implicit decisions are.

### step 5, in the interview, expose the branches

the interview agent will ask 3-8 questions. when it asks "what should happen if X", do not just give one answer. expose the branches you skipped:
  - "if the alert has a customer id, route to step 4. if not, look up by email first."
  - "if the customer is enterprise, also notify the named csm. otherwise skip."

these become decision points in the saved skill.

### step 6, finalize and tag with trigger phrases

the interview will ask what phrases should trigger the skill. give 3-7 distinct phrasings, including how real users would casually ask:
  - "send my weekly status update"
  - "weekly status email"
  - "what did i ship this week, email it to my manager"
  - "friday status"

the more phrasings (within reason), the better the recommender matches it later.

### step 7, run it once end to end

immediately invoke the new skill on a fresh instance of the workflow. catch anything the recording missed. iterate via /implexa:update-skill with a re-recording if needed.

## decision points

- **the workflow has no consistent shape between runs**: it is not a skill yet. it is judgment work. do not force it into a skill, the result will be brittle.
- **the workflow touches secrets you do not want in the skill body**: mention them in free-text addendum but do not narrate them during the demo. the scrubber will strip them but better not to capture in the first place.
- **the workflow is faster to do by hand than to record plus interview**: it is too small. skip recording until the workflow grows.
- **you want to share with another team**: record once, share via /implexa:share-this with team mode. they install one-click, no re-recording needed.

## output contract

a saved org skill with:
  - one-sentence name plus description
  - 3-7 trigger phrases
  - the recorded procedure (the happy path)
  - the decision points (the branches you exposed)
  - error handling for the common failures
  - usable by anyone in the org from the moment of save

## outcome signal

the skill runs at least once a week in the 30 days after recording, by you or someone on your team. if it does not, the trigger phrases did not match how people search, or the scope was wrong. iterate via update-skill or archive and re-record.

## notes

- recurrence is the bar, not aspiration. record what you actually do, not what you wish you did.
- one skill, one job. resist the temptation to add "and while we are at it, also do X". split into a second skill that can chain.
- the first version is never the final version. expect to update once or twice based on real usage.