Building Rainwater Harvesting

SKILL.md — building-rainwater-harvesting Registry

Skill Registration

This document serves as the central registry for the building-rainwater-harvesting skill, documenting all sub-skills, tools, hooks, and execution protocols.

Skill Identity

• Name: building-rainwater-harvesting
• Version: 1.0.0
• Category: Engineering & Environment
• Domain: Building Rainwater Harvesting & Water Reuse
• Type: Harness Skill (orchestrates sub-skills)

Triggering Criteria

The skill automatically triggers when:

• User mentions rainwater harvesting, water reuse, or stormwater
• Building water system design or sizing is requested
• Rainfall calculations or storage capacity analysis is needed
• Water quality or treatment design for rainwater is discussed
• Compliance with rainwater standards (ARCSA, WHO, ISO) is referenced
• Sustainable water management or green building features are mentioned

---

Sub-Skill Registry

1. sub-gather-requirements

File: skills/sub-gather-requirements.md

Purpose: Clarify the object of analysis, constraints, timeframe, available inputs, target audience, and language before any data fetching.

Input Schema:

{
  "type": "object",
  "properties": {
    "user_message": {"type": "string", "description": "Raw user input"},
    "provided_materials": {"type": "array", "items": {"type": "string"}, "description": "Any files or context provided"}
  }
}

Output Schema:

{
  "type": "object",
  "properties": {
    "object": {"type": "string", "description": "Primary object of analysis"},
    "scope": {"type": "string", "description": "Analysis scope and boundaries"},
    "timeframe": {"type": "string", "description": "Analysis timeframe"},
    "available_inputs": {"type": "object", "description": "Available data and parameters"},
    "target_audience": {"type": "string", "description": "Intended audience for output"},
    "language": {"type": "string", "enum": ["en", "vi"], "description": "Output language"},
    "analysis_type": {"type": "string", "description": "Type of analysis requested"}
  },
  "required": ["object", "language"]
}

Quality Gate: At least one object of analysis confirmed before proceeding.

---

2. sub-evidence-collector

File: skills/sub-evidence-collector.md

Purpose: Fetch authoritative real-time and reference data for the object: current status/parameters, authoritative documents/standards, and recent developments from domain and academic sources.

Input Schema:

{
  "type": "object",
  "properties": {
    "requirements": {"type": "object", "description": "Requirements from Step 1"}
  },
  "required": ["requirements"]
}

Output Schema:

{
  "type": "object",
  "properties": {
    "current_data": {"type": "object", "description": "Current status and parameters"},
    "authoritative_docs": {"type": "array", "description": "Authoritative documents and standards"},
    "recent_news": {"type": "array", "description": "Recent developments"},
    "reference_benchmarks": {"type": "object", "description": "Reference benchmarks"}
  }
}

Tools Required: WebSearch, WebFetch, Read

Quality Gate: At least current data + 1 authoritative document retrieved, or limitation flag.

---

3. sub-core-analysis

File: skills/sub-core-analysis.md

Purpose: Design a building rainwater-harvesting system: size storage from supply/demand, design first-flush/treatment, and specify end-use and maintenance.

Input Schema:

{
  "type": "object",
  "properties": {
    "roof_area": {"type": "number", "description": "Roof catchment area in m²"},
    "rainfall": {"type": "number", "description": "Annual rainfall in mm"},
    "demand": {"type": "number", "description": "Daily water demand in liters"},
    "end_use": {"type": "string", "description": "Intended end use"},
    "language": {"type": "string", "enum": ["en", "vi"]}
  },
  "required": ["roof_area", "rainfall", "demand"]
}

Output Schema:

{
  "type": "object",
  "properties": {
    "runoff_analysis": {"type": "object", "description": "Runoff calculation results"},
    "storage_design": {"type": "object", "description": "Storage sizing and design"},
    "treatment_system": {"type": "object", "description": "First-flush and treatment design"},
    "distribution_design": {"type": "object", "description": "Distribution system design"},
    "regulatory_compliance": {"type": "object", "description": "Compliance assessment"},
    "scenarios": {"type": "array", "description": "Design scenarios"}
  }
}

Tools Required: Read, WebFetch, Arithmetic

Quality Gate: Runoff estimated; storage sized from supply/demand; treatment matched to end-use.

---

4. sub-knowledge-updater

File: skills/sub-knowledge-updater.md

Purpose: Query SECOND-KNOWLEDGE-BRAIN.md for authoritative academic and professional evidence; surface citations with tier labels and flag gaps for the crawl pipeline.

Input Schema:

{
  "type": "object",
  "properties": {
    "topic_keywords": {"type": "array", "items": {"type": "string"}, "description": "Keywords for knowledge lookup"}
  },
  "required": ["topic_keywords"]
}

Output Schema:

{
  "type": "object",
  "properties": {
    "citations": {"type": "array", "description": "Knowledge-base citations with Tier labels"},
    "coverage_rating": {"type": "string", "description": "Coverage assessment"},
    "gaps": {"type": "array", "description": "Knowledge gaps to be filled"}
  }
}

