⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
fair-simulation-packager
>
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
// README
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.
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
sbatchspec, 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 passesmss 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
// HOW IT'S BUILT
// FILES
2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
skills/data-management/fair-simulation-packager/SKILL.md7.8 KBupstream ↗
--- name: fair-simulation-packager description: > Create FAIR-minded reproducibility bundles for materials simulations by collecting input/output file inventories, hashes, units, engine versions, structure identifiers, provenance, and NOMAD/OPTIMADE/Materials Project friendly metadata. Use before publishing, sharing, archiving, or handing simulation results to another agent. allowed-tools: Read, Bash, Write, Grep, Glob metadata: author: HeshamFS version: "1.2.2" security_tier: high security_reviewed: true tested_with: - claude-code last_evaluated: "2026-06-23" eval_cases: 3 last_reviewed: "2026-06-24" standards: - "FAIR Guiding Principles (Wilkinson et al. 2016, Sci. Data)" - "OPTIMADE API specification" - "NOMAD Metainfo / Materials Project metadata schema" - "FIPS 180-4 Secure Hash Standard (SHA-256)" --- # FAIR Simulation Packager ## Goal Build a minimal reproducibility manifest for materials simulation results so another person or agent can understand what was run, with which inputs, and how outputs should be interpreted. ## Requirements - Python 3.10+ - No external dependencies - Works on Linux, macOS, and Windows ## Inputs to Gather | Input | Description | Example | |-------|-------------|---------| | Project name | Human-readable bundle name | `al-cu-diffusion-study` | | Engine | Simulation code | `LAMMPS`, `VASP`, `MOOSE` | | Input files | Files needed to rerun | `in.lammps,data.lmp` | | Output files | Files needed to verify results | `log.lammps,traj.dump` | | Structure ID | Database or local identifier | `mp-149` | | Units | Field/unit mapping | `energy=eV,length=angstrom` | ## Decision Guidance - Always include input files, output files, code version, and units. - Include hashes for every file that exists locally. - Include structure identifiers when using Materials Project, NOMAD, OPTIMADE, CIF, POSCAR, or internal database records. - Record missing files as warnings instead of silently dropping them. ## Script Outputs `scripts/fair_packager.py --json` prints an envelope with two top-level keys: - `inputs`: the parsed CLI arguments echoed back (note: `inputs.inputs` is the raw comma-separated string passed via `--inputs`, not the per-file records). - `results`: contains a single key `manifest`. `results.manifest` contains these fields: - `project_name`, `engine`, `engine_version`, `structure_id`, `units` - `file_inventory` with `inputs` and `outputs`, each a list of per-file records (`path`, `exists`, and when the file exists, `size_bytes` and `sha256`) - `missing_files`: paths that do not exist on disk - `provenance` (`working_directory`, `manifest_schema`) - `fair_checks`: `has_inputs`, `has_outputs`, `has_units`, `has_engine_version`, and `has_hashes_for_existing_files` (`true`/`false`, or `null` when no files exist so the check is not applicable) - `recommended_next_steps` Parse fields at `results.manifest.<field>`. When `--out PATH` is given, only the bare `manifest` object (not the `inputs`/`results` envelope) is written to `PATH`. ## Workflow ```bash python3 skills/data-management/fair-simulation-packager/scripts/fair_packager.py \ --project-name al-cu-diffusion \ --engine LAMMPS \ --inputs in.lammps,data.lmp \ --outputs log.lammps,traj.dump \ --units energy=eV,length=angstrom,time=ps \ --structure-id local:alcu-cell-001 \ --json ``` Use `--out manifest.json` only when the user wants a manifest file written. ## Error Handling Missing files are reported in `missing_files` (exit code 0). Invalid input stops with exit code 2: malformed unit entries, fields containing control characters, fields longer than 4096 characters, more than 1000 input or output entries, or a file larger than 500 MB. Note that ordinary file paths — including absolute paths and paths containing `..` — are accepted and inventoried; the tool reads file contents only to compute metadata and SHA-256 hashes. ## Limitations This skill creates a metadata manifest. It does not upload to NOMAD, Materials Project, or an OPTIMADE provider. ## Verification checklist - [ ] Confirmed `fair_checks.has_hashes_for_existing_files` is `true` (not `null` or `false`); a `null` means no listed file existed on disk, so re-run from the directory where the files actually live before trusting the manifest. - [ ] Reviewed `missing_files` and confirmed it is empty, or recorded an explicit reason for each entry — every missing path means an input/output was named but not hashed, so the bundle is not reproducible as-is. - [ ] Spot-checked at least one `sha256` in `results.manifest.file_inventory` against an independent `sha256sum`/`Get-FileHash` of the same file to confirm the recorded digest matches the bytes on disk. - [ ] Confirmed `engine_version` is a real version string and not the default `"unknown"`; pass `--engine-version` so the bundle records the exact code build. - [ ] Verified `units` is non-empty and every reported quantity (energy, length, time, etc.) has an entry, so downstream consumers do not have to guess the unit system. - [ ] Confirmed `structure_id` is populated when a Materials Project / NOMAD / OPTIMADE / CIF / POSCAR structure was used, so the structure identity is recoverable. - [ ] When `--out PATH` was used, opened `PATH` and confirmed it holds the bare `manifest` object (not the `inputs`/`results` envelope) and that no unintended path outside the working directory was written. ## Common pitfalls & rationalizations | Tempting shortcut | Why it's wrong / what to do | |-------------------|-----------------------------| | "It exited 0, so the bundle is complete." | Exit 0 only means no validation error; missing files are reported in `missing_files` with exit 0. Inspect `missing_files` and `fair_checks` before trusting completeness. | | "`has_hashes_for_existing_files` is `null`, close enough to `true`." | `null` means *no listed file existed on disk* — nothing was hashed. Re-run from the correct directory so the files are found and actually digested. | | "Skip `--engine-version`, the engine name is enough." | The script defaults `engine_version` to `"unknown"`, which silently breaks reproducibility. Always pass the concrete build/version. | | "Parsing `inputs.inputs` from the JSON gives me the per-file records." | `inputs.inputs` is the raw comma-separated CLI string echoed back, not the records. Read per-file data from `results.manifest.file_inventory.inputs/outputs`. | | "The manifest captures the structure, so the run is fully reproducible." | This skill only inventories files, hashes, units, and IDs. It does not record code commit, container digest, or parser versions — follow `recommended_next_steps` and add those yourself. | | "Absolute paths or `..` will be rejected, so the inventory is sandboxed." | Paths are not sandboxed — absolute and `..` paths are inventoried as given, and `--out` can write outside the working directory. Verify the paths you pass are the intended ones. | ## Security ### Input Validation - `--project-name` and `--engine` are required and must be non-empty after stripping whitespace; an empty value stops with exit code 2. - `--project-name`, `--engine`, `--structure-id` (when given), and every file path are checked for control characters (`ord < 32`) and a 4096-character maximum length; either condition stops with exit code 2. - `--inputs` and `--outputs` are split on commas and capped at 1000 entries each; more entries stop with exit code 2. - `--units` entries must be `key=value`; both the key and the value must match the allowlist `^[A-Za-z0-9_.:/@+-]+$`. A missing `=` or a non-matching key/value stops with exit code 2. - There are no numeric inputs, so no finite/positive numeric checks are performed. ### File Access - The script reads each existing input/output file in 1 MB chunks to compute its `size_bytes` and SHA-256 hash; files that do not exist are recorded but not read. - A file larger than 500 MB stops with exit cREADME.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/heshamfs-materials-simulation-skills-skills-data-management-fair-simulation-pack.md