Skip to content

Commit 1baea1b

Browse files
MrXinWangMrXinWang
committed
content: learning-paths: Add the performix-llm-agent-skill guide
Introduces a performix-llm-agent-skill introductory learning path covering how to install the arm-performix skill, trigger it with the right context, and read the analysis report to drive the agent-based optimization loop using Arm Performix on Arm Neoverse. Signed-off-by: Henry Wang <Henry.Wang@arm.com>
1 parent d2fb7ea commit 1baea1b

7 files changed

Lines changed: 375 additions & 0 deletions

File tree

‎assets/contributors.csv‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,7 @@ Geremy Cohen,Arm,geremyCohen,geremyinanutshell,,
8888
Barbara Corriero,Arm,,,,
8989
Nina Drozd,Arm,NinaARM,ninadrozd,,
9090
Jun He,Arm,JunHe77,jun-he-91969822,,
91+
Henry Wang,Arm,MrXinWang,xin-wang-930b4b141,,
9192
Gian Marco Iodice,Arm,,,,
9293
Aude Vuilliomenet,Arm,,,,
9394
Andrew Kilroy,Arm,,,,

‎content/learning-paths/servers-and-cloud-computing/performix-llm-agent-skill/1-what-is-the-skill.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
title: What is the arm-performix skill?
3+
weight: 2
4+
5+
### FIXED, DO NOT MODIFY
6+
layout: learningpathall
7+
---
8+
9+
## A skill, not a tool
10+
11+
**Arm Performix** is the profiling tool. The **arm-performix skill** is a set of
12+
instructions you add to your AI assistant so that it knows *how* to use Performix
13+
correctly on your behalf: which recipe to pick, how to gather context, how to
14+
read the results, and how to report findings.
15+
16+
Without the skill, an assistant tends to guess at performance problems by reading
17+
your source code. With the skill, it follows a disciplined workflow: measure
18+
first, characterize the bottleneck, change one thing at a time, and prove the win
19+
with before/after data.
20+
21+
## What the skill does for you
22+
23+
When the skill is active, the assistant will:
24+
25+
- Ask for the target, binary path, and workload command before profiling
26+
- Choose the narrowest Performix recipe that answers your question
27+
- Run the recipe (through the `apx` CLI or the Arm MCP Server)
28+
- Return a structured **Analysis Report**: bottleneck summary, key metrics, hot
29+
functions, ranked recommendations, and a single next step
30+
31+
## What the skill will not do
32+
33+
- Profile non-Neoverse Arm cores, such as phone-class SoCs
34+
- Guess at bottlenecks from source reading instead of measurement
35+
- Silently switch to another profiler when Performix is unavailable; it asks you
36+
how to proceed instead
37+
38+
## The recipes it can run
39+
40+
Performix exposes five profiling recipes, and the skill orchestrates them as a
41+
workflow: it picks a starting recipe from your question, then follows the
42+
evidence into whichever further recipes are needed to explain and confirm the
43+
bottleneck. Each recipe answers a different question:
44+
45+
| Your question | Recipe | What it shows |
46+
| --- | --- | --- |
47+
| Where is my time spent? | **Code Hotspots** | Hottest functions, call paths, flame graph |
48+
| Why is the pipeline stalling? | **CPU Microarchitecture** | Frontend/backend stalls, bad speculation, retiring |
49+
| Am I using SIMD (Neon/SVE)? | **Instruction Mix** | Scalar vs vector instruction balance |
50+
| Is memory the bottleneck? | **Memory Access** | L1 hit rate, latency, TLB/page-walk pressure |
51+
| What can the hardware do? | **System Characterization** | Memory bandwidth and latency baseline per NUMA node |
52+
53+
{{% notice Note %}}
54+
**Where the recipes run:**
55+
56+
- **Profiling target** (the machine running your workload). The four
57+
microarchitecture-level recipes (CPU Microarchitecture, Instruction Mix,
58+
Memory Access, and System Characterization) require an **Arm Neoverse** target
59+
on Linux; Memory Access additionally needs the Statistical Profiling Extension
60+
(SPE) enabled. Code Hotspots is broader: it also runs on x86-64 Linux and on
61+
Windows 11 (Arm or x86).
62+
- **Host** (the machine where you run the `apx` CLI or your AI assistant). It can
63+
be macOS, Windows, or Linux on either Arm64 or x86-64, and connects to the
64+
target locally or over SSH.
65+
{{% /notice %}}

