---
name: davekilleen/diff-generate
source: https://app.decimal.ai/s/davekilleen-diff-generate@1/SKILL.md
source_sha256: b7d953691fd2
---

## What This Command Does

**In plain English:** You've built a workflow in Dex that works well. This command scans your vault, identifies what you've customised, and writes a methodology document describing how it works. That document can be published to heydex.ai/diff so others can adopt a similar setup using `/diff-adopt`.

**When to use it:**
- You want to share a workflow with someone else
- You want to document how a part of your system works
- You want to package your setup for your team

**How to run it:**
```
/diff-generate "my meeting prep workflow"
/diff-generate
```

---

## Arguments

`$ARGUMENTS`: Optional description of the workflow to package.

- If provided: used to identify which components belong to this workflow
- If omitted: scans everything custom and asks what to package

---

## Process

### Step 1: Discover Customisations

Scan these locations for custom components:

```
.claude/skills/          - custom or modified skills
.claude/hooks/           - custom hooks
CLAUDE.md                - custom sections
.claude/CLAUDE.md        - local extensions
```

To identify what's custom vs. baseline dex-core:
- Skills with `-custom` suffix are always custom
- Skills with `-dave` or other personal suffixes are custom
- Hooks are almost always custom
- CLAUDE.md sections that reference specific folders, people, or workflows are custom

Present findings:

```
I found these customisations in your vault:

Skills ([count] custom):
  [skill-name]  - [one-line description]
  ...

Hooks ([count]):
  [hook-name]   - [one-line description]
  ...

CLAUDE.md extensions ([count] custom sections detected)

What would you like to package?
- Describe a workflow (e.g. "my meeting prep")
- Or pick from the list above
```

### Step 2: Group into a Workflow

If the user provided a description, use it to identify related components.

**Grouping heuristic: components belong together if:**
- They serve the same job to be done (meeting prep, deal review, weekly planning)
- Skills reference the same vault paths
- A hook fires on output from a skill in the same group
- A CLAUDE.md section describes when to use skills in the group
- Skills are typically run in sequence

Present the proposed grouping and let the user adjust.

### Step 3: Write the Methodology

For the selected components, generate a methodology YAML following the v2.0 schema.

**How to write each section:**

- **`methodology.problem`**: What was life like before this workflow? Write from the user's perspective.
- **`methodology.solution`**: What does the workflow do end to end? Describe the experience, not the code.
- **`methodology.user_experience.commands`**: For each skill: name, trigger, description, realistic example input/output.
- **`methodology.vault_structure`**: For each folder the skills reference: purpose, typical path, required/optional.
- **`methodology.data_patterns`**: For each data format expected: description, realistic example (anonymised).
- **`methodology.integrations`**: For each MCP or tool: name, examples, value add, required/optional.
- **`methodology.behaviors`**: For each automatic action: what happens, when, automatic or manual.

**Anonymise real data.** Use realistic but anonymised names, companies, and dates in examples.

### Step 4: Ask for Identity Fields

```
A few details for the methodology:

  Diff ID (URL-safe, kebab-case):  [suggest]
  Display name:                     [suggest]
  Description (1-2 sentences):      [draft]
  Tags:                             [suggest]

Edit any of these, or accept the defaults.
```

### Step 5: Review and Save

Display the complete methodology YAML. Ask:

```
Methodology drafted. What would you like to do?

  [Save]        - saves to the DexDiff draft area (`DEXDIFF_DIFFS_DIR`, default `04-Projects/DexDiff/beta/diffs/[id].yaml`)
  [Edit first]  - adjust any section before saving
  [Test it]     - run /diff-adopt against this to see what it generates
```

---

## Publishing to Heydex (optional)

After the methodology YAML is saved, publishing is optional.

If the user wants to publish it, use the terminal bridge that ships with this skill:

1. Check whether `~/.dex/heydex-auth.json` exists and is less than 30 days old.
2. If it is missing or stale, tell the user to open `https://heydex.ai/connect/?cli=true`, sign in, create a sign-in code, then run:

```
python3 .claude/skills/diff-generate/scripts/publish_diff.py link --code ABC123
```

3. Once the terminal is linked, run:

```
python3 .claude/skills/diff-generate/scripts/publish_diff.py publish <path-to-yaml>
```

The script opens a browser review page. Tell the user that page is where they can edit the workflow and choose Publish. Nothing is shared without their explicit approval on that page.

---

## Important Rules

- **Anonymise real data.** Never include real customer names, deal values, or sensitive context in examples.
- **Describe, don't copy.** The methodology describes how the workflow works, it doesn't contain literal skill code.
- **Err toward inclusion.** If a component might be related, include it and let the user remove it.
- **Use the v2.0 schema.** Always set `dexdiff_schema: "2.0"`. See `04-Projects/DexDiff/design/methodology-schema.md` for the full spec.