Floating Solar Extreme Weather Alert Agent Skill

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.

1. 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.

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:

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

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

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:

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

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
• Source: dungnotnull/floating-solar-extreme-weather-alert--agent-skill
• License: MIT

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