small-datacenter-airflow-thermal-optimization-agent-skill

small-datacenter-airflow-thermal-optimization

Airflow & Temperature Optimization for Small Data Centers

A professional-grade Claude Code harness for Small Data Center Cooling & Airflow Engineering — gathers real-time authoritative data, applies recognized domain methods (ASHRAE TC 9.9, hot/cold-aisle containment, PUE optimization, CFD/hotspot detection, cooling sizing, free cooling), integrates academic research, and delivers evidence-backed, risk-disclosed outputs.

Architecture Upgrade (v2.0.0)

v2.0.0 upgrades this skill to a bulletproof, production-grade, open-source standard:

• dc_thermal/ flexible architecture package @EM@ skill registry, chain-of-thought router, lifecycle hooks (logging/trace/state-sync), rich tool definitions with JSON schemas, token-budgeted context window, pluggable LLM backends (stub/anthropic), and the same 10 quality gates (U1@EM@U6 + G1@EM@G4).
• Modular directories: /scripts (automation), /references (domain knowledge + prompt templates), /assets (JSON schemas + diagrams + glossary), /config (type-safe settings, env > file > defaults).
• SKILL.md @EM@ canonical skill-registry documentation (register / resolve / execute / validate + I/O JSON schemas).
• Full Unicode/Vietnamese remediation @EM@ every mojibake literal ? replaced with the correct character; Vietnamese labels, language table, and Idea paragraph reconstructed with precomposed Unicode.

from dc_thermal import build_default
orch = build_default()
rr = orch.run("Optimize airflow & PUE for a 20-rack, 200 kW small DC in Hanoi (A1)")
print(rr.verdict, rr.gate_summary())   # Conditional (containment)  U1OK ... G4OK

python -m dc_thermal.cli --query "..." --json --emit-trace
python scripts/run_all_tests.py        # pytest + validators, combined exit code

Overview

Small Data Center Cooling & Airflow Engineering practitioners face fragmented data (ASHRAE, Green Grid, TIA/Uptime, vendors, journals), inconsistent methodology (setpoints without class validation, PUE claims without a metering basis, hotspots without CFD/SHI quantification), and tools that do not self-improve. This skill unifies authoritative real-time data, recognized domain methods, a continuously-updated academic knowledge base, an executable thermal engine, and an executable orchestrator into one evidence-backed, risk-disclosed workflow.

• Real-time data aggregation from authoritative Small Data Center Cooling & Airflow Engineering sources
• Systematic domain analysis methods (ASHRAE TC 9.9 setpoints, hot/cold-aisle containment, PUE optimization, CFD/hotspot detection, cooling sizing, free cooling)
• Executable thermal engine (tools/thermal_analysis.py) — ASHRAE lookup, PUE, cooling sizing, required airflow, SHI/RTI/RHI, inlet profile, free-cooling hours, setpoint validation
• Executable 6-step orchestrator (tools/harness.py) — context management, sub-skill invocation, quality-gate enforcement, graceful degradation, language detection, output templating, pluggable LLM backend
• Academic research integration with auto-updating knowledge base
• Risk/limitation-disclosed outputs with best/base/worst scenario coverage
• Self-improving knowledge pipeline (weekly academic + daily news crawl)
• 10 quality gates (U1–U6 universal + G1–G4 domain) with auto-fix and 2-retry max
• 5-level graceful degradation with explicit LIMITATION banners
• Vietnamese/English language detection

Why This Skill

Small Data Center Cooling & Airflow Engineering practitioners face fragmented data, inconsistent methodology, and tools that do not self-improve. This skill unifies authoritative real-time data, recognized domain methods, and a continuously-updated academic knowledge base into one evidence-backed, risk-disclosed workflow.

Installation

pip install -r requirements.txt

Install skill files to ~/.claude/skills/ or use via project CLAUDE.md.

Quick Start

# Validate the project against the 8-File Contract
python tools/validate_project.py

# Run all structural/content scenario checks
python tools/run_test_scenarios.py

# Run the unit-test suites
python tools/test_thermal_analysis.py
python tools/test_knowledge_updater.py

# Dry-run the knowledge crawl (no network writes)
python tools/knowledge_updater.py --dry-run

# Run the executable harness orchestrator on a query (stub LLM backend by default)
python tools/harness.py --query "Optimize airflow & PUE for a 20-rack, 200 kW small DC in Hanoi (ASHRAE A1)"

Usage

Invoke the skill in Claude Code:

/small-datacenter-airflow-thermal-optimization [your query]

Analysis types supported:

• Full combined — airflow + cooling/setpoints + CFD/hotspots + PUE + scenarios (default)
• Airflow — hot/cold aisle, containment, blanking, required-rack-airflow
• Cooling & setpoints — CRAC/CRAH/in-row/liquid sizing + ASHRAE TC 9.9 envelope
• PUE — current/target PUE with levers + free-cooling hours
• CFD/hotspot — inlet profile, SHI/RTI/RHI, hotspot remediation

Architecture

Harness flow: requirements — evidence — core analysis — knowledge — synthesis — quality gate. All numeric computations go through tools/thermal_analysis.py; the 6-step flow is provided as an executable orchestrator in tools/harness.py.

