Solar Skills

Claude Code skills for exporting and AI-driven analysis of residential solar PV system data. Export skills pull hourly data from your inverter's cloud platform (SolisCloud or Deye/Solarman), then the analyze skill produces a consultant-style report.

Disclaimer

This tool is AI-assisted. While the underlying data (CSV export) comes directly from your inverter's API, the analysis report — including recommendations, projections, and financial estimates — is generated by an AI model. Results may contain inaccuracies, misinterpretations, or errors. Always verify critical findings (especially financial and equipment-related decisions) against your own records, manufacturer specifications, or a qualified solar professional before acting on them.

Why Bother?

Most solar monitoring apps show you charts but don't tell you what to do. This tool bridges that gap. The heavy lifting — aggregation, EV day detection, efficiency calculations, bill modelling — is done by a deterministic Python script, not the AI. The AI's role is interpreting those numbers in context: writing the narrative, inferring seasonal factors from your location, and tailoring recommendations to your setup. It won't replace a professional audit, but it surfaces patterns you'd likely miss scrolling through dashboards — and it's a solid starting point for deciding where to focus.

Skills

/solar-skills:export-hourly-soliscloud

Exports monthly 5-minute interval data from a SolisCloud-monitored solar+battery system and aggregates it into hourly CSV files.

• Two export methods: API (primary, ~15s/month) or browser automation (fallback — cmux agent browser preferred, then Chrome DevTools MCP, then Claude in Chrome)
• Pure Python stdlib — no pip dependencies for the API method
• Outputs standardized CSV with PV, battery, grid, load, and SOC columns

/solar-skills:export-hourly-deye

Exports monthly 5-minute interval data from a Deye inverter via the Solarman Open API and aggregates it into hourly CSV files.

• API-only — direct REST API calls via Solarman Open API, no browser needed
• Auto-discovery — finds station and device automatically if not configured
• Pure Python stdlib — no pip dependencies
• Outputs standardized CSV with PV, battery, grid, load, and SOC columns

/solar-skills:analyze

AI-driven analysis of the exported hourly CSV data that produces a detailed performance report with actionable recommendations.

• Monthly totals, EV day detection, hourly patterns, weekday/weekend analysis
• System sizing evaluation, battery health, inverter clipping detection
• Bill impact with flat/tiered/TOU tariff support, ROI calculation
• Anomaly detection, annual projection, carbon offset estimation
• 180-test suite included

Analysis Coverage

The /solar-skills:analyze report covers the following areas, written in a consultant narrative style with quantified findings and actionable guidance:

Question Flow

The /solar-skills:analyze skill asks only 9 questions. Long intake forms cause users to abandon the process or guess at values they don't actually know, which degrades analysis quality. These questions are limited to facts the homeowner knows offhand (system size, battery capacity, electricity rate) that can't be reliably inferred from meter data alone. Everything else — self-consumption rate, battery efficiency, EV detection thresholds, anomaly baselines, seasonal patterns — is computed directly from the CSV data, which is more accurate than asking the owner to estimate.

1. What city/province are you in? — infers latitude, seasonal profile, grid emission factor, currency
2. Do you have an EV or PHEV? — Yes / No
3. What is your PV system size in kWp?
4. What is your inverter capacity in kW? — value or "I don't know" (estimates as PV ÷ 1.3)
5. Do you have a battery? — Yes / No
   ├─ Yes → What is your battery capacity? — kWh or Voltage × Ah
   └─ No → battery sections skipped
6. Is there room for additional panels? — No / specify kWp
7. What is your tariff structure?
   ├─ Flat → import rate
   ├─ Tiered → import rate + tier thresholds/rates
   └─ TOU → import rate + peak/off-peak hours/rates
8. Do you want an ROI estimate? — No / Yes
   └─ Yes → total cost, system age
        └─ if battery → battery cost (for with-vs-without comparison)
9. What is your feed-in tariff arrangement? — none / ~50% of import / specify ratio

Installation

Option A: Install as a plugin (recommended)

/plugin marketplace add marfillaster/solar-skills
/plugin install solar-skills@marfillaster-solar-skills

Once installed, the /solar-skills:export-hourly-soliscloud, /solar-skills:export-hourly-deye, and /solar-skills:analyze slash commands become available in Claude Code.

Option B: Symlink into your project

Copy or symlink the skills into any project's .claude/skills/ directory:

mkdir -p .claude/skills
ln -s /path/to/solar-skills/skills/analyze .claude/skills/analyze
ln -s /path/to/solar-skills/skills/export-hourly-soliscloud .claude/skills/export-hourly-soliscloud
ln -s /path/to/solar-skills/skills/export-hourly-deye .claude/skills/export-hourly-deye

Skills loaded this way are available without the namespace prefix: /analyze, /export-hourly-soliscloud, /export-hourly-deye.

Option C: Local development (this repo)

If you've cloned this repo and want to test skills without installing the plugin, run the one-time setup from the repo root:

mkdir -p .claude/skills
ln -s ../../skills/analyze .claude/skills/analyze
ln -s ../../skills/export-hourly-soliscloud .claude/skills/export-hourly-soliscloud
ln -s ../../skills/export-hourly-deye .claude/skills/export-hourly-deye

