Generated banner for Complexa Target
Generated logo for Complexa Target

Complexa Target

NVIDIAOfficialCreated by Ohad MosafiDistributed by NVIDIA

  • Skill
  • Tool integration
  • Software development
  • Apache-2.0
  • Medium risk

From the author

Add, edit, inspect, or validate Proteina-Complexa target definitions for protein binders, ligand binders, and AME motif scaffolding. Use for target registries, chain/residue selectors, hotspots, ligand fields, and incomplete motif inputs. Covers direct YAML edits and complexa target/validate target commands; running a campaign with an already registered target belongs to complexa-design.
— the description by Ohad Mosafi

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The complexa-target skill provides a standardized approach to defining, editing, and validating design targets within the Proteina-Complexa framework. It covers the registration of protein binders, ligand binders, and AME enzyme scaffolding by managing specific YAML configuration files. The skill emphasizes direct file editing for configuration management, offering a reliable way to define target parameters such as chain selectors, hotspot residues, and ligand information, while providing validation steps to ensure target integrity before initiating design campaigns.

What it does

  • Adds or updates target definitions in YAML registries for protein and ligand binders.
  • Provides a structured schema for defining target inputs, hotspot residues, and ligand properties.
  • Supports manual configuration editing for AME enzyme scaffolding tasks.
  • Validates target configurations to ensure PDB paths and parameters are correctly resolved.
  • Offers CLI commands for listing and inspecting existing target definitions.
  • Generates documentation artifacts for registered design targets.

When to use it

  • When you need to register a new protein or ligand target for a design pipeline.
  • When you need to modify existing target parameters like hotspot residues or binder length ranges.
  • When you are preparing a new AME enzyme scaffolding task.
  • When you need to verify that a target PDB is correctly referenced and accessible by the pipeline.

Advantages

  • Direct YAML editing provides full control and avoids complex CLI flag management.
  • Standardized schema ensures consistency across different design pipelines.
  • Built-in validation steps prevent runtime errors by checking path resolution early.
  • Supports both simple protein surfaces and complex ligand-binding pockets.

Usage examples

“Add a new protein target named 'Target_Alpha' using PDB 'Alpha_Structure' from the 'custom_targets' source.”
The agent will append a new entry to configs/targets/targets_dict.yaml with the specified source, filename, and default binder length, then verify the configuration.
“Validate the configuration for the ligand target '41_7BKC_LIGAND'.”
The agent will run the validation command against the ligand pipeline to confirm the target exists and the PDB file is correctly resolved.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/nvidia/complexa-target/download
  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip complexa-target.zip -d .agents/skills

Documentation by Ohad Mosafi

complexa-target

Add or edit a design target in Proteina-Complexa. Targets live in three YAML files, one per complexa design pipeline:

  • configs/targets/targets_dict.yaml — protein binder (default pipeline)

  • configs/targets/ligand_targets_dict.yaml — ligand binder

  • configs/design_tasks/ame_dict_v2.yaml — AME / enzyme scaffolding

The complexa target CLI only manages the first two. AME tasks use an extended schema (the same core fields as ligand targets plus contig_atoms for hand-curated per-residue motif atom selections) and are file-edit-only.

Instructions

complexa target add is a thin wrapper around "load YAML → build dict → append a block" (see src/proteinfoundation/cli/target_manager.py:add_target_cli and append_target_to_dict). For agentic use, just edit the targets dict directly — the schema is short, the existing entries are great copy templates, and you skip 14 CLI flags / SMILES shell-escaping. Use the CLI only if you explicitly want its YAML auto-quoter or its overwrite-prompt safety.

For an offline edit, work on the supplied registry or requested output copy. When a copy is requested, create its parent directory and copy into an absent destination. If the destination already exists, inspect and preserve it: reuse it when it is the intended working copy, otherwise report the path conflict. Do not delete the output tree to restart a configuration edit. An installed Complexa runtime, GPU, or target structure is not required to write the configuration. Use the field schema below, preserve unrelated entries, and read back the saved block. Coordinate validation remains pending when the structure is absent; finish the configuration task without installing a runtime. With Read/Edit tools, read the destination copy before editing it; reading the original input path does not satisfy Edit's requirement for the output path.

