Topo template tech review

Author: matt-cossins

content/learning-paths/cross-platform/create-your-own-topo-templates/_index.md

@@ -1,27 +1,23 @@
 ---
-title: Create your own Topo Templates
-
-draft: true
-cascade:
-    draft: true
+title: Create and deploy a custom Topo Template
 
-description: Create a Topo Template after your project to use Topo to deploy containerized workloads to Arm-based Linux targets over SSH.
+description: Understand how to create and modify Topo Templates, allowing you to deploy your projects as containerized workloads to Arm-based Linux targets over SSH.
 
 minutes_to_complete: 30
 
 who_is_this_for: This is an introductory topic for embedded, edge, and cloud software developers who want to create their own Topo Templates projects to be natively deployed with Topo.
 
 learning_objectives:
     - Explain the purpose and structure of a Topo Template
-    - Clone and deploy an existing Topo Template to validate the Template workflow
-    - Add clone-time arguments to customize a Topo Template
+    - Clone and deploy an existing Topo Template and modify it by adding new clone-time arguments
     - Create a new Topo Template from a Docker Compose project
     - Add x-topo metadata for configurable arguments, deployment guidance, and hardware requirements
+    - Understand where to find Agent Skills, for use when creating or modifying Topo Templates
 
 prerequisites:
     - This learning path builds on [Deploy containerized workloads to Arm-based Linux targets with Topo](/learning-paths/cross-platform/deploy-containerized-workloads-with-topo/).
     - A host machine (x86 or Arm) with Linux, macOS, or Windows
-    - (Optional) An Arm-based Linux target accessible over SSH, for example an Arm-based Linux VM, Raspberry Pi, DGX Spark, or NXP i.MX 93
+    - An Arm-based Linux target accessible over SSH, for example an Arm-based Linux VM, Raspberry Pi, DGX Spark, or NXP i.MX 93
     - Docker installed on the host and target. For installation steps, see [Install Docker](/install-guides/docker/).
     - Basic familiarity with containers and CLI tools
 

content/learning-paths/cross-platform/create-your-own-topo-templates/agent-skills.md

