Merge pull request #3522 from anupras-mohapatra-arm/servers-and-cloud-computing

arm-performix skill LP review

Author: pareenaverma

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

@@ -1,79 +1,62 @@
 ---
-title: What is the arm-performix skill?
+title: Understand the arm-performix skill
+description: Understand how the arm-performix skill selects Arm Performix recipes, gathers workload context, and returns structured profiling reports.
 weight: 2
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-## A skill, not a tool
+## What the skill is
 
-**Arm Performix** is a desktop application for hardware-specific performance
+Arm Performix is a desktop application for hardware-specific performance
 tuning. It offers curated analysis pathways for performance-critical factors in
-applications, libraries, runtimes, and source code. The **arm-performix skill** is
-a set of instructions you add to your AI assistant so that it knows how to use
-Performix correctly on your behalf: which recipe to pick, how to gather context,
-how to read the results, and how to report findings.
+applications, libraries, runtimes, and source code.
 
-Without the skill, an assistant tends to guess at performance problems by reading
-your source code. With the skill, it follows a disciplined workflow: measure
-first, characterize the bottleneck, change one thing at a time, and confirm the
-improvement with before/after data.
+The `arm-performix` skill is a set of instructions you can add to your AI assistant so that it knows how to use Performix correctly on your behalf. The skill defines which recipe to pick, how to gather context, how to read the results, and how to report findings.
 
-## What the skill does for you
+Without the skill, an assistant might guess at performance problems by reading
+your source code.
 
 When the skill is active, the assistant:
 
 - Asks for the target, binary path, and workload command before profiling
 - Chooses the narrowest Performix recipe that answers your question
 - Runs the recipe through the `apx` command-line interface (CLI), or through the
   Arm Model Context Protocol (MCP) Server
-- Returns a structured Analysis Report with a bottleneck summary, key metrics,
+- Returns a structured analysis report with a bottleneck summary, key metrics,
   hot functions, ranked recommendations, and a single next step
 
-## What the skill does not do
-
-- Profile non-Neoverse Arm cores, such as phone-class SoCs
-- Guess at bottlenecks from source reading instead of measurement
-- Silently switch to another profiler when Performix is unavailable; it asks you
-  how to proceed instead
-
-## The recipes it can run
+## What recipes the skill can run
 
 Performix exposes five profiling recipes, and the skill orchestrates them as a
 workflow: it picks a starting recipe from your question, then follows the
 evidence into whichever further recipes are needed to explain and confirm the
-bottleneck. Each recipe answers a different question:
+bottleneck. 
+
+Each recipe provides a different view of application performance:
 
 | Your question | Recipe | What it shows |
 | --- | --- | --- |
-| Where is my time spent? | **Code Hotspots** | Hottest functions, call paths, flame graph |
-| Why is the pipeline stalling? | **CPU Microarchitecture** | Front-end and back-end stalls, bad speculation, retiring |
-| Am I using single instruction, multiple data (SIMD), such as Neon or Scalable Vector Extension (SVE)? | **Instruction Mix** | Scalar vs vector instruction balance |
-| Is memory the bottleneck? | **Memory Access** | L1 cache hit rate, latency, translation lookaside buffer (TLB) and page-walk pressure |
-| What can the hardware do? | **System Characterization** | Memory bandwidth and latency baseline per non-uniform memory access (NUMA) node |
+| Where is my time spent? | Code Hotspots | Hottest functions, call paths, and flame graphs to identify where time is spent |
+| Why is the pipeline stalling? | CPU Microarchitecture | Front-end and back-end pipeline stalls, bad speculation, retiring |
+| Am I using single instruction, multiple data (SIMD), such as Neon or Scalable Vector Extension (SVE)? | Instruction Mix | Scalar versus vector instruction balance |
+| Is memory the bottleneck? | Memory Access | L1 cache hit rate, latency, translation lookaside buffer (TLB) and page-walk pressure to identify whether memory is the bottleneck |
+| What can the hardware do? | System Characterization | Memory bandwidth and latency baseline per non-uniform memory access (NUMA) node to identify what the hardware can do |
 
 {{% notice Note %}}
-**Where the recipes run:**
-
-- **Profiling target** (the machine running your workload). The four
-  microarchitecture-level recipes (CPU Microarchitecture, Instruction Mix,
-  Memory Access, and System Characterization) require an **Arm Neoverse** target
-  on Linux; Memory Access additionally needs the Statistical Profiling Extension
-  (SPE) enabled. Code Hotspots is broader: it also runs on x86-64 Linux and on
+- The four microarchitecture-level recipes — CPU Microarchitecture, Instruction Mix,
+  Memory Access, and System Characterization — require an Arm Neoverse target
+  on Linux. The Code Hotspots recipe additionally runs on x86-64 Linux and on
   Windows 11 on Arm or x86-64.
