agentleFS
DingyangLyuDingyangLyu/MatClaw/.claude/skills/add-vasp/SKILL.md

add-vasp

Skill98 starsChanged 8 months agoApache-2.0View on GitHub

Configure VASP integration. Connect your HPC cluster or local VASP installation so the agent can run VASP calculations via the 213 built-in computation skills.

  • Reads credentials
  • Deletes or force-pushes

The file

We split this skill into the rules it gives an agent

10 rules. About 0 are common, 6 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If config exists, show it with vasp-remote config and ask the user if they want to reconfigure.

    line 18
  2. Very specific:

    Use AskUserQuestion to determine the setup mode:

    line 22
  3. Distinctive:

    If option 3, tell the user that all 213 computation skills already work without VASP (Method A: MACE for fast screening, Method B: QE for …

    line 30
  4. Distinctive:

    Ask the user for:

    line 36
  5. Distinctive:

    Check if there's a VASP-specific SSH key already, or use the default:

    line 82
  6. Distinctive:

    Add the SSH key mount to container-runner by setting the environment variable:

    line 89
  7. Distinctive:

    If this fails, troubleshoot:

    line 128
  8. Very specific:

    Add to src/container-runner.ts in buildVolumeMounts:

    line 174
  9. Distinctive:

    Ask the user to test with a simple calculation:

    line 221
  10. Very specific:

    All 213 computation skills with VASP methods work automatically — they generate input files and the agent calls vasp-remote run instead of …

    line 244

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Add VASP Integration

This skill configures VASP access for MatClaw. VASP is proprietary and cannot be bundled in the container, so we connect to your existing VASP installation — either on a remote HPC cluster (via SSH) or on the local host (via volume mount).

Phase 1: Pre-flight

Check if already configured

ls ~/.vasp-remote/config.json 2>/dev/null

If config exists, show it with vasp-remote config and ask the user if they want to reconfigure.

Ask the user

Use AskUserQuestion to determine the setup mode:

How is VASP available to you?

  1. Remote HPC cluster — I have SSH access to a cluster with VASP installed (most common)
  2. Local installation — VASP is installed on this machine
  3. I don't have VASP — Skip this, use QE and MACE instead

If option 3, tell the user that all 213 computation skills already work without VASP (Method A: MACE for fast screening, Method B: QE for DFT accuracy). Exit.

Phase 2: SSH Cluster Setup

Collect cluster details

Ask the user for:

FieldExampleRequired
SSH hostlogin.hpc.example.eduYes
SSH userjdoeYes
SSH key path (on host)~/.ssh/id_rsaYes (or use default)
VASP binary path on cluster/opt/vasp/6.4.3/bin/vasp_stdYes
POTCAR directory on cluster/opt/vasp/potpaw_PBENo (agent generates POTCAR)
Scratch/work directory/scratch/jdoe/vasp-jobsYes
Scheduler typeslurm or pbsYes
Default queue/partitionnormalNo
Default number of cores16No (default: 16)
Default walltime24:00:00No (default: 24:00:00)
Modules to loadvasp/6.4.3 intel/2024No

Write configuration

mkdir -p ~/.vasp-remote
cat > ~/.vasp-remote/config.json << 'JSONEOF'
{
  "mode": "ssh",
  "ssh": {
    "host": "<HOST>",
    "user": "<USER>",
    "key": "<KEY_PATH>",
    "vasp_bin": "<VASP_BIN>",
    "potcar_dir": "<POTCAR_DIR>",
    "work_dir": "<WORK_DIR>",
    "scheduler": "<slurm|pbs>",
    "queue": "<QUEUE>",
    "nprocs": <NPROCS>,
    "walltime": "<WALLTIME>",
    "modules": "<MODULES>"
  }
}
JSONEOF

Replace all <PLACEHOLDERS> with the user's actual values.

Set up SSH key for container access

The container agent needs to reach the cluster. The user's SSH key must be mounted into the container.

Check if there's a VASP-specific SSH key already, or use the default:

# Verify the key exists
ls -la <KEY_PATH>

Add the SSH key mount to container-runner by setting the environment variable:

# Add to .env file
echo "VASP_SSH_KEY_PATH=<KEY_PATH>" >> .env

Then update src/container-runner.ts to mount SSH keys. In the buildVolumeMounts function, after the Gmail credentials section, add:

// VASP remote SSH key (for cluster access from container)
const vaspSshKey = process.env.VASP_SSH_KEY_PATH;
if (vaspSshKey && fs.existsSync(vaspSshKey)) {
  // Mount the specific key file
  mounts.push({
    hostPath: path.dirname(vaspSshKey),
    containerPath: '/home/node/.ssh',
    readonly: true,
  });
}

// VASP remote configuration
const vaspConfigDir = path.join(homeDir, '.vasp-remote');
if (fs.existsSync(vaspConfigDir)) {
  mounts.push({
    hostPath: vaspConfigDir,
    containerPath: '/home/node/.vasp-remote',
    readonly: true,
  });
}

Test SSH connection

# Test from host first
ssh -i <KEY_PATH> -o BatchMode=yes -o ConnectTimeout=10 <USER>@<HOST> "echo OK && which vasp_std || ls <VASP_BIN>"

If this fails, troubleshoot:

  • Key permissions: chmod 600 <KEY_PATH>
  • Host key: ssh-keyscan <HOST> >> ~/.ssh/known_hosts
  • Firewall/VPN: user may need to be on campus network

Test from container

Rebuild and test:

npm run build
echo '{"prompt":"Run: vasp-remote config","groupFolder":"test","chatJid":"test@g.us","isMain":false,"secrets":{"ANTHROPIC_API_KEY":"...","ANTHROPIC_BASE_URL":"https://api.anthropic.com"}}' | docker run -i \
  -v ./workspace:/workspace/group \
  -v ~/.vasp-remote:/home/node/.vasp-remote:ro \
  -v ~/.ssh:/home/node/.ssh:ro \
  matclaw-agent:latest

Phase 3: Local VASP Setup

Collect local details

FieldExampleRequired
VASP binary path/opt/vasp/bin/vasp_stdYes
POTCAR directory/opt/vasp/potpaw_PBENo
Number of cores4No (default: 4)

Write configuration

mkdir -p ~/.vasp-remote
cat > ~/.vasp-remote/config.json << 'JSONEOF'
{
  "mode": "local",
  "local": {
    "vasp_bin": "<VASP_BIN>",
    "potcar_dir": "<POTCAR_DIR>",
    "nprocs": <NPROCS>
  }
}
JSONEOF

Set up volume mounts

Add to src/container-runner.ts in buildVolumeMounts:

// Local VASP binary mount
const vaspBinPath = process.env.VASP_BIN_PATH;
if (vaspBinPath && fs.existsSync(vaspBinPath)) {
  mounts.push({
    hostPath: path.dirname(vaspBinPath),
    containerPath: '/opt/vasp/bin',
    readonly: true,
  });
}

// Local VASP POTCAR library mount
const vaspPpPath = process.env.VASP_PP_PATH;
if (vaspPpPath && fs.existsSync(vaspPpPath)) {
  mounts.push({
    hostPath: vaspPpPath,
    containerPath: '/opt/vasp/pp',
    readonly: true,
  });
}

Add to .env:

VASP_BIN_PATH=/opt/vasp/bin/vasp_std
VASP_PP_PATH=/opt/vasp/potpaw_PBE

Test

vasp_std --version  # or just check it exists

Phase 4: Rebuild Container

The container needs openssh-client for SSH mode and the vasp-remote script:

./container/build.sh

Phase 5: Verify

Ask the user to test with a simple calculation:

VASP is now configured! Try asking me to calculate something, for example: "Relax the structure of Si using VASP"

The agent will:

  1. Generate INCAR, POSCAR, KPOINTS, POTCAR
  2. Run vasp-remote run to execute on your cluster
  3. Parse vasprun.xml and return the results

How It Works

Agent (in container)
  ├─ Reads skill → generates VASP input files
  ├─ Runs: vasp-remote run
  │   ├─ SSH mode: scp files → sbatch → poll → fetch results
  │   └─ Local mode: mpirun vasp_std
  └─ Parses vasprun.xml with pymatgen → returns results

The vasp-remote script is at /usr/local/bin/vasp-remote inside the container. It reads config from ~/.vasp-remote/config.json (mounted from host).

All 213 computation skills with VASP methods work automatically — they generate input files and the agent calls vasp-remote run instead of vasp_std directly.

Troubleshooting

ProblemCauseFix
Config not foundNot configuredRun /add-vasp
SSH connection refusedNetwork/firewallCheck VPN, try ssh -v from host
Permission denied (publickey)Wrong key or permissionschmod 600 ~/.ssh/id_rsa
vasp_std: not foundWrong binary pathCheck ssh user@host "which vasp_std"
sbatch: command not foundWrong scheduler typeTry pbs instead of slurm
Job stuck in PENDINGQueue fullTry different queue: vasp-remote run --queue express
Dynamic library errors (local)Container lib mismatchUse SSH mode instead

Removal

rm -rf ~/.vasp-remote
# Remove VASP_* lines from .env
# Remove VASP mount sections from src/container-runner.ts

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.