fair-simulation-packager

Materials Simulation Skills

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.

Validated, not just curated

Most agent-skill collections are unverified prompt text. These are measured:

• Tested scripts — every skill ships Python CLIs with a pure-function core (1283 tests, 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.
• Measured uplift — skills are evaluated with vs. without the skill across coding-agent CLIs; value is the pass-rate delta, not a claim.
• Cited science + an enforced protocol — rules reference authoritative standards (ASME V&V20, the SchedMD sbatch spec, CMSO IRIs).

How and why: evaluation methodology · harness.

---

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):

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

---

Star History