Household Geothermal Heating

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

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

{
  "$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

{
  "$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

{
  "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
• Source: dungnotnull/household-geothermal-heating-agent-skill
• License: MIT

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