‎content/learning-paths/servers-and-cloud-computing/performix-llm-agent-skill/2-install-the-skill.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
title: Install and enable the skill
3+
weight: 3
4+
5+
### FIXED, DO NOT MODIFY
6+
layout: learningpathall
7+
---
8+
9+
## Get the skill files
10+
11+
You can get the skill in either of these ways:
12+
13+
- Clone the skills repository from Gitee:
14+
15+
```bash
16+
git clone https://gitee.com/anolis/anolis-skills.git
17+
```
18+
19+
Use this if you prefer managing the skill source with Git.
20+
21+
- Download the skill package from the SkillHub page:
22+
https://skillhub.openanolis.cn/skill/arm-performix
23+
24+
Use this if you prefer downloading a package from the web page. The downloaded
25+
skill is a `.zip` package, so extract it before placing the folder.
26+
27+
## Place the skill files
28+
29+
The skill is a folder that contains `SKILL.md`, `README.md`, and a
30+
`references/` directory. Put it where your assistant discovers skills. For
31+
GitHub Copilot in VS Code, that is the `.github/skills/` directory of your
32+
workspace:
33+
34+
```text
35+
.github/
36+
skills/
37+
arm-performix/
38+
SKILL.md
39+
README.md
40+
references/
41+
<references>.md
42+
```
43+
44+
The `SKILL.md` file describes the profiling workflow; `README.md` provides
45+
supporting overview information; and files under `references/` provide detailed
46+
reference materials that the assistant reads on demand.
47+
48+
## Confirm the skill is discovered
49+
50+
Reload VS Code, then ask your assistant a profiling question (see the next page).
51+
A correctly installed skill is picked up automatically when your request matches
52+
its triggers; you do not invoke it with an explicit command.
53+
54+
{{% notice Tip %}}
55+
The skill only *describes* how to use Performix. You still need Performix itself
56+
available: either the `apx` CLI on your `PATH`, or the Arm MCP Server configured.
57+
The skill tells you when neither is reachable rather than guessing.
58+
{{% /notice %}}
59+
60+
## Choose how Performix runs
61+
62+
The skill can drive Performix two ways. You do not have to pick manually, but it
63+
helps to know which you have set up:
64+
65+
- **apx CLI**: the full-capability path. Install it on your host and confirm it
66+
with `apx version`. Best for remote SSH targets, automation, and CI.
67+
- **Arm MCP Server**: bundles its own `apx`, so your host needs no CLI install.
68+
Best for fully agent-driven workflows. The skill routes here only when you ask,
69+
or when the CLI is not installed and you confirm MCP.

‎content/learning-paths/servers-and-cloud-computing/performix-llm-agent-skill/3-trigger-the-skill.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
title: Trigger the skill with the right context
3+
weight: 4
4+
5+
### FIXED, DO NOT MODIFY
6+
layout: learningpathall
7+
---
8+
9+
## Phrase the request so the skill activates
10+
11+
The skill activates on performance and profiling intent. Phrasings that work:
12+
13+
- "Profile this workload on Arm and find the hotspots."
14+
- "Why is this binary slow on my Arm Neoverse server?"
15+
- "Use Performix to check whether my hot loop is vectorized."
16+
- "Investigate cache and TLB stalls on my Neoverse target."
17+
18+
Phrasings that will *not* activate it, because these are migration or vague questions:
19+
20+
- "Will my code build on Arm?" That is a migration question, not a profiling one.
21+
- "Make my code faster" with no target or binary, which is too vague; add context.
22+
23+
## Provide the context up front
24+
25+
The skill needs the following before it can profile. Supplying them in your first
26+
message avoids a round of back-and-forth:
27+
28+
1. **Target**: a local Arm machine, or `user@host` for a remote SSH target
29+
2. **Binary**: the **absolute path** to the executable on the target
30+
3. **Workload**: the exact command and arguments, ideally repeatable
31+
4. **Goal**: hotspots, SIMD usage, memory locality, or a regression to chase
32+
33+
If it needs anything else, such as the source tree for line-level attribution or
34+
your build flags, the skill is designed to ask for it rather than guess.
35+
36+
A good first prompt looks like this:
37+
38+
```text
39+
Profile /home/me/build/myapp --input bench.dat on my Arm Neoverse target
40+
me@neoverse-box with Performix. I want to know where the time goes.
41+
```
42+
43+
The skill picks **Code Hotspots** first, runs it, and reports back with the
44+
analysis report described on the next page.
45+
46+
{{% notice Note %}}
47+
Always give the **absolute path** to the binary, and use absolute paths for any
48+
output files your workload writes. Performix may launch the process from a
49+
temporary working directory, so relative paths can resolve unexpectedly.
50+
{{% /notice %}}

