Portable Emergency Water Filter Agent Skill

SKILL.md -- Skill Registry Documentation

portable-emergency-water-filter uses a modular skill-registry pattern: a runtime discovers, validates, and resolves Markdown skill definitions, then the orchestrator executes them as a chain-of-thought pipeline backed by a typed tool registry and a hook bus. This document is the canonical reference for how skills are registered, resolved, executed, and validated -- including their input/output JSON schemas.

---

1. Skill Registration

Discovery

runtime/skill_registry.py auto-discovers every skills/**/*.md file:

skills/
  main.md                       # orchestrator + quality gate (kind: main)
  router.md                     # chain-of-thought router (kind: router)
  sub-gather-requirements.md    # (kind: sub)
  sub-evidence-collector.md     # (kind: sub)
  sub-core-analysis.md          # phase coordinator (kind: sub)
  sub-knowledge-updater.md      # (kind: sub)
  sub-advisor.md                # (kind: sub)
  sub-core-analysis/
    sub-filter-design.md        # specialized (kind: specialized)
    sub-lrv-computation.md      # specialized (kind: specialized)
    sub-field-testing.md        # specialized (kind: specialized)

Frontmatter (the registration contract)

Every skill file begins with YAML frontmatter:

---
name: 
description: 
---

name is the registry key used by Skill("") invocations. description is surfaced in catalogs and agent grounding. Files are classified by location:

• main.md -> main
• router.md -> router
• skills/sub-core-analysis/*.md -> specialized
• all other sub-*.md -> sub

Validation

On load, each skill is validated for:

• frontmatter name and description present (non-empty);
• required sections present (prefix match):
• main: Role & Persona, Harness Execution Protocol, Quality Gates, Graceful Degradation
• router: Role & Persona, Routing Logic, Output Format
• sub/specialized: Role & Persona, Workflow, Output Format, Quality Gates

SkillRegistry.validation_report() returns total/valid/invalid and per-skill errors. The orchestrator surfaces this on every run; an invalid skill does not halt execution (fail-soft) but is reported in the result.

---

2. Skill Catalog

| skill | kind | step | inputs | outputs | tools | |-------|------|------|--------|---------|-------| | portable-emergency-water-filter (main) | main | 0-7 | user query | final report | Skill, Read, Write, Bash | | sub-gather-requirements | sub | 1 | user message + LANG | requirements | none | | sub-evidence-collector | sub | 2 | requirements | evidence | websearch, webfetch, knowledgequery | | router | router | 3a | requirements, evidence | ROUTING PLAN | Read | | sub-core-analysis | sub | 3 | requirements, evidence | scorecard | Skill (router + 3 specialized) | | sub-filter-design | specialized | 3b | requirements, evidence | train + flowassessment | filterselector, Read, WebFetch | | sub-lrv-computation | specialized | 3b | train, target standard | LRV + scenarios + verdict | lrvcalculator, standardsvalidator, Read | | sub-field-testing | specialized | 3b | train, LRV, flowassessment | operational verdict | Read, WebFetch | | sub-knowledge-updater | sub | 4 | scorecard keywords | citations + crawl gaps | knowledgequery, websearch | | sub-advisor | sub | 5 | scorecard + evidence + knowledge | verdict + evidence chain | Skill, reasoning |

---

3. Resolution & Execution

The orchestrator (runtime/orchestrator.py) resolves skills by name from the registry and executes the pipeline deterministically:

pre_run -> on_language_detected
  Step1 sub-gather-requirements   -> state["requirements"]
  Step2 sub-evidence-collector    -> state["evidence"]
  Step3 sub-core-analysis:
         router                   -> ROUTING PLAN (deterministic chain-of-thought)
         sub-filter-design         -> train + flow_assessment
         sub-lrv-computation       -> LRV + standards verdict
         sub-field-testing         -> operational verdict
         coordinator assembles     -> CORE-ANALYSIS SCORECARD
  Step4 sub-knowledge-updater      -> citations + crawl gaps
  Step5 sub-advisor                -> verdict + evidence chain + disclosure
  Step6 quality-gate engine        -> U1-U6 + G1-G4 (auto-fix, 2 retries)
  Step7 render + deliver           -> report (LANG, template)
post_run

Chain-of-thought router

The router reads signals from requirements + evidence and emits a plan:

• analysis_type in {combined, design} -> sub-filter-design
• any pathogen LRV target stated -> sub-lrv-computation
• field/humanitarian/flow context -> sub-field-testing
• comparison of >=2 designs -> design x N then lrv

Sequencing is enforced: design -> lrv -> field. Missing decisive inputs are flagged DATA UNAVAILABLE (degradation Level 3). In the Python runtime the router logic is deterministic (see Orchestrator._step_core_analysis); in the LLM harness it is the router.md prompt.

Execution contract

• A step's output is stored in state[state_key] and fed to the next step.
• Each step emits pre_step/post_step hooks; failures emit on_error and

on_degradation, bumping the degradation level (never crashing the run).

• Tools are invoked through ToolRegistry.execute(name, params) which

validates inputs/outputs against JSON schemas and retries with backoff.

---

4. I/O JSON Schemas

Machine-readable schemas live in assets/schemas/. Summary:

• requirements.schema.json -- Step 1 output (object, analysis_type,

source_water{type,turbidity_ntu,daily_volume_l,power_available,weight_priority}, pathogens[], target_standard, language, assumptions[]).

• evidence-bundle.schema.json -- Step 2 output (`sources[]{title,url,tier,

keyfinding,accessdate}, coverage, degraded`).

• core-analysis.schema.json -- Step 3 output (routing, train[],

flow_assessment, lrv{bacteria,virus,protozoa}, lrv_scenarios{best,base, worst}, standards_validation{standard,verdict,all_pass,remediation}, field_performance{...,operational_verdict}).

• report.schema.json -- final report (language, sections{...},

evidence, claims[]{claim,source,flagged}, analysis).

• tool-invocation.schema.json -- {name, params} envelope.

Each tool in tools/registry.py also declares input_schema / output_schema (see ToolRegistry.schemas() for the full catalog).

---

5. Quality Gates

| gate | check | auto-fix | |------|-------|----------| | U1 | >=3 sources, >=1 academic (Tier.md` with the required frontmatter + sections (Role & Persona, Workflow, Output Format, Quality Gates).

1. If it needs a tool, register it in tools/registry.py (Tool subclass with

input_schema/output_schema + run).

1. Add an input/output schema to assets/schemas/ if it produces a new shape.
2. Wire it into router.md decision table and the orchestrator routing logic.
3. Run python scripts/validate_project.py -- it asserts the skill registry

validates and the tool registry schemas load.

To add a hook: subclass hooks.base.Hook (or use register_callable) and register it in hooks/base.default_registry(); declare the event from hooks.base.EVENTS (or * wildcard).

---

7. Runtime controls (config)

See config/default.yaml and config/schema.py. Environment overrides use the PEWF_ prefix with __ nesting, e.g. PEWF_LLM__MODEL, PEWF_FEATURES__.... Feature flags toggle the router, specialized sub-agents, hook classes, context compaction, and standards auto-validation without code changes.

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/portable-emergency-water-filter-agent-skill
• License: MIT

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