-- **Host** (the machine where you run the `apx` CLI or your AI assistant). It can
-  be macOS, Windows, or Linux on either arm64 or x86-64, and connects to the
-  target locally or over Secure Shell (SSH).
+- To use the Memory Access recipe, enable the Statistical Profiling Extension
+  (SPE).
+- The host machine can be macOS, Windows, or Linux on either arm64 or x86-64. The host can connect to the target locally or over SSH.
+- The skill guides AI assistants to use the `apx` CLI by default. If `apx` isn’t installed or available, it asks how you want to proceed rather than switching tools automatically. You can use the Arm MCP Server as an alternative tool, especially if you want fully agent-driven launch-mode profiling. Note that the MCP server doesn’t expose the System Characterization recipe.
 {{% /notice %}}
 
-{{% notice Note %}}
+## What you've learned and what's next
 
-The `apx` CLI is the full-capability interface. Use it for attach-to-process ID
-(PID), system-wide captures, timed captures, run export/import, custom result
-queries, CI/CD automation, and the System Characterization recipe. The Arm MCP
-Server is useful for agent-driven launch-mode profiling, but it exposes only the
-`code_hotspots`, `instruction_mix`, `cpu_microarchitecture`, and `memory_access`
-recipes. If you need System Characterization or run-history operations, use the
-CLI or the graphical user interface (GUI).
-{{% /notice %}}
+You've now learned how the `arm-performix` skill can help an assistant use Performix correctly, and what Performix recipes the skill can run.
+
+Next, you'll install the skill and make it discoverable to your AI assistant. 

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

@@ -1,18 +1,19 @@
 ---
-title: Install and enable the skill
+title: Install and enable the arm-performix skill
+description: Download and install the arm-performix skill, place it in an AI assistant's skills directory, and confirm that the assistant can discover it.
 weight: 3
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-## Get the skill files
+## Download the skill folder
 
-Use one of these options to get the skill files.
+Use one of the following options to download the skill files:
 
-### Option 1: Clone from Gitee
+### Clone skills repository from Gitee
 
-Use this option if you prefer managing the skill source with Git.
+If you prefer managing the skill source with Git, clone the skill file from Gitee.  
 
 From the root of the project where your assistant works, clone the skills
 repository:
@@ -29,23 +30,22 @@ mkdir -p .github/skills
 cp -R anolis-skills/skills/arm-performix .github/skills/
 ```
 
-### Option 2: Download from SkillHub
+### Download package from SkillHub
 
-Use this option if you prefer downloading a package directly from the web.
+If you prefer downloading a package directly from the web, download the skill from SkillHub.
 
-Go to the [arm-performix SkillHub page](https://skillhub.openanolis.cn/skill/arm-performix)
+Go to the [`arm-performix` SkillHub page](https://skillhub.openanolis.cn/skill/arm-performix)
 and download the skill.
 
 The downloaded skill is a `.zip` package. Extract it, then place the
 `arm-performix` folder in your assistant's skills directory.
 
-## Place the skill files
+## Make the skill folder discoverable
 
-The skill is a folder that contains `SKILL.md`, `README.md`, and a
-`references/` directory. Put it where your assistant discovers skills. For GitHub
-Copilot in VS Code, use the `.github/skills/` directory of your workspace. Other
-assistants use different project directories, such as `.claude/skills/` or
-`.agents/skills/`, so use the directory that matches your assistant:
+The skill folder contains `SKILL.md`, `README.md`, and a
+`references/` directory. Place the folder where your AI assistant discovers skills. 
+
+For GitHub Copilot in VS Code, use the `.github/skills/` directory of your workspace:
 
 ```text
 .github/
