# Rare Earth Supply Chain Risk

> Rare-Earth Supply-Chain Risk Assessment & Management - Critical-Mineral Supply Chain Risk & Geoeconomics evidence-backed analysis harness. Use this skill when the user needs supply-chain risk analysis, geopolitical assessment, concentration metrics, diversification strategies, substitution analysis, recycling potential, or critical-minerals research. Trigger for queries about rare earth elements…

- **Type:** Skill
- **Install:** `agentstack add skill-dungnotnull-rare-earth-supply-chain-risk-agent-skill-rare-earth-supply-chain-risk-agent-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [dungnotnull](https://agentstack.voostack.com/s/dungnotnull)
- **Installs:** 0
- **Category:** [Data & Analytics](https://agentstack.voostack.com/c/data-and-analytics)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [dungnotnull](https://github.com/dungnotnull)
- **Source:** https://github.com/dungnotnull/rare-earth-supply-chain-risk-agent-skill

## Install

```sh
agentstack add skill-dungnotnull-rare-earth-supply-chain-risk-agent-skill-rare-earth-supply-chain-risk-agent-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

```yaml
---
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

```mermaid
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:

```python
# 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:

```python
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:

```python
@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

```json
{
  "$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

```json
{
  "$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](https://github.com/dungnotnull)
- **Source:** [dungnotnull/rare-earth-supply-chain-risk-agent-skill](https://github.com/dungnotnull/rare-earth-supply-chain-risk-agent-skill)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-dungnotnull-rare-earth-supply-chain-risk-agent-skill-rare-earth-supply-chain-risk-agent-skill
- Seller: https://agentstack.voostack.com/s/dungnotnull
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.