@intentsolutionsio/crypto-derivatives-tracker 1.0.0

package/skills/skill-adapter/assets/config-template.json

@@ -0,0 +1,32 @@
+{
+  "skill": {
+    "name": "skill-name",
+    "version": "1.0.0",
+    "enabled": true,
+    "settings": {
+      "verbose": false,
+      "autoActivate": true,
+      "toolRestrictions": true
+    }
+  },
+  "triggers": {
+    "keywords": [
+      "example-trigger-1",
+      "example-trigger-2"
+    ],
+    "patterns": []
+  },
+  "tools": {
+    "allowed": [
+      "Read",
+      "Grep",
+      "Bash"
+    ],
+    "restricted": []
+  },
+  "metadata": {
+    "author": "Plugin Author",
+    "category": "general",
+    "tags": []
+  }
+}

package/skills/skill-adapter/assets/skill-schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Claude Skill Configuration",
+  "type": "object",
+  "required": ["name", "description"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z0-9-]+$",
+      "maxLength": 64,
+      "description": "Skill identifier (lowercase, hyphens only)"
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 1024,
+      "description": "What the skill does and when to use it"
+    },
+    "allowed-tools": {
+      "type": "string",
+      "description": "Comma-separated list of allowed tools"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Semantic version (x.y.z)"
+    }
+  }
+}

package/skills/skill-adapter/assets/test-data.json

@@ -0,0 +1,27 @@
+{
+  "testCases": [
+    {
+      "name": "Basic activation test",
+      "input": "trigger phrase example",
+      "expected": {
+        "activated": true,
+        "toolsUsed": ["Read", "Grep"],
+        "success": true
+      }
+    },
+    {
+      "name": "Complex workflow test",
+      "input": "multi-step trigger example",
+      "expected": {
+        "activated": true,
+        "steps": 3,
+        "toolsUsed": ["Read", "Write", "Bash"],
+        "success": true
+      }
+    }
+  ],
+  "fixtures": {
+    "sampleInput": "example data",
+    "expectedOutput": "processed result"
+  }
+}

package/skills/skill-adapter/references/README.md

@@ -0,0 +1,4 @@
+# References
+
+Bundled resources for crypto-derivatives-tracker skill
+

package/skills/skill-adapter/references/best-practices.md

@@ -0,0 +1,69 @@
+# Skill Best Practices
+
+Guidelines for optimal skill usage and development.
+
+## For Users
+
+### Activation Best Practices
+
+1. **Use Clear Trigger Phrases**
+   - Match phrases from skill description
+   - Be specific about intent
+   - Provide necessary context
+
+2. **Provide Sufficient Context**
+   - Include relevant file paths
+   - Specify scope of analysis
+   - Mention any constraints
+
+3. **Understand Tool Permissions**
+   - Check allowed-tools in frontmatter
+   - Know what the skill can/cannot do
+   - Request appropriate actions
+
+### Workflow Optimization
+
+- Start with simple requests
+- Build up to complex workflows
+- Verify each step before proceeding
+- Use skill consistently for related tasks
+
+## For Developers
+
+### Skill Development Guidelines
+
+1. **Clear Descriptions**
+   - Include explicit trigger phrases
+   - Document all capabilities
+   - Specify limitations
+
+2. **Proper Tool Permissions**
+   - Use minimal necessary tools
+   - Document security implications
+   - Test with restricted tools
+
+3. **Comprehensive Documentation**
+   - Provide usage examples
+   - Document common pitfalls
+   - Include troubleshooting guide
+
+### Maintenance
+
+- Keep version updated
+- Test after tool updates
+- Monitor user feedback
+- Iterate on descriptions
+
+## Performance Tips
+
+- Scope skills to specific domains
+- Avoid overlapping trigger phrases
+- Keep descriptions under 1024 chars
+- Test activation reliability
+
+## Security Considerations
+
+- Never include secrets in skill files
+- Validate all inputs
+- Use read-only tools when possible
+- Document security requirements

