Skip to content

Agentic Skills User Guide

Jump to bottom
ZhaoqiongZ edited this page Jul 20, 2026 · 5 revisions

Agentic Skills User Guide

torch-xpu-ops provides several agentic skills for systematic XPU backend development and analysis.

This is a guide for how to use agentic skills for 4 different user scenarios.

OpenCode setup & repo permissions

All skills run under OpenCode AI. Before invoking any skill, make sure OpenCode has both filesystem and GitHub permissions for the target repos, otherwise the skill will silently fail or ask you to retry.

1. Filesystem / repo access

OpenCode only reads and writes files inside directories it was granted at startup. Two things you'll hit if this is wrong:

  • Skill can't read pytorch/ sources when it lives outside the current working directory → launch opencode from the parent directory that contains BOTH pytorch/ and torch-xpu-ops/, or add the extra path via opencode --allowed-paths / ~/.config/opencode/opencode.jsonc permission block.
  • Skill can't write agent_space_xpu/ → make sure it exists and is writable by the user running opencode; it is git-ignored, safe to mkdir.

Minimal ~/.config/opencode/opencode.jsonc for these skills:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": { "*": "ask" },
    "edit": { "*": "allow" },
    "external_directory": { "*": "allow" }
  }
}

Pipeline mode requires everything be pre-approved (there is no human to answer ask prompts). If you plan to run issue-handler or xpu-alignment unattended, set bash to allow as well:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": { "*": "allow" },
    "edit": { "*": "allow" },
    "external_directory": { "*": "allow" }
  }
}

Anything left as "ask" will block the pipeline the first time the agent shells out, and pipeline mode has no way to answer it.

2. GitHub access (gh CLI + token)

Every skill except oob-perf-analysis calls gh under the hood (fetching issues, PRs, comments, labels; for pipeline mode also posting comments and applying agent:* labels). OpenCode does not proxy this — it shells out to your gh CLI, so gh must be authenticated with a token that has the right scopes:

Skill Required scopes (classic PAT) Fine-grained equivalent
issue-handler (interactive) repo (or at minimum read:issues) Issues: Read
issue-handler (pipeline) repo (needs write:issues) Issues: Read & Write, Metadata: Read
xpu-alignment repo (search + read issues/PRs/commits) Issues: Read, Pull requests: Read, Contents: Read, Metadata: Read
xpu-nightly-ci-fix repo (read CI logs, push fix branches) Contents: Read & Write, Actions: Read, Issues: Read

Verify before starting a session:

gh auth status                  # must show "Logged in to github.com"
gh auth refresh -s repo         # add missing scope if needed
# or for fine-grained tokens, regenerate at
# https://github.com/settings/personal-access-tokens

If gh auth status fails or the token is missing write:issues, issue-handler in pipeline mode degrades to interactive mode (it cannot post state comments or apply labels). See the issue-handler skill's Prerequisites section for the exact permission contract.

3. Common permission errors

Symptom Cause Fix
HTTP 403: Resource not accessible by integration from gh api Token missing write:issues gh auth refresh -s repo
HTTP 404 on a private/internal issue Token has no repo scope Regenerate PAT with repo
OpenCode: permission denied writing agent_space_xpu/... Directory not writable / not in allowed paths mkdir -p agent_space_xpu && chmod u+rw agent_space_xpu; relaunch opencode from repo root
OpenCode: path outside allowed roots: /.../pytorch/... Launched opencode from torch-xpu-ops/ only Relaunch from the parent dir, or add path to permissions in opencode.json
gh: command not found gh CLI not installed Install: https://cli.github.com/

Skill Overview

Skill When to Use
xpu-nightly-ci-fix Analyze and fix failing nightly CI tests
issue-handler Handle a single reported GitHub issue end-to-end
oob-perf-analysis Analyze XPU vs CUDA software efficiency via roofline
xpu-alignment + issue-handler Scan upstream PyTorch for XPU-relevant bugs, then fix them

Scenario 1: Fix Nightly CI Failures (Local Agent)

Use case: Nightly CI tests are failing on XPU. Run the agent locally to automatically verify, analyze root cause, and fix each failure.

Prerequisites:

  1. Download and configure OpenCode AI
  2. Load the skill by invoking /xpu-nightly-ci-fix
  3. Prepare CI failure report (paste or point to the report)

Invoke:

Run the xpu-nightly-ci-fix skill and paste the CI failure report below:

I have a nightly CI failure report from 2026-06-08. Here are the failing tests:
- test_ops_xpu.py::TestBinaryUfuncsXPU::test_add_xpu
- test_nn_xpu.py::TestNNXPU::test_relu_xpu
PyTorch commit: abc123def

Workflow:

  1. Parse failure report — agent extracts date, commit, failing tests
  2. Checkout origin/main and rebuild PyTorch
  3. Reproduce each failure locally and confirm
  4. Analyze root cause by category:
    • XPU backend bug
    • Tolerance too tight
    • Stale skip decorator
    • Upstream regression
    • Test infrastructure
  5. Apply fixes aligned with CUDA reference
  6. Verify each fix individually — run test, confirm pass, lint, commit
  7. Generate summary report to agent_space_xpu/summary_<report_date>.md

Branch strategy: Each fix is a separate commit/PR. Fixes in torch-xpu-ops kernel code require a separate PR to intel/torch-xpu-ops.

