# Household Geothermal Heating

> Household Geothermal Heating System Design & Operation — Small-Scale Geothermal Heat Pump Engineering evidence-backed analysis harness. Use for geothermal system design, heat pump sizing, ground loop design, COP/economics analysis, and O&M planning. Triggers on: geothermal design, heat pump sizing, ground loop, GSHP, borehole design, heating system economics, geothermal operation & maintenance.

- **Type:** Skill
- **Install:** `agentstack add skill-dungnotnull-household-geothermal-heating-agent-skill-household-geothermal-heating-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/household-geothermal-heating-agent-skill

## Install

```sh
agentstack add skill-dungnotnull-household-geothermal-heating-agent-skill-household-geothermal-heating-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 & System Documentation

## Overview

`household-geothermal-heating` is a production-grade harness skill for **Small-Scale Geothermal Heat Pump Engineering**. It transforms Claude into a domain-expert that delivers structured, evidence-backed outputs through an orchestrated 6-step workflow.

## System Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                    USER INPUT (/skill-name invoke)                │
└────────────────────────┬────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│              PRE-FLIGHT: Language Detection & Routing            │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  Language Detection (Vietnamese/English/Other)              │  │
│  │  Skill Router (determine execution path)                   │  │
│  │  Context Window Manager (optimize token usage)            │  │
│  └────────────────────────────────────────────────────────────┘  │
└────────────────────────┬────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│                    MAIN HARNESS (6-Step Workflow)                │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │ Step 1: sub-gather-requirements                            │  │
│  │ Step 2: sub-evidence-collector                             │  │
│  │ Step 3: sub-core-analysis                                  │  │
│  │ Step 4: sub-knowledge-updater                              │  │
│  │ Step 5: sub-advisor                                        │  │
│  │ Step 6: Quality Gate Review (U1-U6, G1-G6)                 │  │
│  └────────────────────────────────────────────────────────────┘  │
└────────────────────────┬────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│                 OUTPUT GENERATION & DELIVERY                     │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  Structured Report (all mandatory sections)                │  │
│  │  Evidence Chain (citations with tiers)                     │  │
│  │  Risk/Limitation Disclosure                                │  │
│  │  Post-Execution Gate Checklist                             │  │
│  └────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
```

## Skill Registration & Resolution

### Registration Schema

```json
{
  "skill_id": "household-geothermal-heating",
  "version": "1.0.0",
  "name": "household-geothermal-heating",
  "type": "harness",
  "domain": "Small-Scale Geothermal Heat Pump Engineering",
  "entry_point": "skills/main.md",
  "sub_skills": [
    "sub-gather-requirements",
    "sub-evidence-collector",
    "sub-core-analysis",
    "sub-knowledge-updater",
    "sub-advisor"
  ],
  "tools": ["WebSearch", "WebFetch", "Read", "Write", "Bash", "Skill"],
  "quality_gates": {
    "universal": ["U1", "U2", "U3", "U4", "U5", "U6"],
    "domain": ["G1", "G2", "G3", "G4", "G5", "G6"]
  },
  "supported_languages": ["en", "vi"],
  "triggers": [
    "geothermal design",
    "heat pump sizing",
    "ground loop",
    "GSHP",
    "borehole design",
    "heating system economics",
    "geothermal O&M"
  ]
}
```

### Resolution Process

1. **Trigger Detection**: Skill is invoked via `/household-geothermal-heating` or trigger phrases
2. **Capability Check**: Verify required tools are available
3. **Language Detection**: Determine output language (English/Vietnamese)
4. **Context Loading**: Load SKILL.md body and sub-skill files
5. **Execution**: Begin Step 1 of harness workflow

### Input/Output JSON Schemas

#### Input Schema

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "Household Geothermal Heating Skill Input",
  "required": ["user_query"],
  "properties": {
    "user_query": {
      "type": "string",
      "description": "Natural language query from user"
    },
    "language": {
      "type": "string",
      "enum": ["en", "vi", "auto"],
      "default": "auto",
      "description": "Output language (auto-detect if not specified)"
    },
    "analysis_type": {
      "type": "string",
      "enum": ["standard", "comparison", "risk_assessment", "minimal"],
      "default": "standard"
    },
    "context": {
      "type": "object",
      "properties": {
        "building_params": {
          "type": "object",
          "properties": {
            "floor_area": {"type": "number"},
            "insulation_level": {"type": "string"},
            "ceiling_height": {"type": "number"},
            "window_area_pct": {"type": "number"}
          }
        },
        "location": {
          "type": "string",
          "description": "City, region, or climate zone"
        },
        "climate_data": {
          "type": "object",
          "properties": {
            "design_temp": {"type": "number"},
            "hdd": {"type": "number"},
            "ground_temp": {"type": "number"}
          }
        },
        "economics": {
          "type": "object",
          "properties": {
            "electricity_cost": {"type": "number"},
            "alternative_fuel": {"type": "string"},
            "alternative_cost": {"type": "number"}
          }
        }
      }
    }
  }
}
```