@@ -0,0 +1,37 @@
+---
+title: Use agent skills for Topo Templates
+weight: 6
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Skills for authoring Templates
+
+If you already have a Docker Compose project and want to convert it to a Topo Template, or you want to create your own Topo Template from scratch, you can do so with an Agent Skill.
+
+Visit [Topo Skills](https://github.com/arm/topo-template-format#authoring-skills) for the most up-to-date list of the available Topo Template skills and instructions on how to install them.
+
+At the time of writing, the [Topo Template Format Specification](https://github.com/arm/topo-template-format) provides the following skills:
+
+1. `topo-template-context`: provides Topo and Topo Template reference context for questions about x-topo metadata, schema, docs, and CLI Template behavior.
+2. `topo-template-bootstrap`: converts a repository into a Topo Template by adding or improving `compose.yaml` and `x-topo` metadata.
+3. `topo-template-lint`: reviews an existing Topo Template for correctness, consistency, and authoring best practices.
+
+## Install the skills
+
+Install the Topo Template skills with [npx skills](https://github.com/vercel-labs/skills):
+
+```bash
+npx skills add arm/topo-template-format --all --yes
+```
+
+Restart your agent after installing or updating skills.
+
+## Use the skills
+
+You can then prompt your agent to use the skill to create a Topo Template from an existing project:
+
+```text
+Use the topo-template-bootstrap skill to convert this repository into a Topo Template.
+```

content/learning-paths/cross-platform/create-your-own-topo-templates/creating-a-new-template.md

@@ -22,8 +22,8 @@ The Template you create serves a small web page with configurable text and color
 Create a new directory for the Template:
 
 ```bash
-mkdir topo-message-card
-cd topo-message-card
+mkdir -p ~/topo-message-card
+cd ~/topo-message-card
 ```
 
 A Topo Template is a normal project directory. At minimum, it must contain a `compose.yaml` file. Most Templates also include a `Dockerfile` and application source code.
@@ -48,7 +48,7 @@ Create the application HTML file:
   <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
-    <title>{{CARD_TITLE}}</title>
+    <title>__CARD_TITLE__</title>
     <style>
       body {
         margin: 0;
@@ -62,7 +62,7 @@ Create the application HTML file:
 
       main {
         width: min(720px, calc(100vw - 40px));
-        border-top: 8px solid {{ACCENT_COLOR}};
+        border-top: 8px solid __ACCENT_COLOR__;
         background: white;
         padding: 40px;
         box-shadow: 0 18px 40px rgba(15, 23, 42, 0.12);
@@ -82,14 +82,14 @@ Create the application HTML file:
   </head>
   <body>
     <main>
-      <h1>{{CARD_TITLE}}</h1>
-      <p>{{CARD_MESSAGE}}</p>
+      <h1>__CARD_TITLE__</h1>
+      <p>__CARD_MESSAGE__</p>
     </main>
   </body>
 </html>
 ```
 
-The values wrapped in double braces are placeholders. The `Dockerfile` replaces them with values supplied by Topo.
+The values wrapped in double underscores are placeholders. The `Dockerfile` replaces them with values supplied by Topo.
 
 ### Create the Dockerfile
 
@@ -104,9 +104,9 @@ ARG CARD_TITLE="Hello from Topo"
 ARG CARD_MESSAGE="This page was created from a Topo Template."
 ARG ACCENT_COLOR="#0091bd"
 
-RUN sed -i "s|{{CARD_TITLE}}|${CARD_TITLE}|g" /usr/share/nginx/html/index.html
-RUN sed -i "s|{{CARD_MESSAGE}}|${CARD_MESSAGE}|g" /usr/share/nginx/html/index.html
-RUN sed -i "s|{{ACCENT_COLOR}}|${ACCENT_COLOR}|g" /usr/share/nginx/html/index.html
+RUN sed -i "s|__CARD_TITLE__|${CARD_TITLE}|g" /usr/share/nginx/html/index.html
+RUN sed -i "s|__CARD_MESSAGE__|${CARD_MESSAGE}|g" /usr/share/nginx/html/index.html
+RUN sed -i "s|__ACCENT_COLOR__|${ACCENT_COLOR}|g" /usr/share/nginx/html/index.html
 ```
 
 Topo passes configuration values to Templates through Docker build arguments. The `ARG` lines define the values consumed during the image build.
@@ -136,7 +136,7 @@ x-topo:
     message, and accent color.
   type: "application"
   deploy_success_message: |
-    Message Card is running. Open http://localhost:8088/ in your browser.
+    Message Card is running on port 8088.
   args:
     CARD_TITLE:
       description: "The title to show on the message card"
@@ -170,30 +170,29 @@ The argument names in `x-topo.args` match the keys under `services.message-card.
 
 ### Clone the local Template
 
-Move to the parent directory and clone your local Template with Topo:
+Clone your local Template into a new project directory. You can choose to answer interactive prompts for the arguments (using the first command below), or you can opt to include the arguments in the command (using the second command).
 
+Interactive argument prompts:
 ```bash
-cd ..
-topo clone dir:./topo-message-card ./message-card-demo \
-  CARD_TITLE="Hello from Arm" \
-  CARD_MESSAGE="Created from a new Topo Template" \
-  ACCENT_COLOR="#00a3a3"
+topo clone dir:$HOME/topo-message-card $HOME/message-card-demo
 ```
 
-You can also omit the argument values and answer the interactive prompts:
-
+Arguments included in command:
 ```bash
-topo clone dir:./topo-message-card ./message-card-demo
+topo clone dir:$HOME/topo-message-card $HOME/message-card-demo \
+  CARD_TITLE="Hello from Arm" \
+  CARD_MESSAGE="Created from a new Topo Template" \
+  ACCENT_COLOR="#00a3a3"
 ```
 
 After cloning, inspect the generated project:
 
 ```bash
-cd message-card-demo
+cd ~/message-card-demo
 sed -n '1,80p' compose.yaml
 ```
 
-The `build.args` values should contain the values you provided:
+The `build.args` should contain the values you provided:
 
 ```yaml
 services:
@@ -209,25 +208,33 @@ services:
 
 ### Deploy the new project
 
-Deploy the cloned project to the host machine:
+Deploy the cloned project to your target:
 
 ```bash
-topo deploy --target localhost
+topo deploy --target user@my-target
 ```
 
-When deployment completes, open `http://localhost:8088/` in your browser.
+When deployment completes, open `http://<target-ip-address>:8088/` in your browser. You can also forward the port over SSH:
+
+```bash
+ssh -L 8088:localhost:8088 user@my-target
+```
+
+Then open `http://localhost:8088/` in your browser.
+
+![Screenshot of the new Topo Template - a simple web page. This confirms successful deployment and provides a visual reference for the expected result.#center](new_template.png "Hello from Arm web page")
 
 Confirm that the container is running:
 
 ```bash
-topo ps --target localhost
+topo ps --target user@my-target
 ```
 
 The output should include the `message-card` service and port `8088`.
 
-### Add hardware requirements
+### Adding hardware requirements
 
-Only add `features` when your Template needs specific Arm hardware features. For example, a SIMD benchmark that requires SVE can declare:
+Only add `features` when your Template needs specific Arm hardware features. For example, a SIMD benchmark that requires SVE can declare that it needs SVE:
 
 ```yaml
 x-topo:
@@ -257,4 +264,8 @@ If the Template is intended to be reusable by the wider Topo community, include:
 - A license file
 - Clear `x-topo` metadata and argument descriptions
 
-You now have a complete Topo Template created from scratch.
+## What you've accomplished and what's next
+
+You have now created a complete Topo Template from scratch. You created the web page HTML, added a Compose file, described the Template with `x-topo` metadata, supplied clone-time arguments, and deployed the generated project to an Arm-based Linux target.
+
+Next, you will learn where to find Agent Skills that can help you create, modify, and review Topo Templates.

content/learning-paths/cross-platform/create-your-own-topo-templates/hello-world-template.md

@@ -1,50 +1,26 @@
 ---
-title: Clone Topo Hello World, deploy and modify it
+title: Deploy the Topo 'Hello World' Template
 weight: 3
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-## Clone and deploy the Hello World Template
+This section quickly runs through the deployment of the `Hello World` Template, similar to the LLM on CPU Template in the [Deploy containerized workloads to Arm-based Linux targets with Topo](/learning-paths/cross-platform/deploy-containerized-workloads-with-topo/) Learning Path.
 
-### List Topo Templates
+## Clone the 'Hello World' Topo Template
 
-List the available Topo Templates from the curated list in Topo:
+On your host machine, use the terminal to clone the template into your home directory.
 
 ```bash
-topo templates
-```
-
-The output should be similar to the following, the Hello World Template should be present:
-
-```output
-Hello World | https://github.com/Arm-Examples/topo-welcome.git | main
-  A minimal "Hello, World" web app for validating a Topo setup and deployment.
-  It runs a single service that exposes a web page on the target,
-  with the greeting text customizable via the GREETING_NAME parameter.
-
-Lightbulb Moment | https://github.com/Arm-Examples/topo-lightbulb-moment.git | main
-  Features: remoteproc-runtime
-  Reads a switch over GPIO pins on an M class cpu, reports switch state over
-  Remoteproc Message, then a web application on the A class reads this and
-  displays a lightbulb in either the on or off state. The lightbulb state is
-  described by an LLM in any user-specified style.
-
-(...)
-```
-
-### Clone the Hello World Template
-
-```bash
-topo clone https://github.com/Arm-Examples/topo-welcome.git
+topo clone https://github.com/Arm-Examples/topo-welcome.git ~/topo-welcome
 ```
 
 The output should be similar to the following. You will be prompted for configuration arguments:
 
 ```output
 ┌─ Copy files ──────────────────────────────────────────
-Cloning into 'topo-welcome'...
+Cloning into '/home/user/topo-welcome'...
 remote: Enumerating objects: 12, done.
 remote: Counting objects: 100% (12/12), done.
 remote: Compressing objects: 100% (9/9), done.
@@ -58,48 +34,43 @@ Default: World
 GREETING_NAME (required)>
 ```
 
-You can fill the GREETING_NAME with your own name of press Enter to choose the defaults.
-You will then see something similar to the following output:
+Provide a name for the `GREETING_NAME` argument, e.g., 'Tomas'. 
+
+Press Enter to submit your entry. You will then see a similar output to below:
 
 ```output
 ┌─ Project ready ───────────────────────────────────────
-Created in 'topo-welcome'
+Created in '/home/user/topo-welcome'
 
 Now run:
-  cd topo-welcome
+  cd ~/topo-welcome
   topo deploy
 ```
 
-### Prepare the host machine for emulation
+## Prepare your target
 
-Topo Templates are meant to be deployed to Arm-based Linux targets. In this learning path, we are going to be deploying to your host machine. If your machine is an x86 machine, you may need to install an arm64 emulator, such as:
+Topo Templates are meant to be deployed to Arm-based Linux targets. In this Learning Path, use the Arm-based Linux target you prepared in the previous Learning Path, for example a Raspberry Pi, AWS Arm instance, or other Linux target accessible over SSH.
+
+Confirm that Topo can inspect your target, and that there are no compatibility issues:
 
 ```bash
-docker run --privileged --rm tonistiigi/binfmt --install arm64
-docker run --rm --platform linux/arm64 alpine uname -m
+topo health --target user@my-target
 ```
 
-The expected output should be:
+If your host machine is a Linux machine and you want to use it as the target, you can use `--target localhost`.
 
-```output
-aarch64
-```
-
-### Deploy the template to localhost
+## Deploy the template to your target
 
-You can now deploy the project to the host/build machine:
+You can now deploy the project to your target:
 
 ```bash
-cd topo-welcome
-topo deploy --target localhost
+cd ~/topo-welcome
+topo deploy --target user@my-target
 ```
 
 Wait for the build and deploy to complete. The expected output is similar to:
 
 ```output
-$ topo deploy --target localhost
-10:52:52 WRN registry transfer is not yet supported with this configuration. Falling back to direct transfer.
-
 ┌─ Build images ────────────────────────────────────────
 [+] Building 6.4s (11/11) FINISHED                                                                                                  
  => [internal] load local bake definitions    0.0s
@@ -128,22 +99,37 @@ Run `topo ps` to see deployed containers    0.2s
 Confirm that the container is running correctly:
 
 ```bash
-topo ps
+topo ps --target user@my-target
 ```
 
-The output should be similar to:
+The `topo ps` command lists the services that Topo deployed to the target. The output should be similar to:
 
 ```output
 Image              Status                  Processing Domain   Address
-topo-welcome-app   Up Less than a second   Linux Host          localhost:8000, [::]:8000
+topo-welcome-app   Up 58 seconds           Linux Host          my-target:8000, [::]:8000
 ```
 
+The columns show:
+
+- `Image`: the container image or service that Topo started
+- `Status`: whether the service is running, and how long it has been running
+- `Processing Domain`: where the workload is running, such as the Linux Host on the target
+- `Address`: the exposed address and port for the service
+
 ### Visualize the application
 
-Open your browser on `http://localhost:8000/`, you should see the Hello World application running.
+If the target is reachable on your network, open `http://<target-ip-address>:8000/` in your browser.
+
+If you prefer to forward the port over SSH, run:
+
+```bash
+ssh -L 8000:localhost:8000 user@my-target
+```
+
+Then open `http://localhost:8000/` in your browser.
 
 
 The Hello World application appears as follows:
 
 
-![Screenshot of the Hello World web interface running on localhost. This confirms successful deployment and provides a visual reference for the expected result.#center](topo_hello_world.png "Hello World web interface on localhost")
+![Screenshot of the Hello World web interface. This confirms successful deployment and provides a visual reference for the expected result.#center](hello_tomas.png "Hello World web interface")