Galaxy Tool Wrapping Expert

Expert knowledge for developing Galaxy tool wrappers. Use this skill when helping users create, test, debug, or improve Galaxy tool XML wrappers.

Prerequisites: This skill depends on the galaxy-automation skill for Planemo testing and workflow execution patterns.

When to Use This Skill

Creating new Galaxy tool wrappers from scratch
Converting command-line tools to Galaxy wrappers
Generating .shed.yml files for Tool Shed submission
Debugging XML syntax and validation errors
Writing Planemo tests for tools
Implementing conditional parameters and data types
Handling tool dependencies (conda, containers)
Creating tool collections and suites
Optimizing tool performance and resource allocation
Understanding Galaxy datatypes and formats
Implementing proper error handling

Core Concepts

Galaxy Tool XML Structure

A Galaxy tool wrapper consists of:

<tool> root element with id, name, and version
<description> brief tool description
<requirements> for dependencies (conda packages, containers)
<command> the actual command-line execution
<inputs> parameter definitions
<outputs> output file specifications
<tests> automated tests
<help> documentation in reStructuredText
<citations> DOI references

Tool Shed Metadata (.shed.yml)

Required for publishing tools to the Galaxy Tool Shed:

name: tool_name                  # Match directory name, underscores only
owner: iuc                       # Usually 'iuc' for IUC tools
description: One-line tool description
homepage_url: https://github.com/tool/repo
long_description: |
  Multi-line detailed description.
  Can include features, use cases, and tool suite contents.
remote_repository_url: https://github.com/galaxyproject/tools-iuc/tree/main/tools/tool_name
type: unrestricted
categories:
- Assembly                       # Choose 1-3 relevant categories
- Genomics

See reference.md for comprehensive .shed.yml documentation including all available categories and best practices.

Key Components

Command Block:

Use Cheetah templating: $variable_name or ${variable_name}
Conditional logic: #if $param then... #end if
Loop constructs: #for $item in $collection... #end for
CDATA sections for complex commands

Cheetah Template Best Practices:

Working around path handling issues in conda packages:

<command detect_errors="exit_code"><![CDATA[
    ## Add trailing slash if script concatenates paths without separator
    tool_command
        -o 'output_dir/'  ## Quoted with trailing slash

    ## Script does: output_dir + 'file.txt' → 'output_dir/file.txt' ✓
    ## Without slash: output_dir + 'file.txt' → 'output_dirfile.txt' ✗
]]></command>

When to use quotes in Cheetah:

Always quote user inputs: '$input_file'
Quote literal strings with special chars: 'output_dir/'
Use bare variables for simple references: $variable

Input Parameters:

<param> elements with type, name, label
Types: text, integer, float, boolean, select, data, data_collection
Optional vs required parameters
Validators and sanitizers
Conditional parameter display

Outputs:

<data> elements for output files
Dynamic output naming with label and name
Format discovery and conversion
Filters for conditional outputs
Collections for multiple outputs

Tests:

Input parameters and files
Expected output files or assertions
Test data location and organization
See testing.md for detailed testing strategies including large file handling

Best Practices

Always include tests - Planemo won't pass without them
Use semantic versioning - Increment tool version on changes
Specify exact dependencies - Pin conda package versions
Add clear help text - Document all parameters
Handle errors gracefully - Check exit codes, validate inputs
Use collections - For multiple related files
Follow IUC standards - If contributing to intergalactic utilities commission
Plan for large output files - Before creating tests, check expected output sizes. If over 1MB, use assertion-based tests (has_size, has_line) instead of full file comparison (see testing.md)

Common Planemo Commands

# Test tool locally
planemo test tool.xml

# Serve tool in local Galaxy
planemo serve tool.xml

# Lint tool for best practices
planemo lint tool.xml

# Upload tool to ToolShed
planemo shed_update --shed_target toolshed

# Test with conda
planemo test --conda_auto_init --conda_auto_install tool.xml

Output Routing with Symlinks