Tools Required: Read, WebSearch

Quality Gate: At least 1 academic/authoritative source surfaced; coverage rating provided.

---

5. sub-advisor

File: skills/sub-advisor.md

Purpose: Synthesize all prior analysis into a risk-disclosed conclusion with a full evidence chain and recommended actions.

Input Schema:

{
  "type": "object",
  "properties": {
    "core_analysis_scorecard": {"type": "object"},
    "evidence_bundle": {"type": "object"},
    "knowledge_evidence": {"type": "object"}
  },
  "required": ["core_analysis_scorecard"]
}

Output Schema:

{
  "type": "object",
  "properties": {
    "conclusion": {"type": "string", "enum": ["Optimal System", "Conditional (sizing)", "Water-Quality Risk", "Inconclusive"]},
    "scenarios": {"type": "array"},
    "key_risks": {"type": "array"},
    "evidence_chain": {"type": "object"},
    "remediation": {"type": "object"},
    "disclosure": {"type": "string"}
  },
  "required": ["conclusion", "disclosure"]
}

Tools Required: Reasoning, Skill('sub-knowledge-updater')

Quality Gate: Conclusion is exactly one of the declared categories; disclosure appears before conclusion.

---

Tool Registry

Built-in Tools

Tools are defined in tools/registry.py and can be dynamically invoked:

| Tool | Description | Parameters | Returns | |------|-------------|------------|---------| | calculate_runoff | Calculate rainwater runoff from roof area | roof_area, rainfall, runoff_coefficient | runoff_volume_liters | | size_storage | Size storage tank from supply and demand | annual_supply, daily_demand, reliability | storage_volume_liters | | design_first_flush | Design first-flush diversion system | roof_area, contamination_factor | first_flush_volume_liters | | calculate_treatment | Calculate treatment requirements | source_quality, end_use, volume | treatment_recommendations | | check_compliance | Check compliance with standards | system_design, standards | compliance_assessment | | estimate_costs | Estimate system costs | system_components, location | cost_breakdown |

Tool Invocation Example

from tools.registry import get_tool_registry

registry = get_tool_registry()

result = registry.execute(
    "calculate_runoff",
    {
        "roof_area": 200,  # m²
        "rainfall": 1200,  # mm/year
        "runoff_coefficient": 0.9
    }
)

if result.success:
    print(f"Runoff: {result.data} liters/year")

---

Hooks System

Available Hooks

Hooks are defined in hooks/manager.py and can be registered to respond to lifecycle events:

| Hook Event | Description | Context Data | |------------|-------------|--------------| | BEFORE_SKILL_LOAD | Before skill loads into memory | skill_name, config | | AFTER_SKILL_LOAD | After skill loads successfully | skill_name, load_time_ms | | BEFORE_SKILL_EXECUTE | Before skill execution begins | query, requirements | | AFTER_SKILL_EXECUTE | After skill execution completes | result, execution_time_ms | | BEFORE_SUBSKILL_INVOKE | Before sub-skill invocation | subskill_name, inputs | | AFTER_SUBSKILL_INVOKE | After sub-skill completes | subskill_name, outputs | | BEFORE_QUALITY_GATE | Before quality gate check | gate_name, output | | AFTER_QUALITY_GATE | After quality gate check | gate_name, passed, auto_fix_applied | | ON_ERROR | When an error occurs | error, context | | STATE_CHANGE | When shared state changes | key, old_value, new_value |

Hook Registration Example

from hooks.manager import get_hook_manager, HookEvent

manager = get_hook_manager()

@manager.register(
    HookEvent.BEFORE_SKILL_EXECUTE,
    priority=10
)
def log_execution(context):
    print(f"Executing skill with query: {context.data.get('query')}")

@manager.register(
    HookEvent.ON_ERROR,
    conditions={"severity": "critical"}
)
def handle_critical_errors(context):
    # Send alert for critical errors
    pass

---

Configuration Management

Configuration Structure

Configuration is managed through config/config.py with the following structure:

| Section | Purpose | Key Parameters | |---------|---------|----------------| | environment | Deployment environment | development, staging, production | | llm | LLM interaction settings | model, temperature, max_tokens, cache_enabled | | knowledge | Knowledge pipeline config | keywords, update_interval_hours, max_entries | | sources | Authoritative sources config | primary_sources, fallback_enabled, cache_sources | | quality_gates | Quality gate enforcement | max_retries, strict_mode, auto_fix_enabled | | monitoring | Monitoring and metrics | log_level, metrics_enabled, performance_tracking | | feature_flags | Feature toggles | Custom feature flags |

Accessing Configuration

from config.config import get_config

config = get_config()

# Access configuration
model = config.llm.model
timeout = config.llm.timeout_seconds

# Reload configuration
from config.config import reload_config
config = reload_config()

---

Quality Gates

Universal Gates (U1-U6)

