Fog Water Harvester Design Agent Skill

SKILL.md ? Skill Registry Documentation

Skill: fog-water-harvester-design v2.0.0 Domain: Fog-Water Collection Engineering & Atmospheric Water

This document is the canonical registry specification. It explains how skills are registered, resolved, executed, and validated, including the input/output JSON schemas. The runtime implementation lives in fog_skill/registry.py; the schemas live in assets/schemas/.

---

1. What a "skill" is

A skill is a Markdown file under skills/ whose YAML frontmatter declares its manifest (name, description, dependencies, tools, quality gate, execution order). The body contains the prompt instructions the orchestrating agent executes at runtime. Pure-compute skills may additionally register a Python handler (SkillRegistry.register_handler) so they can run deterministically in tests without an LLM.

A skill manifest validates against [assets/schemas/skill.schema.json](assets/schemas/skill.schema.json):

{
  "required": ["name", "description"],
  "properties": {
    "name": {"type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$"},
    "description": {"type": "string"},
    "order": {"type": "integer"},
    "depends_on": {"type": "array", "items": {"type": "string"}},
    "tools": {"type": "array", "items": {"type": "string"}},
    "gate": {"type": ["string", "null"]},
    "inputs": {"type": "object"},
    "outputs": {"type": "object"},
    "path": {"type": "string"}
  },
  "additionalProperties": false
}

---

2. Register

Skills are discovered by scanning skills/*.md. Each file is parsed by fog_skill.registry._parse_frontmatter (PyYAML when available, else a built-in minimal parser) and validated against the skill schema before insertion.

from fog_skill import SkillRegistry
reg = SkillRegistry(skills_dir="skills")
reg.load_dir()              # registers every *.md in skills/
reg.register_file("skills/sub-core-analysis.md")   # explicit
reg.register_handler("sub-core-analysis", handler)  # attach a Python handler

A registration that fails schema validation raises FogSkillError; the offending skill is rejected. The global registry is fog_skill.skill_registry.

---

3. Resolve

resolve_chain(entrypoint) walks depends_on in declared order, deduplicates, and returns the ordered execution list. It raises FogSkillError on a dependency cycle. Order within a level is (order, name).

fog-water-harvester-design (entrypoint)
?? sub-gather-requirements      (order 1)
?? sub-evidence-collector       (order 2, depends on gather-requirements)
?? sub-core-analysis            (order 3, depends on evidence-collector)
?? sub-knowledge-updater        (order 4, depends on core-analysis)
?? sub-advisor                  (order 5, depends on core-analysis, knowledge-updater)

The static registry contract is mirrored in [assets/skill-registry.json](assets/skill-registry.json).

---

4. Execute

SkillRegistry.execute(name, payload, context) runs a single skill:

1. Emits the BEFORE_SKILL lifecycle hook.
2. If a Python handler is attached, calls it with {**payload, "_context": ctx}

and expects a dict result.

1. Otherwise returns a `{"mode": "prompt", "instructions": , "gate": ...,

"payload": ...}` envelope for the orchestrating agent to execute.

1. Emits AFTER_SKILL (or ON_ERROR on exception).

execute_chain(entrypoint) runs the whole resolved chain, threading each step's output into ctx["chain"] for the next step.

---

5. Validate

Three validation surfaces enforce correctness end-to-end:

| Surface | Schema | When | |--------|--------|------| | Skill manifest | assets/schemas/skill.schema.json | at registration | | Tool call envelope | assets/schemas/tool-call.schema.json | every tool_registry.call | | Final report | assets/schemas/report.schema.json | before delivery (Step 6) |

Tool-call envelope schema:

{
  "required": ["tool", "params"],
  "properties": {
    "tool": {"type": "string", "pattern": "^[a-z0-9_]+$"},
    "params": {"type": "object"}
  },
  "additionalProperties": false
}

The final report schema enforces: language in {Vietnamese, English}; verdict in {Viable Harvest Plan, Conditional (climatology), Low Yield, Inconclusive}; ?3 key risks; tier labels in {Tier 1..Tier 4}; and the full post_execution_gate_checklist (U1..U6 + G1..G4).

The validator is a dependency-free subset of JSON Schema Draft 2020-12 implemented in fog_skill/schemas.py (no jsonschema dependency).

---

6. Hooks & Tools integration

• Hooks (fog_skill/hooks.py): HookBus emits lifecycle events

(pre_invoke, before_skill, after_skill, before_tool, after_tool, quality_gate, on_degradation, on_error, on_language, post_deliver). Policy hooks (registered with is_policy=True) may mutate the event payload. A built-in policy hook prepends the LIMITATION banner on degradation level ? 1.

• Tools (fog_skill/tools/): each tool declares an input_schema

(JSON Schema fragment) + a Python handler and is invoked through tool_registry.call(name, params, ctx), which validates the envelope, emits before_tool/after_tool hooks, and caches cacheable results.

Bundled tools (see assets/skill-registry.json for the full list):

| Tool | Category | Purpose | |------|----------|---------| | compute_collection_efficiency | physics | CE for a mesh + wind | | compute_water_yield | physics | Y = LWC?U?CE?86400/1000 | | lwc_from_visibility | physics | LWC from visibility (Gultepe 2006) | | select_mesh | design | multi-criteria mesh recommendation | | score_siting | siting | site exposure score (FogQuest) | | scenario_yields | design | best/base/worst + viability flag | | fetch_evidence | evidence | curated source-map fallback (offline-safe) | | query_knowledge | knowledge | citations + gaps from the brain | | append_knowledge_entry | knowledge | manual curation append |

---

7. Production-grade practices enforced

• Context & tokens: fog_skill.context.ContextWindow allocates per-step

budgets and compresses rolling history to keep the prompt under the model window while reserving output space.

• Error handling: fog_skill.errors.FallbackChain degrades through

declared providers (levels 0..4); a failed chain raises FallbackChainError carrying a LIMITATION notice ? never silent stale data.

• Structured logging: fog_skill.logging emits JSON lines keyed by

component (registry, hook, tool:, skill:).

• Configuration: config/ layers defaults ? config/settings.json ?

FOGSKILL_* env vars, type-safe via dataclasses.

---

8. Running the registry

# register + execute the deterministic chain, validate the report
python scripts/run_pipeline.py --object "Cerro Grande highland (900 m)" --json out.json

# validate the whole project (registry, tools, schemas, brain)
python scripts/validate_project.py

# seed the knowledge base through the same validated path
python scripts/seed_knowledge_base.py

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/fog-water-harvester-design-agent-skill
• License: MIT

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