Materials Simulation Skills

Open-source Agent Skills for computational materials science and numerical simulation workflows.

Give your AI coding agent domain expertise in numerical methods, simulation best practices, and scientific computing -- without re-explaining the same concepts every session. Skills are portable across Claude Code, Codex, Gemini CLI, Cursor, VS Code Copilot, and 20+ other compatible tools.

---

Table of Contents

• The Problem
• The Solution
• What's Inside
• How Skills Work
• Quick Start
• Adding Skills to Your Agent
  • Claude Code
  • Gemini CLI
  • OpenAI Codex
  • VS Code / GitHub Copilot
  • Cursor
  • Other Agents
• Repository Layout
• Contributing
• License
• Acknowledgements

---

The Problem

Simulation engineers repeat the same guidance to AI agents constantly: "Check the CFL number before running," "Use Richardson extrapolation for grid convergence," "Exit code 2 means bad input." General-purpose agents lack the domain knowledge to run reliable numerical simulations without heavy hand-holding.

The Solution

This project packages that domain knowledge into skills -- structured folders of instructions, scripts, and references that agents discover automatically and load on demand. Each skill teaches an agent a specific simulation competency, backed by validated Python scripts that produce reproducible results.

You: Check if dt=0.001 is stable for my advection problem with v=2.0 m/s and dx=0.01.

Agent: I'll use the numerical-stability skill to check this.
       [runs cfl_checker.py --dx 0.01 --dt 0.001 --velocity 2.0 --json]

       CFL number = 0.2 (limit: 1.0) -- stable.
       Recommended max dt = 0.005 with safety factor 1.0.

No prompt engineering. No copy-pasting formulas. The agent finds the right skill, runs the script, and interprets the results.

---

What's Inside

13 skills | 56 scripts | 738 tests | 50 examples | Cross-platform CI on Python 3.10-3.12

Core Numerical Skills (skills/core-numerical/)

Foundational numerical methods and analysis tools.

Skill	What it does
numerical-stability	CFL/Fourier analysis, von Neumann stability, stiffness detection, matrix conditioning
time-stepping	Time integrator selection, adaptive step-size control, output scheduling
mesh-generation	Mesh quality metrics (aspect ratio, skewness, orthogonality), refinement guidance
convergence-study	Grid/time convergence analysis, Richardson extrapolation, GCI calculation
numerical-integration	Quadrature rule selection, error estimation, adaptive stepping
differentiation-schemes	Finite difference stencil generation, truncation error analysis, scheme comparison
linear-solvers	Iterative/direct solver selection, preconditioner advice, convergence diagnostics
nonlinear-solvers	Newton/quasi-Newton/fixed-point selection, globalization strategies, convergence diagnostics

Simulation Workflow Skills (skills/simulation-workflow/)

End-to-end simulation management and automation.

Skill	What it does
simulation-validator	Pre-flight checks, runtime log monitoring, post-flight validation
parameter-optimization	DOE sampling (LHS, factorial), optimizer selection, sensitivity analysis
simulation-orchestrator	Parameter sweeps, batch campaign management, result aggregation
post-processing	Field extraction, time series analysis, derived quantity computation
performance-profiling	Timing analysis, scaling studies, memory profiling, bottleneck detection

---

How Skills Work

Skills follow the open Agent Skills standard. Each skill is a folder with three tiers of content, loaded progressively to keep context efficient:

skills/core-numerical/numerical-stability/
    SKILL.md              # Instructions + YAML metadata (loaded when skill triggers)
    scripts/              # Python CLI tools (executed for reproducible results)
        cfl_checker.py
        von_neumann_analyzer.py
        matrix_condition.py
        stiffness_detector.py
    references/           # Deep domain knowledge (loaded only when needed)
        stability_reference.md

1. Discovery -- The agent sees each skill's name and description at startup (~100 tokens per skill)
2. Activation -- When a task matches, the agent loads the full SKILL.md with decision guidance, workflows, and CLI examples
3. Execution -- Scripts run as subprocesses with --json output for structured, parseable results

All scripts are standalone CLI tools with --help, a pure-function core for testing, and consistent error handling (exit code 2 for bad input, 1 for runtime errors).

---

Quick Start

Install

git clone https://github.com/heshamfs/materials-simulation-skills.git
cd materials-simulation-skills
pip install -r requirements-dev.txt

Run a script directly

# Check CFL stability
python skills/core-numerical/numerical-stability/scripts/cfl_checker.py \
  --dx 0.01 --dt 0.001 --velocity 2.0 --diffusivity 1e-5 --json

