/diff-generate

name: diff-generate
description: "Package one workflow — how you use Dex for a specific job — into a shareable DexDiff methodology doc. Use when the user says 'share how I do X', 'package this workflow'. Not for packaging your *entire* system; use `diff-profile`. Not for adopting someone else's; use `diff-adopt`."

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.