‎content/learning-paths/servers-and-cloud-computing/performix-llm-agent-skill/4-read-the-report.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
---
2+
title: Read the report and drive the optimization loop
3+
weight: 5
4+
5+
### FIXED, DO NOT MODIFY
6+
layout: learningpathall
7+
---
8+
9+
## The analysis report
10+
11+
After every recipe run, the skill returns a structured report instead of raw
12+
data. Expect these sections:
13+
14+
- **Bottleneck Summary**: what dominates, and how confident the skill is
15+
- **Key Metrics**: the three to five most decision-relevant numbers
16+
- **Hot Functions**: ranked, each with a brief root-cause note
17+
- **Recommended Actions**: concrete, prioritized fixes (file, function, line)
18+
- **Ruled Out**: hypotheses the data did *not* support, and why
19+
- **Next Step**: a single actionable instruction to run next, such as the next
20+
recipe to try or one code change to make, then re-profile
21+
22+
This report is the skill's primary deliverable. If the data is noisy or
23+
insufficient, the skill says so plainly and recommends a re-run rather than
24+
guessing.
25+
26+
## A worked example
27+
28+
For a compute-bound workload, a first Code Hotspots report from the skill looks
29+
like this:
30+
31+
```markdown
32+
## Performix Analysis Report
33+
34+
**Recipe:** Code Hotspots
35+
**Target:** neoverse-box (Arm Neoverse, 64 cores)
36+
**Workload:** /home/me/build/myapp --input bench.dat
37+
38+
### Bottleneck Summary
39+
40+
The escape-check loop in `escape_iterations` dominates CPU time (72% of samples),
41+
driven by an avoidable `sqrt` call inside the tight iteration. High confidence:
42+
a single function, stable across runs.
43+
44+
### Key Metrics
45+
46+
| Metric | Value | Assessment |
47+
|--------|-------|------------|
48+
| escape_iterations self % | 72.3% | Critical: single dominant hotspot |
49+
| sqrt self % | 45.1% | Critical: unnecessary math |
50+
| Total samples | 48,201 | Good: enough for reliable data |
51+
52+
### Hot Functions
53+
54+
| # | Function | Samples (%) | Root Cause |
55+
|---|----------|-------------|------------|
56+
| 1 | escape_iterations | 72.3% | sqrt in inner loop |
57+
| 2 | sqrt | 45.1% | magnitude check in escape_iterations |
58+
59+
### Recommended Actions (priority order)
60+
61+
1. **Remove sqrt** in `mandelbrot.c:22`: replace `sqrt(zr2 + zi2) > 2.0` with
62+
`(zr2 + zi2) > 4.0`.
63+
64+
### Ruled Out
65+
66+
- Memory locality is not the issue: the hotspot is purely scalar FP compute.
67+
68+
### Next Step
69+
70+
Rebuild with the sqrt removal, re-run Code Hotspots, and confirm
71+
escape_iterations drops below 30%.
72+
```
73+
74+
Notice the report names a file and line, ranks the cost by measured samples, and
75+
ends with a single action you can take immediately, rather than a wall of raw
76+
counters.
77+
78+
## Expect a two-pass investigation
79+
80+
The skill does not let a single Code Hotspots run justify "this is as fast as it
81+
gets." Code Hotspots shows *where* time goes, never *why*. Expect the skill to
82+
propose a **second pass** with a characterizing recipe (CPU Microarchitecture,
83+
Instruction Mix, or Memory Access) to explain why the hot spot is hot. Let it
84+
run that pass before deciding a cost is irreducible.
85+
86+
## Drive the optimization loop
87+
88+
Work with the skill one change at a time:
89+
90+
1. It establishes a **baseline** run.
91+
2. You, or the skill, make **one** focused change.
92+
3. It **re-profiles** with the same recipe and workload.
93+
4. It reports a **before/after comparison**, a measurement, not a claim.
94+
5. It looks for the **next bottleneck**, or summarizes the remaining trade-offs.
95+
96+
If you want to stop, ask for the remaining opportunities. The skill is designed to
97+
hand you measured options with their trade-offs rather than declare the work
98+
finished on its own.
99+
100+
{{% notice Tip %}}
101+
You can ask the skill to export a run with `apx run export` so you can share it
102+
with a teammate, or re-render its results as JSON with the `--json` flag for
103+
machine-readable output.
104+
{{% /notice %}}