# Generate a Latin Hypercube DOE
python skills/simulation-workflow/parameter-optimization/scripts/doe_generator.py \
  --params '{"temp": [300, 600], "pressure": [1, 10]}' --samples 20 --method lhs --json

# Analyze mesh quality
python skills/core-numerical/mesh-generation/scripts/mesh_quality.py \
  --mesh-file examples/mesh-generation/sample_mesh.json --json

Run the test suite

python -m pytest tests/ -v --tb=short          # All 738 tests
python -m pytest tests/unit -v --tb=short       # Unit tests only
python -m pytest tests/integration -v           # Integration tests only

---

Adding Skills to Your Agent

These skills follow the open Agent Skills standard and work across 20+ AI coding tools. Choose your agent below.

Claude Code

Copy individual skills (or the whole skills/ tree) into your personal or project skills directory:

# Personal (available across all projects)
cp -r skills/core-numerical/numerical-stability ~/.claude/skills/numerical-stability

# Project-level (committed to version control)
cp -r skills/core-numerical/numerical-stability .claude/skills/numerical-stability

Or clone the whole repo and point Claude Code at it with --add-dir:

claude --add-dir /path/to/materials-simulation-skills/skills

Verify with: What skills are available? or type / to see skills in the autocomplete menu.

See the Claude Code skills docs for more details.

Gemini CLI

Install directly from the repo, or copy skills into your Gemini skills directory:

# User-scoped (available across all workspaces)
cp -r skills/core-numerical/numerical-stability ~/.gemini/skills/numerical-stability

# Workspace-scoped (project-specific)
cp -r skills/core-numerical/numerical-stability .gemini/skills/numerical-stability

Verify with: gemini skills list

See the Gemini CLI skills docs for more details.

OpenAI Codex

Copy skills into one of the Codex skills directories:

# User-scoped
cp -r skills/core-numerical/numerical-stability ~/.agents/skills/numerical-stability

# Repository-scoped
cp -r skills/core-numerical/numerical-stability .agents/skills/numerical-stability

Restart Codex after adding skills. Use /skills or $ to invoke skills by name.

See the Codex skills docs for more details.

VS Code / GitHub Copilot

Copy skills into your workspace or personal skills directory:

# Workspace (committed to version control)
cp -r skills/core-numerical/numerical-stability .github/skills/numerical-stability

# Personal (across all workspaces)
cp -r skills/core-numerical/numerical-stability ~/.copilot/skills/numerical-stability

Type /skills in the chat input to see and invoke available skills.

See the VS Code skills docs for more details.

Cursor

Copy skills into a skills/ directory at your project root:

cp -r skills/core-numerical/numerical-stability skills/numerical-stability

Cursor's MCP server auto-discovers skills from the skills/ directory.

Other Agents

Any agent that supports the Agent Skills standard can use these skills. The general pattern:

1. Copy the skill directory (containing SKILL.md, scripts/, references/) into your agent's skills folder
2. The agent discovers the skill by its name and description in the YAML frontmatter
3. Mention the skill by name or ask a task that matches its description

Use numerical-stability to check a proposed dt for my phase-field run.

The agent loads the skill's instructions, runs the appropriate scripts, and interprets the results.

---

Repository Layout

skills/
    core-numerical/          # 8 skills: stability, solvers, meshing, convergence, ...
    simulation-workflow/     # 5 skills: validation, optimization, orchestration, ...
examples/                    # Shell scripts + sample data for every skill
tests/
    unit/                    # Pure-function tests via load_module()
    integration/             # Subprocess + JSON schema validation
.github/
    workflows/ci.yml         # Cross-platform CI (Ubuntu, Windows, macOS)
    ISSUE_TEMPLATE/          # Bug reports, skill proposals
    PULL_REQUEST_TEMPLATE.md # PR checklist

---

Contributing

We welcome contributions of all kinds -- new skills, bug fixes, documentation, and examples. The project is designed to grow from 13 skills across 2 categories into a broader collection spanning materials physics, verification & validation, HPC deployment, and more.

See CONTRIBUTING.md for:

• Step-by-step guide to creating a new skill
• Script, test, and example templates
• Skill taxonomy and open categories for community contributions
• PR guidelines and checklists

---

License

Apache 2.0

Acknowledgements

• Agent Skills standard -- Open specification for portable agent capabilities
• Anthropic -- Original developer of the Agent Skills format
• agentskills/agentskills -- Reference implementation and validation library