Clarity Analyze

Submit research questions for AI-powered analysis via Clarity Protocol. Use when the user asks to analyze a protein variant, ask a research question, get AI...

Security Scan

The skill appears to implement a coherent Clarity Protocol client for submitting research questions, but the package metadata omits the required API credential and there are small inconsistencies that should be clarified before installing.

Purpose & Capability

The skill's name, description, SKILL.md, and code all align: they contact clarityprotocol.io to submit research questions and return AI-grounded answers. Requesting a write API key (CLARITY_WRITE_API_KEY) is reasonable for submitting analysis jobs. However, the registry metadata claims no required environment variables or primary credential, which contradicts the SKILL.md and api_client.py that require CLARITY_WRITE_API_KEY for POST operations (and optionally CLARITY_API_KEY for GET). This metadata omission is an incoherence.

Instruction Scope

Runtime instructions and included scripts only build and send an /analysis POST with question text, optional variant_id, focus, and context. They do not instruct the agent to read arbitrary local files, other credentials, or send data to unexpected endpoints. The declared external endpoint (https://clarityprotocol.io/api/v1) matches the SKILL.md.

Install Mechanism

This is an instruction-only skill with small Python scripts included. There is no install spec, no downloads from third-party URLs, and no archive extraction — low install risk.

Credentials

The code and SKILL.md require CLARITY_WRITE_API_KEY for write operations (and support CLARITY_API_KEY for read). Those credentials are proportional to the stated purpose. The concern is that the registry metadata lists 'Required env vars: none' and 'Primary credential: none', which is inconsistent and may lead users to install without providing the required key or without realizing the skill will require/consume a write-capable API key.

Persistence & Privilege

The skill is not always-enabled and does not request system-level persistence. It does not modify other skills or system configurations. Autonomous invocation is enabled by default (normal), but there are no additional privilege escalations requested.

What to consider before installing

This skill generally does what it says — it posts research questions to clarityprotocol.io and returns AI-backed analyses. Before installing: 1) Verify the service (https://clarityprotocol.io) and confirm you trust where your questions and variant identifiers will be sent. 2) The package metadata omits required env vars, but the scripts require CLARITY_WRITE_API_KEY (and optionally CLARITY_API_KEY). Don’t supply high-privilege credentials (e.g., reuse of cloud provider keys); create a scoped, revocable API key for this service. 3) Avoid sending private or sensitive patient data to the external API. 4) Ask the publisher to correct the registry metadata to declare required environment variables and the primary credential so the permission model is clear. If the publisher cannot justify the missing metadata, treat the omission as a red flag and consider not installing.

Clarity Analyze Skill

Submit research questions to Clarity Protocol's AI analysis engine. Questions are answered using data from 7 aggregated sources: fold data, ClinVar, gnomAD, PubMed literature, Open Targets, agent findings, and agent annotations.

Quick Start

Ask a research question:

python scripts/ask_question.py --question "What is the clinical significance of SOD1 A4V?"

Ask about a specific variant:

python scripts/ask_question.py \
  --question "How does this mutation affect protein stability?" \
  --variant-id 1 \
  --focus clinical literature

Get plain text answer (no JSON wrapper):

python scripts/ask_question.py \
  --question "What is the clinical significance of SOD1 A4V?" \
  --format text

Data Sources

The analysis engine draws from:

1. Fold data — AlphaFold structure predictions, confidence scores
2. Clinical data — ClinVar pathogenicity, gnomAD allele frequency
3. Literature — PubMed papers and citations
4. Structural analysis — AlphaFold structural predictions
5. Open Targets — Disease-gene associations
6. Agent findings — Research agent discoveries
7. Agent annotations — Community observations

Focus Options

Prioritize specific data sources in the analysis:

• clinical — ClinVar, gnomAD data
• literature — PubMed papers
• structural — AlphaFold predictions
• functional — Open Targets, agent findings

Authentication

export CLARITY_WRITE_API_KEY=your_write_key_here

Rate Limits

• Analysis requests: 10 per day (per API key)
• Identical questions return cached responses (7-day TTL)

Error Handling

• 403 Forbidden: Invalid or missing write API key
• 404 Not Found: Specified variant does not exist
• 422 Validation Error: Question is off-topic (must be about protein research)