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. - The Proble
Add this skill
npx mdskills install HeshamFS/materials-simulation-skillsComprehensive collection of 13 numerical simulation skills with validated scripts and extensive test coverage
1# Materials Simulation Skills23[](https://github.com/heshamfs/materials-simulation-skills/actions/workflows/ci.yml)4[](LICENSE)5[](https://agentskills.io)6[](https://www.python.org/)78**Open-source [Agent Skills](https://agentskills.io) for computational materials science and numerical simulation workflows.**910Give 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](https://agentskills.io).1112---1314## Table of Contents1516- [The Problem](#the-problem)17- [The Solution](#the-solution)18- [What's Inside](#whats-inside)19- [How Skills Work](#how-skills-work)20- [Quick Start](#quick-start)21- [Adding Skills to Your Agent](#adding-skills-to-your-agent)22 - [Claude Code](#claude-code)23 - [Gemini CLI](#gemini-cli)24 - [OpenAI Codex](#openai-codex)25 - [VS Code / GitHub Copilot](#vs-code--github-copilot)26 - [Cursor](#cursor)27 - [Other Agents](#other-agents)28- [Repository Layout](#repository-layout)29- [Contributing](#contributing)30- [License](#license)31- [Acknowledgements](#acknowledgements)3233---3435## The Problem3637Simulation 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.3839## The Solution4041This 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.4243```text44You: Check if dt=0.001 is stable for my advection problem with v=2.0 m/s and dx=0.01.4546Agent: I'll use the numerical-stability skill to check this.47 [runs cfl_checker.py --dx 0.01 --dt 0.001 --velocity 2.0 --json]4849 CFL number = 0.2 (limit: 1.0) -- stable.50 Recommended max dt = 0.005 with safety factor 1.0.51```5253No prompt engineering. No copy-pasting formulas. The agent finds the right skill, runs the script, and interprets the results.5455---5657## What's Inside5859**13 skills** | **56 scripts** | **738 tests** | **50 examples** | Cross-platform CI on Python 3.10-3.126061### Core Numerical Skills (`skills/core-numerical/`)6263Foundational numerical methods and analysis tools.6465| Skill | What it does |66|-------|-------------|67| `numerical-stability` | CFL/Fourier analysis, von Neumann stability, stiffness detection, matrix conditioning |68| `time-stepping` | Time integrator selection, adaptive step-size control, output scheduling |69| `mesh-generation` | Mesh quality metrics (aspect ratio, skewness, orthogonality), refinement guidance |70| `convergence-study` | Grid/time convergence analysis, Richardson extrapolation, GCI calculation |71| `numerical-integration` | Quadrature rule selection, error estimation, adaptive stepping |72| `differentiation-schemes` | Finite difference stencil generation, truncation error analysis, scheme comparison |73| `linear-solvers` | Iterative/direct solver selection, preconditioner advice, convergence diagnostics |74| `nonlinear-solvers` | Newton/quasi-Newton/fixed-point selection, globalization strategies, convergence diagnostics |7576### Simulation Workflow Skills (`skills/simulation-workflow/`)7778End-to-end simulation management and automation.7980| Skill | What it does |81|-------|-------------|82| `simulation-validator` | Pre-flight checks, runtime log monitoring, post-flight validation |83| `parameter-optimization` | DOE sampling (LHS, factorial), optimizer selection, sensitivity analysis |84| `simulation-orchestrator` | Parameter sweeps, batch campaign management, result aggregation |85| `post-processing` | Field extraction, time series analysis, derived quantity computation |86| `performance-profiling` | Timing analysis, scaling studies, memory profiling, bottleneck detection |8788---8990## How Skills Work9192Skills follow the open [Agent Skills standard](https://agentskills.io/specification). Each skill is a folder with three tiers of content, loaded progressively to keep context efficient:9394```95skills/core-numerical/numerical-stability/96 SKILL.md # Instructions + YAML metadata (loaded when skill triggers)97 scripts/ # Python CLI tools (executed for reproducible results)98 cfl_checker.py99 von_neumann_analyzer.py100 matrix_condition.py101 stiffness_detector.py102 references/ # Deep domain knowledge (loaded only when needed)103 stability_reference.md104```1051061. **Discovery** -- The agent sees each skill's name and description at startup (~100 tokens per skill)1072. **Activation** -- When a task matches, the agent loads the full `SKILL.md` with decision guidance, workflows, and CLI examples1083. **Execution** -- Scripts run as subprocesses with `--json` output for structured, parseable results109110All 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).111112---113114## Quick Start115116### Install117118```bash119git clone https://github.com/heshamfs/materials-simulation-skills.git120cd materials-simulation-skills121pip install -r requirements-dev.txt122```123124### Run a script directly125126```bash127# Check CFL stability128python skills/core-numerical/numerical-stability/scripts/cfl_checker.py \129 --dx 0.01 --dt 0.001 --velocity 2.0 --diffusivity 1e-5 --json130131# Generate a Latin Hypercube DOE132python skills/simulation-workflow/parameter-optimization/scripts/doe_generator.py \133 --params '{"temp": [300, 600], "pressure": [1, 10]}' --samples 20 --method lhs --json134135# Analyze mesh quality136python skills/core-numerical/mesh-generation/scripts/mesh_quality.py \137 --mesh-file examples/mesh-generation/sample_mesh.json --json138```139140### Run the test suite141142```bash143python -m pytest tests/ -v --tb=short # All 738 tests144python -m pytest tests/unit -v --tb=short # Unit tests only145python -m pytest tests/integration -v # Integration tests only146```147148---149150## Adding Skills to Your Agent151152These skills follow the open [Agent Skills standard](https://agentskills.io) and work across 20+ AI coding tools. Choose your agent below.153154### Claude Code155156Copy individual skills (or the whole `skills/` tree) into your personal or project skills directory:157158```bash159# Personal (available across all projects)160cp -r skills/core-numerical/numerical-stability ~/.claude/skills/numerical-stability161162# Project-level (committed to version control)163cp -r skills/core-numerical/numerical-stability .claude/skills/numerical-stability164```165166Or clone the whole repo and point Claude Code at it with `--add-dir`:167168```bash169claude --add-dir /path/to/materials-simulation-skills/skills170```171172Verify with: `What skills are available?` or type `/` to see skills in the autocomplete menu.173174See the [Claude Code skills docs](https://code.claude.com/docs/en/skills) for more details.175176### Gemini CLI177178Install directly from the repo, or copy skills into your Gemini skills directory:179180```bash181# User-scoped (available across all workspaces)182cp -r skills/core-numerical/numerical-stability ~/.gemini/skills/numerical-stability183184# Workspace-scoped (project-specific)185cp -r skills/core-numerical/numerical-stability .gemini/skills/numerical-stability186```187188Verify with: `gemini skills list`189190See the [Gemini CLI skills docs](https://geminicli.com/docs/cli/skills/) for more details.191192### OpenAI Codex193194Copy skills into one of the Codex skills directories:195196```bash197# User-scoped198cp -r skills/core-numerical/numerical-stability ~/.agents/skills/numerical-stability199200# Repository-scoped201cp -r skills/core-numerical/numerical-stability .agents/skills/numerical-stability202```203204Restart Codex after adding skills. Use `/skills` or `$` to invoke skills by name.205206See the [Codex skills docs](https://developers.openai.com/codex/skills) for more details.207208### VS Code / GitHub Copilot209210Copy skills into your workspace or personal skills directory:211212```bash213# Workspace (committed to version control)214cp -r skills/core-numerical/numerical-stability .github/skills/numerical-stability215216# Personal (across all workspaces)217cp -r skills/core-numerical/numerical-stability ~/.copilot/skills/numerical-stability218```219220Type `/skills` in the chat input to see and invoke available skills.221222See the [VS Code skills docs](https://code.visualstudio.com/docs/copilot/customization/agent-skills) for more details.223224### Cursor225226Copy skills into a `skills/` directory at your project root:227228```bash229cp -r skills/core-numerical/numerical-stability skills/numerical-stability230```231232Cursor's MCP server auto-discovers skills from the `skills/` directory.233234### Other Agents235236Any agent that supports the [Agent Skills standard](https://agentskills.io) can use these skills. The general pattern:2372381. Copy the skill directory (containing `SKILL.md`, `scripts/`, `references/`) into your agent's skills folder2392. The agent discovers the skill by its `name` and `description` in the YAML frontmatter2403. Mention the skill by name or ask a task that matches its description241242```text243Use numerical-stability to check a proposed dt for my phase-field run.244```245246The agent loads the skill's instructions, runs the appropriate scripts, and interprets the results.247248---249250## Repository Layout251252```253skills/254 core-numerical/ # 8 skills: stability, solvers, meshing, convergence, ...255 simulation-workflow/ # 5 skills: validation, optimization, orchestration, ...256examples/ # Shell scripts + sample data for every skill257tests/258 unit/ # Pure-function tests via load_module()259 integration/ # Subprocess + JSON schema validation260.github/261 workflows/ci.yml # Cross-platform CI (Ubuntu, Windows, macOS)262 ISSUE_TEMPLATE/ # Bug reports, skill proposals263 PULL_REQUEST_TEMPLATE.md # PR checklist264```265266---267268## Contributing269270We 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.271272See **[CONTRIBUTING.md](CONTRIBUTING.md)** for:273- Step-by-step guide to creating a new skill274- Script, test, and example templates275- Skill taxonomy and open categories for community contributions276- PR guidelines and checklists277278---279280## License281282[Apache 2.0](LICENSE)283284## Acknowledgements285286- [Agent Skills standard](https://agentskills.io) -- Open specification for portable agent capabilities287- [Anthropic](https://anthropic.com) -- Original developer of the Agent Skills format288- [agentskills/agentskills](https://github.com/agentskills/agentskills) -- Reference implementation and validation library289
Full transparency — inspect the skill content before installing.