Skill: clarityprotocol/clarity-fold-status (version 1.0.0)

--- name: clarity-fold-status description: > Get overview and status information from Clarity Protocol. Use when the user asks about fold status, how many variants, research overview, what data is available, or Clarity Protocol status. Capabilities: API info, variant counts, endpoint availability. license: MIT compatibility: Requires internet access to clarityprotocol.io. Optional CLARITY_API_KEY env var for 100 req/min (vs 10 req/min). metadata: author: clarity-protocol version: "1.0.0" homepage: https://clarityprotocol.io --- # Clarity Fold Status Skill Get overview and status information about Clarity Protocol's protein folding research database, including API capabilities, available endpoints, and data statistics. ## Quick Start Get full status report: ```bash python scripts/check_status.py ``` Get status in JSON format: ```bash python scripts/check_status.py --format json ``` ## Status Information The status check provides: - **API version**: Current API version - **API description**: What the API provides - **Total variants**: Count of protein variants in database - **Available endpoints**: List of all API endpoints - **Rate limits**: Anonymous and authenticated limits - **Data freshness**: When data was last updated ## API Endpoints The Clarity Protocol API v1 provides these endpoints: - `GET /api/v1/`: API information - `GET /api/v1/variants`: List all variants (with filters) - `GET /api/v1/variants/{fold_id}`: Get variant details - `GET /api/v1/variants/{fold_id}/findings`: Get agent findings - `GET /api/v1/literature`: List research papers - `GET /api/v1/literature/{pmid}`: Get paper details - `GET /api/v1/clinical`: List clinical variants - `GET /api/v1/clinical/{gene}/{variant}`: Get clinical variant details ## Rate Limits - **Anonymous (no API key)**: 10 requests/minute - **With API key**: 100 requests/minute To use an API key, set the `CLARITY_API_KEY` environment variable: ```bash export CLARITY_API_KEY=your_key_here python scripts/check_status.py ``` Get your API key at https://clarityprotocol.io ## Error Handling **429 Rate Limit**: You've exceeded the rate limit. The script will display how long to wait. **500 Server Error**: The API server encountered an error. Try again later. **Timeout**: The request took longer than 30 seconds. ## Use Cases - Check if the API is available - Get an overview of available data - Verify endpoint URLs before making requests - Monitor rate limit status - Understand API capabilities for integration planning

path: scripts/api_client.py
content: #!/usr/bin/env python3
"""
Shared API client for Clarity Protocol skills.

Provides:
- API_BASE: Base URL for Clarity Protocol API
- get_headers(): Get HTTP headers including optional API key from env var
- api_get(): Perform GET request with error handling and rate limit management
"""

import os
import sys
import requests
from typing import Optional, Dict, Any


API_BASE = "https://clarityprotocol.io/api/v1"


def get_headers() -> Dict[str, str]:
    """
    Get HTTP headers for API requests.

    Reads CLARITY_API_KEY from environment variable if present.

    Returns:
        Dict with Accept header and optional X-API-Key header
    """
    headers = {
        "Accept": "application/json"
    }

    [REDACTED_SECRET]"CLARITY_API_KEY")
    if [REDACTED_SECRET]"X-API-Key"] = api_key

    return headers


def api_get(endpoint: str, params: Optional[Dict[str, Any]] = None) -> Any:
    """
    Perform GET request to Clarity Protocol API with error handling.

    Args:
        endpoint: API endpoint (e.g., "/variants" or "/variants/123")
        params: Optional query parameters

    Returns:
        Parsed JSON response

    Raises:
        SystemExit: On error (prints user-friendly message and exits)
    """
    url = API_BASE + endpoint

    try:
        response = requests.get(
            url,
            params=params,
            headers=get_headers(),
            timeout=30
        )

        # Handle rate limiting
        if response.status_code == 429:
            retry_after = response.headers.get("Retry-After", "unknown")
            print(f"Error: Rate limit exceeded.", file=sys.stderr)
            print(f"Retry after: {retry_after} seconds", file=sys.stderr)
            print(f"\nTip: Set CLARITY_API_KEY environment variable for higher rate limits.", file=sys.stderr)
            print(f"  Anonymous: 10 requests/minute", file=sys.stderr)
            print(f"  With API key: 100 requests/minute", file=sys.stderr)
            print(f"\nGet your API key at: https://clarityprotocol.io", file=sys.stderr)
            sys.exit(1)

        # Handle not found
        if response.status_code == 404:
            print(f"Error: Resource not found: {endpoint}", file=sys.stderr)
            print(f"The requested resource does not exist.", file=sys.stderr)
            sys.exit(1)

        # Handle other errors
        response.raise_for_status()

        return response.json()

    except requests.exceptions.Timeout:
        print(f"Error: Request timed out after 30 seconds.", file=sys.stderr)
        print(f"The API server may be unavailable or under heavy load.", file=sys.stderr)
        sys.exit(1)

    except requests.exceptions.RequestException as e:
        print(f"Error: API request failed: {e}", file=sys.stderr)
        sys.exit(1)

    except ValueError as e:
        print(f"Error: Failed to parse API response as JSON: {e}", file=sys.stderr)
        sys.exit(1)


path: scripts/check_status.py
content: #!/usr/bin/env python3
"""
Check status and overview of Clarity Protocol API.

Usage:
  python check_status.py                 # Human-readable status report
  python check_status.py --format json   # JSON format
"""

import argparse
import json
from api_client import api_get


def main():
    parser = argparse.ArgumentParser(
        description="Check Clarity Protocol API status and overview"
    )
    parser.add_argument(
        "--format",
        choices=["json", "summary"],
        default="summary",
        help="Output format (default: summary)"
    )

    args = parser.parse_args()

    # Get API info
    api_info = api_get("/")

    # Get variant count
    variants = api_get("/variants")
    variant_count = len(variants.get("items", []))

    # Output results
    if args.format == "json":
        combined = {
            "api_info": api_info,
            "variant_count": variant_count
        }
        print(json.dumps(combined, indent=2))
    else:
        # Summary format
        print("Clarity Protocol Status Report")
        print("=" * 60)
        print(f"API: {api_info.get('name', 'Unknown')} v{api_info.get('version', 'Unknown')}")
        print(f"Description: {api_info.get('description', 'N/A')}")
        print()

        print(f"Total Variants Tracked: {variant_count}")
        print()

        print("Available Endpoints:")
        print("-" * 60)
        endpoints = api_info.get("endpoints", [])
        for endpoint in endpoints:
            print(f"  {endpoint}")
        print()

        print("Rate Limits:")
        print("-" * 60)
        rate_limits = api_info.get("rate_limits", {})
        anonymous = rate_limits.get("anonymous", "Unknown")
        authenticated = rate_limits.get("authenticated", "Unknown")
        print(f"  Anonymous: {anonymous}")
        print(f"  With API key: {authenticated}")
        print()

        print("Get your API key at: https://clarityprotocol.io")


if __name__ == "__main__":
    main()


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)