‎content/learning-paths/servers-and-cloud-computing/performix-llm-agent-skill/_index.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
---
2+
title: Profile and optimize Arm workloads with the arm-performix agent skill
3+
description: Learn how to install and use the arm-performix skill so an AI coding assistant can drive Arm Performix for you to find code hotspots, diagnose pipeline stalls, and propose measured optimizations on Arm Neoverse.
4+
5+
minutes_to_complete: 30
6+
7+
who_is_this_for: This is an introductory topic for developers who use an AI coding assistant (such as GitHub Copilot in VS Code) and want it to drive Arm Performix on their behalf to profile and optimise software performance through the arm-performix skill, without having to memorize the apx CLI themselves.
8+
9+
learning_objectives:
10+
- Install and enable the arm-performix skill in your AI assistant
11+
- Trigger the skill with phrasing that activates the profiling workflow
12+
- Provide the context the skill needs to profile (target, binary, workload)
13+
- Read the analysis report the skill produces and drive the optimization loop
14+
15+
prerequisites:
16+
- An AI assistant that supports skills, such as GitHub Copilot in VS Code
17+
- An Arm Neoverse-based instance reachable from the assistant's environment
18+
- Arm Performix (the `apx` CLI) installed, or the Arm MCP Server configured
19+
20+
author:
21+
- Henry Wang
22+
23+
### Tags
24+
skilllevels: Introductory
25+
subjects: Performance and Architecture
26+
armips:
27+
- Neoverse
28+
tools_software_languages:
29+
- Arm Performix
30+
- GitHub Copilot
31+
- MCP
32+
operatingsystems:
33+
- Linux
34+
- macOS
35+
- Windows
36+
37+
further_reading:
38+
- resource:
39+
title: Arm Performix product page
40+
link: https://developer.arm.com/Tools%20and%20Software/Arm%20Performix
41+
type: website
42+
- resource:
43+
title: Find Code Hotspots with Arm Performix
44+
link: /learning-paths/servers-and-cloud-computing/cpu_hotspot_performix/
45+
type: learning-path
46+
- resource:
47+
title: Optimize application performance using Arm Performix CPU microarchitecture analysis
48+
link: /learning-paths/servers-and-cloud-computing/performix-microarchitecture/
49+
type: learning-path
50+
- resource:
51+
title: Optimize memory access behavior using Arm Performix and the Arm MCP Server
52+
link: /learning-paths/servers-and-cloud-computing/performix-memory-access/
53+
type: learning-path
54+
- resource:
55+
title: Migrate applications to Arm servers using migrate-ease
56+
link: /learning-paths/servers-and-cloud-computing/migrate-ease/
57+
type: learning-path
58+
- resource:
59+
title: Automate x86-to-Arm application migration using Arm MCP Server
60+
link: /learning-paths/servers-and-cloud-computing/arm-mcp-server/
61+
type: learning-path
62+
- resource:
63+
title: Get started with Servers and Cloud Computing
64+
link: /learning-paths/servers-and-cloud-computing/intro/
65+
type: learning-path
66+
- resource:
67+
title: Learn about Arm Neoverse processors
68+
link: https://www.arm.com/products/silicon-ip-cpu/neoverse
69+
type: website
70+
71+
72+
73+
### FIXED, DO NOT MODIFY
74+
# ================================================================================
75+
weight: 1 # _index.md always has weight of 1 to order correctly
76+
layout: "learningpathall" # All files under learning paths have this same wrapper
77+
learning_path_main_page: "yes" # This should be surfaced when looking for related content. Only set for _index.md of learning path content.
78+
---

‎content/learning-paths/servers-and-cloud-computing/performix-llm-agent-skill/_next-steps.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
# ================================================================================
3+
# FIXED, DO NOT MODIFY THIS FILE
4+
# ================================================================================
5+
weight: 21 # The weight controls the order of the pages. _index.md always has weight 1.
6+
title: "Next Steps" # Always the same, html page title.
7+
layout: "learningpathall" # All files under learning paths have this same wrapper for Hugo processing.
8+
---

0 commit comments

Comments
 (0)