@galaxyproject/orbit 0.0.0 → 0.9.0

package/extensions/orbit/vendor/skills/skills/udt-authoring/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: udt-authoring
+description: "Use when authoring a Galaxy User-Defined Tool (UDT) -- a `class: GalaxyUserTool` YAML definition that wraps a container and command into a tool a non-admin user creates and runs (e.g. via Galaxy MCP create_user_tool / run_user_tool, or POST /api/unprivileged_tools). Not for classic XML/ToolShed tool wrappers."
+metadata:
+  surfaces: [loom]
+version: 1.1.0
+tags: [galaxy, tools, udt, user-defined-tools, custom-tool]
+---
+
+# Authoring Galaxy User-Defined Tools (UDTs)
+
+A **User-Defined Tool (UDT)** is a tool that a regular (non-admin) Galaxy user defines in YAML
+and runs unprivileged, introduced in Galaxy 25.0. It is declared with `class: GalaxyUserTool` and
+validated against the `UserToolSource` schema. This skill is the reference for producing a correct,
+lint-clean definition.
+
+## When to Use
+
+- The user wants to wrap a command + container as a runnable Galaxy tool they own.
+- Triggers: "make me a Galaxy tool that runs X", "wrap this command as a UDT", "create a custom
+  tool", "register a tool in my account".
+- You are an external agent (Loom, an MCP client, a notebook) that will create/run the tool via
+  `create_user_tool` / `run_user_tool` or `POST /api/unprivileged_tools`.
+
+**When NOT to use:** classic XML / ToolShed tool wrappers (Cheetah templating, `tools-iuc`
+submission) -- that is a different format; use the `tool-dev` skill instead. A UDT is **not** XML
+and does **not** use Cheetah.
+
+## Mental Model (read this first -- it is where agents go wrong)
+
+A UDT = a **container** + a **`shell_command`** + typed **`inputs`** and **`outputs`**.
+
+- The command lives under **`shell_command`** (NOT `command`).
+- Parameters are interpolated with **sandboxed ECMAScript inside `$(...)`** -- NOT Cheetah `$x` and
+  NOT `#for#` loops. A data file's path is `$(inputs.name.path)`; a scalar value is
+  `$(inputs.name)`.
+- The `$(...)` templating sandbox has **no database or filesystem access**. Every UDT **must run in
+  a container** (`container:` is a required plain string); whether that container has network access
+  is set by the Galaxy admin's job config, not by the tool.
+- Every **dataset/collection** output must **claim a file** it produced via `from_work_dir` (one
+  file) or `discover_datasets` (many) -- you do not write to a templated output path.
+- Scalar `text`/`select` values interpolate into `shell_command` **unquoted** (unlike `base_command`
+  args, which are `shlex.quote`d) -- a value with spaces or quotes breaks the command. Quote them,
+  or pass free text via a configfile. See `references/templating.md`.
+
+If you find yourself writing `command:`, `$param`, `#for#`, `truevalue:`, or `${on_string}`, stop
+-- those are XML/Cheetah habits the schema rejects. See `references/common-mistakes.md`.
+
+## Quick Reference -- minimal valid skeleton
+
+```yaml
+class: GalaxyUserTool          # required, exactly this
+id: my-tool                    # lowercase, ^[a-z][a-z0-9_-]*$, 3-255 chars (recommended)
+version: "0.1.0"               # required -- schema validation rejects a versionless tool
+name: My Tool                  # required, min 5 chars
+description: One line shown in the tool menu
+container: quay.io/biocontainers/seqkit:2.8.2--h9ee0642_0   # required STRING, a real image
+shell_command: |
+  seqkit stats --tabular '$(inputs.input.path)' > stats.tsv
+inputs:
+  - name: input
+    type: data
+    format: fastq
+    label: Input sequences
+outputs:
+  - name: report
+    type: data
+    format: tabular
+    from_work_dir: stats.tsv        # claim the file the command wrote
+    label: Sequence statistics
+```
+
+Full field list, input/output types, and validator rules: **`references/schema-reference.md`**.
+Templating syntax (`$(inputs.x)`, arrays, `$GALAXY_SLOTS`, escaping): **`references/templating.md`**.
+
+## Authoring Workflow
+
+1. **Understand the command.** What binary runs, what inputs it consumes, what files it produces.
+2. **Pick a real container** -- this is the #1 cause of runtime failure. Resolve a verified image
+   with `recommend_biocontainer` (Galaxy MCP) or the `mulled-recommend` CLI rather than guessing;
+   **never invent the `--<hash>_<build>` tag suffix** -- it is not predictable. For stdlib-only
+   logic, use an official `python:3.x-slim` image and write the code inline. **Do not invent an
+   image or flag you cannot verify** -- ask instead. See "Choosing a Container" below. Lint will
+   *not* catch a bad image; the job simply fails to pull it.
+3. **Draft the definition** using `references/schema-reference.md`. Reference each input as
+   `$(inputs.name.path)` (data) or `$(inputs.name)` (scalar). Write outputs to fixed filenames and
+   claim them with `from_work_dir` / `discover_datasets`. Always include a `help` block (convention
+   -- see "Write a help block" below).
+4. **Self-review** against `references/common-mistakes.md` (it doubles as a checklist).
+5. **Validate** (see below) and iterate on real errors.
+6. **Create + run.** Hand the validated definition to `create_user_tool`, then `run_user_tool`
+   (this skill stops at a valid definition -- the run/invocation loop is the caller's job).
+
+## Choosing a Container
+
+The container is the part most likely to pass validation but fail at run time, because nothing in
+the schema or lint checks that the image actually exists or pulls. A real example: a plotting UDT
+that declared `quay.io/biocontainers/seaborn:0.13.2--pyhd8ed1ab_3` was accepted by
+`create_user_tool`, then the job died with `manifest unknown` -- that exact build tag did not exist
+on quay. Guard against it:
+
+- **Resolve a verified image instead of guessing one -- do this first.** If a
+  `recommend_biocontainer` tool is available (Galaxy MCP), call it with the conda packages your
+  command needs -- e.g. `["samtools=1.17", "bwa"]` -- and use the `image` it returns. It's resolved
+  and checked against quay.io rather than hallucinated, so it can't invent a nonexistent tag. A
+  single package yields a single-package image; several yield a mulled-v2 image. The returned
+  `match_quality` tells you whether the exact version matched (`exact_version`) or only the name did
+  (`name_only`, newest tag used), and `verified` confirms the tag is actually built. Only auto-apply
+  an `exact_version` result; if it comes back `name_only` and the exact version matters, review the
+  substituted tag before using it. From a terminal,
+  the same resolver is the **`mulled-recommend`** CLI in `galaxy-tool-util`:
+  `mulled-recommend samtools=1.17`, `mulled-recommend --json "bwa,samtools"`.
+- **If you must pick by hand, don't guess the biocontainers build suffix** (`--<hash>_<build>`). It
+  is not derivable from the version. Look up the real tag: browse
+  `https://quay.io/repository/biocontainers/<tool>?tab=tags` or query
+  `https://quay.io/api/v1/repository/biocontainers/<tool>/tag/?onlyActiveTags=true`.
+- **For a stdlib-only tool, skip biocontainers entirely.** Use an official base image like
+  `python:3.11-slim` (or `busybox` for shell-only) and write the logic inline (see the heredoc
+  pattern in `references/templating.md`). The seaborn failure above was fixed exactly this way:
+  switch to `python:3.11-slim` and emit SVG with the standard library, no third-party image to get
+  wrong. (A bare language image ships no third-party libraries -- `python:3.13` cannot `import
+  pandas` -- so this is only for genuinely stdlib-only logic; otherwise resolve a package image
+  above.)
+- **Never invent an image, tag, or CLI flag you can't verify** -- resolve it (above) or ask the user
+  rather than guessing.
+
+## Write a `help` block (convention)
+
+`help` is schema-optional, but **always include a real one**. Galaxy renders it under the parameter
+form on the tool page, so a UDT without help is a black box to anyone -- including the same user
+weeks later -- who opens it. The wire shape is an object, not a bare string:
+
+```yaml
+help:
+  format: markdown        # markdown | restructuredtext | plain_text
+  content: |
+    Cuts a single column from a tab-separated file.
+
+    **Inputs**
+    - `input`: TSV file (with or without header).
+    - `column`: 1-based column index.
+
+    **Outputs**
+    - `output`: TSV with only the selected column, in input row order.
+
+    Header lines are not auto-detected; the column index applies to every row.
+```
+
+Three short paragraphs is enough: what the tool does, its inputs/outputs, and any caveat (resource
+limits, expected file shape, non-obvious behavior). Don't ship a `TODO` placeholder -- an empty or
+stub `help` is no better than none. If help genuinely isn't worth writing (a one-off throwaway), say
+so and confirm with the user before creating the tool.
+
+## Validating a Definition
+
+Validation logic is pure Python in `galaxy-tool-util` -- the same code the server runs -- so you can
+check offline before submitting. Three tiers, weakest to strongest:
+
+1. **Local** (fast, offline, side-effect-free): `python scripts/validate.py my-tool.yml`. Needs
+   `pip install 'galaxy-tool-util>=26.1'`. Catches structural errors, the four semantic validators, and
+   lint warnings. Use this whenever a Python env is available (terminal, CI). See `scripts/`.
+   **Version-sensitive:** the installed galaxy-tool-util *is* the schema, and the 26.1 behaviors this
+   skill describes (data inputs rejecting `min`/`max`, a minimal `discover_datasets`,
+   `--check-container`) need galaxy-tool-util **26.1+** -- so install
+   `pip install 'galaxy-tool-util>=26.1'`. On an older install the same file validates against the
+   older schema, which is a different answer, not a wrong one: if your target server is older, that
+   *is* the schema you're writing against. Either way the server create (tier 3) is the final word.
+2. **`planemo lint`** -- not available yet (planemo does not lint UDTs as of this writing). It
+   already depends on `galaxy-tool-util`, so teaching it to lint a `GalaxyUserTool` YAML would be a
+   small addition, and it's the natural future home for tier 1. Down the road `scripts/validate.py`
+   should migrate to `planemo lint <tool>.yml`, so authors get this check through the standard Galaxy
+   tool CLI instead of a bundled script. Until that lands, use tier 1.
+3. **Server create** -- `create_user_tool` / `POST /api/unprivileged_tools` runs the same lint and
+   confirms *this server* accepts it (needs `enable_beta_tool_formats` + the Custom Tool Execution
+   role). This is the final word, and the practical gate for environments without Python (e.g.
+   Loom): submit, then iterate on the returned errors.
+
+> **Lint-clean is necessary but not sufficient.** Neither validate.py nor the server's create lint
+> checks that the command actually succeeds. The one thing you *can* check ahead of time is the
+> container: a nonexistent tag (`manifest unknown` at run time) is the most common real-world UDT
+> failure, so resolve a verified image with `recommend_biocontainer` / `mulled-recommend` (see
+> "Choosing a Container") -- or run `validate.py --check-container` to test the tag you already have.
+> Beyond that, validation can't see runtime JS-expression errors, shell quoting, the server's
+> role/config gates, or whether the command produces the declared outputs -- only running the tool
+> does.
+
+## Iterating & Cleanup
+
+There is no in-place update API -- every `create_user_tool` call makes a **new** tool. When you
+iterate, bump `version` (e.g. `0.1.0` -> `0.2.0`); Galaxy keeps every prior version under the user's
+account. Heavy iteration accumulates stale versions, so once a design stabilizes, offer to deactivate
+the superseded ones with `delete_user_tool` -- it marks the tool inactive (hidden from the toolbox),
+not a hard delete; the records remain.
+
+## Limitations
+
+UDTs deliberately can't reach several things classic tools can (per the Galaxy docs):
+
+- **No reference data** -- no built-in genome indexes or `.loc` files.
+- **No metadata files** -- e.g. a BAM index (`.bai`) isn't available; if the command needs one, build
+  it inside the `shell_command` or take it as an explicit `data` input.
+- **No `extra_files` directory** -- composite / extra-file outputs aren't supported.
+
+Design around these: pass whatever the tool needs as an explicit input, and generate any side files
+inside the container.
+
+## Common Patterns
+
+| Goal | shell_command snippet |
+|------|-----------------------|
+| Single data file path | `tool '$(inputs.reads.path)'` |
+| Scalar value | `tool --count $(inputs.count)` |
+| Multiple data files | `cat $(inputs.datasets.map(d => d.path).join(' ')) > out.txt` |
+| Boolean as a flag | `tool $(inputs.verbose ? '--verbose' : '')` |
+| Use the job's allocated cores | `tool --threads $GALAXY_SLOTS` (+ a `resource` requirement, `cores_min`) |
+| Capture one output file | declare output with `from_work_dir: out.txt` |
+| Capture many outputs | declare output `type: collection` with `discover_datasets` |
+| Run a non-trivial inline script | `python <<'PY'` ... `PY` heredoc; reference inputs as `$(inputs.x)` inside (see `references/templating.md`) |
+
+See `examples/` for eight complete, validated UDTs spanning these patterns.
+
+## Troubleshooting
+
+| Symptom / error code | Cause | Fix |
+|----------------------|-------|-----|
+| `dynamic_tool.output_unclaimed` | Output has no `from_work_dir`/`discover_datasets` | Write to a fixed filename and claim it |
+| `dynamic_tool.undeclared_input_ref` | `$(inputs.X)` with no input named `X` | Declare the input or fix the name |
+| `dynamic_tool.blank_container` | `container` empty / missing | Set a real container image string |
+| `string_pattern_mismatch` on `id` | Uppercase, leading digit, spaces | Use `^[a-z][a-z0-9_-]*$` |
+| extra-field rejection | XML-ism like `truevalue`, `command`, `${on_string}` | Remove it -- schema is `extra="forbid"` |
+| `manifest unknown` / `Unable to find image` at **run** time | Container tag doesn't exist on the registry | Resolve a verified image with `recommend_biocontainer` / `mulled-recommend` (or `python:3.x-slim` for stdlib tools) -- lint can't catch this |
+| HTTP 403 "not allowed to run unprivileged" | The admin's job routing (TPV) rejects `tool_type_user_defined` by default | Not fixable client-side -- the admin must add a destination/routing rule for user-defined tools |
+| `help` rejected at create | `help` sent as a bare string | Use the object form: `help: {format, content}` |
+
+Full list with the why behind each: `references/common-mistakes.md`.
+
+## Resources
+
+- `references/schema-reference.md` -- every `UserToolSource` field, input/output types, validators
+- `references/templating.md` -- the `$(...)` ECMAScript model, arrays, `$GALAXY_SLOTS`, escaping
+- `references/common-mistakes.md` -- pre-submit self-review checklist
+- `scripts/validate.py` -- offline validate + lint via `galaxy-tool-util`
+- `examples/` -- eight complete UDTs, simple to complex (incl. inline-script and configfile-script `python:slim` tools)
+- Galaxy docs: [User-Defined Tools](https://docs.galaxyproject.org/en/master/admin/user_defined_tools.html)
+- For classic XML tools instead: the `tool-dev` skill.

package/extensions/orbit/vendor/skills/skills/udt-authoring/examples/01-minimal-echo.yml

@@ -0,0 +1,27 @@
+# Smallest useful UDT: one text input, one captured output.
+class: GalaxyUserTool
+id: echo-message
+version: "0.1.0"
+name: Echo a message
+description: Write a user-provided message to a text file
+container: busybox
+shell_command: |
+  echo "$(inputs.message)" > out.txt
+inputs:
+  - name: message
+    type: text
+    value: "Hello, Galaxy!"
+    label: Message to write
+outputs:
+  - name: out
+    type: data
+    format: txt
+    from_work_dir: out.txt
+    label: Message file
+help:
+  format: markdown
+  content: |
+    Writes a user-provided message to a text file.
+
+    **Inputs** -- `message`: the text to write.
+    **Outputs** -- `out`: a text file containing the message.

package/extensions/orbit/vendor/skills/skills/udt-authoring/examples/02-single-data-in-out.yml

@@ -0,0 +1,27 @@
+# One data input referenced by .path, transformed, one output claimed by from_work_dir.
+class: GalaxyUserTool
+id: to-uppercase
+version: "0.1.0"
+name: Uppercase a text file
+description: Convert all letters in a text file to uppercase
+container: busybox
+shell_command: |
+  tr '[:lower:]' '[:upper:]' < '$(inputs.input.path)' > upper.txt
+inputs:
+  - name: input
+    type: data
+    format: txt
+    label: Input text file
+outputs:
+  - name: output
+    type: data
+    format: txt
+    from_work_dir: upper.txt
+    label: Uppercased text
+help:
+  format: markdown
+  content: |
+    Converts all letters in a text file to uppercase.
+
+    **Inputs** -- `input`: a text file.
+    **Outputs** -- `output`: the same text, uppercased.

package/extensions/orbit/vendor/skills/skills/udt-authoring/examples/03-multiple-data-js.yml

@@ -0,0 +1,28 @@
+# A multiple:true data input is an array -- map over it to build the command.
+# format_source copies the output datatype from an input instead of hardcoding it.
+class: GalaxyUserTool
+id: concatenate-files
+version: "0.1.0"
+name: Concatenate files
+description: Concatenate one or more files head-to-tail
+container: busybox
+shell_command: |
+  cat $(inputs.datasets.map((input) => input.path).join(' ')) > output.txt
+inputs:
+  - name: datasets
+    type: data
+    multiple: true
+    label: Files to concatenate
+outputs:
+  - name: output
+    type: data
+    format_source: datasets
+    from_work_dir: output.txt
+    label: Concatenated output
+help:
+  format: markdown
+  content: |
+    Concatenates one or more files head-to-tail into a single file.
+
+    **Inputs** -- `datasets`: one or more files.
+    **Outputs** -- `output`: the concatenated result (datatype copied from the inputs).

package/extensions/orbit/vendor/skills/skills/udt-authoring/examples/04-select-integer-boolean.yml

@@ -0,0 +1,41 @@
+# Scalar parameter types: select (with options), integer (with bounds), and a
+# boolean turned into a flag via a ternary -- NOT truevalue/falsevalue.
+class: GalaxyUserTool
+id: repeat-greeting
+version: "0.1.0"
+name: Repeat a greeting
+description: Print a chosen greeting a number of times, optionally shouting
+container: busybox
+shell_command: |
+  yes "$(inputs.greeting)$(inputs.shout ? '!' : '')" | head -n $(inputs.count) > greetings.txt
+inputs:
+  - name: greeting
+    type: select
+    label: Greeting
+    help: Which greeting to print.
+    options:
+      - { label: Hi, value: Hi, selected: true }
+      - { label: Hello, value: Hello, selected: false }
+  - name: count
+    type: integer
+    value: 3
+    min: 1
+    max: 100
+    label: Number of lines
+  - name: shout
+    type: boolean
+    value: false
+    label: Add an exclamation mark
+outputs:
+  - name: output
+    type: data
+    format: txt
+    from_work_dir: greetings.txt
+    label: Greetings
+help:
+  format: markdown
+  content: |
+    Prints a chosen greeting a number of times, optionally with an exclamation mark.
+
+    **Inputs** -- `greeting` (Hi/Hello), `count` (1-100), `shout` (adds "!").
+    **Outputs** -- `output`: the greetings, one per line.

package/extensions/orbit/vendor/skills/skills/udt-authoring/examples/05-resource-requirements.yml

@@ -0,0 +1,25 @@
+# Request cores with a resource requirement; read the allocation at runtime via
+# the $GALAXY_SLOTS shell variable (no parentheses -> not a $() expression).
+class: GalaxyUserTool
+id: report-cores
+version: "0.1.0"
+name: Report allocated cores
+description: Write the number of CPU cores Galaxy allocated to this job
+container: busybox
+requirements:
+  - type: resource
+    cores_min: 2
+shell_command: |
+  echo "$GALAXY_SLOTS" > galaxy_cores.txt
+outputs:
+  - name: cores
+    type: data
+    format: txt
+    from_work_dir: galaxy_cores.txt
+    label: Allocated cores
+help:
+  format: markdown
+  content: |
+    Reports the number of CPU cores Galaxy allocated to the job (from `$GALAXY_SLOTS`).
+
+    **Outputs** -- `cores`: a one-line text file with the core count.

package/extensions/orbit/vendor/skills/skills/udt-authoring/examples/06-biocontainer-tool.yml

@@ -0,0 +1,38 @@
+# Realistic capstone: a real bioinformatics tool in a biocontainer, multiple data
+# inputs joined with .map().join(), threads from $GALAXY_SLOTS, tabular output.
+#
+# IMPORTANT: verify the exact container tag exists before use -- do not guess.
+# Browse https://quay.io/repository/biocontainers/seqkit?tab=tags for current tags.
+class: GalaxyUserTool
+id: seqkit-stats
+version: "0.1.0"
+name: SeqKit sequence statistics
+description: Summary statistics (num seqs, length, N50, GC) for FASTA/FASTQ files
+container: quay.io/biocontainers/seqkit:2.8.2--h9ee0642_0
+requirements:
+  - type: resource
+    cores_min: 2
+shell_command: |
+  seqkit stats --tabular --all --threads $GALAXY_SLOTS $(inputs.input_files.map((f) => f.path).join(' ')) > stats.tsv
+inputs:
+  - name: input_files
+    type: data
+    format: [fasta, fastq]
+    multiple: true
+    label: Input sequence file(s)
+    help: One or more FASTA or FASTQ files to summarize.
+outputs:
+  - name: report
+    type: data
+    format: tabular
+    from_work_dir: stats.tsv
+    label: Sequence statistics (TSV)
+help:
+  format: markdown
+  content: |
+    Computes summary statistics (num seqs, length, N50, GC) for FASTA/FASTQ files with `seqkit stats`.
+
+    **Inputs** -- `input_files`: one or more FASTA/FASTQ files.
+    **Outputs** -- `report`: a tabular statistics report.
+
+    Uses the job's allocated cores (`$GALAXY_SLOTS`).

package/extensions/orbit/vendor/skills/skills/udt-authoring/examples/07-inline-python-script.yml

@@ -0,0 +1,56 @@
+# Real-world pattern: a stdlib-only Python tool in an OFFICIAL python:3.x-slim image
+# (not a biocontainer whose build-hash tag you'd have to guess), with the script
+# embedded via a quoted heredoc. Modeled on a plotting UDT whose seaborn-biocontainer
+# tag did not exist at run time -- switching to python:3.11-slim + stdlib was the fix.
+class: GalaxyUserTool
+id: column-summary
+version: "0.1.0"
+name: Summarize a numeric column
+description: Report count, mean, min, and max of one numeric column in a tabular file
+container: python:3.11-slim
+shell_command: |
+  python <<'PY'
+  import csv
+  path = '$(inputs.table.path)'
+  column = '$(inputs.column)'
+  values = []
+  with open(path, newline='') as fh:
+      reader = csv.DictReader(fh, delimiter='\t')
+      for row in reader:
+          cell = row.get(column, '')
+          if cell not in ('', None):
+              values.append(float(cell))
+  if not values:
+      raise SystemExit(f'No numeric values found in column {column!r}')
+  n = len(values)
+  with open('summary.txt', 'w') as out:
+      out.write(f'column\t{column}\n')
+      out.write(f'count\t{n}\n')
+      out.write(f'mean\t{sum(values) / n}\n')
+      out.write(f'min\t{min(values)}\n')
+      out.write(f'max\t{max(values)}\n')
+  PY
+inputs:
+  - name: table
+    type: data
+    format: tabular
+    label: Tabular input
+  - name: column
+    type: text
+    label: Column name to summarize
+    help: Must match a column header in the tabular file.
+outputs:
+  - name: summary
+    type: data
+    format: txt
+    from_work_dir: summary.txt
+    label: Column summary
+help:
+  format: markdown
+  content: |
+    Reports count, mean, min, and max of one numeric column in a tabular file.
+
+    **Inputs** -- `table`: a tabular file; `column`: the column header to summarize.
+    **Outputs** -- `summary`: a small text report.
+
+    The column must match a header in the file; non-numeric/empty cells are skipped.

package/extensions/orbit/vendor/skills/skills/udt-authoring/examples/08-configfile-script.yml

@@ -0,0 +1,74 @@
+# Real-world pattern: run a longer script by NAME, and pass an untrusted `text`
+# parameter SAFELY. Two things to notice:
+#   1. The script is materialized by a `configfiles` entry whose `filename` is
+#      exactly what `shell_command` runs -- the critical rule from
+#      references/templating.md. (`python summarize.py` with no configfile that
+#      creates summarize.py would be broken -- the file wouldn't exist at run time.)
+#   2. The `column` value is a free-text input, so it is NOT interpolated into
+#      Python source (a quote or newline could break or inject into the code).
+#      Instead it's written to a JSON configfile via `JSON.stringify(...)` -- which
+#      safely encodes any string -- and the script reads it back as data.
+class: GalaxyUserTool
+id: column-summary-configfile
+version: "0.1.0"
+name: Summarize a numeric column (configfile)
+description: Report count, mean, min, and max of one numeric column in a tabular file
+container: python:3.11-slim
+configfiles:
+  - filename: params.json
+    content: |
+      {"table": $(JSON.stringify(inputs.table.path)), "column": $(JSON.stringify(inputs.column))}
+  - filename: summarize.py
+    content: |
+      import csv
+      import json
+
+      with open("params.json") as fh:
+          params = json.load(fh)
+      path = params["table"]
+      column = params["column"]
+
+      values = []
+      with open(path, newline="") as fh:
+          for row in csv.DictReader(fh, delimiter="\t"):
+              cell = row.get(column, "")
+              try:
+                  values.append(float(cell))
+              except (TypeError, ValueError):
+                  continue  # skip empty and non-numeric cells
+      if not values:
+          raise SystemExit(f"No numeric values found in column {column!r}")
+      n = len(values)
+      with open("summary.txt", "w") as out:
+          out.write(f"column\t{column}\n")
+          out.write(f"count\t{n}\n")
+          out.write(f"mean\t{sum(values) / n}\n")
+          out.write(f"min\t{min(values)}\n")
+          out.write(f"max\t{max(values)}\n")
+shell_command: python summarize.py
+inputs:
+  - name: table
+    type: data
+    format: tabular
+    label: Tabular input
+  - name: column
+    type: text
+    label: Column name to summarize
+    help: Must match a column header in the tabular file.
+outputs:
+  - name: summary
+    type: data
+    format: txt
+    from_work_dir: summary.txt
+    label: Column summary
+help:
+  format: markdown
+  content: |
+    Reports count, mean, min, and max of one numeric column in a tabular file.
+
+    **Inputs** -- `table`: a tabular file; `column`: the column header to summarize.
+    **Outputs** -- `summary`: a small text report.
+
+    The script is delivered as a configfile named `summarize.py` and run by name;
+    the column name is passed via a JSON configfile (not inlined into the code).
+    The column must match a header in the file; empty and non-numeric cells are skipped.

package/extensions/orbit/vendor/skills/skills/udt-authoring/references/common-mistakes.md

@@ -0,0 +1,76 @@
+# Common Mistakes & Pre-Submit Checklist
+
+UDTs are modeled after XML tools, so the most common failures are XML/Cheetah habits leaking in,
+plus a few schema-specific traps. Run through this before submitting.
+
+## Checklist
+
+- [ ] Command is under **`shell_command`**, not `command`.
+- [ ] Parameters use **`$(inputs.x)`** / **`$(inputs.x.path)`**, not Cheetah `$x` or `#for#`.
+- [ ] `container` is a **plain string** of a **real** image (verified biocontainer when possible).
+- [ ] Every output has **`from_work_dir`** or **`discover_datasets`** (collections: `discover_datasets`).
+- [ ] Outputs are captured by file (`from_work_dir`/`discover_datasets`); there is **no** `$(outputs.X.path)`.
+- [ ] Every `$(inputs.X)` reference has a matching declared input named `X`.
+- [ ] If `shell_command` runs a script by name (`python script.py`), a `configfiles` entry creates that exact filename -- otherwise inline it with `python -c` / `Rscript -e`.
+- [ ] No `min`/`max` on a `data` input (it's already required; use `optional: true` to relax, `multiple: true` for a list).
+- [ ] `id` matches `^[a-z][a-z0-9_-]*$`; `name` is at least 5 characters.
+- [ ] No rejected fields: `truevalue`, `falsevalue`, `argument`, `parameter_type`, `${on_string}`, `${tool.name}`.
+- [ ] Booleans become flags via a ternary, not `truevalue`/`falsevalue`.
+- [ ] The parallelism flag's **value** is `$GALAXY_SLOTS` (+ a `resource` requirement), not a hardcoded number -- and not merely echoed to a log while the flag stays a literal.
+- [ ] Optional parameters have sensible `value` defaults.
+- [ ] Labels and description say what the tool actually does (not "Run the tool").
+- [ ] A real `help` block is present (object form `{format, content}`, no `TODO` placeholder).
+- [ ] Scalar `text`/`select` values are quoted in `shell_command` (or passed via a configfile) -- they interpolate unquoted.
+
+## Mistakes table
+
+| Mistake | Why it's wrong | Fix |
+|---------|----------------|-----|
+| `command: ...` | The field is `shell_command`; `command` is rejected (`extra="forbid"`). | Rename to `shell_command`. |
+| `$threads`, `#for f in $files#` | Cheetah templating. UDTs use sandboxed ECMAScript. | `$(inputs.threads)`, `$(inputs.files.map(f => f.path).join(' '))`. |
+| `'$(inputs.reads)'` for a data input | A data input is an object, not a path. | `'$(inputs.reads.path)'`. |
+| `container: {type: docker, image: ...}` | `container` is a plain string. | `container: quay.io/biocontainers/...`. |
+| Output written to `'$(inputs.out)'` / a templated output path | UDTs don't pass output paths in; the file is claimed afterward. | Write to a fixed filename, then `from_work_dir: that-file`. |
+| `$(outputs.name.path)` in the command | There is no `outputs` object in the template namespace -- only `inputs`. | Write to a fixed filename and claim it with `from_work_dir`/`discover_datasets`. |
+| `python script.py` with no `configfiles` entry named `script.py` | The file is never created in the working dir, so the command fails at runtime (lint won't catch it). | Add a `configfiles` entry whose `filename` is exactly `script.py`, or inline the code with `python -c`. |
+| Output with neither `from_work_dir` nor `discover_datasets` | `dynamic_tool.output_unclaimed`. | Add one of them. |
+| `$(inputs.foo)` but no input `foo` | `dynamic_tool.undeclared_input_ref`. | Declare `foo` or fix the typo. |
+| `min: 1` / `max: N` on a `data` input | Dropped from the schema in 26.1 (`extra="forbid"` rejects them); authors used `min: 1` to mean "required," but data inputs already are. | Remove them. Data inputs are required by default (`optional: true` to relax); use `multiple: true` to accept several. |
+| `truevalue: --x` / `falsevalue: ""` on a boolean | XML-only fields, rejected. | `value: false` + `$(inputs.x ? '--x' : '')` in the command. |
+| `${on_string}`, `${tool.name}` in labels | Cheetah macros; not supported. | Use a plain string label, or `format_source` to inherit. |
+| `id: My_Tool` / `id: 2pass` | Must be lowercase and start with a letter (`string_pattern_mismatch`). | `id: my-tool`, `id: two-pass`. |
+| Hardcoded `--threads 8` -- even while echoing `$GALAXY_SLOTS` elsewhere | Ignores the job's real allocation; recording the value isn't using it. | Make the flag's value `$GALAXY_SLOTS` (`--threads $GALAXY_SLOTS`) + `resource` `cores_min`. |
+| `container: ubuntu:latest` for a bioinformatics tool | Generic image won't have the binary; not reproducible. | Use the tool's biocontainer. |
+| Invented image/tag/flags | A guessed container or CLI flag fails at runtime. | Use only images/flags you can verify; otherwise ask. |
+| Unescaped literal `$(date)` in the command | Galaxy treats `$(...)` as an expression and errors/misfires. | Escape it: `\$(date)`. |
+| `help` omitted, a bare string, or a `TODO` stub | Galaxy wants `{format, content}`; an empty/missing help leaves a documentation-free black box on the tool page. | Write a real help block: 3 short paragraphs (what / inputs+outputs / caveats). |
+| Free-text scalar inlined unquoted in `shell_command` | `$(inputs.x)` for `text`/`select` interpolates raw (no `shlex.quote`); spaces/quotes break or inject into the command. | Quote it (`'$(inputs.x)'`) or pass free text via a configfile; fixed `select`/numeric values are safe. |
+
+## Verifying a container (the #1 runtime failure)
+
+A wrong container is the most common way a UDT passes validation and then fails at run time --
+schema/lint never check that the image exists. Real case: a plotting UDT declared
+`quay.io/biocontainers/seaborn:0.13.2--pyhd8ed1ab_3`, was accepted by `create_user_tool`, and the
+job died with `manifest unknown` because that exact build tag didn't exist on quay.
+
+- **Resolve a verified image instead of guessing.** Call `recommend_biocontainer` (Galaxy MCP) with
+  the conda packages (`["samtools=1.17", "bwa"]`) and use the `image` it returns, or run
+  `mulled-recommend samtools=1.17` in a terminal -- both check quay.io rather than hallucinating.
+- **Never guess the biocontainers build suffix** (`--<hash>_<build>`) -- it isn't derivable from the
+  version number. Look it up: browse `https://quay.io/repository/biocontainers/<tool>?tab=tags` or
+  query `https://quay.io/api/v1/repository/biocontainers/<tool>/tag/?onlyActiveTags=true`.
+- **Stdlib-only tool? Skip biocontainers.** Use `python:3.x-slim` (or `busybox` for shell-only) and
+  write the logic inline -- there's no third-party tag to get wrong. The seaborn failure above was
+  fixed precisely this way: switch to `python:3.11-slim` and emit SVG with the standard library.
+- **A clean `validate.py` does not mean the image pulls.** Lint validates the YAML, not the
+  registry. Verify the image separately -- `validate.py --check-container`, `recommend_biocontainer`,
+  or `mulled-recommend` -- or let the server-create + first run confirm it.
+
+## Clarity pass (what a deterministic validator can't catch)
+
+The schema accepts plenty of unhelpful-but-valid tools. Before finishing, also check:
+
+- `description` states what the tool does, specifically.
+- Non-obvious inputs have `help` text; `label`s aren't just the parameter name repeated.
+- Common, useful options for the wrapped tool are exposed (e.g. a threads input for an aligner).
+- Defaults are sensible so a user can run it without filling in everything.