package/skills/skill-adapter/references/examples.md

@@ -0,0 +1,73 @@
+# Skill Usage Examples
+
+This document provides practical examples of how to use this skill effectively.
+
+## Basic Usage
+
+### Example 1: Simple Activation
+
+**User Request:**
+```
+[Describe trigger phrase here]
+```
+
+**Skill Response:**
+1. Analyzes the request
+2. Performs the required action
+3. Returns results
+
+### Example 2: Complex Workflow
+
+**User Request:**
+```
+[Describe complex scenario]
+```
+
+**Workflow:**
+1. Step 1: Initial analysis
+2. Step 2: Data processing
+3. Step 3: Result generation
+4. Step 4: Validation
+
+## Advanced Patterns
+
+### Pattern 1: Chaining Operations
+
+Combine this skill with other tools:
+```
+Step 1: Use this skill for [purpose]
+Step 2: Chain with [other tool]
+Step 3: Finalize with [action]
+```
+
+### Pattern 2: Error Handling
+
+If issues occur:
+- Check trigger phrase matches
+- Verify context is available
+- Review allowed-tools permissions
+
+## Tips & Best Practices
+
+- ✅ Be specific with trigger phrases
+- ✅ Provide necessary context
+- ✅ Check tool permissions match needs
+- ❌ Avoid vague requests
+- ❌ Don't mix unrelated tasks
+
+## Common Issues
+
+**Issue:** Skill doesn't activate
+**Solution:** Use exact trigger phrases from description
+
+**Issue:** Unexpected results
+**Solution:** Check input format and context
+
+## See Also
+
+- Main SKILL.md for full documentation
+- scripts/ for automation helpers
+- assets/ for configuration examples
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/skill-adapter/scripts/README.md

@@ -0,0 +1,8 @@
+# Scripts
+
+Bundled resources for crypto-derivatives-tracker skill
+
+- [ ] fetch_derivatives_data.py: Script to fetch and parse derivatives data from various exchanges.
+- [ ] analyze_funding_rates.py: Script to analyze funding rates and identify potential trading signals.
+- [ ] calculate_open_interest.py: Script to calculate open interest across different exchanges and contracts.
+- [ ] liquidation_levels.py: Script to determine liquidation levels based on current market conditions.

package/skills/skill-adapter/scripts/helper-template.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+# Helper script template for skill automation
+# Customize this for your skill's specific needs
+
+set -e
+
+function show_usage() {
+    echo "Usage: $0 [options]"
+    echo ""
+    echo "Options:"
+    echo "  -h, --help     Show this help message"
+    echo "  -v, --verbose  Enable verbose output"
+    echo ""
+}
+
+# Parse arguments
+VERBOSE=false
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        -h|--help)
+            show_usage
+            exit 0
+            ;;
+        -v|--verbose)
+            VERBOSE=true
+            shift
+            ;;
+        *)
+            echo "Unknown option: $1"
+            show_usage
+            exit 1
+            ;;
+    esac
+done
+
+# Your skill logic here
+if [ "$VERBOSE" = true ]; then
+    echo "Running skill automation..."
+fi
+
+echo "✅ Complete"

package/skills/skill-adapter/scripts/validation.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# Skill validation helper
+# Validates skill activation and functionality
+
+set -e
+
+echo "🔍 Validating skill..."
+
+# Check if SKILL.md exists
+if [ ! -f "../SKILL.md" ]; then
+    echo "❌ Error: SKILL.md not found"
+    exit 1
+fi
+
+# Validate frontmatter
+if ! grep -q "^---$" "../SKILL.md"; then
+    echo "❌ Error: No frontmatter found"
+    exit 1
+fi
+
+# Check required fields
+if ! grep -q "^name:" "../SKILL.md"; then
+    echo "❌ Error: Missing 'name' field"
+    exit 1
+fi
+
+if ! grep -q "^description:" "../SKILL.md"; then
+    echo "❌ Error: Missing 'description' field"
+    exit 1
+fi
+
+echo "✅ Skill validation passed"

