From mthds
Build new AI method from scratch using the MTHDS standard (.mthds bundle files). Use when user says "create a pipeline", "build a workflow", "new .mthds file", "make a method", "design a pipe", or wants to create any new method from scratch. Guides the user through a 10-phase construction process.
How this skill is triggered — by the user, by Claude, or both
Slash command
/mthds:mthds-buildThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Create new MTHDS bundles through an adaptive, phase-based approach. This skill guides you through drafting (markdown), structuring (CLI/JSON), and assembling complete .mthds bundles.
Create new MTHDS bundles through an adaptive, phase-based approach. This skill guides you through drafting (markdown), structuring (CLI/JSON), and assembling complete .mthds bundles.
Explicit override: If the user states a preference, always honor it:
Skill default: Each skill defines its own default based on the nature of the task.
Request analysis: If no explicit signal and no strong skill default, assess the request:
Automatic mode:
Interactive mode:
Default: Automatic for simple-to-moderate methods. Interactive for complex multi-step methods or when the user's request is ambiguous.
Detection heuristics:
Run mthds-agent --version. The minimum required version is 0.1.3 (declared in this skill's front matter as min_mthds_version).
The
mthds-agentCLI is required but not installed. Install it with:npm install -g mthdsThen re-run this skill.
This skill requires
mthds-agentversion 0.1.3 or higher (found X.Y.Z). Upgrade with:npm install -g mthds@latestThen re-run this skill.
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-setupwhen you're ready.
Goal: Gather complete information before planning.
Ask the user:
Output: Requirements summary (keep in context)
Goal: Create a pseudo-code narrative of the method.
Draft a plan in markdown that describes:
Rules:
documents), singular for items (e.g., document)Show ASCII Overview — see Manual Build Phases for the diagram template.
Output: Plan draft (markdown)
Goal: Identify all data types needed in the method.
From the plan, identify input, intermediate, and output concepts.
For each concept, draft:
Invoice not Invoices)refines: NativeConcept OR structure: {...}Native concepts (built-in, do NOT redefine): Text, Html, Image, Document, Number, Page, TextAndImages, ImgGenPrompt, JSON, SearchResult, Anything, Dynamic. See MTHDS Language Reference — Native Concepts
Note:
Documentis the native concept for any document (PDF, Word, etc.).Imageis for any image format (JPEG, PNG, etc.). File formats like "PDF" or "JPEG" are not concepts.
Each native concept has accessible attributes (e.g., Image has url, public_url, filename, caption...; Document has url, public_url, filename...; Page has text_and_images and page_view). See Native Content Types for the full attribute reference — essential for $var.field prompts and construct blocks.
Concept naming rules:
Article not LongArticleArgument not CounterArgumentEmployee not EmployeesOutput: Concepts draft (markdown)
Goal: Convert concept drafts to validated TOML using the CLI.
Prepare JSON specs for all concepts, then convert them in parallel by making multiple concurrent tool calls. Each command outputs validated TOML directly — keep the output in context for assembly in Phase 8.
Example (3 concepts converted in parallel):
# Call all three in parallel (single response, multiple tool calls):
mthds-agent pipelex concept --spec '{"the_concept_code": "Invoice", "description": "A commercial invoice document", "structure": {"invoice_number": "The unique identifier", "vendor_name": {"type": "text", "description": "Vendor name", "required": true}, "total_amount": {"type": "number", "description": "Total amount", "required": true}}}'
mthds-agent pipelex concept --spec '{"the_concept_code": "LineItem", "description": "A single line item on an invoice", "structure": {"description": "Item description", "quantity": {"type": "integer", "required": true}, "unit_price": {"type": "number", "required": true}}}'
mthds-agent pipelex concept --spec '{"the_concept_code": "Summary", "description": "A text summary of content", "refines": "Text"}'
Field types: text, integer, boolean, number, date, concept, list
Choices (enum-like constrained values):
status = {choices = ["pending", "processing", "completed"], description = "Order status", required = true}
score = {type = "number", choices = ["0", "0.5", "1", "1.5", "2"], description = "Score on a half-point scale"}
When choices is present, type defaults to text if omitted. You can also pair choices with integer or number types explicitly.
Nested concept references in structures:
field = {type = "concept", concept_ref = "my_domain.OtherConcept", description = "...", required = true}
items = {type = "list", item_type = "concept", item_concept_ref = "my_domain.OtherConcept", description = "..."}
Output: Validated concept TOML (raw TOML output, held in context for Phase 8)
Partial failures: If some commands fail, fix the failing specs using the error message (
error_domain: "input"means the spec is wrong). Re-run only the failed commands.
Goal: Design the complete pipeline structure with controller selection.
| Controller | Use When | Key Pattern |
|---|---|---|
| PipeSequence | Steps must execute in order | step1 → step2 → step3 |
| PipeBatch | Same operation on each list item | map(items, transform) |
| PipeParallel | Independent operations run together | fork → join |
| PipeCondition | Route based on data values | if-then-else |
| Operator | Use When |
|---|---|
| PipeLLM | Generate text or structured objects with AI |
| PipeExtract | Extract content from PDF/Image/Web Page → Page[] |
| PipeCompose | Template text or construct objects |
| PipeImgGen | Generate images from text prompts |
| PipeSearch | Search the web for information → SearchResult |
| PipeFunc | Custom Python logic |
Critical — PipeImgGen requires a
promptfield: Thepromptfield is required for PipeImgGen. It is a template that defines the text sent to the image generation model — use$variablesyntax to insert inputs. Examples:
- Direct passthrough:
prompt = "$img_prompt"— uses the input as-is- Template with context:
prompt = "A black and white sketch of $description"— wraps the input in a richer promptEven if the input already contains the full prompt text, you must still declare the
promptfield. Without it, validation fails withmissing required fields: 'prompt'.
Note:
Page[]outputs from PipeExtract automatically convert to text when inserted into prompts using@variable.
Show detailed ASCII flow — see Manual Build Phases for all controller flow diagrams.
Output: Flow draft with pipe contracts (markdown)
Goal: Validate consistency before structuring.
Check:
input_item_name (singular) differs from input_list_name (plural) and all inputs keysbatch_as (singular) differs from batch_over (plural)batch_over supports dotted paths for nested attributes (e.g., "search_result.sources" to iterate over sources inside a SearchResult)prompt field (template that references inputs, e.g., prompt = "$description" or prompt = "A watercolor painting of $subject") — required even when the input IS the promptConfirm with user before proceeding to structuring.
Goal: Convert pipe drafts to validated TOML using the CLI.
Use talent names (left column) from Talents and Presets. Do NOT use model preset names (right column, prefixed with $ or @) — those are internal identifiers. For example, use creative-writer, not writing-creative or $writing-creative. Only look up specific model presets when the user has explicit instructions about model choice. In all cases, verify that referenced presets exist:
mthds-agent pipelex models --type llm # when structuring PipeLLM pipes
mthds-agent pipelex models --type extract # when structuring PipeExtract pipes
mthds-agent pipelex models --type img_gen # when structuring PipeImgGen pipes
mthds-agent pipelex models --type search # when structuring PipeSearch pipes
Prepare JSON specs for all pipes, then convert them in parallel by making multiple concurrent tool calls.
Exact field names for
--specJSON:type(notpipe_type),pipe_code(notthe_pipe_code), and the talent field matching the pipe type:llm_talentfor PipeLLM,extract_talentfor PipeExtract,img_gen_talentfor PipeImgGen,search_talentfor PipeSearch. Do NOT use generic names liketalent_name.
PipeImgGen
promptis required: Thepromptfield must be included in the--specJSON. It is a template — use$variableto insert inputs. Examples:"prompt": "$img_prompt"(passthrough) or"prompt": "A black and white sketch of $description"(template with context). Omittingpromptcauses a validation error.
For detailed CLI examples for each pipe type (PipeLLM, PipeSequence, PipeBatch, PipeCondition, PipeCompose, PipeParallel, PipeExtract, PipeImgGen, PipeSearch), see Manual Build Phases.
Output: Validated pipe TOML (raw TOML output, held in context for Phase 8)
Partial failures: Fix failing specs using the error message. Re-run only the failed commands.
Goal: Combine all parts into a complete .mthds file.
Save location: Always save method bundles to mthds-wip/. Do not ask the user for the save location.
Procedure:
mkdir -p mthds-wip/<bundle_dir>/.mthds file by combining the CLI-validated TOML fragments from Phases 4 and 7 (this is deterministic assembly, not manual authoring), using this structure:domain = "<domain>"
description = "<description>"
main_pipe = "<main_pipe_code>"
# Concept TOML from Phase 4
[concept.MyInput]
# ...
# Pipe TOML from Phase 7
[pipe.main_pipe_code]
# ...
mthds-wip/<bundle_dir>/bundle.mthds — this triggers the PostToolUse hook for automatic lint/format/validate.No intermediate files are needed. The concept --spec and pipe --spec commands (Phases 4 and 7) already validated each fragment — assembly is just combining them with the bundle header.
For the full .mthds file structure, see Manual Build Phases.
Goal: Ensure the bundle is valid and works correctly.
Always use -L pointing to the bundle's own directory to avoid namespace collisions with other bundles in the project.
# Validate and generate flowchart (isolated from other bundles)
mthds-agent pipelex validate bundle mthds-wip/pipeline_01/bundle.mthds -L mthds-wip/pipeline_01/ --graph
# Generate example inputs
mthds-agent pipelex inputs bundle mthds-wip/pipeline_01/bundle.mthds -L mthds-wip/pipeline_01/
On success, dry_run.html is saved next to the bundle. The JSON output includes the path in graph_files.
Fix any validation errors and re-validate. If validation fails unexpectedly or errors are unclear, re-run with --log-level debug for additional context:
mthds-agent --log-level debug pipelex validate bundle mthds-wip/pipeline_01/bundle.mthds -L mthds-wip/pipeline_01/
Goal: Generate input template after a successful build.
After validation passes (Phase 9), generate the input template:
# Input template (extracts the input schema as JSON)
mthds-agent pipelex inputs bundle <mthds_file> -L <output_dir>/
Replace <mthds_file> and <output_dir> with actual paths from the build output.
After the command succeeds:
Input template: Show the inputs JSON from the inputs command output. Save it to <output_dir>/inputs.json for the user to fill in.
Flowchart: Tell the user that an interactive flowchart (dry_run.html) was generated during validation next to the bundle.
Next steps — test with mock inference: If the method requires inputs, the saved inputs.json still contains placeholder values, so suggest a dry run to test with mock inference:
To test this method with mock inference, use /mthds-run or from the terminal:
mthds run bundle <output_dir>/ --dry-run --mock-inputs
Next steps — run with real data: Explain how to prepare real inputs, then run for real:
To run with real data, use /mthds-inputs to prepare your inputs (provide your own files, or generate synthetic test data), then:
mthds run bundle <output_dir>/
Replace <output_dir> with the actual output directory path used throughout the build.
Text - single itemText[] - variable-length listText[3] - exactly 3 items@variable - Block insertion (multi-line, with delimiters)$variable - Inline insertion (short text)@?variable - Conditional block insertion (only renders if variable is truthy)$var.field - Access nested field (dotted paths work with all three patterns){{ }} / {% %} also supportedsnake_casePascalCase, singularsnake_casesnake_case$var.field in prompts or from in construct blocks, to know which attributes each native concept exposesCreates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub mthds-ai/skills-sandbox --plugin mthds