Rare Earth Supply Chain Risk

SKILL.md - Rare-Earth Supply-Chain Risk Registry

Overview

This document defines the rare-earth-supply-chain-risk skill registry, including how skills are registered, resolved, executed, and validated. The skill implements a production-grade harness for Critical-Mineral Supply Chain Risk & Geoeconomics analysis with evidence-backed outputs.

Skill Registry System

Registration

Skills are registered in the /skills directory with the following naming convention:

• Main harness skill: skills/main.md (entry point)
• Sub-skills: skills/sub-{name}.md (specialized components)

Each skill file must include YAML frontmatter:

---
name: {skill-name}
description: {one-line summary of when to trigger and what it does}
version: {x.y.z}
last_updated: YYYY-MM-DD
---

Skill Resolution

Skills are resolved through the following priority order:

1. Explicit invocation: User calls /skill-name or Skill("skill-name")
2. Intent matching: Claude analyzes user query against skill descriptions
3. Chain-of-thought routing: Main harness routes to appropriate sub-skill based on workflow state

The description field is the primary trigger mechanism - include both what the skill does AND specific contexts for when to use it.

Skill Execution Model

graph TD
    A[User Input] --> B{Language Detection}
    B --> C[Step 1: Gather Requirements]
    C --> D{Gate Passed?}
    D -->|Yes| E[Step 2: Evidence Collector]
    D -->|No| F[Graceful Degradation]
    E --> G{Gate Passed?}
    G -->|Yes| H[Step 3: Core Analysis]
    G -->|No| F
    H --> I{Gate Passed?}
    I -->|Yes| J[Step 4: Knowledge Updater]
    I -->|No| F
    J --> K{Gate Passed?}
    K -->|Yes| L[Step 5: Advisor]
    K -->|No| F
    L --> M{Gate Passed?}
    M -->|Yes| N[Quality Gate Review]
    M -->|No| F
    N --> O[Final Output]

Sub-Skill Catalog

| Sub-Skill | Purpose | Trigger | Output | |-----------|---------|---------|--------| | sub-gather-requirements | Clarify analysis object, constraints, timeframe | Start of harness | Structured requirements object | | sub-evidence-collector | Fetch real-time and reference data | After requirements | Evidence bundle with Tier labels | | sub-core-analysis | Quantitative risk assessment | After evidence | Risk scorecard with HHI/CRn/geo/CSR | | sub-knowledge-updater | Query knowledge base | During analysis | Academic citations with gaps | | sub-advisor | Synthesize recommendations | After all analysis | Final verdict with disclosure |

Tool Definitions

Available Tools

| Tool | Purpose | Schema | Usage | |------|---------|--------|-------| | WebSearch | Live domain news, reports | {query: str} | Fetch recent developments | | WebFetch | Scrape authoritative sources | {url: str} | Get specific documents | | Read | Read knowledge base | {file_path: str} | Query SECOND-KNOWLEDGE-BRAIN | | Write | Append knowledge entries | {file_path: str, content: str} | Update knowledge base | | Bash | Execute Python tools | {command: str} | Run risk_engine, etc. | | Skill | Invoke sub-skills | {skill: str, args: str} | Sequential orchestration |

Tool Execution Handlers

Tools are executed through the following handler pattern:

# Handler interface
class ToolHandler:
    def execute(self, tool: str, params: dict) -> Any:
        """Execute tool with error handling and fallbacks."""
        try:
            return self._execute(tool, params)
        except Exception as e:
            return self._handle_error(tool, params, e)

    def _handle_error(self, tool: str, params: dict, error: Exception) -> Any:
        """Implement graceful degradation strategy."""
        # Fallback chain based on error type

Hooks System

Lifecycle Hooks

Hooks are executed at specific points in the harness workflow:

| Hook | Timing | Purpose | Parameters | |------|--------|---------|------------| | before_harness | Before Step 1 | Initialize context | {user_input, language} | | before_step | Before each step | Validate prerequisites | {step_num, step_data} | | after_step | After each step | Validate gate passage | {step_num, output} | | on_gate_failure | When gate fails | Trigger degradation | {gate, failure_reason} | | on_degradation | When degraded mode | Notify user | {degradation_level} | | after_harness | After final output | Cleanup and metrics | {duration, tokens, gates} |

Hook Implementation

Hooks are registered in /scripts/hooks.py with the following interface:

from typing import Callable, Any
from dataclasses import dataclass

@dataclass
class HookContext:
    step: str
    data: dict[str, Any]
    metadata: dict[str, Any]

class HookRegistry:
    def register(self, name: str, hook: Callable[[HookContext], None]) -> None:
        """Register a hook function."""
        self._hooks[name] = hook

    def execute(self, name: str, context: HookContext) -> None:
        """Execute registered hook with error handling."""
        if name in self._hooks:
            try:
                self._hooks[name](context)
            except Exception as e:
                # Log but don't fail harness
                get_logger(__name__).warning(f"Hook {name} failed: {e}")

State Synchronization

State is synchronized between steps through a shared context object:

