agentleFS
intelintel/torch-xpu-ops/.claude/skills/xpu-build-pytorch/SKILL.md

xpu-build-pytorch

Skill121 starsChanged 5 months agoApache-2.0View on GitHub

Build PyTorch from source with Intel XPU (GPU) support. Use when the user asks to build PyTorch, set up the XPU build environment, rebuild after code changes, install PyTorch for XPU, or configure oneAPI. Handles prerequisites check, build_pytorch.env setup, build verification, and torch-xpu-ops development pin override.

  • Reads credentials
  • Deletes or force-pushes
  • Installs packages

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 4 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Always check local memory for build configuration (env vars, paths, incremental-build shortcuts) before running the build.

    line 17
  2. Distinctive:

    Create in PyTorch root. Adjust paths for your system.

    line 32
  3. Distinctive:

    Always redirect build output to a log file so failures can be diagnosed:

    line 50
  4. Very specific:

    Never skip sourcing build_pytorch.env: before running tests — XPU ops are unavailable without the oneAPI runtime.

    line 69
  5. Distinctive:

    After modifying inductor headers: delete the PCH cache before rebuilding:

    line 76

≈ “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

Build PyTorch with XPU Support

The only build command is pip install -e . -v --no-build-isolation. Never use any other command.

The ## Build section of AGENTS.md covers the baseline: the build command, the BUILD_SEPARATE_OPS flag, and the xpu.txt commit-pin override for local development. This skill extends that with XPU-specific prerequisites (oneAPI) and a step-by-step verification workflow.

Instructions

Always check local memory for build configuration (env vars, paths, incremental-build shortcuts) before running the build. Apply what you find; if nothing applicable is in memory, ask the user.

1. Verify prerequisites

# Confirm in PyTorch root (xpu.txt is unique to this repo)
test -f third_party/xpu.txt || echo "ERROR: Not in PyTorch root"

# Verify oneAPI installation (icpx not in PATH before sourcing vars — check directory instead)
test -d /opt/intel/oneapi/compiler || echo "WARNING: oneAPI not found at /opt/intel/oneapi/compiler"

2. Configure build_pytorch.env

Create in PyTorch root. Adjust paths for your system.

# Target hardware: pvc (Data Center GPU Max), dg2 (Arc GPU), etc.
# Omitting targets all supported architectures — safe default.
# export TORCH_XPU_ARCH_LIST=pvc

export USE_XPU=1
export USE_CUDA=0

# Adjust to your oneAPI installation path
source /opt/intel/oneapi/compiler/latest/env/vars.sh
# Alternative: source /opt/intel/oneapi/setvars.sh
# Optional PTI support: source /opt/intel/oneapi/pti/latest/env/vars.sh

3. Build

Always redirect build output to a log file so failures can be diagnosed:

source build_pytorch.env
pip install -e . -v --no-build-isolation 2>&1 | tee /tmp/pytorch_build_$(date +%Y%m%d_%H%M%S).log
echo "Build log saved to /tmp/pytorch_build_*.log"

4. Verify

source build_pytorch.env
python -c "import torch; print('XPU available:', torch.xpu.is_available())"

Expected: XPU available: True

Best practices

  • Never skip sourcing build_pytorch.env before running tests — XPU ops are unavailable without the oneAPI runtime.
  • Always rebuild after git rebase or git checkout — stale C++ extensions produce unreliable or silently wrong test results.
  • Faster iteration builds: set BUILD_SEPARATE_OPS=1 to shrink translation unit scope. Debug/RelWithDebInfo builds enable this automatically.
    BUILD_SEPARATE_OPS=1 pip install -e . -v --no-build-isolation 2>&1 | tee /tmp/pytorch_build_$(date +%Y%m%d_%H%M%S).log
  • After editing a C++ header: manually copy to torch/include/ — editable installs serve C++ headers from the installed path, not source.
  • After modifying inductor headers: delete the PCH cache before rebuilding:
    rm -rf /tmp/torchinductor_$USER/precompiled_headers/
  • Leave TORCH_XPU_ARCH_LIST commented out unless you know your target hardware — setting pvc on an Arc GPU produces a silently incorrect build.

Requirements

  • Intel oneAPI Base Toolkit installed (provides icpx, libsycl, DPC++ runtime)
  • PyTorch cloned from source with third_party/torch-xpu-ops populated
  • Python environment with build dependencies (ninja, cmake, pyyaml, typing_extensions)

Advanced usage

For developing torch-xpu-ops locally (commit pin override so CMake does not overwrite your changes on every build), see reference.md.

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.