How to use the Folklore Variant Evidence agent skill

What an agent skill is and what this one makes the agent do

An agent skill is a folder containing a SKILL.md file with instructions, plus optional reference files. When the skill is installed, the agent reads its description and uses the instructions when a request matches.

This skill connects the agent to a hosted public clinical-genetics service. For one GRCh38 germline nuclear single-nucleotide variant (SNV) or simple insertion/deletion shorter than 50 base pairs, the agent can return whether the variant was resolved, ambiguous, or not found, along with source-linked public literature. For a gene or disease, it can return ClinGen gene-disease validity assertions.

• Variant lookup: one public identifier such as genomic coordinates, HGVS, SPDI, an rsID, or a canonical_key returned by Folklore.
• Gene-disease lookup: one exact gene symbol or HGNC identifier, or an exact MONDO identifier or disease-name substring.
• Literature: variant-linked publications and publication details from the same service.
• Provenance: ClinGen results include source version and snapshot hash fields where returned.

Install the skill from the ZIP file

Download the skill ZIP from the skill page on this site and unzip it. The folder should contain SKILL.md and a references folder with mcp-contract.md.

For a personal install, place the folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder. Start a new agent session afterwards so the skill is picked up.

If you use the Claude apps instead of a folder, upload the skill under Settings → Capabilities → Skills.

Check the connection before relying on results

The skill needs network access to api.helena.bio. No account or API key is required. If your host supports MCP, it can connect to the endpoint directly. Otherwise the skill describes a curl request that sends a JSON-RPC POST to the same endpoint.

The example below asks for rs80357914 on GRCh38. A successful HTTP response is not enough. The skill says to check the JSON-RPC error first, then the adapter error, then the result status.

Trigger the skill with natural requests

You do not need special syntax. Name the variant or gene and ask for sourced public evidence. Include the GRCh38 assembly when you can, since the skill requires it. Keep requests to public identifiers only.

The skill is meant for requests that need a structured answer, such as a status you can branch on, ClinGen assertions, or publications linked to a resolved variant.

• Look up GRCh38 variant rs80357914 and tell me whether it resolves to one variant with public evidence.
• What ClinGen gene-disease validity assertions exist for BRCA1? Include source versions.
• Find publications linked to this resolved variant, then give me the publication details for the most relevant one.
• Check whether MONDO disease term X has any gene assertions in ClinGen, and list the pagination warnings if there are more pages.

Read the outcome before acting on it

The skill treats the variant status as a control value. Each outcome has a required action. A resolved variant returns a canonical_key that can be reused. An ambiguous result lists candidates, and the agent must ask you to pick one rather than choosing automatically.

Other outcomes described by the skill include not found, invalid, unsupported, and unavailable. An unavailable result, including a resolution failure, is a service problem. It is not evidence that the variant lacks evidence.

A not_found result means no matching assertion or record was found in the available source. It does not mean no association exists.

• resolved: reuse the canonical_key and review the interpretation, provenance, source links and limitations.
• ambiguous: show candidates and request an explicit public variant selection.
• not_found: report that the bounded source had no match; do not treat it as a negative finding.
• unavailable or failed calls: report the availability problem and retry later if appropriate.

Requirements, safety and what the skill refuses

The skill needs network access to api.helena.bio and an MCP-capable host, or curl. It does not run scripts, and it uses the network. Its public contract is published under the MIT licence for the skill itself.

The skill refuses patient-specific input. It will not accept phenotypes, family history, segregation evidence, clinical records, uploaded files, or case identifiers, and it will not present a public variant lookup as an answer to a patient question.

The output is decision support for professional review only. It does not replace direct database checks or qualified clinical judgment.

• Do not paste patient names, case IDs, symptoms, family history or sequencing files into requests.
• Batch annotation of VCF files, somatic variants, structural variants and polygenic scores are out of scope.
• ClinGen data is a bounded local snapshot, not the latest ClinGen release.

Tips for better results

Give the agent a single variant per request. Multiple variants in one message make it harder to get a clean status and may produce an ambiguity prompt.

If you need a different kind of check, such as broad lookups across several databases or a check of genomic coordinates, ask for those tasks separately. The skill itself names other skills for those jobs.

• Confirm the assembly is GRCh38 before you start; the skill does not accept other assemblies.
• When a gene query returns more pages, ask the agent to follow pagination until it stops.
• Keep the source version and snapshot hash in any notes you export, so the evidence can be traced later.