Scenario 2: Fix a Single GitHub Issue (UT Fix)

Use case: A specific GitHub issue is reported on pytorch or torch-xpu-ops. Configure issue-handler, paste the issue, and let the agent fix it end-to-end.

Prerequisites:

  1. Load the issue-handler skill by invoking /issue-handler
  2. Paste the GitHub issue URL or raw issue body
  3. gh CLI authenticated with read:issues + write:issues (classic PAT: repo; fine-grained: Issues Read & Write, Metadata Read). See OpenCode setup & repo permissions above. Verify with gh auth status.
    • Interactive mode: read:issues is enough — the agent only fetches the issue.
    • Pipeline mode: write:issues is required — the agent posts state comments, edits its own comment via gh api ... -X PATCH, and applies agent:* labels. Without write access, pipeline mode will fail with HTTP 403: Resource not accessible; fall back to interactive.

Invoke:

Fix the issue https://github.com/pytorch/pytorch/issues/123456

Pipeline:

format -> verify-exists -> triage -> propose-fix -> verify-fix -> report
Stage Sub-skill Purpose
1. Format issue-format Classify bug/nonbug, extract metadata
2. Verify test-verification Confirm failure reproduces locally
3. Triage xpu-issues-triaging Root cause, fix strategy, verdict
4. Propose fix issue-fix Implement fix
5. Verify fix test-verification Re-run to confirm resolution
6. Report issue-handler Summarize outcome

Execution modes:

  • Interactive (default): agent asks user when blocked
  • Pipeline: no human, agent writes status to issue body directly

Scenario 3: Analyze OOB Performance (Roofline)

Use case: Compare XPU vs CUDA software efficiency using T1/T2/R roofline methodology. User specifies raw logs directly (no download step).

Prerequisites:

  1. Load the oob-perf-analysis skill by invoking /oob-perf-analysis
  2. Prepare raw logs directory with expected layout

Input layout (user provides path directly, no download):

<user_raw_logs>/<session>/
  <model>/
    t1/rcpi1-ins0.log
    xpu_profiler/timeline/trace.json
    cuda_profiler/timeline/trace.json
    unitrace/python.<pid>.json
    xpu_t2/rcpi1-ins0.log
    cuda_t2/rcpi1-ins0.log

Invoke:

Run oob-perf-analysis with my_raw_logs/session20250611

Metrics:

  • T1 — roofline projection (hardware minimum time given compute + memory work)
  • T2 — measured wall-clock batch latency
  • R = T1/T2 — software efficiency (XPU vs CUDA directly comparable)

Reports generated under agent_space_xpu/reports/<session>/:

Report Path
Per-model models/<model>.md
Fleet summary summary_eager_inference.md
Graph consistency graph_consistency_eager_inference.md
Insights insights_summary.md

Operating rules:

  1. Read methodology.md before computing any metric
  2. Read inputs.md before accessing any artifact
  3. Use platform-specific cache-adjusted memory columns (col 5/6/7), never raw memory

Scenario 4: Align CUDA and XPU (Two Skills)

Use case: Scan upstream PyTorch for bugs that affect XPU but lack CUDA alignment, then fix them using a two-step workflow.

Step 1: Discover unaligned issues

Prerequisites:

  1. Load the xpu-alignment skill by invoking /xpu-alignment
  2. Provide a scan window

Invoke:

Run the xpu-alignment for 2026-06-01 to 2026-06-07

Workflow (Step 1):

  1. Preflight — verify XPU interpreter, GitHub access, create output dirs
  2. Collect candidates — search pytorch/pytorch issues/PRs/commits in scan window
  3. Filter — title filter → ledger; then batch deep-fetch details
  4. Write reproducers — XPU-adapted repro_<id>.py scripts
  5. Serial execution — run each repro, capture RESULT: logs
  6. Batch route — apply bucket rules to confirmed/related-failure candidates
  7. Write reports — full_scan.md + issue_drafts.md
  8. Agent asks before filing — user confirms before any GitHub issue creation

Output layout under agent_space_xpu/runs/<scan-window>/:

artifacts/   raw_candidates.json, candidate_ledger.jsonl, details/<id>.json, output_<id>.log, collect_env.txt
scripts/     repro_<id>.py
reports/     full_scan.md, issue_drafts.md

Step 2: Fix discovered issues

For each issue/PR identified in Step 1 that needs fixing:

Invoke:

Fix the issue https://github.com/pytorch/pytorch/issues/<id>

Use the issue-handler pipeline (Scenario 2) to implement and verify the fix.

Two-skill flow summary:

Step Skill Output
1 xpu-alignment Reports + issue drafts identifying unaligned bugs
2 issue-handler Verified fix, PR ready for submission

Quick Reference

Task Skill(s) Invoke
Fix failing CI tests xpu-nightly-ci-fix Run xpu-nightly-ci-fix and paste CI report
Fix a single UT issue issue-handler Fix the issue <url>
Analyze OOB perf oob-perf-analysis Run oob-perf-analysis with <path>
Align CUDA+XPU xpu-alignment -> issue-handler 1. Run xpu-alignment for <window> 2. Fix issue <id>

All skills write to agent_space_xpu/ (git-ignored scratch space). Outputs are never written elsewhere without explicit user instruction.

Clone this wiki locally