package/skills/tracking-crypto-derivatives/ARD.md

@@ -0,0 +1,376 @@
+# ARD: Crypto Derivatives Tracker
+
+> Part of [Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)
+
+## Architecture Pattern
+
+**Multi-Exchange Aggregation with Real-Time Processing**
+
+This skill aggregates derivatives data from multiple exchanges, normalizes formats, and provides unified analysis across funding rates, open interest, liquidations, and options markets.
+
+---
+
+## Architectural Overview
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                    derivatives_tracker.py (CLI)                     │
+│       funding | oi | liquidations | options | basis commands        │
+└─────────────────────────────────────────────────────────────────────┘
+                                  │
+         ┌────────────────────────┼────────────────────────┐
+         ▼                        ▼                        ▼
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│ FundingTracker  │    │   OIAnalyzer    │    │LiquidationMonitor│
+│ Multi-exchange  │    │ Position data   │    │ Heatmap & alerts │
+│ rate aggregation│    │ trend analysis  │    │ cascade risk     │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+         │                        │                        │
+         └────────────────────────┼────────────────────────┘
+                                  ▼
+                    ┌─────────────────────────┐
+                    │    ExchangeClient       │
+                    │  Unified API interface  │
+                    │  Rate limit handling    │
+                    └─────────────────────────┘
+                                  │
+         ┌────────────────────────┼────────────────────────┐
+         ▼                        ▼                        ▼
+    ┌─────────┐            ┌─────────┐            ┌─────────┐
+    │ Binance │            │  Bybit  │            │ Deribit │
+    │   API   │            │   API   │            │   API   │
+    └─────────┘            └─────────┘            └─────────┘
+```
+
+---
+
+## Workflow
+
+### Step 1: Exchange Client Initialization
+Configure API connections for each supported exchange with rate limiting.
+
+### Step 2: Data Fetching
+Parallel fetch from all exchanges for:
+- Funding rates (perpetuals)
+- Open interest (futures + perps)
+- Recent liquidations
+- Options data (Deribit primarily)
+
+### Step 3: Data Normalization
+Standardize formats across exchanges:
+- Convert funding to 8-hour basis
+- Normalize OI to USD equivalent
+- Unify liquidation formats
+
+### Step 4: Analysis & Aggregation
+- Calculate weighted averages
+- Detect divergences
+- Generate signals
+
+### Step 5: Output
+Present in requested format (console/JSON).
+
+---
+
+## Data Flow
+
+```
+Exchange APIs          Normalization           Analysis              Output
+┌───────────┐         ┌───────────┐         ┌───────────┐         ┌───────┐
+│ Binance   │─────────│ Funding   │─────────│ Rate      │─────────│Console│
+│ funding   │         │ Normalize │         │ Comparison│         │ JSON  │
+└───────────┘         └───────────┘         └───────────┘         └───────┘
+     │                      │                     │
+┌───────────┐         ┌───────────┐         ┌───────────┐
+│ Bybit     │─────────│ OI        │─────────│ Trend     │
+│ OI data   │         │ Normalize │         │ Analysis  │
+└───────────┘         └───────────┘         └───────────┘
+     │                      │                     │
+┌───────────┐         ┌───────────┐         ┌───────────┐
+│ Deribit   │─────────│ Options   │─────────│ Flow      │
+│ options   │         │ Normalize │         │ Analysis  │
+└───────────┘         └───────────┘         └───────────┘
+```
+
+---
+
+## Progressive Disclosure Strategy
+
+### Level 1: Quick Summary
+Single-line current funding rate or OI.
+```
+BTC Funding: +0.015% (Binance) | OI: $18.5B (+2.3% 24h)
+```
+
+### Level 2: Standard Report
+Tabular view across exchanges with key metrics.
+```
+BTC FUNDING RATES
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Exchange    Current    24h Avg    Annualized
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Binance     +0.0150%   +0.0120%   +16.43%
+Bybit       +0.0180%   +0.0140%   +19.71%
+...
+```
+
+### Level 3: Deep Analysis
+Full derivatives dashboard with all metrics, signals, and risk assessment.
+
+---
+
+## Tool Permission Strategy
+
+```yaml
+allowed-tools: Read, Write, Edit, Grep, Glob, Bash(crypto:derivatives-*)
+```
+
+### Tool Justification
+
+| Tool | Usage |
+|------|-------|
+| Read | Load config, API credentials |
+| Write | Save reports, cache data |
+| Edit | Update configuration |
+| Grep | Search historical data |
+| Glob | Find data files |
+| Bash(crypto:derivatives-*) | Execute data fetching scripts |
+
+---
+
+## Directory Structure
+
+```
+skills/tracking-crypto-derivatives/
+├── SKILL.md                     # Core skill instructions
+├── PRD.md                       # Product requirements
+├── ARD.md                       # This file
+├── scripts/
+│   ├── derivatives_tracker.py   # Main CLI entry point
+│   ├── exchange_client.py       # Unified exchange interface
+│   ├── funding_tracker.py       # Funding rate analysis
+│   ├── oi_analyzer.py           # Open interest analysis
+│   ├── liquidation_monitor.py   # Liquidation tracking
+│   ├── options_analyzer.py      # Options market analysis
+│   ├── basis_calculator.py      # Basis/arbitrage calculations
+│   └── formatters.py            # Output formatting
+├── config/
+│   └── settings.yaml            # Exchange configs, thresholds
+└── references/
+    ├── errors.md                # Error handling guide
+    ├── examples.md              # Usage examples
+    └── implementation.md        # Implementation details
+```
+
+---
+
+## API Integration Architecture
+
+### Exchange Client Interface
+
+```python
+class ExchangeClient:
+    """Unified interface for all exchanges."""
+
+    def get_funding_rate(self, symbol: str) -> FundingRate
+    def get_open_interest(self, symbol: str) -> OpenInterest
+    def get_liquidations(self, symbol: str, limit: int) -> List[Liquidation]
+    def get_options_data(self, symbol: str) -> OptionsData
+```
+
+### Supported Exchanges
+
+| Exchange | Funding | OI | Liquidations | Options |
+|----------|---------|-------|--------------|---------|
+| Binance  | ✓ | ✓ | ✓ | ✗ |
+| Bybit    | ✓ | ✓ | ✓ | ✓ |
+| OKX      | ✓ | ✓ | ✓ | ✓ |
+| Deribit  | ✓ | ✓ | ✗ | ✓ (primary) |
+| BitMEX   | ✓ | ✓ | ✓ | ✗ |
+
+### Rate Limiting Strategy
+
+```python
+RATE_LIMITS = {
+    "binance": {"requests_per_minute": 1200, "weight_per_request": 1},
+    "bybit": {"requests_per_minute": 120, "weight_per_request": 1},
+    "okx": {"requests_per_minute": 60, "weight_per_request": 1},
+    "deribit": {"requests_per_day": 10000, "weight_per_request": 1},
+}
+```
+
+---
+
+## Data Models
+
+### FundingRate
+```python
+@dataclass
+class FundingRate:
+    exchange: str
+    symbol: str
+    rate: Decimal           # Current 8-hour rate
+    predicted_rate: Decimal # Next predicted rate
+    next_payment: datetime  # Time until next payment
+    annualized: float       # Annualized yield
+```
+
+### OpenInterest
+```python
+@dataclass
+class OpenInterest:
+    exchange: str
+    symbol: str
+    oi_usd: Decimal         # Total OI in USD
+    oi_contracts: Decimal   # Total contracts
+    change_24h_pct: float   # 24h change
+    change_7d_pct: float    # 7d change
+    long_ratio: float       # Long/short ratio
+```
+
+### Liquidation
+```python
+@dataclass
+class Liquidation:
+    exchange: str
+    symbol: str
+    side: str               # "long" or "short"
+    price: Decimal
+    quantity: Decimal
+    value_usd: Decimal
+    timestamp: datetime
+```
+
+### OptionsSnapshot
+```python
+@dataclass
+class OptionsSnapshot:
+    symbol: str
+    expiry: date
+    atm_iv: float           # At-the-money IV
+    put_call_ratio: float   # By volume
+    put_call_oi: float      # By open interest
+    max_pain: Decimal       # Max pain price
+    total_oi_usd: Decimal
+```
+
+---
+
+## Error Handling Strategy
+
+### Exchange Errors
+
+| Error Type | Handling |
+|------------|----------|
+| API Rate Limit | Exponential backoff, queue requests |
+| API Timeout | Retry with fallback exchange |
+| Invalid Symbol | Skip exchange, continue others |
+| Auth Failed | Log warning, use public endpoints |
+
+### Data Quality
+
+| Issue | Handling |
+|-------|----------|
+| Stale Data | Flag staleness, show warning |
+| Missing Exchange | Exclude from aggregation |
+| Inconsistent Units | Normalize to standard format |
+
+---
+
+## Composability & Stacking
+
+### Works With
+
+| Skill | Integration |
+|-------|-------------|
+| market-price-tracker | Spot price for basis calculations |
+| arbitrage-finder | Cross-exchange funding arbitrage |
+| options-flow-analyzer | Deep options analysis |
+| whale-alert-monitor | Large liquidation correlation |
+
+### Output Formats
+
+- **Console**: Formatted tables and reports
+- **JSON**: Machine-readable for pipelines
+- **CSV**: Export for spreadsheet analysis
+
+---
+
+## Performance & Scalability
+
+### Caching Strategy
+
+```python
+CACHE_TTL = {
+    "funding_rates": 60,      # 1 minute
+    "open_interest": 30,      # 30 seconds
+    "liquidations": 10,       # 10 seconds
+    "options_data": 300,      # 5 minutes
+}
+```
+
+### Parallel Fetching
+
+```python
+async def fetch_all_funding(symbols: List[str]) -> Dict[str, FundingRate]:
+    """Fetch funding from all exchanges in parallel."""
+    tasks = [
+        fetch_funding(exchange, symbol)
+        for exchange in EXCHANGES
+        for symbol in symbols
+    ]
+    return await asyncio.gather(*tasks)
+```
+
+---
+
+## Testing Strategy
+
+### Unit Tests
+- Funding rate calculations
+- OI normalization
+- Liquidation aggregation
+- Basis calculations
+
+### Integration Tests
+- Exchange API connectivity
+- Rate limit handling
+- Error recovery
+
+### Mock Data
+- Simulated exchange responses
+- Historical liquidation data
+- Options chain snapshots
+
+---
+
+## Security & Compliance
+
+### API Key Handling
+- Keys stored in environment variables or config
+- Read-only permissions only (no trading)
+- No key logging in outputs
+
+### Data Privacy
+- No personal data collected
+- No trading history stored
+- Analysis only, no execution
+
+---
+
+## Monitoring & Alerts
+
+### Alert Thresholds (Configurable)
+
+```yaml
+alerts:
+  funding_extreme: 0.1      # 0.1% 8-hour funding
+  oi_change_large: 15       # 15% OI change
+  liquidation_large: 1000000 # $1M liquidation
+  iv_extreme: 100           # 100% IV
+```
+
+### Alert Outputs
+- Console warnings with emoji indicators
+- JSON alerts for webhook integration
+- Summary at end of report