# Fog Water Harvester Design Agent Skill

> A Claude skill from dungnotnull/fog-water-harvester-design-agent-skill.

- **Type:** Skill
- **Install:** `agentstack add skill-dungnotnull-fog-water-harvester-design-agent-skill-fog-water-harvester-design-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/fog-water-harvester-design-agent-skill

## Install

```sh
agentstack add skill-dungnotnull-fog-water-harvester-design-agent-skill-fog-water-harvester-design-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

**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):

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

```python
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.
3. Otherwise returns a `{"mode": "prompt", "instructions": , "gate": ...,
   "payload": ...}` envelope for the orchestrating agent to execute.
4. 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:

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

```bash
# 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](https://github.com/dungnotnull)
- **Source:** [dungnotnull/fog-water-harvester-design-agent-skill](https://github.com/dungnotnull/fog-water-harvester-design-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-fog-water-harvester-design-agent-skill-fog-water-harvester-design-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%.