# fair-simulation-packager

Adopt this skill: https://proskills.md/skills/other/heshamfs-materials-simulation-skills-skills-data-management-fair-simulation-pack

Page: https://proskills.md/skills/other/heshamfs-materials-simulation-skills-skills-data-management-fair-simulation-pack
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/data-management/fair-simulation-packager/SKILL.md
size: 8012
upstream: https://github.com/heshamfs/materials-simulation-skills/blob/main/skills/data-management/fair-simulation-packager/SKILL.md

````text
---
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 c
````

## File: README.md
upstream: https://github.com/heshamfs/materials-simulation-skills/blob/main/README.md

````text
# Materials Simulation Skills

[![CI](https://github.com/HeshamFS/materials-simulation-skills/actions/workflows/ci.yml/badge.svg)](https://github.com/HeshamFS/materials-simulation-skills/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Agent Skills](https://img.shields.io/badge/Agent_Skills-standard-orange.svg)](https://agentskills.io)
[![Python 3.10-3.12](https://img.shields.io/badge/Python-3.10--3.12-blue.svg)](https://www.python.org/)
[![Skills](https://img.shields.io/badge/skills-24-blue.svg)](skills_index.json)
[![Deterministic eval coverage](https://img.shields.io/badge/deterministic_eval_coverage-100%25-brightgreen.svg)](docs/EVALUATION_METHODOLOGY.md)

**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](https://agentskills.io) 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:

```text
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](docs/PROTOCOL.md)** — rules reference authoritative standards (ASME V&V20, the SchedMD `sbatch` spec, CMSO IRIs).

How and why: **[evaluation methodology](docs/EVALUATION_METHODOLOGY.md)** · **[harness](docs/EVAL_HARNESS.md)**.

Latest [deterministic evaluation (2026-10-20)](docs/evaluations/2026-10-20.md): **115 cases, 131 checks, 725 assertions passed**. Live-agent uplift remains unvalidated.

See **[validation scope and remaining limits](docs/VALIDATION_SCOPE.md)** 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:

```bash
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:

```bash
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](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:

```text
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](docs/SKILLS.md)** (or the machine-readable
[`skills_index.json`](skills_index.json)).

**Try it locally / develop:**

```bash
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](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](docs/PROTOCOL.md)**
and **[docs/SECURITY.md](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](https://github.com/HeshamFS/materials-simulation-skills/issues) (there are templates for bug reports and skill proposals) — early ideas are great even without code.
- **Want to build a skill?** **[CONTRIBUTING.md](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](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](docs/SKILLS.md) | Full skill catalog, how skills work, repo layout |
| [docs/INSTALL.md](docs/INSTALL.md) | Install for every supported agent |
| [docs/EVALUATION_METHODOLOGY.md](docs/EVALUATION_METHODOLOGY.md) | How skills are evaluated, with results |
| [docs/EVAL_HARNESS.md](docs/EVAL_HARNESS.md) | The three-layer evaluation harness |
| [docs/PROTOCOL.md](docs/PROTOCOL.md) | The Materials Simulation Skill Protocol |
| [docs/SECURITY.md](docs/SECURITY.md) | Safeguards and security tiers |
| [CONTRIBUTING.md](CONTRIBUTING.md) · [ROADMAP.md](ROADMAP.md) | Contributing guide · direction |

---

## Star History

<a href="https://www.star-history.com/?repos=HeshamFS%2Fmaterials-simulation-skills&type=date&legend=top-left">
 <picture>
   <source media="(prefers-color-scheme: da
````
