# Floating Solar Extreme Weather Alert Agent Skill

> A Claude skill from dungnotnull/floating-solar-extreme-weather-alert--agent-skill.

- **Type:** Skill
- **Install:** `agentstack add skill-dungnotnull-floating-solar-extreme-weather-alert-agent-skill-floating-solar-extreme-weather-alert-agent-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [dungnotnull](https://agentstack.voostack.com/s/dungnotnull)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [dungnotnull](https://github.com/dungnotnull)
- **Source:** https://github.com/dungnotnull/floating-solar-extreme-weather-alert--agent-skill

## Install

```sh
agentstack add skill-dungnotnull-floating-solar-extreme-weather-alert-agent-skill-floating-solar-extreme-weather-alert-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 — Skill Registry Documentation

> Canonical reference for how skills are **registered, resolved, executed, and
> validated** in the `floating-solar-extreme-weather-alert` runtime. This is the
> contract between the markdown skill files (`skills/*.md`), the machine-readable
> registry (`assets/skill-registry.json`), and the Python runtime
> (`tools/floating_solar/`).

## 1. Overview

The skill is a **modular agent runtime**. Instead of a single hardcoded
pipeline, it exposes:

- A **Skill Registry** — declares every skill/sub-skill, its inputs/outputs,
  tools, gate, and the Python agent module that implements it.
- A **Tool Registry** — declares every tool, its typed input schema, and its
  execution handler.
- A **Hook Registry** — lifecycle hooks for audit, state sync, and degradation
  tracking.
- A **Chain-of-Thought Router** — turns the structured requirements into an
  ordered execution plan with a traceable reasoning trace.
- A **Quality-Gate Engine** — universal gates U1–U6 + domain gates G1–G4 with
  auto-fix and 2-retry enforcement.
- A **Graceful Degradation Manager** — levels 0–4 with mandatory LIMITATION
  banners; never fabricates data.

## 2. Registration

### 2.1 Skill registration

Skills are registered in two complementary ways:

1. **Markdown frontmatter** (`skills/*.md`): every skill file declares
   `name` and `description` in its YAML frontmatter. The
   `SkillRegistry.load_registry()` parser reads these.
2. **Machine-readable index** (`assets/skill-registry.json`): declares the
   structured fields the markdown cannot express cleanly — `step`,
   `inputs`, `outputs`, `tools`, `gate`, `agent_module`, and `file`.

`load_registry()` merges both sources (markdown frontmatter first, then any
declarative-only JSON entries). Each `SkillSpec` is validated for uniqueness
of `name`.

```python
from floating_solar.registry import load_registry, export_schemas
reg = load_registry()
reg.main()        # -> SkillSpec(step=0, the orchestrator)
reg.steps()       # -> [SkillSpec(step=1..5)] ordered
export_schemas(reg)  # -> list[dict] machine-readable
```

### 2.2 Skill resolution

Resolution is by exact `name`:

```python
spec = reg.get("sub-core-analysis")  # -> SkillSpec or None
```

The orchestrator resolves the main skill (`step == 0`) and then resolves each
routed sub-skill by name to its agent instance in
`Orchestrator.agents` (`build_default_agents`).

### 2.3 Skill execution

Execution is delegated to the agent module named in `agent_module`. The
orchestrator calls `agent.run(ctx, prior)` where `ctx` is the shared
`AgentContext` (user input, language, raw inputs, tool-results cache) and
`prior` is the dict of canonical stage outputs so far
(`requirements`, `evidence`, `analysis`, `knowledge`). Each agent returns a
typed, validated schema object.

### 2.4 Skill validation

Every skill output is validated by its schema `validate()` (see
`floating_solar.schemas`). The final `HarnessResult` is validated as a whole
before the quality-gate review. A skill whose output fails validation is
treated as an agent error and replaced with a typed fallback, escalating
degradation.

## 3. Skill Catalogue