@dataclass
class HarnessContext:
    requirements: dict[str, Any] | None = None
    evidence: dict[str, Any] | None = None
    analysis: dict[str, Any] | None = None
    knowledge: dict[str, Any] | None = None
    recommendation: dict[str, Any] | None = None
    degradation_level: int = 0
    gates_passed: list[str] = None
    gates_failed: list[str] = None
    language: str = "en"

Input/Output JSON Schemas

Requirements Input Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "object": {
      "type": "string",
      "description": "Primary object of analysis (company, material, country)"
    },
    "scope": {
      "type": "string",
      "enum": ["full", "specific", "comparative"]
    },
    "timeframe": {
      "type": "string",
      "description": "Analysis timeframe (e.g., '2024-2030')"
    },
    "available_inputs": {
      "type": "array",
      "items": {"type": "string"}
    },
    "target_audience": {
      "type": "string",
      "enum": ["practitioner", "researcher", "decision-maker", "learner"]
    },
    "language": {
      "type": "string",
      "enum": ["en", "vi"]
    },
    "analysis_type": {
      "type": "string",
      "enum": ["risk_assessment", "comparison", "methodology", "educational"]
    }
  },
  "required": ["object", "scope"]
}

Analysis Output Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "verdict": {
      "type": "string",
      "enum": ["Resilient Plan", "Conditional (diversify)", "High Supply Risk", "Inconclusive"]
    },
    "composite_supply_risk": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "hhi": {"type": "number"},
    "cr3": {"type": "number"},
    "cr4": {"type": "number"},
    "geopolitical_composite": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "substitutability": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "recycling_potential": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "diversification_benefit": {
      "type": "object",
      "properties": {
        "delta_hhi": {"type": "number"},
        "percent_reduction": {"type": "number"}
      }
    },
    "scenarios": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "probability": {"type": "number"},
          "impact": {"type": "string"},
          "description": {"type": "string"}
        }
      }
    },
    "key_risks": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "risk": {"type": "string"},
          "probability": {"type": "string"},
          "impact": {"type": "string"},
          "mitigation": {"type": "string"}
        }
      }
    },
    "evidence_chain": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "claim": {"type": "string"},
          "source": {"type": "string"},
          "tier": {"type": "string"}
        }
      }
    },
    "disclosure": {"type": "string"},
    "remediation": {
      "type": "array",
      "items": {"type": "string"}
    }
  },
  "required": ["verdict", "disclosure"]
}

Quality Gates

Universal Gates (U1-U6)

| Gate | Criterion | Enforcement | |------|-----------|-------------| | U1 | ≥3 sources cited, ≥1 academic/authoritative | Auto-fix from knowledge base | | U2 | Disclosure before recommendation | Block until present | | U3 | Evidence hierarchy per source | Auto-tag tiers | | U4 | Language matches user | Auto-translate | | U5 | Output uses template | Reformat | | U6 | Claims traceable or flagged | Auto-mark |

Domain Gates (G1-G4)

| Gate | Criterion | Enforcement | |------|-----------|-------------| | G1 | Value chain mapped | Auto-map from analysis | | G2 | Concentration & geopolitical quantified | Calculate with risk_engine | | G3 | Diversification/recycling recommended | Generate options | | G4 | Inventory & ESG safeguards | Add notes |

Validation

All skill outputs must pass the following validation:

1. Schema validation: JSON schemas enforced
2. Gate validation: All U1-U6 and G1-G4 must pass
3. Evidence validation: Minimum source count and tier requirements
4. Format validation: Template sections present and complete

Context Window Management

To optimize token consumption:

1. Layered loading: Skills load in layers (metadata → body → resources)
2. Selective reference loading: Only read relevant reference files
3. Pruned output: Truncate verbose intermediate outputs
4. Caching: Cache repeated calculations (HHI, geopolitical scores)

Error Handling

Error Types and Recovery

| Error Type | Detection | Recovery | Retry Limit | |------------|-----------|----------|------------| | Source timeout | 30s no response | Alternate source | 3 | | Invalid input | Schema validation fail | Request confirmation | 2 | | Missing input | Field absent | Proceed with available | N/A | | Stale data | Timestamp old | Flag and request refresh | 1 | | Knowledge miss | No matches | WebSearch gap-fill | 2 | | Tool failure | Exception raised | Graceful degradation | 2 |

Graceful Degradation Levels

| Level | Condition | Behavior | |-------|-----------|----------| | 0 | All sources available | Full analysis | | 1 | Some sources fail | Use secondary + flag | | 2 | Most sources fail | Knowledge base only | | 3 | Input variables missing | Proceed with available | | 4 | All sources fail | Emit DATA UNAVAILABLE |

Version History

| Version | Date | Changes | |---------|------|---------| | 1.1.0 | 2025-01-06 | Production-grade upgrade, hooks system, SKILL.md registry | | 1.0.0 | 2024-07-13 | Initial production release |

References

• PROJECT-detail.md - Full technical specification
• PROJECT-DEVELOPMENT-PHASE-TRACKING.md - Build roadmap
• skills/main.md - Main harness implementation
• scripts/hooks.py - Hooks implementation
• references/schemas.md - Complete JSON schemas

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dungnotnull
• Source: dungnotnull/rare-earth-supply-chain-risk-agent-skill
• License: MIT

Install and usage instructions live in the source repository linked above.