⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v1.2.2

fair-simulation-packager

heshamfs@heshamfs⭐ 83 stars· last commit 25d ago· 0 open issues

>

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.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐ 83 on GitHubGitHub ↗

Growing

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

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

CategorySkillsFocus
Core Numerical8stability, time-stepping, meshing, convergence, integration, differentiation, linear/nonlinear solvers
Simulation Workflow7validation, DOE/optimization, orchestration, post-processing, profiling, workflow mapping, MD analysis
HPC Deployment2SLURM script generation, runtime diagnosis
Verification & Validation1manufactured solutions, benchmarks, pass/fail reports
Data Management1FAIR reproducibility packaging
Robustness1cross-code failure triage & retry ladders
Ontology3CMSO/ASMO exploration, mapping, validation
Meta1skill-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

DocWhat's in it
docs/SKILLS.mdFull skill catalog, how skills work, repo layout
docs/INSTALL.mdInstall for every supported agent
docs/EVALUATION_METHODOLOGY.mdHow skills are evaluated, with results
docs/EVAL_HARNESS.mdThe three-layer evaluation harness
docs/PROTOCOL.mdThe Materials Simulation Skill Protocol
docs/SECURITY.mdSafeguards and security tiers
CONTRIBUTING.md · ROADMAP.mdContributing 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 c
  • README.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

// REPO STATS

83 stars
0 open issues
Last commit: 25d ago