Merge pull request #3376 from matt-cossins/topo

[TECH REVIEW CHANGES] Topo Template LP

Author: pareenaverma

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

@@ -1,27 +1,27 @@
 ---
-title: Create your own Topo Templates
+title: Create and deploy a custom Topo Template
 
 draft: true
 cascade:
     draft: true
 
-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,39 @@
+---
+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.
+
+These skills are optional authoring aids. The Template you created in this Learning Path works with Topo without them.
+
+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,13 +104,15 @@ 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.
 
+`sed` is a command-line text replacement tool. The `sed` commands replace placeholder text in `index.html` during the image build, so each cloned project can customize the web page without manually editing the source file.
+
 ### Create the compose file
 
 Create `compose.yaml`:
@@ -136,7 +138,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"
@@ -168,32 +170,33 @@ The `x-topo` section is the Topo metadata block:
 
 The argument names in `x-topo.args` match the keys under `services.message-card.build.args`. When Topo resolves the arguments, it writes the selected values into the build arguments.
 
+The same argument name appears in three places: `x-topo.args` defines what Topo asks for, `build.args` passes the value to Docker, and the Dockerfile `ARG` consumes it.
+
 ### 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 +212,39 @@ services:
 
 ### Deploy the new project
 
-Deploy the cloned project to the host machine:
+Check that your target is ready:
+
+```bash
+topo health --target user@my-target
+```
+
+Deploy the cloned project to your target:
+
+```bash
+topo deploy --target user@my-target
+```
+
+When deployment completes, open `http://<target-ip-address>:8088/` in your browser. You can also forward the port over SSH:
 
 ```bash
-topo deploy --target localhost
+ssh -L 8088:localhost:8088 user@my-target
 ```
 
-When deployment completes, open `http://localhost:8088/` in your browser.
+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 +274,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.