Inland Wetland Satellite Conservation Agent Skill

SKILL.md - Skill Registry & Execution Contract

> Single source of truth for how skills are registered, resolved, executed, > and validated in the inland-wetland-satellite-conservation harness (v2.0). > Machine-readable companion: skills/registry/skills.json. Schemas: > assets/schemas/*.schema.json. Tools: assets/tool-manifest.json (generated > by tools/tool_registry.py).

This document is the contract between the orchestrator (skills/main.md), the sub-skills (skills/sub-*.md), the tool registry (tools/tool_registry.py), the lifecycle hooks (hooks/), and the type-safe config (config/).

---

1. Registry

A skill is a named, schema-bound unit of work with a fixed role, step index, declared inputs/outputs, and a quality gate. Skills are registered in two places that must stay in sync:

1. skills/registry/skills.json - the machine-readable registry manifest.
2. skills/*.md - the human/LLM-readable skill definitions (frontmatter

name + description + sections per SKILL-STANDARD.md).

Registry entry shape (excerpt)

{
  "id": "sub-core-analysis",
  "name": "sub-core-analysis",
  "path": "skills/sub-core-analysis.md",
  "role": "inland-wetland remote-sensing & conservation advisor",
  "step": 3,
  "input": "requirements + evidence",
  "output": "core analysis scorecard",
  "output_schema": "assets/schemas/core-analysis.schema.json",
  "gate": "extent mapped; regime analyzed; threats detected; restoration prioritized",
  "tools": ["wetland_indices", "restoration_score", "kb_query"],
  "tags": ["analysis", "remote-sensing"]
}

Registered skills (v2.0)

| Step | Skill | Role | Output schema | |------|-------|------|---------------| | 0 | main (router + gate) | orchestrator | - | | 1 | sub-gather-requirements | intake specialist | requirements.schema.json | | 2 | sub-evidence-collector | data librarian | evidence-bundle.schema.json | | 3 | sub-core-analysis | remote-sensing & conservation advisor | core-analysis.schema.json | | 4 | sub-knowledge-updater | research librarian | knowledge-evidence.schema.json | | 5 | sub-advisor | senior advisor / synthesizer | advisor-report.schema.json |

Registering a new skill

1. Add skills/sub-.md with frontmatter + Role/Workflow/Tools/Output

Format/Quality Gates sections.

1. Add a JSON Schema for its output to assets/schemas/.schema.json.
2. Append an entry to skills/registry/skills.json (synced step, output_schema, tools, gate).
3. Wire the step into skills/main.md Harness Execution Protocol and into

scripts/run_harness.py (the offline reference runner).

1. python tools/validate_project.py must stay green.

---

2. Resolution (Chain-of-Thought Router)

skills/main.md is a chain-of-thought router, not a fixed script:

1. Pre-Flight: detect language (vi/en) from the user message; default en.

Load config (config/settings.py) for feature flags, gate set, degradation levels, and LLM parameters.

1. Intent parse: map the query to analysis_type (single / comparison / risk

/ monitoring) and scope (extent / regime / vegetation / threats / restoration / combined). This determines which tools each step may invoke.

1. Step routing: resolve each step via the registry in order 1->5. Each

step's output_schema is the contract the next step consumes.

1. Conditional tools: a step only invokes a tool whose tags match the

resolved intent (e.g. wetland_indices only when band data is available; web_search only when features.enable_web_search is true and the run is online).

1. Fallback chain: on tool/source failure, escalate the degradation level

(L0->L4) per skills/main.md; never fabricate missing data.

query -> pre_flight(lang) -> intent(scope,type) -> [1 req -> 2 evidence -> 3 core -> 4 knowledge -> 5 advisor] -> gate

---

3. Schema (Input / Output JSON Schemas)

Every skill output is validated against a JSON Schema (draft 2020-12) in assets/schemas/. Validation is enforced by:

• tools/tool_registry.py (jsonschema.validate on tool input/output),
• scripts/run_harness.py (validate() after each stage),
• tools/validate_project.py (schema files are valid JSON + referenced by the registry).

| Schema | Producer | Required fields (summary) | |--------|----------|---------------------------| | requirements.schema.json | sub-gather-requirements | object, scope, timeframe, availableinputs, targetaudience, language, analysistype | | evidence-bundle.schema.json | sub-evidence-collector | currentdata, authoritativedocs, recentnews, referencebenchmarks, degradationlevel; each item: source, tier(1-4), accessdate, value | | core-analysis.schema.json | sub-core-analysis | extent, regime, vegetation(indices NDVI/NDWI/MNDWI/NDMI in [-1,1]), threats, restoration, scenarios(best/base/worst) | | knowledge-evidence.schema.json | sub-knowledge-updater | citations(>=1, tier 1-4, relevance H/M/L), coverage(Strong/Moderate/Weak) | | advisor-report.schema.json | sub-advisor | verdict(enum), scenarios, keyrisks(>=3), evidence_chain, remediation, disclosure |

Tool input/output schemas are declared inline in tools/tool_registry.py and exported to assets/tool-manifest.json via tools.tool_registry.write_manifest().

---

4. Execution

4.1 Live mode (Claude Code)

/inland-wetland-satellite-conservation [query] invokes skills/main.md, which routes through the sub-skills (invoked via the Skill tool), calls native WebSearch/WebFetch/Read/Write/Bash tools, and runs the quality gate. Config and feature flags are read from config/settings.py.

4.2 Headless mode (offline reference runner)

scripts/run_harness.py reproduces the same orchestration deterministically using tools/tool_registry.py + hooks/. It performs REAL computation (spectral indices from band arrays, KB queries, the restoration-priority formula, verdict selection) and validates every stage against the schemas. It is the executable specification of the harness and is used by CI.

python scripts/run_harness.py --query "Analyze Mekong Delta wetland change" \
  --aoi assets/sample-aoi.geojson --bands assets/sample-bands.npz

4.3 Lifecycle hooks

hooks/ emits structured events around every step:

| Event | When | Default handlers | |-------|------|------------------| | pre_step | before each sub-skill | structured log + token-budget guard | | post_step | after each sub-skill | structured log + state snapshot | | on_error | step/tool raises | error capture + degradation escalation + limitation flag | | on_gate | quality gate evaluated | gate result recorded into RunState | | on_finish | run complete | finalize timestamps | | on_event | generic | state synchronisation |

State is carried in hooks/state.py:RunState (JSON-serialisable; snapshotted to logs/state/.json). All hooks fail-soft: a hook exception is logged and never crashes the run.

4.4 Tools

Tools are registered in tools/tool_registry.py with an inline JSON Schema and a typed execute(args, ctx) handler. The registry validates input before execution and output after. Registered tools:

| Tool | Scope | Behaviour | |------|-------|-----------| | wetland_indices | local | NDVI/NDWI/MNDWI/NDMI from surface-reflectance band values (scalar) | | restoration_score | local | weighted priority score + band (low/moderate/high/critical) | | aoi_validate | local | validate GeoJSON FeatureCollection (Polygon/MultiPolygon) + bbox | | kb_query | local | keyword search over SECOND-KNOWLEDGE-BRAIN.md with tier/DOI extraction | | web_search | network | live search via native tool; graceful offline fallback (no fabrication) | | web_fetch | network | fetch URL via native tool; graceful offline fallback |

Array-based index computation (full rasters) lives in tools/wetland_indices.py (NumPy), used by scripts/ingest_aoi.py and scripts/run_harness.py.

---

5. Validation

Three layers, all must be green:

1. Project structure - python tools/validate_project.py

(8-File Contract + v2.0 modular additions + registry + schemas).

1. Content & scenarios - python tools/run_test_scenarios.py

(frontmatter, sections, gate coverage, verdict coverage, knowledge base).

1. Unit tests - python tools/test_knowledge_updater.py and

python -m pytest tests/unit/ (hooks, tool registry, wetland indices, config, schema conformance).

Quality gates (enforced in execution)

Universal U1-U6 + domain G1-G4 (table in skills/main.md). Enforcement: apply each gate in order; on failure run the Auto-Fix; after 2 failed retries emit an explicit limitation for that gate and continue (fail-open). A run is deliverable only after all gates pass OR every failing gate has a recorded limitation flag (degradation >= L1 requires the LIMITATION banner).

Run-level deliverable check

scripts/run_harness.py writes logs/runs/.report.json containing the verdict, gate results, limitation flags, and all stage outputs - a complete, auditable artifact per run.

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/inland-wetland-satellite-conservation-agent-skill
• License: MIT

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