Materials project workflow
Begin with the research goal and the project's actual files, results, jobs and instructions. When the next action is clear and within the researcher's confirmed scope, do it. Otherwise propose a short route: what each stage answers, which results advance, and where the researcher must choose a scientific alternative. A question about the next step does not itself approve unchosen scientific settings or extra calculations. Use the user's prompt language and project convention. Do not make an onboarding interview a prerequisite for a small task.
Scale the work to the request. For a small edit, inspect the affected settings and current records, reuse existing tools, and run checks relevant to the change. Re-read unchanged material or repeat a verified backup/accepted-result assessment only when new evidence or the action requires it. Build a helper for a concrete recurring need, not each parameter change. Follow existing project contracts; this Skill does not require a new audit framework or duplicate authorization documents.
Read the researcher's saved default if present: materials-project-workflow/DEFAULT.md in the agent's configuration folder ($CODEX_HOME, normally ~/.codex, for Codex; ~/.claude for Claude Code). It is that user's preference, not project authority; it stands in for a researcher decision only where this Skill says so, and a project may override it. At a researcher's first substantial project without a saved default, invite them to describe their usual workflow, suggest improvements, and save only the route they choose for later projects; continue a one-off task without this setup. The example personal default shows what a saved default for 2D adsorption may hold; apply its settings only when the researcher's default or project selects them. For a new project, record chosen stages, candidate counts, tools, meaningful input settings, backup destination/retention and review points in a short project WORKFLOW.md using the optional outline; ask only about unknown capabilities when a selected stage needs them. Later projects confirm differences rather than repeat settled preferences.
By default, optimize all ML candidates directly to fmax = 0.01 eV/Å, then select structures, with 3000 cumulative optimizer steps per structure unless the researcher chooses another force criterion or step limit. Set the actual runner to this limit from the start and finish earlier on convergence, without planned short-step runs. Whichever ML tool is used, from the saved default or the project's choice, follow its manual for how to run it, and write the force criterion and step limit explicitly into every copied runner; a tool's own defaults do not replace them. This Skill, not a tool manual, sets the force criterion, the step ceiling (raising it needs the researcher), candidate selection, review, monitoring, records and STATUS; use the scheduled follow-up rather than a manual's in-session polling, apart from the local startup check. A tool's own send-to-DFT list is a proposal; apply the project's agreed candidate count and diversity rule and note any difference. Recover genuine interruptions, including walltime timeouts, autonomously within the remaining allowance, without importing DFT restart-review gates: use the tool's resume function where it exists; without one, continue a single structure from its last saved structure with only its remaining steps. If resume refuses, or a batch cannot carry each structure's remaining steps, diagnose and report instead of working around it. Do not automatically add a coarse ML pass; another route may be chosen for a specific project. For local ML, preserve desktop responsiveness with bounded resource use. Choose local resources from the actual hardware, current load and interactive or dedicated use; reuse a verified machine profile, account for other projects, and verify effective worker/thread settings and memory headroom before raising throughput. Resource pressure warrants autonomous throttling, not weaker scientific settings.
Make the first HPC input preparation for a new route and site a researcher review point. Explain the proposed method, test/optimization sequence, resources, per-job walltime and maximum restarts with brief reasons; distinguish agreed choices from proposals. Agreement on a goal such as bulk optimization, or provision of an HPC path/script, does not approve an unchosen method, added tests, account or budget. Prepare one actual representative draft for human review before staging a whole series or submitting a job: structure, INCAR, KPOINTS, POTCAR identity and generation method, executable, adapted site script, resources and work scope. Project-authorized reads and POTCAR generation may be used to make that draft reviewable. Prefer the researcher's successful script from that HPC site; otherwise adapt the site's official example. Preserve project-consistent input ordering and formatting so diff exposes meaningful changes. Once reviewed, related structures and intermediates under the same method proceed without per-job review, even when their geometry and POTCAR composition differ. Review one actual example for a genuinely new calculation type or unrelated route. A reviewed first input is not a scientific result or an unlimited execution grant. A researcher's saved default may exempt HPC ML screening from this review only by naming the tool, the site/account and a per-screen cost limit; without all three the review applies, and a project may tighten but not loosen them without the researcher. Under such an exemption, ask before any screen whose worst-case cost (every structure reaching the step ceiling, resumes included) could exceed the limit. Set walltime from the tool's measured throughput and step statistics, with margin; a timeout under it is resumed, not a planned short-step run. Record estimated and actual cost (core-hours or the site's unit) in the run record.
For DFT, confirm each stage's per-job walltime and maximum restarts per structure at first-input review. The initial job does not count as a restart; each subsequent continuation or corrected execution in that same stage does, even after a directory or optimizer change. Record usage in the existing run record. Diagnose before autonomous continuation within these limits. If the last allowed restart ends without passing the stage, report the diagnosis in STATUS.md and obtain human review and an explicit extension before another job. A converged stage advances normally; reaching the count alone does not stop an otherwise healthy running job. Honor any additional project budget already agreed.
Carry out ordinary submission, monitoring, stage handoff and bounded recovery within the chosen route without pausing for each routine change. Keep one submit/retry owner and record a unique attempt identity plus input/script digests before calling the scheduler. If the submission outcome is unknown, keep that attempt fenced: reconcile it against the run record, queue, accounting and outputs; absence from squeue or delayed sacct is not proof that no job was accepted. Do not automatically resubmit until the outcome is positively resolved; ask if it remains ambiguous. For VASP geometry optimization, coarse or fine (not CI-NEB or IDM), use the optimizer chosen by the researcher's default or the project, otherwise native CG (IBRION=2). For the tags, verification, switching and other failures, read optimizer and recovery guidance; inspect electronic and ionic trends before a justified correction rather than blindly restarting. Preserve each attempt's inputs, outputs and source. If a live job is confirmed NaN, fatally broken or clearly runaway while consuming resources, preserve evidence and cancel that specific job; diagnose before any resubmission. Ask when the physical model, scientific target, final comparison protocol, site/account or agreed execution limits change, or when a material ambiguity remains. Only compare final energies obtained under the project's common energy-affecting settings.
For reaction paths and transition states, read CI-NEB/IDM guidance. Standalone frequency validation runs only for paths the researcher selects. An IDM direction-finding frequency calculation is part of an approved IDM recovery, not automatic validation of every CI-NEB result.
For Wannier tight-binding models and Wilson loops, read Wannier guidance; for invariants from symmetry eigenvalues (parity criteria, irreducible representations, symmetry indicators), read symmetry-eigenvalue guidance.
During active local ML or HPC work, maintain one project-root STATUS.md readable in one screen: pending actions, unresolved anomalies, grouped current work/next milestone and a few short recent events. Empty action/exception sections contain only “none”; link detailed jobs, evidence and older history. Use status, monitoring and directory guidance. When first creating or adopting this page, tell the researcher it is in use, provide a clickable file link, and briefly state what it tracks and whether their action is needed. At the end of each meaningful workflow step, check current evidence and update STATUS.md when the result, action needed, anomaly or next step changed; do this before reporting the step complete or handing off. An unchanged check needs no file rewrite. Use the linked guidance for active-work scheduling and access; keep ordinary unchanged progress quiet and retire the follow-up when work is reconciled. Keep adopted results immediately findable, raw evidence traceable and the agreed backup current. Do not create filesystem links inside cloud-synced folders such as OneDrive; on HPC a final_choice symlink with a neighboring FINAL_CHOICE.md is fine.
When handing the researcher a POSCAR/CONTCAR to view, run scripts/clean_poscar_species.py on it if its species line carries POTCAR labels or hashes (e.g. Ti_sv/0a1b2c3d4), which VESTA cannot read, and point to the _vesta.vasp copy; the original stays unchanged.
This Skill stands alone. Use verified local/project tools where appropriate; AiiDA is an optional provenance layer, never a prerequisite or a substitute for readable files.