Skip to main content

Materials Simulation Skills

CI License Agent Skills Python 3.10-3.12 Skills Deterministic eval coverage

Give your AI coding agent real expertise in numerical methods, simulation best practices, and computational materials science — so it stops guessing.

New to Agent Skills? A "skill" is a portable folder of instructions + small scripts that an AI coding agent discovers automatically and loads only when relevant. They follow the open Agent Skills standard and work across 20+ tools — Claude Code, Codex, Cursor, Antigravity, GitHub Copilot, and more. Nothing to wire up: drop them in and your agent gets smarter at the task.


What it solves

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 — so they pick wrong time steps, miss convergence checks, and misread solver failures.

This project packages that domain knowledge into skills the agent finds and runs on its own:

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. 24 skills span numerical methods, simulation workflows, HPC deployment, verification & validation, FAIR data, robustness, and materials ontologies.

Tested scripts and explicit validation limits

The repository includes executable checks at several levels:

  • Tested scripts — unit, integration, analytic-oracle and negative-control tests exercise the Python CLIs and numerical cores. CI targets Python 3.10–3.12.
  • 100% deterministic eval coverage — every eval case runs the script and asserts its exact output, so docs can't silently drift from code. Enforced in CI.
  • Agent evaluation support — the harness compares runs with and without a skill. Harness tests and deterministic coverage do not establish an improvement in agent scientific correctness.
  • Cited science + an enforced protocol — rules reference authoritative standards (ASME V&V20, the SchedMD sbatch spec, CMSO IRIs).

How and why: evaluation methodology · harness.

Latest deterministic evaluation (2026-10-20): 115 cases, 131 checks, 725 assertions passed. Live-agent uplift remains unvalidated.

See validation scope and remaining limits before interpreting a passing check as evidence about a physical simulation.


Install

The repo follows the open standard, so the ecosystem installers work out of the box:

npx skills add HeshamFS/materials-simulation-skills          # any agent → ~/.agents/skills/
gh skill install HeshamFS/materials-simulation-skills --pin v1.0.0   # version-pinned

Or install a curated bundle into a specific agent with the bundled mss CLI:

mss bundles                                                  # list bundles
mss install --agent claude --bundle verification-and-validation

Claude Code users can also /plugin marketplace add HeshamFS/materials-simulation-skills. Full per-agent guide → docs/INSTALL.md.


Use it

Once installed, just describe your task — the agent picks the right skill, runs the script, and interprets the result (as in the example above). You can also name a skill explicitly:

Use convergence-study to check if my mesh is in the asymptotic range:
h = 0.4, 0.2, 0.1 gave stress = 98.5, 99.6, 99.9 MPa.

Browse the full catalog in docs/SKILLS.md (or the machine-readable skills_index.json).

Try it locally / develop:

git clone https://github.com/HeshamFS/materials-simulation-skills.git
cd materials-simulation-skills && pip install -e ".[dev]"

mss list                                              # list skills
mss run numerical-stability cfl_checker -- --dx 0.01 --dt 0.001 --velocity 2.0 --json
mss eval                                              # run the deterministic eval gate
python -m pytest tests/                               # full test suite

What's inside

24 skills across 8 categories (one-line summary; full tables in docs/SKILLS.md):

Category Skills Focus
Core Numerical 8 stability, time-stepping, meshing, convergence, integration, differentiation, linear/nonlinear solvers
Simulation Workflow 7 validation, DOE/optimization, orchestration, post-processing, profiling, workflow mapping, MD analysis
HPC Deployment 2 SLURM script generation, runtime diagnosis
Verification & Validation 1 manufactured solutions, benchmarks, pass/fail reports
Data Management 1 FAIR reproducibility packaging
Robustness 1 cross-code failure triage & retry ladders
Ontology 3 CMSO/ASMO exploration, mapping, validation
Meta 1 skill-evaluator — evaluate any skill across any agent CLI

Quality is gated in CI: spec-valid frontmatter, deterministic script_checks, the standardized Security section, and a fresh index — see docs/PROTOCOL.md and docs/SECURITY.md.


Contributing

This is an open project and contributions are very welcome — a new skill, a fix, docs, or just an idea.

  • Have an idea or a skill to propose? Open an issue (there are templates for bug reports and skill proposals) — early ideas are great even without code.
  • Want to build a skill? CONTRIBUTING.md has a step-by-step guide, script/test templates, the skill taxonomy, and open categories. The bar that keeps this project trustworthy: a skill ships a tested script + an eval case with a deterministic script_check, and passes mss validate + mss eval.
  • Where it's headed: the ROADMAP.md — growing toward materials-physics and code-interface skills (LAMMPS, DFT) and a richer skill protocol.

Documentation

Doc What's in it
docs/SKILLS.md Full skill catalog, how skills work, repo layout
docs/INSTALL.md Install for every supported agent
docs/EVALUATION_METHODOLOGY.md How skills are evaluated, with results
docs/EVAL_HARNESS.md The three-layer evaluation harness
docs/PROTOCOL.md The Materials Simulation Skill Protocol
docs/SECURITY.md Safeguards and security tiers
CONTRIBUTING.md · ROADMAP.md Contributing guide · direction

Star History

Star History Chart

License

Apache 2.0

Acknowledgements

Metadata

Release files for materials-simulation-skills 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for materials-simulation-skills 1.0.0
File Size Uploaded Provenance Actions
materials_simulation_skills-1.0.0.tar.gz 558.4 kB With provenance Details for materials_simulation_skills-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for materials-simulation-skills 1.0.0
File Interpreter ABI Platform Actions
materials_simulation_skills-1.0.0-py3-none-any.whl Python 3 none any Details for materials_simulation_skills-1.0.0-py3-none-any.whl

Total release size: 1.3 MB

Release files / materials_simulation_skills-1.0.0.tar.gz

Download URL materials_simulation_skills-1.0.0.tar.gz
Size 558.4 kB
Tags Source
SHA-256 checksum
How to use checksums
2ed15ca0ee8b323ddef0dc9b245f54334047cd7ffc9ff2085985de579bf2c157
BLAKE2b-256 checksum
How to use checksums
50e6d5510598fa1dc44c6d377ace870392422afddf73ceaf98b66e8dc4aa4ea5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / materials_simulation_skills-1.0.0-py3-none-any.whl

Download URL materials_simulation_skills-1.0.0-py3-none-any.whl
Size 700.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c7d9ecd9e53607013b68ac09e9e554067dd57040b0085738f4a750fba57a0f2e
BLAKE2b-256 checksum
How to use checksums
a7ad47a8d514f10cca36a5421d20c5090f6aa253d3bac82b03e179d8452fecd4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for materials-simulation-skills 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for materials_simulation_skills-1.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page