@@ -57,36 +57,25 @@ assistants use different project directories, such as `.claude/skills/` or
         <references>.md
 ```
 
-The `SKILL.md` file describes the profiling workflow; `README.md` provides
-supporting overview information; and files under `references/` provide detailed
+Other assistants use different project directories, such as `.claude/skills/` or
+`.agents/skills/`, so use the directory that matches your assistant. 
+
+The `SKILL.md` file describes the profiling workflow. `README.md` provides
+supporting overview information. The files under `references/` provide detailed
 reference materials that the assistant reads on demand.
 
-## Confirm the skill is discovered
-
-Reload your assistant or IDE, then ask your assistant a profiling question (see
-the next page). In VS Code, confirm that Agent Skills are enabled in the
-**Configure Chat** skills view or with the `/skills` command. A correctly
-installed skill is picked up automatically when your request matches its
-triggers; you do not need to invoke it with an explicit command.
-
-{{% notice Tip %}}
-The skill only *describes* how to use Performix. You still need Performix itself
-available: either the `apx` CLI on your `PATH`, or the Arm MCP Server configured.
-The skill tells you when neither is reachable rather than guessing.
-{{% /notice %}}
-
-## Choose how Performix runs
-
-The skill can start Performix in two ways. You do not have to pick manually, but
-it helps to know which path you have set up:
-
-- **apx CLI**: the full-capability path. Install it on your host, add the `apx`
-  directory to your `PATH`, and confirm it with `apx version` from the same
-  terminal environment your assistant can use. This path works best for remote
-  Secure Shell (SSH) targets, automation, and CI.
-- **Arm MCP Server**: bundles its own `apx`, so your host needs no CLI install.
-  This path works best for fully agent-driven launch-mode profiling. The skill
-  routes here only when you ask, or when the CLI is not installed and you confirm
-  MCP. Use the CLI or GUI for attach-to-process ID (PID), system-wide profiling,
-  run export/import, custom result queries, CI/CD automation, and System
-  Characterization.
+## Confirm the skill is discoverable
+
+Reload your assistant or IDE to confirm that it can discover the skill. 
+
+In VS Code, confirm that Agent Skills are enabled in the **Configure Chat** skills view or with the `/skills` command.
+
+A correctly installed skill is picked up automatically when your request shows profiling or performance intent. You don't need to use a specific command to invoke the skill. 
+
+For prompts you can use to confirm skill discovery, see [Best practices for prompting AI assistants to use the arm-performix skill](/learning-paths/servers-and-cloud-computing/performix-llm-agent-skill/3-trigger-the-skill).
+
+## What you've accomplished and what's next
+
+You've now installed the `arm-performix` skill folder and made it discoverable to your AI assistant. 
+
+Next, you'll learn best practices for writing prompts to profile an application using the skill. 

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

@@ -1,53 +1,61 @@
 ---
-title: Trigger the skill with profiling context
+title: Best practices for prompting AI assistants to use the arm-performix skill
+description: Write prompts that activate the arm-performix skill by providing profiling intent, an Arm target, an absolute binary path, and a repeatable workload.
 weight: 4
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-## Write a prompt that activates the skill
+## Ensure the prompt shows performance and profiling intent
 
-The skill activates on performance and profiling intent. Prompts that work:
+The skill activates on performance and profiling intent. 
+
+The following are examples of prompts that show the expected intent:
 
 - "Profile this workload on Arm and find the hotspots."
 - "Why is this binary slow on my Arm Neoverse server?"
 - "Use Performix to check whether my hot loop uses vector instructions."
 - "Investigate cache and translation lookaside buffer stalls on my Neoverse target."
 
-Prompts that don't activate the skill:
+Prompts that are vague won't activate the skill.
+
+The following are example vague prompts:
 
-- "Will my code build on Arm?" — a migration question, not a profiling one.
-- "Make my code faster" — too vague without a target or binary; add both.
+- "Will my code build on Arm?" 
+- "Make my code faster" 
 
 ## Provide context up front
 
-The skill needs these details before it can profile. Supplying them in your first
-message avoids a round of back-and-forth:
+In addition to prompting with the right intent, you need to provide the following context:
 
-1. **Target**: a local Arm machine, or `user@host` for a remote Secure Shell (SSH) target
-2. **Binary**: the **absolute path** to the executable on the target
-3. **Workload**: the exact command and arguments, ideally repeatable
-4. **Goal**: hotspots, vector instruction usage, memory locality, or a regression
+1. Target: a local Arm machine, or `user@host` for a remote Secure Shell (SSH) target
+2. Binary: the absolute path to the executable on the target
+3. Workload: the exact command and arguments, ideally repeatable
+4. Goal: hotspots, vector instruction usage, memory locality, or a regression
    to investigate
 
-If it needs anything else, such as the source tree for line-level attribution or
-your build flags, the skill asks rather than guesses.
+If the AI assistant needs anything else, such as the source tree for line-level attribution or
+your build flags, it'll prompt you for it rather than making an assumption.
 
-A good starting prompt looks like this:
+The following is a good starting prompt:
 
 ```text
 Profile /home/me/build/myapp --input /home/me/data/bench.dat on my Arm Neoverse target
 me@neoverse-box with Performix. I want to know where the time goes.
 ```
 
 This prompt gives the assistant the workload command and the SSH target. The
-skill picks **Code Hotspots** first, runs it, and reports back with an analysis.
-
-{{% notice Note %}}
-Always give the **absolute path** to the binary, and use absolute paths for input
-files, output files, and other files your workload reads or writes. If the
-workload must run from a specific directory, tell the assistant that working
-directory explicitly. Performix can launch the process from a different working
-directory, so relative paths can resolve unexpectedly.
-{{% /notice %}}
+skill picks Code Hotspots first, runs it, and reports back with an analysis.
+
+## Provide absolute paths
+
+Always provide the absolute path to the binary. Use absolute paths for all files your workload reads or writes. 
+
+If the workload must run from a specific directory, include the directory in the prompt. Performix can launch the process from a different working directory, so relative paths can resolve unexpectedly.
+
+## What you've learned and what's next
+
+You've now learned how to best structure your prompts to profile an application using the `arm-performix` skill.
+
+Next, you'll learn how to use generated reports to drive performance improvements.