mthds-explain

name	mthds-explain
min_mthds_version	0.1.3
description	Explain and document MTHDS bundles. Use when user says "what does this pipeline do?", "explain this workflow", "explain this method", "walk me through this .mthds file", "describe the flow", "document this pipeline", "how does this work?", or wants to understand an existing MTHDS method bundle.

Explain MTHDS bundles

Analyze and explain existing MTHDS method bundles in plain language.

Process

Step 0 — CLI Check (mandatory, do this FIRST)

Run mthds-agent --version. The minimum required version is 0.1.3 (declared in this skill's front matter as min_mthds_version).

• If the command is not found: STOP. Do not proceed. Tell the user:

The mthds-agent CLI is required but not installed. Install it with:

npm install -g mthds

Then re-run this skill.

• If the version is below 0.1.3: STOP. Do not proceed. Tell the user:

This skill requires mthds-agent version 0.1.3 or higher (found X.Y.Z). Upgrade with:

npm install -g mthds@latest

Then re-run this skill.

• If the version is 0.1.3 or higher: proceed to the next step.

Do not write .mthds files manually, do not scan for existing methods, do not do any other work. The CLI is required for validation, formatting, and execution — without it the output will be broken.

No backend setup needed: This skill works without configuring inference backends or API keys. You can start building/validating methods right away. Backend configuration is only needed to run methods with live inference — use /mthds-pipelex-setup when you're ready.

Step 1: Read the .mthds File

Read the entire bundle file to understand its structure.

Step 2: Identify Components

List all components found in the bundle:

• Domain: the [domain] declaration
• Concepts: all [concept.*] blocks — note which are custom vs references to native concepts
• Pipes: all [pipe.*] blocks — identify the main pipe and sub-pipes
• Main pipe: declared in [bundle] section

Step 3: Trace Execution Flow

Starting from the main pipe, trace the execution path:

1. For PipeSequence: follow the steps array in order
2. For PipeBatch: identify batch_over and batch_as, then the inner pipe
3. For PipeParallel: list all branches
4. For PipeCondition: map condition → pipe for each branch
5. For PipeLLM / PipeExtract / PipeImgGen / PipeSearch / PipeFunc: these are leaf operations

Step 4: Present Explanation

Structure the explanation as:

1. Purpose: one-sentence summary of what the method does
2. Inputs: list each input with its concept type and expected content
3. Output: the final output concept and what it contains
4. Step-by-step flow: walk through execution in order, explaining what each pipe does
5. Key concepts: explain any custom concepts defined in the bundle

Step 5: Generate Flow Diagram

Create an ASCII diagram showing the execution flow:

[input_a, input_b]
        |
   main_sequence
   ├── step_one (PipeLLM) → intermediate_result
   └── step_two (PipeExtract) → final_output

Adapt the diagram style to the method structure (linear, branching, batched).

Step 6: Optional — Validate

If the user wants to confirm the method is valid:

mthds-agent pipelex validate bundle <file>.mthds -L <bundle-dir>/

Step 7: Optional — Visual Graph

For an interactive visual graph, suggest running the method with /mthds-run using real inputs:

mthds-agent pipelex run bundle <bundle-dir>/

This produces an interactive HTML visualization (live_run.html) next to the bundle alongside the execution results (graph is generated by default).

Reference

• Error Handling — read when CLI returns an error to determine recovery
• MTHDS Agent Guide — read for CLI command syntax or output format details
• MTHDS Language Reference — read for concept definitions and syntax
• Native Content Types — read when explaining what data flows through pipes (e.g., what attributes Page or Image content carries)