| Name | Step | Agent module | Inputs → Outputs | Gate |
|------|------|--------------|------------------|------|
| `floating-solar-extreme-weather-alert` | 0 | `orchestrator.Orchestrator` | user message → HarnessResult + report | U1–U6 + G1–G4 |
| `sub-gather-requirements` | 1 | `agents.gather_requirements.GatherRequirementsAgent` | user message → Requirements | ≥1 object confirmed |
| `sub-evidence-collector` | 2 | `agents.evidence_collector.EvidenceCollectorAgent` | Requirements → EvidenceBundle | current data + 1 authoritative doc, or limitation |
| `sub-core-analysis` | 3 | `agents.core_analysis.CoreAnalysisAgent` | farm + met-ocean → CoreAnalysis | thresholds w/ margins; durability; actions tied |
| `sub-knowledge-updater` | 4 | `agents.knowledge_updater.KnowledgeUpdaterAgent` | keywords → KnowledgeEvidence | ≥1 academic source; coverage rating |
| `sub-advisor` | 5 | `agents.advisor.AdvisorAgent` | analysis + evidence + knowledge → Conclusion | verdict ∈ 6 categories; disclosure before verdict |

## 4. Tool Registry

Each tool subclasses `floating_solar.tools.base.Tool`, declares a class-level
`name`, `description`, `input_cls` (a dataclass), and a `run(parsed_input)`
handler returning a plain dict. `Tool.schema()` exposes a JSON-Schema-like
contract consumed by agents and by `assets/schemas/`.

| Tool | Input dataclass | Output (dict) | Tier |
|------|-----------------|---------------|------|
| `web_search` | `WebSearchInput{query, max_results, prefer_tier}` | `{results[], source, _degradation_level}` | 3 |
| `web_fetch` | `WebFetchInput{url, max_chars, timeout_seconds}` | `{url, text, source, _degradation_level}` | 3 |
| `met_ocean_fetch` | `MetOceanInput{location, latitude, longitude, station_id, design_hs_m, design_wind_ms}` | `{wave_hs_m, wave_tp_s, wind_speed_ms, radiation_wm2, cyclone_probability, source, *_degradation_level}` | 2 |
| `risk_calculator` | `RiskCalcInput{wave_hs_m, wave_tp_s, wind_speed_ms, design_*, mooring_type, cyclone_probability, uv_exposure_years}` | `{load_margins, exceeded, mooring_tension_proxy, storm_fatigue_index, uv_degradation, risk_index, risk_band, early_warning_actions}` | 2 |
| `knowledge_query` | `KnowledgeQueryInput{keywords, top_n, brain_path}` | `{citations[], gaps[], coverage, total_entries}` | 1 |

### Tool execution contract

```python
from floating_solar.tools import build_default_registry
reg = build_default_registry(settings)
result = reg.invoke("risk_calculator", {"wave_hs_m": 2.2, "wave_tp_s": 7.0,
    "wind_speed_ms": 33.0, "design_hs_m": 2.0, "design_tp_s": 6.0,
    "design_wind_ms": 30.0, "mooring_type": "taut", "cyclone_probability": 0.4})
# -> ToolResult(ok=True, data={...}, source="risk_calculator", degradation_level=0)
```

`ToolResult` is the universal envelope: `ok`, `data`, `error`, `source`,
`degradation_level` (0–4). Tools never raise through the registry; failures
are contained and surfaced as `ok=False` so downstream agents can degrade
gracefully.

## 5. Hook Registry

Lifecycle events (see `floating_solar.hooks.HookEvent`):

| Event | When fired | Payload keys |
|-------|-----------|--------------|
| `BEFORE_HARNESS` / `AFTER_HARNESS` | run start / end | `user_input`, gates summary |
| `BEFORE_STEP` / `AFTER_STEP` | around each agent | `step`, `reason`, `result` |
| `BEFORE_TOOL` / `AFTER_TOOL` | around each tool call | `tool`, `agent`, `ok` |
| `BEFORE_GATE` / `AFTER_GATE` | around each quality gate | `gate`, `passed`, `retries` |
| `ON_DEGRADATION` | degradation level escalates | `level`, `reason`, `step` |
| `ON_ERROR` | unrecoverable error | error detail |