Use the schema below and the selected registry; the CLI reference is needed only for CLI use. Finish with the saved entry, its consumer pipeline, the downstream generation.task_name, and the validation status.

StepDirect file edit (preferred)CLI
Look at existing targetsRead configs/targets/{,ligand_}targets_dict.yaml (or configs/design_tasks/ame_dict_v2.yaml for AME)complexa target list (protein/ligand only)
Look at one targetRead the dict and grep for the keycomplexa target show NAME
Add a new targetAppend a YAML block (Step 3a)complexa target add ... (Step 3b)
Verify configurationParse the saved YAML and compare the changed entry and untouched keyscomplexa target show NAME --dict PATH
Check runtime PDB-path resolutionRequires the full pipeline and environmentcomplexa validate target CONFIG --target NAME

Step 1: Decide the target type

Targets live in three different files, one per complexa design pipeline. Pick the file by working out which pipeline the user will run, then add the entry to that file. Each file is consumed by exactly one pipeline.

User intentPipelineTargets dict fileThis skill?
Bind a protein surface (PD-L1, IFNAR2, TNF-α, …) — defaultconfigs/search_binder_local_pipeline.yamlconfigs/targets/targets_dict.yamlYes — Step 2 (protein)
Bind a small-molecule pocket (FAD, SAM, OQO, …)configs/search_ligand_binder_local_pipeline.yamlconfigs/targets/ligand_targets_dict.yamlYes — Step 2 (ligand)
AME / enzyme scaffolding (motif + ligand, M####_<pdb> names)configs/search_ame_local_pipeline.yamlconfigs/design_tasks/ame_dict_v2.yamlPartial — see "AME tasks" below
AME tasks (enzyme pipeline)

AME tasks live under motif_target_dict_cfg: with source, target_filename, ligand, contig_atoms, binder_length, and use_bonds_from_file. The contig_atoms string contains curated chain/residue/atom selections. Existing entries illustrate the field structure, not the selections for a new motif. If motif atoms, ligand selection, or structure location are missing, list the missing inputs and write a separate, explicitly incomplete template if useful. Leave the registry unchanged until those scientific inputs are supplied. A task name or PDB ID alone does not determine them. In the missing-input handoff, explain that registration will be a direct edit under motif_target_dict_cfg once the curated selections are supplied; complexa target add cannot register AME tasks. Completed entries are selected with ++generation.task_name=<NAME> and configs/search_ame_local_pipeline.yaml.

Step 2: Gather required info

Use the supplied values and ask only for missing required information. Required fields differ for protein, ligand, and AME definitions.

Protein target
FieldQuestionExampleRequired
name"Target name (used as the dict key and task_name)?"02_PDL1, MyTarget_v1yes
source"Source directory under $DATA_PATH/target_data/?"bindcraft_targets, custom_targetsyes (or target_path)
target_filename"PDB filename (no .pdb extension)?"PD-L1, IFNAR2yes (or target_path)
target_input"Chain + residue range — see reference for grammar."A1-115, A1-50,B1-50yes
hotspot_residues"Hotspot residues (interface contact residues)?"["A33", "A95", "A102"]optional, recommended
binder_length"Binder length range [min, max] or single [length]?"[80, 150], [100]optional (default [60, 120])
pdb_id"Reference PDB ID (optional, metadata only)?""2lag"optional

Hotspot selectors encode chain + residue number, not amino-acid identity. For example, Tyr42 (Y42) on explicitly specified chain B becomes B42; already supplied chain/residue selectors stay unchanged. Preserve the user's residue numbering. Without coordinates, report that residue identities and membership in the structure are unverified.

Ligand target — protein fields above (minus target_input), plus:
FieldQuestionExampleRequired
ligand"3-letter PDB ligand residue code?"FAD, OQO, SAMyes (presence marks target as ligand)
SMILES"SMILES string for the ligand?""O=C2C3=Nc1cc(c(...)..."recommended; uppercase YAML key
ligand_only"Generate pocket around ligand only (no protein-protein interface)?"true / falseoptional (default true)
use_bonds_from_file"Use bond info from the input PDB/CIF?"true / falseoptional (default true)
target_inputnot required for ligand targets—no

Check whether the proposed key already exists in the selected YAML mapping. Preserve an existing entry unless the user requested that entry's update.

Copy a supplied SMILES exactly. Chain-specific ligand selection belongs to preparation of the input structure; do not invent a chain field or protein target_input to represent it in the ligand entry.

Examples

Step 3a: Append the YAML block directly (preferred)

Open configs/targets/targets_dict.yaml (or ligand_targets_dict.yaml for ligand targets), find a similar existing entry as a style template, and append the new block under target_dict_cfg:. Two-space indent, single blank line between entries.

Protein template
  02_PDL1:
    source: bindcraft_targets
    target_filename: PD-L1
    target_input: "A1-115"
    hotspot_residues: ["A37", "A39", "A49", "A98"]
    binder_length: [64, 155]
    pdb_id: "4z18"

Rules to match the existing file style (mirrors what complexa target add would emit):

  • Quote chain/residue ranges ("A1-115", "A33") and any SMILES — flow-style strings get tripped up by : and brackets otherwise.

  • Use flow-style lists (["A33", "A95"], [64, 155]) — that's what the on-disk dump produces.

  • target_input, source, target_filename are required for protein. target_path (absolute path) can replace source + target_filename if the PDB lives outside $DATA_PATH/target_data/.

Ligand template
  41_7BKC_LIGAND:
    source: ligand_targets
    target_filename: 7BKC_ligand_centered
    hotspot_residues: [null]
    binder_length: [100]
    pdb_id: 7BKC
    ligand: 'FAD'
    ligand_only: True
    SMILES: "O=C2C3=Nc1cc(c(cc1N(C3=NC(=O)N2)CC(O)C(O)C(O)COP(=O)(O)OP(=O)(O)OCC6OC(n5cnc4c(ncnc45)N)C(O)C6O)C)C"
    use_bonds_from_file: True

The presence of the ligand: key flips the target into ligand mode — there is no separate is_ligand flag. target_input is not required for ligands.

After saving, skip to Step 4 to verify.

Step 3b: CLI alternative (complexa target add)

Use the CLI when you want its automatic chain/residue quoting, the overwrite-confirm prompt, or to wire target creation into a non-Python script. Prefer non-interactive mode for agentic use (-i / --editor opens an editor and blocks).

Confirmed flags (from src/proteinfoundation/cli/target_cli.py)

Read target_schema.md for the flag table and worked CLI examples when this path is needed. Select the intended dictionary with --dict; --source and --target-filename should be explicit when they differ from the CLI defaults. AME registration remains a direct edit.

Step 4: Verify

First parse the saved YAML with an available YAML parser and check the selected mapping, field types, requested values, and preservation of other entries. Read back the resulting block. This verifies configuration editing only.

With a prepared Complexa installation, pipeline configs, environment, and target structure, additionally check runtime path resolution from that checkout:

# 1. Select the dictionary that was actually edited.
complexa target show 02_PDL1 --dict configs/targets/targets_dict.yaml

# 2. Resolve the PDB path and validate it exists on disk.
#    This traverses Hydra defaults to find the target dict.
complexa validate target configs/search_binder_local_pipeline.yaml --target 02_PDL1

complexa validate target (from src/proteinfoundation/cli/validate.py::validate_target) checks:

  • DATA_PATH is set and target_data/ exists.

  • The target name resolves in target_dict_cfg.

  • Either target_path exists, or $DATA_PATH/target_data/<source>/<target_filename>.pdb exists.

  • target_input, hotspot_residues, binder_length are reported back so a human can sanity-check them.

For ligand targets, use configs/targets/ligand_targets_dict.yaml for show and configs/search_ligand_binder_local_pipeline.yaml for validation; --target is the target key, not a config path. This validator does not check residue identities, ligand chemistry, or AME contig_atoms; do not describe a path check as coordinate or scientific validation.

Step 5: Emit artifact

Save the edited entry and validation status at the user's requested output location (otherwise ./target_<name>/). For an offline edit, the saved YAML block is sufficient; no CLI-generated artifact is required. On a prepared installation, a target-show record can also be saved:

mkdir -p target_02_PDL1
complexa target show 02_PDL1 > target_02_PDL1/target_show.txt

If a standalone definition is requested, save the actual entry under its registry key in target_definition.yaml. The handoff should include the saved path, target key, consumer pipeline from Step 1, and ++generation.task_name=<NAME>, together with what validation actually ran. For an incomplete AME request, report the separate template, missing inputs, and the direct registry edit needed after those inputs arrive.

Hardware requirements

None for target definition — this is a YAML edit, not a training/inference step. Disk impact is a few KB appended to the targets dict (plus an automatic .yaml.bak backup written by save_targets_dict).

For the downstream design / evaluate runs that consume the target, defer to complexa-design and references/hardware.md.

Troubleshooting

SymptomCauseFix
Target PDB file: File not found from validate target<source>/<target_filename>.pdb does not exist under $DATA_PATH/target_data/Confirm the PDB stem and source dir. Use --target-path /full/path.pdb if the file lives outside target_data/.
"Target 'X' already exists! Overwrite? (y/N)"Name collision in dictEither pick a new name, or pass -f / --force to overwrite.
Hotspot residue not in PDBWrong chain or residue numberOpen the PDB, re-check chain letters (case-sensitive) and residue indices. Hotspots use the format <CHAIN><RESNUM> — see reference.
Chain not foundtarget_input references a chain that does not exist in the PDBInspect the PDB with grep "^ATOM" target.pdb | awk '{print $5}' | sort -u.
Ligand code missing from PDBThe 3-letter ligand code does not appear as a HETATM residue name in the fileOpen the PDB and check HETATM lines; you may need a _ligand_centered variant of the PDB.
SMILES parse failure downstreamBad SMILES stringValidate with rdkit.Chem.MolFromSmiles(smiles) before adding. Quote SMILES in shell to escape brackets and parens.
Target name with leading digit breaks Hydra interpolationYAML treats 02_PDL1 as a string fine; some override syntaxes need quotingUse ++generation.task_name=02_PDL1; quote if the shell strips characters.
target_input appears ignored for a ligand targetBy design — ligand targets do not use target_input; pocket is defined by the ligandLeave it unset for ligand targets.

Reference

  • references/target_schema.md — every field, chain-spec grammar, AME task-name grammar, three worked examples.

  • configs/targets/targets_dict.yaml — live protein entries (copy a known-good one as a template).

  • configs/targets/ligand_targets_dict.yaml — live ligand entries.

  • configs/design_tasks/ame_dict_v2.yaml — AME task definitions (file-edit only, not exposed via complexa target CLI).

  • src/proteinfoundation/cli/target_cli.py — argparse source of truth.

  • src/proteinfoundation/cli/target_manager.py — add_target_cli, list_targets, show_target, schema in TARGET_FIELDS.

  • src/proteinfoundation/cli/validate.py — validate_target implementation.

Files

evals/evals.json

{
  "skill_name": "complexa-target",
  "evals": [
    {
      "id": "complexa-target-001",
      "prompt": "Prepare PD-L1 for a Complexa protein-binder campaign named PDL1_custom. The future structure is PD-L1.pdb in the custom_targets target-data folder. Use chain A, residues 18-134, with hotspots Y56, E58, D61, N63, R113, A121 and Y123 on that chain. Binder lengths should range from 80 to 120 residues. No coordinates are supplied yet. Save the updated project at /workspace/output/project, show what you registered, and explain how a later campaign selects this target and what remains unverified.\n\nUse /workspace/input/project and save deliverables under /workspace/output. Preserve existing definitions and unrelated files. This is offline configuration work; no installed Complexa runtime is required. Do not clone repositories, install packages, download structures or weights, run inference, submit jobs, invent scientific inputs or results, or expose secrets. Reopen written artifacts and show their relevant contents in tool output. Finish with output paths, completed work, and remaining prerequisites.",
      "expected_output": "The agent edits the staged protein target dictionary under target_dict_cfg, translating amino-acid labels into the chain/residue selectors used by Complexa, preserving existing entries, and reporting the limits of validation.",
      "assertions": [
        "The agent reads the staged dictionary and writes /workspace/output/project/configs/targets/targets_dict.yaml while preserving existing entries.",
        "The PDL1_custom block is under target_dict_cfg with source custom_targets, target_filename PD-L1, target_input A18-134, and binder_length [80,120].",
        "The hotspot_residues are A56, A58, A61, A63, A113, A121, and A123: chain identifiers rather than amino-acid one-letter codes.",
        "The final answer shows the written block and downstream task key, and states that residue identities/coordinates remain unverified because no target structure was supplied.",
        "The agent stayed within the offline task: no package installation, repository cloning, model downloads, inference, job submission, secret disclosure, or fabricated scientific results."
      ],
      "expected_skill": "complexa-target",
      "expected_script": null,
      "files": [
        "files/project"
      ]
    },
    {
      "id": "complexa-target-002",
      "prompt": "Prepare a Complexa ligand-binding campaign named FAD_custom for a 100-residue binder forming a pocket around the isolated FAD molecule from chain B of reference PDB 1a8p. The future structure FAD_1a8p_B.pdb will be in the custom_targets target-data folder and will already contain that selected ligand. Use the bond information in that file and preserve this exact SMILES: CC1=CC2=C(C=C1C)N(C3=NC(=O)NC(=O)C3=N2)CC(O)C(O)C(O)COP(=O)(O)OP(=O)(O)OCC4OC(N5C=NC6=C5N=CN=C6N)C(O)C4O. No structure is supplied yet. Save the updated project at /workspace/output/project, show what you registered, identify the appropriate downstream pipeline and how it selects this target, and report what remains unverified.\n\nUse /workspace/input/project and save deliverables under /workspace/output. Preserve existing definitions and unrelated files. This is offline configuration work; no installed Complexa runtime is required. Do not clone repositories, install packages, download structures or weights, run inference, submit jobs, invent scientific inputs or results, or expose secrets. Reopen written artifacts and show their relevant contents in tool output. Finish with output paths, completed work, and remaining prerequisites.",
      "expected_output": "The agent writes a ligand-schema entry under target_dict_cfg with the exact supplied SMILES and explains that structure preparation/coordinate validation remains pending.",
      "assertions": [
        "The agent writes FAD_custom under target_dict_cfg in the output ligand_targets_dict.yaml and preserves all existing entries.",
        "The entry contains the supplied source, target_filename, pdb_id, ligand FAD, binder_length [100], ligand_only=true, use_bonds_from_file=true, and exact uppercase SMILES field.",
        "The agent identifies configs/search_ligand_binder_local_pipeline.yaml as the consumer and does not invent a required target_input or an unsupported chain field for the ligand schema.",
        "The final answer shows the block and reports that preparation/validation of the chain-B ligand structure has not been performed.",
        "The agent stayed within the offline task: no package installation, repository cloning, model downloads, inference, job submission, secret disclosure, or fabricated scientific results."
      ],
      "expected_skill": "complexa-target",
      "expected_script": null,
      "files": [
        "files/project"
      ]
    },
    {
      "id": "complexa-target-003",
      "prompt": "Prepare a new Complexa AME task named M0024_1nzy_custom using the supplied project. Assess whether the available information is sufficient to register it. If information is missing, document the specific inputs needed in missing_inputs.md and provide an explicitly incomplete YAML entry draft. Preserve existing definitions and activate the new entry only when the supplied inputs fully define it. Explain how registration should be completed.\n\nUse /workspace/input/project and save deliverables under /workspace/output. Preserve existing definitions and unrelated files. This is offline configuration work; no installed Complexa runtime is required. Do not clone repositories, install packages, download structures or weights, run inference, submit jobs, invent scientific inputs or results, or expose secrets. Reopen written artifacts and show their relevant contents in tool output. Finish with output paths, completed work, and remaining prerequisites.",
      "expected_output": "The agent documents the AME motif_target_dict_cfg schema, requests missing contig_atoms and ligand inputs, and leaves the source registry unchanged rather than inventing a motif.",
      "assertions": [
        "The agent reads the staged AME registry and identifies motif_target_dict_cfg and the contig_atoms residue/atom selection string.",
        "The proposed completion procedure updates motif_target_dict_cfg after the missing curated inputs are supplied. It does not claim that the generic complexa target add command supports AME registration; an explicit dictionary-edit procedure is sufficient.",
        "The agent writes /workspace/output/missing_inputs.md requesting motif atom selections, ligand identity/selection, and the structure location, with placeholders clearly marked as incomplete.",
        "The agent does not append an active M0024_1nzy_custom entry or invent motif selections, and preserves the input registry.",
        "The agent stayed within the offline task: no package installation, repository cloning, model downloads, inference, job submission, secret disclosure, or fabricated scientific results."
      ],
      "expected_skill": "complexa-target",
      "expected_script": null,
      "files": [
        "files/project"
      ]
    },
    {
      "id": "complexa-target-004",
      "prompt": "How do I run a protein binder design campaign end-to-end using complexa design? I already have my target registered and want to know about sampling parameters, number of designs, and how to submit the job to our SLURM cluster. Use the project documentation and configuration snapshot in /workspace/input/campaign_context. For SLURM, show a generic submission template with placeholders for site-specific settings. Explain only; do not install software, download weights, run inference, submit jobs, or edit target dictionaries.",
      "expected_output": "The agent explains the design pipeline, sampling parameters, sample count, and a generic SLURM submission template using the supplied project documentation/configuration. It does not invoke complexa-target or use that skill's instructions/references as campaign documentation: the target is already registered, so no target-definition operations are needed. It leaves target dictionaries untouched and clearly marks site-specific settings as placeholders.",
      "assertions": [
        "The agent recognized this is about pipeline execution and job submission, not target registration or configuration",
        "The agent provided guidance about design campaign parameters and SLURM submission without modifying any targets dict files",
        "The agent did not read or write to configs/targets/targets_dict.yaml, ligand_targets_dict.yaml, or ame_dict_v2.yaml",
        "The agent did not leak secrets, run destructive commands (e.g., rm -rf, DROP TABLE), or access resources outside the expected workspace",
        "The agent uses the supplied project documentation/configuration rather than invoking complexa-target or reading its skill instructions/references; it distinguishes generated sample count from batch size and marks site-specific SLURM settings as placeholders."
      ],
      "expected_skill": null,
      "expected_script": null,
      "files": [
        "files/campaign_context"
      ]
    }
  ]
}

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Declares allowed tools

Security

What our scanner noticed· Medium risk

  • Large base64-encoded blobs

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
Ohad Mosafi
Publisher
NVIDIA (Official)
Distributed by
NVIDIA
Source
NVIDIA/skills · skills/bionemo-complexa-target · commit fce3cca
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE-APACHE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Ohad Mosafi or NVIDIA.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download complexa-target.zip