mthds-edit

name	mthds-edit
description	Edit existing MTHDS bundles (.mthds files). Use when user says "change this pipe", "update the prompt", "rename this concept", "add a step", "remove this pipe", "modify the workflow", "modify the method", "refactor this pipeline", or wants any modification to an existing .mthds file. Supports automatic mode for clear changes and interactive mode for complex modifications.
min_mthds_version	0.17.0
allowed-tools	["Bash","Read","Write","Edit","Grep","Glob"]

Edit MTHDS bundles

Modify existing MTHDS method bundles.

Mode Selection

How mode is determined

1. Explicit override: If the user states a preference, always honor it:

   • Automatic signals: "just do it", "go ahead", "automatic", "quick", "don't ask"
   • Interactive signals: "walk me through", "help me", "guide me", "step by step", "let me decide"

2. Skill default: Each skill defines its own default based on the nature of the task.

3. Request analysis: If no explicit signal and no strong skill default, assess the request:

   • Detailed, specific requirements → automatic
   • Brief, ambiguous, or subjective → interactive

Mode behavior

Automatic mode:

• State assumptions briefly before proceeding
• Make reasonable decisions at each step
• Present the result when done
• Pause only if a critical ambiguity could lead to wasted work

Interactive mode:

• Ask clarifying questions at the start
• Present options at decision points
• Confirm before proceeding at checkpoints
• Allow the user to steer direction

Mode switching

• If in automatic mode and the user asks a question or gives feedback → switch to interactive for the current phase
• If in interactive mode and the user says "looks good, go ahead" or similar → switch to automatic for remaining phases

Default: Automatic for clear, specific changes. Interactive for ambiguous or multi-step modifications.

Detection heuristics:

• "Rename X to Y" → automatic
• "Update the prompt in pipe Z" with new text provided → automatic
• "Add a step to do X" (open-ended) → interactive
• "Refactor this pipeline" (subjective) → interactive
• Multiple changes requested at once → interactive (confirm the plan)

---

Process

Do not write .mthds files manually, 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.

1. Read the existing .mthds file — Understand current structure before making changes

2. Understand requested changes:

   • What pipes need to be added, removed, or modified?
   • What concepts need to change?
   • Does the method structure need refactoring?

   Interactive checkpoint: Present a summary of planned changes. Ask "Does this plan look right?" before proceeding to step 3.

   Automatic: Proceed directly to step 3. State planned changes in one line.

3. Apply changes:

   • Maintain proper pipe ordering (controllers before sub-pipes)
   • Keep TOML formatting consistent
   • Preserve cross-references between pipes
   • Keep inputs on a single line
   • Maintain POSIX standard (empty line at end, no trailing whitespace)

4. Validate after editing: If you suspect TOML syntax issues after editing, run mthds-agent plxt lint <file>.mthds for a quick check before the heavier semantic validation. Then validate:

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

   If errors, see Error Handling Reference for recovery strategies by error domain. Use /mthds-fix skill for automatic error resolution.

5. Regenerate inputs if needed:

   • If inputs changed, run mthds-agent inputs bundle <file>.mthds -L <bundle-dir>/
   • Update existing inputs.json if present

6. Present completion:

   • If inputs were regenerated (step 5 triggered), show the path to the updated file.

Common Edit Operations

• Add a pipe: Define concept if needed, add pipe in correct order
• Modify a prompt: Update prompt text, check variable references
• Change inputs/outputs: Update type, regenerate inputs
• Add batch processing: Add batch_over (plural list name or dotted path like "result.sources") and batch_as (singular item name) to step — they must be different
• Refactor to sequence: Wrap multiple pipes in PipeSequence

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 when writing or modifying .mthds TOML syntax
• Native Content Types — read when using $var.field in prompts or from in construct blocks, to know which attributes each native concept exposes
• Model References — read when setting or changing model references in a pipe. The model field is optional — omit it to use defaults

---

Method summary (on request only)

After applying an edit, do not volunteer a recap of what changed — no updated pipeline-flow diagram, no list of modified pipes, no prompt-by-prompt narration. The platform renders the method visually, so a written summary here is redundant noise.

Confirm completion in one line (e.g. "Updated <name>."). Never hide problems: still surface any validation errors, warnings, or fixes plainly.

Give the full summary (flow + what changed) only when the user explicitly asks — "explain it", "summarize", "what changed", "walk me through".