When a tool writes output to a filename it constructs internally (not $output), use symlinks in the command block to route the file to Galaxy's output variable.

Pattern: Symlink before command execution

<command detect_errors="exit_code"><![CDATA[
    ## Create symlink so tool output lands where Galaxy expects it
    ln -s '$output_variable' 'expected_tool_output_name' &&
    tool_command --input '$input' -o 'expected_tool_output_name'
]]></command>

Pattern: Prefix-based output naming

Some tools use --out-prefix where the output filename is prefix + input_filename. The tool constructs the filename internally, so you must predict it and symlink:

<command><![CDATA[
    #set $mangled_input = re.sub(r"[^\w\-\s]", "_", str($input.element_identifier)) + "." + str($input.ext)
    ln -s '$input' '$mangled_input' &&
    ln -s '$output_var' 'myprefix${mangled_input}' &&
    tool_command --input-reads '$mangled_input' -p myprefix
]]></command>

Key points:

Symlink is created before running the tool -- the tool writes through it
Must match the exact filename the tool will produce
For prefix mode: output = prefix + getFileName(input), so mangle the input name to match

Using `format_source` for dynamic output formats

When output format should match the input format (e.g., subsampled reads):

<data name="subsampled_outfile" format_source="input_reads" label="Subsampled reads">
    <filter>output_options["output_type"]["type_selector"] == "subsampled_reads"</filter>
</data>

This is preferable to change_format when the output is always the same format as input. Use change_format when the user explicitly selects the output format.

XML Template Example

<tool id="tool_id" name="Tool Name" version="1.0.0">
    <description>Brief description</description>

    <requirements>
        <requirement type="package" version="1.0">package_name</requirement>
    </requirements>

    <command detect_errors="exit_code"><![CDATA[
        tool_command
            --input '$input'
            --output '$output'
            #if $optional_param
                --param '$optional_param'
            #end if
    ]]></command>

    <inputs>
        <param name="input" type="data" format="txt" label="Input file"/>
        <param name="optional_param" type="text" optional="true" label="Optional parameter"/>
    </inputs>

    <outputs>
        <data name="output" format="txt" label="${tool.name} on ${on_string}"/>
    </outputs>

    <tests>
        <test>
            <param name="input" value="test_input.txt"/>
            <output name="output" file="expected_output.txt"/>
        </test>
    </tests>

    <help><![CDATA[
**What it does**

Describe what the tool does.

**Inputs**

- Input file: description

**Outputs**

- Output file: description
    ]]></help>

    <citations>
        <citation type="doi">10.1234/example.doi</citation>
    </citations>
</tool>

Supporting Documentation

This skill includes detailed reference documentation:

reference.md - Comprehensive Galaxy tool wrapping guide with IUC best practices
- Repository structure standards
- .shed.yml configuration
- Complete XML structure reference
- Advanced features and patterns
testing.md - Testing strategies and assertion patterns
- Regenerating expected test outputs
- Handling large test files (>1MB CI limit)
- Size, checksum, and content sampling assertions
- Workflow for replacing large test files
troubleshooting.md - Practical troubleshooting guide
- Reading tool_test_output.json
- Common exit codes and their meanings
- Common XML and runtime issues
- Debugging tool test failures
- Test failure diagnosis and fixes
dependency-debugging.md - Dependency conflict resolution
- Using planemo mull for diagnosis
- Conda solver error interpretation
- macOS testing considerations
- Version conflict workflows

These files provide deep technical details that complement the core concepts above.

Related Skills

galaxy-automation - BioBlend & Planemo foundation (dependency)
galaxy-workflow-development - Building workflows that use these tools
conda-recipe - Creating conda packages for tool dependencies
bioinformatics-fundamentals - Understanding file formats and data types used in tools

Resources

Galaxy Tool Development: https://docs.galaxyproject.org/en/latest/dev/
Planemo Documentation: https://planemo.readthedocs.io/
IUC Standards: https://galaxy-iuc-standards.readthedocs.io/
Galaxy Training: https://training.galaxyproject.org/

galaxy-tool-wrapping