{"id":26682,"plugin_id":"plugin_asdk_app_6abdcb3d2970819186a0c7a25c953c4b","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-10-05T18:29:27.544Z","digest":"010653b0806743f70cbe4f9b3b9e74013ad96be8cd86e320b6bb6934c215a1af","against":null,"payload":{"description":"Use when the user wants proteins similar to a protein, a protein name or accession resolved to a sequence, an Atlas record, SAE feature profile, or cluster context for a sequence, one Atlas SAE feature explained, or a protein structure viewed, all through the public Biohub MCP. Also use for the full Atlas feature catalog, thumbnails, batch jobs, MD5-only records, or anonymous S3 data, which stay on the plugin script. Use ESMC instead to extract SAE activations with a chosen ESMC checkpoint. Atlas is public data, not a model to deploy, and needs no client key.","included_files":[{"relative_path":"LICENSE.md","size_in_bytes":1093},{"relative_path":"agents/openai.yaml","size_in_bytes":431},{"relative_path":"references/api.md","size_in_bytes":7438},{"relative_path":"references/bulk-data.md","size_in_bytes":4336},{"relative_path":"references/mcp-tools.md","size_in_bytes":5960}],"name":"esm-atlas","skill_md_contents":"---\nname: esm-atlas\ndescription: Use when the user wants proteins similar to a protein, a protein name or accession resolved to a sequence, an Atlas record, SAE feature profile, or cluster context for a sequence, one Atlas SAE feature explained, or a protein structure viewed, all through the public Biohub MCP. Also use for the full Atlas feature catalog, thumbnails, batch jobs, MD5-only records, or anonymous S3 data, which stay on the plugin script. Use ESMC instead to extract SAE activations with a chosen ESMC checkpoint. Atlas is public data, not a model to deploy, and needs no client key.\nlicense: MIT\n---\n\n# ESM Atlas\n\nThe user's instructions take precedence over guidelines provided in a skill.\nIf explicit user instructions conflict with a skill's instructions, prioritize the user's instructions.\n\nAtlas is public data and discovery infrastructure, not a model to run on Modal or Hugging Face.\nAnswer Atlas questions through the public Biohub MCP, which is anonymous and needs no client key, and never through the plugin script, `curl`, or another HTTP client.\nThe plugin script remains only for the work the MCP does not cover: the full feature catalog, thumbnails, batch jobs, MD5-only records, and anonymous S3 data.\nEvery reply, including a clarifying question, states limits and choices as facts about the Atlas and never mentions, quotes, or links this skill, its rules, or its file.\n\n## Tools\n\nResolve these logical tool names in the connected catalog.\nA host may show a server prefix around a name, so match the logical name and never hard-code a prefix.\n\n| Need | Tool |\n| --- | --- |\n| Protein name or UniProt accession to sequence | `esm_atlas_search_uniprot` |\n| UniParc, MGnify, or IMG accession to sequence | `esm_atlas_lookup_accession` |\n| Similar proteins | `esm_atlas_search_similar_protein_clusters` |\n| Atlas record and top SAE features | `esm_atlas_get_protein_details` |\n| Cluster context for a sequence | `esm_atlas_get_cluster_info` |\n| One SAE feature | `esm_atlas_get_sae_feature_detail` |\n| Structure view | `ui_show_protein_structure` |\n\nIf these tools are not in the catalog, say the Biohub MCP is not connected and point to `$biohub-esm-setup`.\nRead [the MCP tool reference](references/mcp-tools.md) for arguments, returned fields, and error codes.\n\n## Resolve the input\n\n- Raw sequence or FASTA: drop the header and whitespace, keep every residue letter, and pass it on unchanged.\n- UniProt accession, such as `P69905`: call `esm_atlas_search_uniprot` once with the accession as `query` and `size=1`, and accept only a record whose accession matches exactly.\n- Protein name, such as `hemoglobin`: call `esm_atlas_search_uniprot` once with the name verbatim as `query` and `size=6`; never rewrite it, field it, or guess an accession first.\n  When several candidates return, list their accessions, protein names, and organisms, and ask the user to choose without recommending one, even one you already mentioned.\n- UniParc, MGnify, or IMG accession: call `esm_atlas_lookup_accession`, which does not accept UniProt accessions.\n- A 32-character MD5 protein hash with no sequence: the MCP is keyed by sequence, so read the stored record with the script's `atlas protein --protein-hash` command and continue with its returned sequence.\n- Starter launcher `Find proteins similar to GB1.`: resolve the pinned fixture in `../../examples/starter-examples.json`; never ask the user to paste the bundled sequence.\n\nFunction text returned while resolving an input describes the input, not the Atlas result, so never present it as Atlas evidence.\n\n## Length limits\n\nNever clip, truncate, or window a sequence yourself.\n\n- Similarity search and SAE features take at most 2,048 residues.\n  For a longer sequence, do not call the search; name the limit and the sequence length, and ask the user for a domain or residue range.\n  A `sequence_too_long_for_features` error from `esm_atlas_get_protein_details` gets the same answer.\n- `ui_show_protein_structure` returns stored Atlas coordinates at any supported length, and folds a miss only up to 700 residues.\n  On `sequence_too_long_to_fold`, explain the 700-residue fold limit with the returned `actual_length`, and ask for a domain of at most 700 residues without retrying.\n\n## Find similar proteins\n\nFor `Find proteins similar to GB1.`, or any similar-protein request:\n\n1. Call `esm_atlas_search_similar_protein_clusters` exactly once with the resolved sequence, `top_k=10`, and `uncharacterized_only=false`, unless the user asked only for uncharacterized clusters.\n2. Report up to ten hits in the returned order with accession, protein name, length, similarity score, and cluster size, and never manufacture missing hits.\n3. For a non-empty result, call `ui_show_protein_structure` once with the top-ranked hit's returned `sequence`.\n4. Make zero script calls, and make no cluster, protein-detail, or feature-detail follow-up calls unless the user asks what the neighbors are or do.\n\nRead hits correctly:\n\n- `similarity_score` is cosine similarity between sparse-autoencoder (SAE) feature vectors, not sequence identity, alignment, or homology.\n- The search runs over cluster representatives only, so a missing relative can reflect index coverage rather than absence.\n- A short or empty hit list means nothing cleared the service's unreported similarity floor, never that nothing exists.\n- A nonzero `restricted_count` means results were withheld; say so without guessing what they held.\n- `top_features_across_results` lists SAE features shared across hits; report counts as `occurrence_count` out of the returned hit count.\n- A hit that scores far above the rest, is very short yet scores high, or has a `cluster_size` of one may be lab contamination such as an expression construct; flag it rather than feature it.\n\nWhen the user asks what a protein does or which neighbors are informative, call `esm_atlas_get_cluster_info` for every hit, in parallel where the host allows, with each hit's returned `sequence`.\nRank neighbors by `cluster_pct_characterized`, then by how specific `top_pfam_domains` is, then by `cluster_size`, and never by similarity score alone.\nEvery cluster field describes the neighbor's cluster, never the query, and characterized means Pfam-annotated, not experimentally studied.\n\n## Read a protein's record and features\n\nCall `esm_atlas_get_protein_details` once with the exact sequence.\nReport `sae_features` in returned order, copying each `label` verbatim.\nReport `value` with its `label_reliability` band as signal strength only; the band is never a judgement of the label's quality.\nReport `residue_regions` positions as returned, and never compare their raw `mean_activation` with the normalized `value`.\nWhen `features_computed_on_miss` is true, say the sequence is not in the Atlas and its features were computed on demand; infer nothing more.\nFor a feature-profile request, call `esm_atlas_get_sae_feature_detail` once for each of the three features with the highest `value`, breaking ties by lowest `feature_index`, and use its `label`, `summary`, and `description` as the only biological wording; skip it for a plain record lookup.\n\nAtlas features come from the fixed 16,384-feature dictionary of `esmc-6b-2024-12-sae-layer60-k64-codebook16384`.\nNever apply them to another checkpoint, model, layer, or codebook; extract activations for a different SAE with `$esmc`.\n\n## Show a structure\n\nCall `ui_show_protein_structure` once with the exact sequence; pass `view_options` only when the user asks for a representation, confidence coloring, or highlighted residues.\nHighlight a residue on chain `A` by its one-based position in that sequence, and set `expected_residue` to its three-letter code.\nIn a host that renders MCP Apps, the result opens the interactive Mol* viewer (`ui://biohub-public/structure-viewer/v1`).\nEvery host also receives a PNG preview and a text descriptor; describe what the preview shows in words, and never say a structure is shown above, write viewer code, draw your own image of the structure, or hand the result to a different viewer.\nIf `preview_status` is not `available`, say visual inspection is unresolved.\nAtlas coordinates and on-demand folds are model hypotheses, not experimental structures.\nWhen the user asks for an experimental method, resolution, or citation, say the Atlas does not provide one.\nThe other Biohub ESM skills use this same tool, as [Show a protein with the Biohub MCP](../../references/structure-viewer-handoff.md#show-a-protein-with-the-biohub-mcp) describes.\n\n## Write the answer\n\nReport only what the tools returned; never add proteins, structures, PDB entries, or literature from memory.\nMCP answers write no files.\nEnd every MCP answer with one source line naming each tool called, the Atlas version, and the license, for example:\n\n`Source: Biohub MCP esm_atlas_search_similar_protein_clusters, ui_show_protein_structure; ESM Atlas v1 through the v1alpha1 API; CC-BY-4.0.`\n\nFollow it with one link to <https://biohub.ai/esm/protein/atlas>.\n\n## When a tool fails\n\nBranch on the returned `code`, not on the message text.\n`rate_limited` means wait as the error advises before one retry.\n`indeterminate` means the compute outcome is unknown, so never retry it automatically.\n`invalid_input`, `not_found`, `restricted`, `dependency_unavailable`, `resource_too_large`, and `internal_error` on the search or input resolution stop the answer without a biological conclusion.\nA call the host blocks, for example by denying approval, is a failure too.\nName the failed tool and code, never retry with different arguments or switch to the script, and never fill the gap with results from memory, literature, or your own sequence comparison.\n\n## Script route\n\nThe script needs no client key and writes `raw-response.json`, `result.json`, and `provenance.json` with each result.\n\n```bash\n# Full 16,384-feature catalog\npython3 <plugin-root>/scripts/biohub_esm.py atlas features \\\n  --output-dir /absolute/path/features\n\n# Stored record for an MD5 protein hash with no known sequence\npython3 <plugin-root>/scripts/biohub_esm.py atlas protein \\\n  --protein-hash <md5> --output-dir /absolute/path/protein\n\n# pLDDT or pct-characterized thumbnail for an MD5 protein hash\npython3 <plugin-root>/scripts/biohub_esm.py atlas thumbnail \\\n  --protein-hash <md5> --thumbnail-type plddt \\\n  --output /absolute/path/thumbnail.png\n\n# Batch of up to 500 unique MD5 hashes, with atomic resumable state\npython3 <plugin-root>/scripts/biohub_esm.py atlas batch-submit \\\n  --hashes /absolute/path/hashes.json \\\n  --state /absolute/path/batch-state.json \\\n  --output /absolute/path/batch.zip\npython3 <plugin-root>/scripts/biohub_esm.py atlas batch-status \\\n  --state /absolute/path/batch-state.json\npython3 <plugin-root>/scripts/biohub_esm.py atlas batch-wait \\\n  --state /absolute/path/batch-state.json \\\n  --output /absolute/path/batch.zip\npython3 <plugin-root>/scripts/biohub_esm.py atlas batch-cancel \\\n  --state /absolute/path/batch-state.json\n```\n\nNever pass `--fold-on-miss` to `atlas protein`; structures go through `ui_show_protein_structure`.\nSmall batches may return a zip immediately, and larger batches return resumable job state.\nAn interrupted submit without a durably captured `job_id` becomes `submission-indeterminate`: preserve it, reconcile manually with Atlas operators, and never resume or resubmit that state.\nA definitive `400`, `401`, `402`, `403`, `404`, `422`, or `429` becomes `submission-rejected`, and only a new `batch-submit` for the exact same request may retry, never before the persisted `Retry-After` deadline.\nTo adopt an older job once, pass both `--state <new-path>` and `--job-id <id>`.\nCancellation is idempotent, and completed results can remain available.\n\nRead the [script-route HTTP contract](references/api.md), the shared [safety and provenance contract](../../references/safety-and-provenance.md), and the [batch and S3 guidance](references/bulk-data.md), whose confirmation rules apply before any multi-gigabyte or multi-terabyte S3 transfer.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}