oil-and-gas-claude-skills

# Oil and Gas Engineering Agent Instructions

> Universal agent instructions file. Compatible with OpenAI Codex CLI, Cursor, Aider, Continue,
> Cline, Roo, OpenCode, Gemini CLI, and any agent that reads `AGENTS.md` or `CLAUDE.md`.

---

## What this repository does

This library provides AI coding agent skills for the **oil and gas engineering** domain. Each skill
gives the agent deep, domain-specific knowledge to analyze engineering files, extract structured data,
and assist with petroleum engineering workflows.

When working in a project that involves oil and gas data, activate the relevant skill before
performing analysis.

---

## Available skills and when to use them

### Oil & Gas Data Manager — `skills/oil_and_gas_data_manager/`
**Use when:** User uploads or references any engineering file (PDF, LAS, XLSX, CSV, DLIS, DOCX).
Detects file type, routes to the correct parser, extracts structured data, links to project context.
Read `skills/oil_and_gas_data_manager/SKILL.md` before responding to these requests.

**Trigger phrases:**
- "analyze these drilling files"
- "identify oil and gas file types"
- "extract well data from these reports"
- "parse this LAS file"
- "what data can you get from these files?"

---

### Drilling KPI Analyzer — `skills/drilling_kpi_analyzer/`
**Use when:** User has daily drilling reports (DDRs), morning reports, or bit records and wants
performance analysis. Read `skills/drilling_kpi_analyzer/SKILL.md`.

**Trigger phrases:**
- "analyze drilling performance"
- "compute drilling KPIs"
- "benchmark ROP"
- "NPT breakdown"
- "flat time analysis"

---

### Well Log Interpreter — `skills/well_log_interpreter/`
**Use when:** User has LAS or DLIS well log files and wants petrophysical interpretation,
formation top picking, or pay zone identification. Read `skills/well_log_interpreter/SKILL.md`.

**Trigger phrases:**
- "interpret this LAS file"
- "find pay zones"
- "compute porosity and water saturation"
- "pick formation tops"
- "analyze well logs"

---

### Completion Design Reviewer — `skills/completion_design_reviewer/`
**Use when:** User has completion design spreadsheets, frac stage sheets, or pump schedules
and wants validation, QC, or offset comparison. Read `skills/completion_design_reviewer/SKILL.md`.

**Trigger phrases:**
- "review completion design"
- "check frac stage parameters"
- "validate pump schedule"
- "compare against offset wells"

---

### Production Data Analyst — `skills/production_data_analyst/`
**Use when:** User has production history data, production test reports, or decline curves.
Read `skills/production_data_analyst/SKILL.md`.

**Trigger phrases:**
- "analyze production data"
- "run decline curve"
- "what are the IP30/IP90 rates"
- "estimate EUR"
- "check production allocation"

---

### Directional Survey Analyzer — `skills/directional_survey_analyzer/`
**Use when:** User has directional survey files and wants trajectory validation, DLS computation,
or anticollision checks. Read `skills/directional_survey_analyzer/SKILL.md`.

**Trigger phrases:**
- "analyze directional survey"
- "compute dogleg severity"
- "validate wellbore trajectory"
- "check anticollision"

---

### HSE Incident Tracker — `skills/hse_incident_tracker/`
**Use when:** User wants safety events, near misses, NPT, or HSE incidents extracted from
drilling reports. Read `skills/hse_incident_tracker/SKILL.md`.

**Trigger phrases:**
- "extract HSE events"
- "safety incident log"
- "NPT by cause"
- "IADC classification"

---

## Key rules for all agents

1. **Read the SKILL.md first** before answering domain questions — it contains extraction schemas,
   routing rules, and sanity checks that must be followed.

2. **Never fabricate engineering values** — if extraction confidence is low, flag it with a
   quality warning instead of guessing.

3. **Preserve units** — always record the original unit alongside any normalized value.

4. **Use the output schema** — return structured JSON matching the schema in each `SKILL.md`
   when the user asks for structured output.

5. **Flag sanity check failures** — mud weight outside 6–22 ppg, inclination > 180°,
   TVD > MD, and other impossible values must be flagged, not silently accepted.

6. **Source every extraction** — include page number, section, or depth range as a reference
   for every extracted value.

---

## Python implementation

The Oil & Gas Data Manager has a full Python implementation:

```bash
pip install oil-and-gas-claude-skills
```

Or install from source:
```bash
pip install -e .
```

Run directly:
```bash
python -m skills.oil_and_gas_data_manager.skill report.pdf log.las
```

MCP server (for agents with MCP support):
```bash
python -m mcp_server.server
```

---

## Supported file types

| Extension | Type | Skill |
|---|---|---|
| `.las` | LAS well log | Oil & Gas Data Manager, Well Log Interpreter |
| `.dlis`, `.lis` | DLIS log container | Oil & Gas Data Manager, Well Log Interpreter |
| `.pdf` | Drilling/completion report | Oil & Gas Data Manager, Drilling KPI Analyzer, HSE |
| `.xlsx`, `.xls` | Engineering spreadsheets | Oil & Gas Data Manager, Completion Design Reviewer |
| `.csv` | Sensor/parameter data | Oil & Gas Data Manager, Directional Survey Analyzer |
| `.docx` | Well programs, procedures | Oil & Gas Data Manager |
| `.xml` | WITSML exports | Oil & Gas Data Manager |