Built-in hooks: `make_audit_hook` (structured logging), `make_state_sync_hook`
(mirrors step outputs into a state dict), `make_degradation_hook` (records
degradation events). Hook exceptions are caught and logged so a faulty hook
can never break the core flow.

## 6. Input / Output JSON Schemas

Authoritative JSON Schemas live in `assets/schemas/` and mirror the dataclasses
in `floating_solar.schemas` (single source of truth):

| Schema file | Dataclass | Stage |
|-------------|-----------|-------|
| `requirements.schema.json` | `Requirements` | Step 1 |
| `evidence-bundle.schema.json` | `EvidenceBundle` / `EvidenceItem` | Step 2 |
| `analysis.schema.json` | `CoreAnalysis` / `FarmSpec` / `MetOceanForecast` / `LoadMargin` | Step 3 |
| `conclusion.schema.json` | `Conclusion` / `KeyRisk` | Step 5 |
| `harness-result.schema.json` | `HarnessResult` | Final |

Every schema enforces required fields, enums (e.g. verdict ∈ 6 categories,
language ∈ {en, vi}, tiers ∈ 1–4), and numeric bounds (design thresholds > 0,
cyclone_probability ∈ 0–1).

## 7. End-to-End Execution

```
user_input
   │
   ▼
Orchestrator.run()
   ├── fire BEFORE_HARNESS
   ├── GatherRequirementsAgent.run() ────────────► Requirements (validated)
   ├── router.route(Requirements) ───────────────► RoutePlan + thought trace
   ├── for each routed step:
   │      fire BEFORE_STEP
   │      Agent.run(ctx, prior) ── invokes tools ──► typed output (validated)
   │      fire AFTER_STEP
   │      DegradationManager.observe(tool results)
   │      if abort (L4): break
   ├── assemble HarnessResult (validated)
   ├── run_gates(U1–U6 + G1–G4) ── auto-fix + 2 retries
   ├── render_report() ── bilingual markdown + LIMITATION banner
   └── fire AFTER_HARNESS
```

## 8. Programmatic Usage

```python
from floating_solar import run_harness, load_settings

settings = load_settings("config/production.yaml")
result = run_harness(
    "Analyze extreme-weather risk for a 50MW floating solar farm near Quang Ninh bay.",
    {"latitude": 20.9, "longitude": 107.1, "design_hs_m": 2.0, "design_wind_ms": 35.0},
    settings=settings,
)
print(result.result.conclusion.verdict)   # e.g. "Normal Ops"
print(result.report_markdown)             # full bilingual report
```

CLI:

```bash
python scripts/run_skill.py "Analyze extreme-weather risk for..." \
    --inputs '{"latitude":20.9,"design_hs_m":2.0,"design_wind_ms":35.0}' --json
```

## 9. Validation

```bash
python scripts/validate_project.py          # 8-File Contract + runtime + headless run
python tools/run_test_scenarios.py          # structural + content validator
python tools/test_knowledge_updater.py      # knowledge pipeline unit tests
pytest                                       # full runtime test suite (tests/)
```

## 10. Extending the Skill

- **Add a tool**: subclass `Tool` in `tools/floating_solar/tools/`, declare
  `name`, `description`, `input_cls`, implement `run()`, and register it in
  `build_default_registry()`.
- **Add a sub-skill**: add a `skills/sub-*.md` (frontmatter `name`+`description`),
  add an entry to `assets/skill-registry.json` with `step`, `agent_module`,
  `inputs`, `outputs`, `tools`, `gate`, implement the agent in
  `tools/floating_solar/agents/`, register it in `build_default_agents()`, and
  add a route branch in `router.py` if needed.
- **Add a hook**: `hooks.register(HookEvent.AFTER_STEP, my_callback, name="x")`.
- **Add a quality gate**: append a `QualityGate` in
  `quality_gates.build_default_gates()`.

See `CONTRIBUTING.md` for coding standards and `references/` for domain
grounding.

## 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/floating-solar-extreme-weather-alert--agent-skill](https://github.com/dungnotnull/floating-solar-extreme-weather-alert--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-floating-solar-extreme-weather-alert-agent-skill-floating-solar-extreme-weather-alert-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%.