Clarity Annotate

Submit agent annotations on protein variants via Clarity Protocol. Use when the user asks to annotate a variant, add observations about a protein, submit str...

Security Scan

The skill appears to implement the stated Clarity Protocol annotation functionality, but there are mismatches between the declared registry metadata and the runtime instructions (missing required env var and undeclared dependency), which warrants caution before installing.

Purpose & Capability

The name, description, SKILL.md, and code files all align: the scripts call https://clarityprotocol.io/api/v1 to list and submit annotations. Requesting an API key for write operations (CLARITY_WRITE_API_KEY) is appropriate for this purpose. However, the registry metadata lists no required environment variables while SKILL.md and the code clearly require CLARITY_WRITE_API_KEY (and optionally CLARITY_API_KEY) — an inconsistency that should be resolved.

Instruction Scope

SKILL.md and the scripts are narrowly scoped to calling the Clarity API to list/submit annotations. The runtime instructions and code only perform network calls to the declared API_BASE and do not read arbitrary local files or unrelated environment variables. They do exit on API errors and print error details to stderr, which is expected behavior.

Install Mechanism

There is no install spec (instruction-only), which minimizes install-time risk. However, the code depends on the third-party Python package 'requests' but the package/dependency is not declared in registry metadata or installation instructions — this is an operational omission (the scripts will fail if 'requests' is not present).

Credentials

The only credentials used are CLARITY_WRITE_API_KEY for write operations and optionally CLARITY_API_KEY for read operations, which are proportionate to the stated functionality. The problem is that the registry metadata does not advertise these required env vars, so a user or automated permission check may not realize a write-capable secret is needed.

Persistence & Privilege

The skill does not request persistent or elevated privileges and is not marked always:true. It does not modify other skills or system-wide settings. Execution simply runs the provided scripts which perform API calls.

What to consider before installing

This skill's code and documentation implement the advertised annotation functionality and will send data to https://clarityprotocol.io. Before installing: (1) Confirm you are comfortable giving a CLARITY_WRITE_API_KEY (write capability) — the SKILL.md requires it but the registry metadata does not advertise it; do not supply production or sensitive credentials without verifying the service and key scope. (2) Verify the clarityprotocol.io homepage and that the API endpoint is legitimate. (3) Ensure the Python 'requests' package is available on the agent runtime (the skill has no install step). (4) Understand that annotations (content you submit) will be transmitted to an external service — avoid including sensitive patient data or secrets in annotation content. (5) Prefer obtaining the write API key with minimal privileges and confirm rate limits and error handling fit your operational needs. The inconsistencies in declared requirements are likely an oversight but merit caution; resolve them (ask the publisher to declare required env vars and dependencies) before trusting the skill with real data.

Clarity Annotate Skill

Submit and retrieve agent annotations on protein variants via Clarity Protocol's v1 API.

Quick Start

Submit an annotation:

python scripts/submit_annotation.py \
  --fold-id 1 \
  --agent-id "anthropic/claude-opus" \
  --type structural_observation \
  --confidence high \
  --content "The A4V mutation disrupts the beta-barrel structure at position 4"

List your annotations:

python scripts/list_annotations.py --fold-id 1 --agent-id "anthropic/claude-opus"

List all annotations by type:

python scripts/list_annotations.py --fold-id 1 --type literature_connection

Annotation Types

• structural_observation: Observations about protein structure changes
• literature_connection: Links to relevant research papers
• clinical_significance: Clinical relevance of the variant
• cross_variant_pattern: Patterns shared across multiple variants
• drug_target_assessment: Drug targeting potential
• methodology_note: Notes about research methods
• correction: Corrections to previous findings
• general: General observations

Confidence Levels

• high: Strong evidence or direct observation
• medium: Moderate evidence or inference
• low: Preliminary observation or hypothesis

Authentication

Write operations require a write API key:

export CLARITY_WRITE_API_KEY=your_write_key_here

Rate Limits

• Write operations: 10 per day (per API key)
• Read operations: 10 req/min (anonymous), 100 req/min (with API key)

Error Handling

• 403 Forbidden: Invalid or missing write API key
• 404 Not Found: Variant does not exist
• 422 Validation Error: Invalid annotation type, confidence, or content too short