Then open Claude Code from inside the repo directory. The skills are available as /analyze, /export-hourly-soliscloud, and /export-hourly-deye (no solar-skills: prefix). Any edits to files under skills/ take effect immediately, and new skills are picked up automatically — no reinstall needed.

Option D: Install for Codex

Symlink the skills into your global Codex skills directory:

mkdir -p ~/.codex/skills
ln -s /path/to/solar-skills/skills/analyze ~/.codex/skills/analyze
ln -s /path/to/solar-skills/skills/export-hourly-soliscloud ~/.codex/skills/export-hourly-soliscloud
ln -s /path/to/solar-skills/skills/export-hourly-deye ~/.codex/skills/export-hourly-deye

Then invoke them in Codex with prompts such as:

Use $export-hourly-soliscloud to export my SolisCloud data for 2026-02.
Use $export-hourly-deye to export my Deye/Solarman data for 2026-02.
Use $analyze to analyze my solar CSV data and produce a report.

Codex note: $export-hourly-soliscloud can use direct API credentials, but its browser fallback needs a browser backend. If you do not have SolisCloud API credentials configured, set one up before relying on the fallback path.

Cross-agent note: the browser backend must be available in the specific agent environment that runs the skill. If you use both Claude Code and Codex, or if work may be delegated to another agent/session, each runtime that needs the fallback path needs its own access.

Preferred backend — cmux agent browser. If cmux is installed and its browser panel is enabled, the skill uses it automatically. Nothing to install per agent: the skill drives it through the cmux browser CLI from Bash, so it works the same in Claude Code, Codex, or any agent with shell access.

command -v cmux && cmux browser-status   # expect: enabled
cmux enable-browser                      # if it reports disabled

Fallback backend — Chrome DevTools MCP, used only when cmux is unavailable:

# Claude Code
claude mcp add chrome-devtools -- npx chrome-devtools-mcp@latest

# Codex
codex mcp add chrome-devtools -- npx chrome-devtools-mcp@latest

Last resort — Claude in Chrome, used when neither of the above is available. It can't read the httpOnly session cookie, so chrome_fetch.py --serve runs a one-shot listener on 127.0.0.1: the logged-in page fetches signed requests from it, sends them with its own cookie, and posts the responses back. Nothing to install beyond the extension itself.

If you're developing inside this repo, you can also point the symlinks directly at this checkout so edits under skills/ are picked up immediately.

Quick Start

1. Set up SolisCloud API credentials

Request API access from Solis support, then add to your shell profile:

export SOLISCLOUD_API_KEY="your_key_id"
export SOLISCLOUD_API_SECRET="your_key_secret"
export SOLISCLOUD_STATION_ID="your_station_id"
export SOLISCLOUD_INVERTER_SN="your_inverter_sn"

2. Export data

/solar-skills:export-hourly-soliscloud 2026-02

3. Run analysis

/solar-skills:analyze

The analysis skill asks for system parameters interactively (PV size, battery capacity, tariff, etc.) and writes a report to data/solar-analysis.md.

Project Structure

solar-skills/
├── .claude-plugin/
│   ├── plugin.json           # Plugin metadata
│   └── marketplace.json      # Marketplace manifest
└── skills/
    ├── analyze/
    │   ├── SKILL.md              # Claude Code skill definition
    │   ├── README.md             # Detailed documentation
    │   └── scripts/
    │       ├── analyze.py        # Analysis engine (pure stdlib)
    │       └── test_check.py     # 180-test suite
    ├── export-hourly-deye/
    │   ├── SKILL.md              # Claude Code skill definition
    │   ├── README.md             # Detailed documentation
    │   └── scripts/
    │       └── api_export.py     # API-based export (pure stdlib)
    └── export-hourly-soliscloud/
        ├── SKILL.md              # Claude Code skill definition
        ├── README.md             # Detailed documentation
        └── scripts/
            ├── api_export.py     # API-based export (pure stdlib)
            └── chrome_fetch.py   # Browser fallback bulk fetcher (auth from cmux or DevTools MCP, or a page relay via Claude in Chrome)

Requirements

• Python 3
• Claude Code
• SolisCloud account with API access, or Solarman Smart account with API access (for Deye inverters)

Claude Code authentication

Any Claude Code authentication method works (Pro/Max subscription or API key). To use an API key: sign up at console.anthropic.com, add billing, generate a key, then set it in your shell profile:

export ANTHROPIC_API_KEY="sk-ant-..."

The browser fallback needs one of three backends. It prefers the cmux agent browser (cmux, browser panel enabled — check with cmux browser-status), which is driven entirely from Bash via cmux browser and needs no MCP server. When cmux is not available it falls back to the Chrome DevTools MCP plugin, installed and configured in Claude Code, and failing that to Claude in Chrome.

CSV Format

All export methods produce identical output in data/solar_hourly_YYYY-MM.csv with 16 columns covering PV generation, battery flow, grid import/export, loads, and battery SOC. Sign conventions:

• Battery: positive = charging, negative = discharging
• Grid: positive = export, negative = import

See each skill's README for full details.

Data directory

The skills read and write CSVs (and the report) under data/ in the current working directory by default. Set the SOLAR_DATA_DIR environment variable to use a different directory — absolute, or relative to the current working directory. It is honored by the analysis script and every export path, so exports and analysis stay in sync. Useful for keeping the data in a synced or version-controlled folder outside the repo.