Mandatory for all projects:

| Gate | Criterion | |------|-----------| | U1 | ≥3 sources cited, ≥1 academic/authoritative | | U2 | Safety/risk/limitation disclosure present BEFORE recommendation | | U3 | Evidence hierarchy stated per source (Tier 1–4) | | U4 | Language matches user preference | | U5 | Output uses project's declared output template | | U6 | Every claim traceable to ≥1 cited source OR flagged as judgment |

Domain Gates (G1-G4)

Specific to building rainwater harvesting:

| Gate | Criterion | Auto-Fix | |------|-----------|----------| | G1 | Runoff calculated with documented coefficients | Add standard coefficient table | | G2 | Storage sized from both supply and demand analysis | Add demand-side sizing | | G3 | Treatment design matched to end-use classification | Add treatment matrix | | G4 | At least 2 compliance standards referenced | Add standard references |

---

Output Template

All outputs MUST follow this structure:

# Building Rainwater Harvesting Analysis: [Object]

## Executive Summary
[2-3 sentence summary of findings and conclusion]

## System Requirements
- Object of Analysis: [from requirements step]
- Scope: [defined scope]
- Constraints: [identified constraints]

## Analysis

### Runoff Analysis
[Runoff calculations, coefficients, assumptions]

### Storage Design
[Supply/demand balance, sizing methodology, reliability analysis]

### Treatment System
[First-flush design, treatment train, end-use matching]

### Regulatory Compliance
[Standards referenced, compliance assessment, permits required]

## Scenarios
[Best case, typical, worst case scenarios]

## Risk Assessment
[Key risks, mitigation strategies, limitations]

## Evidence and Sources
[Tier 1–4 categorized sources with access dates]

## Disclosure
[Safety/limitation/risk disclosure BEFORE recommendation]

## Recommendations
[Actionable recommendations with priority]

## Implementation Notes
[Maintenance requirements, monitoring, optimization opportunities]

---

Error Handling and Graceful Degradation

Degradation Levels

The skill implements 5 degradation levels:

| Level | Condition | Behavior | |-------|-----------|----------| | 0 | Full operation | All systems operational | | 1 | External sources unavailable | Fallback to knowledge base | | 2 | Knowledge base outdated | Use cached data with explicit limitation | | 3 | Real-time data unavailable | Use reference values with strong limitation | | 4 | Critical failure | Abort with clear error message |

Limitation Banners

When operating in degraded mode, include:

---
⚠️ LIMITATION NOTICE
This analysis was conducted without access to [specific data source].
Results are based on [alternative source/reference values] and may not reflect
current conditions. Verify with up-to-date local data before implementation.
---

---

Knowledge Pipeline

Update Schedule

# Weekly academic update (Mondays 8:00 AM)
0 8 * * 1 python tools/knowledge_updater.py >> logs/knowledge_update.log 2>&1

# Daily news update (Daily 7:00 AM)
0 7 * * * python tools/knowledge_updater.py --news-only >> logs/knowledge_news.log 2>&1

Manual Execution

# Dry run to preview updates
python tools/knowledge_updater.py --dry-run

# Update specific topics
python tools/knowledge_updater.py --keywords "rainwater treatment UV"

# News only
python tools/knowledge_updater.py --news-only

---

Testing and Validation

Running Tests

# Run all test scenarios
python tools/run_test_scenarios.py

# Run with specific scenario
python tools/run_test_scenarios.py --scenario standard

# Generate coverage report
python tools/run_test_scenarios.py --coverage

Test Scenarios

Located in tests/test-scenarios.md:

1. Standard Scenario: Full system design request
2. Minimal Input: Limited parameters provided
3. Comparison: Multiple design alternatives
4. Risk/Conflict: Identifying and mitigating risks
5. Degraded Mode: Operation without external sources

---

Performance Metrics

The skill tracks the following metrics:

| Metric | Description | Target | |--------|-------------|--------| | Execution Time | End-to-end execution time | 80% | | Source Retrieval Rate | Successful data source access | >90% | | Knowledge Hit Rate | Knowledge base cache hits | >70% |

---

Maintenance

Regular Maintenance Tasks

• [ ] Weekly: Review knowledge update logs for failed fetches
• [ ] Monthly: Review and update authoritative source URLs
• [ ] Quarterly: Run full test suite and review results
• [ ] Annually: Review and update skill architecture

Configuration Updates

To update configuration:

from config.config import ConfigManager, SkillConfig

manager = ConfigManager()
config = manager.get()

# Update specific setting
new_config = SkillConfig(
    **config.to_dict(),
    llm=LLMConfig(model="claude-sonnet-4-6")  # Update model
)

manager.save(new_config)

---

Extension Points

Adding New Sub-Skills

1. Create file in skills/sub-[name].md
2. Add frontmatter with name and description
3. Define Role, Workflow, Tools, Output Format, Quality Gates
4. Register in main harness w

…

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/building-rainwater-harvesting-agent-skill
• License: MIT

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