reservoir-engineering-claude — Summary

Claude-for-reservoir-engineering is a structured course teaching reservoir and petroleum engineers how to use Claude Code through domain-authentic exercises: production data QA, PVT unit bugs, decline curve analysis, material balance, nodal analysis, simulation preparation, and parallel sensitivity studies. The repo ships a reservoir-engineering skill, a run-tests skill, and a reservoir-reviewer subagent that checks unit consistency, correlation applicability, pyResToolbox parameter naming mistakes, and engineering sanity. Course modules (01–09) map directly to Claude Code features: explore/plan/code/verify loop, specific context, TDD, CLAUDE.md, skills, subagents, CLI workflow, MCP integration, and parallel fan-out. The project explicitly cites pyResToolbox and pyrestoolbox-mcp as the preferred library/MCP for calculations, prohibiting hand-rolled PVT formulas. Adapted from claude-code-for-hydrology by lorenliu13.

Differs from seeds: No seed addresses scientific/engineering domains. Closest to superpowers (skills + subagent, no commands) but the reservoir-reviewer agent's review criteria are domain-specific (units, correlation applicability, mass balance) rather than general code quality, and the course structure itself is the primary artifact — not just the skills.

reservoir-engineering-claude — Overview

Origin

Created by Gabriel Serrao, a reservoir engineering data scientist. Adapted from claude-code-for-hydrology (lorenliu13), which used the same exercise structure for hydrology workflows. Licensed MIT.

Philosophy

"The goal is not to make Claude 'do engineering' blindly. The goal is to teach engineers how to direct Claude like a disciplined technical assistant: give it context, constrain assumptions, require units, verify results, use tests, and prefer proven libraries or MCP tools over invented formulas."

The course emphasizes that AI tools accelerate reservoir engineering work only when the engineer:

• Supplies domain context explicitly (units, parameter names, correlation ranges)
• Demands verification (known-value tests, monotonicity checks, physical bounds)
• Prefers proven libraries (pyResToolbox, pyrestoolbox-mcp) over hand-rolled correlations

Target Audience

• Reservoir engineers learning AI-assisted coding
• Production engineers working with CSV exports and decline curves
• Petroleum engineering students who know the domain but want better coding workflows
• Data scientists supporting subsurface teams

Course Structure

9 modules mapping directly to Claude Code capabilities:

1. Explore/plan/code/verify loop
2. Specific context (PVT unit bugs)
3. Verify your work (DCA sanity checks)
4. CLAUDE.md project memory
5. Claude skills
6. Subagent review
7. CLI workflow for production CSV QA
8. MCP + pyResToolbox
9. Parallel fan-out for sensitivity studies

reservoir-engineering-claude — Architecture

Distribution

Standalone repository — clone and use as a course. No plugin, no npm package.

Install

git clone https://github.com/gabrielserrao/Claude-for-reservoir-engineering
pip install -r requirements.txt  # Python deps for exercises

Directory Tree

.
├── .claude/
│   ├── agents/
│   │   └── reservoir-reviewer.md         # Subagent: unit/correlation reviewer
│   └── skills/
│       ├── reservoir-engineering/
│       │   └── SKILL.md                  # Reservoir engineering skill
│       └── run-tests/
│           └── SKILL.md                  # Test runner skill
├── 01_explore_plan_code/                 # Production analysis exercises
├── 02_specific_context/                  # PVT conversion bug exercises
├── 03_verify_your_work/                  # DCA sanity check exercises
├── 04_init_claude_md/                    # CLAUDE.md project memory exercises
├── 05_skills/                            # Skills exercises
├── 06_subagent_review/                   # Subagent reviewer workflow exercises
├── 07_cli_workflow/                      # Shell + Python QA exercises
├── 08_mcp_pyrestoolbox/                  # pyResToolbox MCP exercises
├── 09_parallel_fanout/                   # Parallel sensitivity exercises
├── assets/                               # Generated plots and result tables
├── references/pyrestoolbox-workflows.md  # Workflow reference
├── scripts/generate_course_figures.py    # Figure generation
├── CLAUDE.md                             # Project memory file
├── requirements.txt
└── README.md

Required Runtime

• Python (for exercises)
• Claude Code
• pyRestoolbox Python package
• pyrestoolbox-mcp (optional, for Module 08)

Target AI Tools

• Claude Code (primary, .claude/ directory structure)

reservoir-engineering-claude — Components

Skills (2)

Agents (1)

Hooks (0)

None.

Course Modules (9)

MCP Server Referenced

pyrestoolbox-mcp — an MCP server wrapping pyResToolbox, allowing agents to call reservoir engineering calculations as MCP tools.

reservoir-engineering-claude — Uniqueness

Differs from Seeds

No seed addresses engineering science domains. Closest to superpowers (skills + subagent review, no commands), but the reservoir-reviewer agent's criteria are domain-specific: unit system consistency (psia vs barsa, degF vs degC), correlation applicability ranges (API gravity, gas gravity, pressure/temperature bounds), pyResToolbox parameter naming (sg vs sg_g by tool family), and engineering sanity (monotonicity of decline curves, mass balance, non-negative rates). This is the only entry in the corpus that treats physical unit consistency and correlation applicability as first-class review dimensions.

Positioning

An onboarding course for petroleum engineers, not a ready-to-use plugin. The primary value is pedagogical — mapping Claude Code concepts to engineering workflows engineers recognize. The skills and reviewer agent are secondary deliverables.

Observable Failure Modes

1. pyResToolbox API drift: Parameter naming pitfalls are pinned to a specific version of pyResToolbox; API changes break the documented patterns.
2. No automation: The reservoir-reviewer agent must be manually dispatched; there are no hooks to auto-trigger review.
3. Course vs production gap: The exercises are toy problems; real reservoir engineering workflows (large datasets, full-physics simulators) are not covered.

Explicit Antipatterns

• Hand-rolling PVT, VLP, material balance, or DCA formulas (use pyResToolbox)
• Skipping unit documentation in answers
• Trusting decline curve forecasts without monotonicity checks
• Using gas tool parameter names (sg) with oil tool APIs