#### Output Schema

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "Household Geothermal Heating Skill Output",
  "required": [
    "report_metadata",
    "executive_summary",
    "inputs_scope",
    "evidence_collected",
    "analysis_scorecard",
    "action_plan",
    "academic_evidence",
    "disclosure",
    "verdict",
    "gate_checklist"
  ],
  "properties": {
    "report_metadata": {
      "type": "object",
      "properties": {
        "date": {"type": "string", "format": "date"},
        "analyst": {"type": "string"},
        "language": {"type": "string"},
        "domain": {"type": "string"},
        "version": {"type": "string"}
      }
    },
    "executive_summary": {
      "type": "string",
      "description": "2-3 sentence summary of verdict and headline action"
    },
    "inputs_scope": {
      "type": "object",
      "properties": {
        "object_of_analysis": {"type": "string"},
        "constraints": {"type": "array"},
        "timeframe": {"type": "string"},
        "available_inputs": {"type": "object"}
      }
    },
    "evidence_collected": {
      "type": "object",
      "properties": {
        "current_data": {"type": "object"},
        "authoritative_docs": {"type": "array"},
        "recent_developments": {"type": "array"},
        "reference_benchmarks": {"type": "array"}
      }
    },
    "analysis_scorecard": {
      "type": "object",
      "properties": {
        "building_load": {"type": "object"},
        "heat_pump_spec": {"type": "object"},
        "ground_loop_design": {"type": "object"},
        "cop_economics": {"type": "object"},
        "operation_maintenance": {"type": "object"}
      }
    },
    "action_plan": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "action": {"type": "string"},
          "priority": {"type": "string"},
          "magnitude": {"type": "string"},
          "safety_limits": {"type": "array"}
        }
      }
    },
    "academic_evidence": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "authors": {"type": "string"},
          "year": {"type": "integer"},
          "title": {"type": "string"},
          "venue": {"type": "string"},
          "doi": {"type": "string"},
          "tier": {"type": "integer", "minimum": 1, "maximum": 4},
          "key_finding": {"type": "string"}
        }
      }
    },
    "disclosure": {
      "type": "string",
      "description": "Mandatory risk/limitation disclosure"
    },
    "verdict": {
      "type": "object",
      "properties": {
        "category": {
          "type": "string",
          "enum": [
            "Optimal & Economical",
            "Conditional (loop space)",
            "Low Efficiency",
            "Inconclusive"
          ]
        },
        "scenarios": {"type": "object"},
        "key_risks": {"type": "array"},
        "evidence_chain": {"type": "array"},
        "remediation": {"type": "string"}
      }
    },
    "gate_checklist": {
      "type": "object",
      "properties": {
        "universal_gates": {"type": "object"},
        "domain_gates": {"type": "object"},
        "limitations": {"type": "array"}
      }
    }
  }
}
```

## Validation & Enforcement

### Quality Gate Validation

Each quality gate implements the following validation logic:

1. **Gate Check**: Verify condition is met
2. **Auto-Fix**: Attempt automatic remediation if condition not met
3. **Retry**: Allow up to 2 retry attempts
4. **Limitation Flag**: Emit explicit limitation if gate cannot pass
5. **Continue**: Proceed to next gate (system continues even if some gates fail with limitations)

### Error Handling Matrix

| Error Type | Severity | Detection | Recovery | Max Retries |
|------------|----------|-----------|----------|-------------|
| Source timeout | Warning | No response 30s | Alternate source | 3 |
| Invalid input | Error | Schema mismatch | User confirmation | 2 |
| Missing input | Warning | Field absent | Default + flag | N/A |
| Stale reading | Warning | Timestamp old | Refresh request | 1 |
| Knowledge base miss | Warning | No matches | WebSearch gap-fill | 2 |
| Conflicting actions | Error | Mutually exclusive | Precedence rules | N/A |
| Envelope unavailable | Warning | No setpoint | Genus fallback | 1 |
| Object/class ambiguous | Warning | Unclear classification | User confirm | 2 |

### Graceful Degradation Levels

| Level | Condition | Behavior | Output |
|-------|-----------|----------|--------|
| 0 | All sources reachable | Full analysis | Complete report |
| 1 | Some sources fail | Secondary sources + flags | Report with substituted sources |
| 2 | Most sources fail | Knowledge base only | Historical context notice |
| 3 | Required input missing | Available variables only | DATA UNAVAILABLE flags |
| 4 | All sources fail | No output | DATA UNAVAILABLE notice |

## Sub-Skill Registry

### Sub-Skill Manifest

```json
{
  "sub_skills": [
    {
      "name": "sub-gather-requirements",
      "step": 1,
      "file": "skills/sub-gather-requirements.md",
      "purpose": "Clarify object, scope, constraints, timeframe, inputs, audience, language",
      "inputs": ["user_query", "language"],
      "outputs": ["requirements_object"],
      "gate": "G1",
      "tools": ["conversation only"]
    },
    {
      "name": "sub-evidence-collector",
      "step": 2,
      "file": "skills/sub-evidence-collector.md",
      "purpose": "Fetch real-time and reference data from authoritative sources",
      "inputs": ["requirements_object"],
      "outputs": ["evidence_bundle"],
      "gate": "G2",
      "tools": ["WebSearch", "WebFetch", "Read"]
    },
    {
      "name": "sub-core-analysis",
      "step": 3,
      "file": "skills/sub-core-analysis.md",
      "purpose": "Design system: load calculation, heat pump sizing, loop design, COP/economics",
      "inputs": ["evidence_bundle", "requirements_object"],
      "outputs": ["analysis_scorecard"],
      "gates": ["G3", "G4"],
      "tools": ["Read", "WebFetch", "Arithmetic"]
    },
    {
      "name": "sub-knowledge-updater",
      "step": 4,
      "file": "skills/sub-knowledge-updater.md",
      "purpose": "Query knowledge base for academic evidence with tier labels",
      "inputs": ["topic_keywords"],
      "outputs": ["citations_with_tiers", "gaps"],
      "gate": "G5",
      "tools": ["Read", "WebSearch"]
    },
    {
      "name": "sub-advisor",
      "step": 5,
      "file": "skills/sub-advisor.md",
      "purpose": "Synthesize analysis into risk-disclosed conclusion with evidence chain",
      "inputs": ["analysis_scorecard", "evidence_bundle", "citations"],
      "outputs": ["verdict", "scenarios", "risks", "actions", "disclosure"],
      "gate": "G6",
      "tools": ["Reasoning", "Skill"]
    }
  ]
}
```

## Context Window Management

### Token Optimization Strategy

1. **Progressive Disclosure**: Load only metadata initially (~100 tokens)
2. **Just-In-Time Loading**: Load skill body when triggered ( 95% gates passing
- **Source Success Rate**: Target > 80% primary sources reachable
- **User Satisfaction**: Measured via feedback

## Deployment

### Installation

1. Copy skill directory to Claude Code skills folder
2. Verify required tools are available
3. Test with sample query
4. Configure environment variables (optional)

### Dependencies

See `requirements.txt` for Python dependencies.

### Version Compatibility

- Claude Code: >= 1.0
- Python: >= 3.8
- Claude Model: Opus 4.7 (recommended), Sonnet 4.6 (compatible)

---

## Appendix A: Language Translation Table

See `skills/main.md` for complete English/Vietnamese translation table.

## Appendix B: Quality Gate Reference

See `skills/main.md` for complete gate definitions and auto-fix logic.

## Appendix C: Error Recovery Procedures

See `skills/main.md` for graceful degradation and error handling tables.

## Appendix D: Knowledge Base Schema

See `SECOND-KNOWLEDGE-BRAIN.md` for knowledge base structure and update protocol.

---

**Document Version**: 1.0.0
**Last Updated**: 2026-07-27
**Maintainer**: 972026 Skill Library

## 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/household-geothermal-heating-agent-skill](https://github.com/dungnotnull/household-geothermal-heating-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-household-geothermal-heating-agent-skill-household-geothermal-heating-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%.