NNN-small-datacenter-airflow-thermal-optimization/
├── CLAUDE.md                         # Identity card
├── CHANGELOG.md                      # Version history
├── CODE_OF_CONDUCT.md                # Contributor Covenant
├── CONTRIBUTING.md                   # Contribution guide
├── LICENSE                           # MIT
├── PROJECT-detail.md                 # Full technical spec
├── PROJECT-DEVELOPMENT-PHASE-TRACKING.md
├── README.md
├── SECOND-KNOWLEDGE-BRAIN.md         # Living knowledge base
├── SECURITY.md                       # Security policy
├── pyproject.toml                    # Python packaging & pytest config
├── progression.json
├── requirements.txt
├── .editorconfig
├── .gitignore
├── .github/
│   ├── workflows/ci.yml              # CI/CD pipeline
│   ├── ISSUE_TEMPLATE/
│   │   ├── bug_report.md
│   │   ├── feature_request.md
│   │   └── config.yml
│   └── PULL_REQUEST_TEMPLATE.md
├── skills/
│   ├── main.md                       # Harness orchestrator + quality gates
│   └── sub-*.md                      # 5 sub-skills
├── tools/
│   ├── __init__.py                   # Package init with __version__
│   ├── knowledge_updater.py          # Crawl pipeline
│   ├── thermal_analysis.py           # Domain thermal engine
│   ├── harness.py                    # 6-step orchestrator
│   ├── validate_project.py           # 8-File Contract validator
│   ├── run_test_scenarios.py         # Structural & content validator
│   ├── test_knowledge_updater.py     # Unit tests (crawl)
│   └── test_thermal_analysis.py      # Unit tests (engine)
├── tests/
│   ├── __init__.py
│   ├── conftest.py                   # Pytest configuration
│   ├── test-scenarios.md
│   ├── TEST_RESULTS.md
│   ├── test_thermal_analysis_pytest.py
│   ├── test_knowledge_updater_pytest.py
│   └── test_harness_pytest.py
└── logs/                             # Artifact directory (.gitignored)

See PROJECT-detail.md for the full architecture diagram.

Quality Gates

Universal gates U1–U6 plus domain gates defined in skills/main.md:

• U1 ≥3 sources cited, ≥1 academic/authoritative
• U2 Disclosure/limitations before recommendation
• U3 Evidence hierarchy (Tier 1–4) per source
• U4 Language matches user preference
• U5 Declared template (all sections)
• U6 Every claim traceable or flagged
• G1 Airflow containment designed (hot/cold aisle, blanking, cable mgmt)
• G2 ASHRAE TC 9.9 setpoints for declared class (A1 recommended 18–27 °C, 40–60% RH; validate_setpoint PASS)
• G3 CFD hotspots/bypass/recirculation addressed (all top-of-rack inlets ≤ ASHRAE limit OR remediation stated)
• G4 PUE optimized; cooling —1.15–1.25—IT; redundancy N+1

Data Sources

• ASHRAE TC 9.9 data center thermal guidelines
• ASHRAE Handbook — HVAC Applications (Datacom)
• The Green Grid — PUE / ERE / CUE references
• TIA-942 / Uptime Institute Tier Standard
• CFD for data centers references (6Sigma / Future Facilities)
• UPS / power redundancy references
• Applied Thermal Engineering, Int. J. Heat & Mass Transfer, Building and Environment, IEEE TCPMT, Sustainable Computing, Energy and Buildings

Testing

python tools/validate_project.py        # 8-File Contract
python tools/run_test_scenarios.py      # scenarios + structure
python tools/test_thermal_analysis.py  # thermal engine unit tests
python tools/test_knowledge_updater.py # crawl pipeline unit tests

All suites exit 0 on success.

Knowledge Base

SECOND-KNOWLEDGE-BRAIN.md is auto-updated weekly via tools/knowledge_updater.py. Dedup is SHA256 of DOI/URL; scoring is a composite 0–10 of recency (0.4) + keyword relevance (0.4) + citation count (0.2). See PROJECT-detail.md for the crawl config and CLAUDE.md for the cron schedule.

Development

# Format/lint (recommended)
python -m py_compile tools/*.py          # byte-compile sanity check
python tools/test_thermal_analysis.py
python tools/test_knowledge_updater.py
python tools/validate_project.py
python tools/run_test_scenarios.py

The codebase targets Python 3.11+, uses the stdlib logging module, dataclasses for config, type hints throughout, and explicit exit codes. The thermal engine has zero third-party runtime dependencies (stdlib only) so it runs anywhere.

Roadmap

• Phase 0: Architecture
• Phase 1: Core sub-skills (5)
• Phase 2: Main harness + gates + degradation
• Phase 3: Knowledge pipeline
• Phase 4: Testing
• Phase 5: Integration & polish — PRODUCTION READY v2.0.0
  • Encoding audit (UTF-8 no-BOM)
  • Domain thermal engine (tools/thermal_analysis.py)
  • Executable harness orchestrator (tools/harness.py)
  • 8-File Contract validator (tools/validate_project.py)
  • LICENSE (MIT)

Contributing

Contributions are welcome. Please:

1. Open an issue describing the change.
2. Ensure python tools/validate_project.py, tools/run_test_scenarios.py, tools/test_thermal_analysis.py, and tools/test_knowledge_updater.py all pass.
3. Add/expand unit tests for any new domain method.
4. Keep all files UTF-8 no-BOM.

Acknowledgments

• ASHRAE TC 9.9 — Thermal Guidelines for Data Processing Environments
• The Green Grid — PUE / ERE / CUE metrics
• TIA-942 / Uptime Institute — reliability topology
• Academic venues: Applied Thermal Engineering, Int. J. Heat & Mass Transfer, Building and Environment, IEEE TCPMT, Sustainable Computing, Energy and Buildings

License

MIT — see LICENSE.

Citation

@software{small-datacenter-airflow-thermal-optimization,
  title  = {small-datacenter-airflow-thermal-optimization: Airflow & Temperature Optimization for Small Data Centers},
  year   = {2026},
  version= {1.1.0}
}