Skip to content

SKILL.md

Latest commit

 

History

History
252 lines (177 loc) · 7.94 KB

SKILL.md

File metadata and controls

252 lines (177 loc) · 7.94 KB
Raw

Skill: new-ryzer

Scaffold a new Ryzer Docker package with all required files.

Usage

new-ryzer <category> <package_name>
  • category — one of the existing directories under packages/ (e.g. llm, vlm, vla, robotics, vision, npu, ros, graphics, ide, adaptive-socs), or a new category name if none fits.
  • package_name — lowercase, no spaces or hyphens (e.g. ollama, genesis, mobilesam).

What is a Ryzer?

A Ryzer is a self-contained, composable Docker package for running AI/ML/robotics workloads on AMD Ryzen AI hardware. Ryzers are layered — each one builds on top of a base image, and multiple ryzers can be chained together in a single build.

Users build and run ryzers with:

ryzers build <package_name>        # build a single package
ryzers build pkg1 pkg2 pkg3        # chain multiple packages (each layers on the previous)
ryzers run                         # run the most recently built image
ryzers run bash                    # override CMD to get a shell

Required Output

Every ryzer package lives at packages/<category>/<package_name>/ and must contain exactly these 4 files:

packages/<category>/<package_name>/
├── Dockerfile
├── config.yaml
├── test.sh (or test.py)
└── README.md

Optional extras: demo.sh, demo.py, LICENSE, additional test files.

File Specifications

1. Dockerfile

Rules:

  • MUST start with ARG BASE_IMAGE and FROM ${BASE_IMAGE} — this enables layered composition.
  • MUST include the copyright header.
  • Set WORKDIR /ryzers before copying test/demo scripts.
  • Copy test scripts into /ryzers/test_<package_name>.<ext> and chmod +x them.
  • End with CMD /ryzers/test_<package_name>.<ext> so the default action validates the install.
  • Use EXPOSE for any ports the package serves on.
  • Keep installs minimal — only what this package needs.

Template:

# Copyright(C) 2026 Advanced Micro Devices, Inc. All rights reserved.
# SPDX-License-Identifier: MIT

ARG BASE_IMAGE
FROM ${BASE_IMAGE}

ENV DEBIAN_FRONTEND=noninteractive

# Install dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    <system-packages> \
 && rm -rf /var/lib/apt/lists/*

# Install Python packages
RUN pip3 install --no-cache-dir --break-system-packages \
    "<package1>==<version>" \
    "<package2>==<version>"

# Copy test script
WORKDIR /ryzers
COPY test.sh /ryzers/test_<package_name>.sh
RUN chmod +x /ryzers/test_<package_name>.sh

# EXPOSE <port>  # if applicable

CMD /ryzers/test_<package_name>.sh

Notes:

  • Use --no-install-recommends and clean up apt lists to keep image size down.
  • Use --no-cache-dir and --break-system-packages with pip3.
  • Pin versions where possible for reproducibility.
  • If the package needs build args, declare them with ARG and document in config.yaml.

2. config.yaml

This file configures Docker build and run flags. All fields are optional — include only what the package needs. An empty/commented config.yaml is valid.

Template:

# Copyright(C) 2026 Advanced Micro Devices, Inc. All rights reserved.
# SPDX-License-Identifier: MIT

### ryzers build options

# gpu_support: false          # add GPU support, default is true
# x11_display: false          # add X11 support, default is true
# init_image: "image_name"    # The first docker image to use as a base
                              # default is ryzers.RYZERS_DEFAULT_INIT_IMAGE

# build_arguments:            # List of ARGs to pass to the `docker build` call
# - "ARG=VALUE"               # E.g. - "PYTHON_VERSION=3.12"


### ryzers run options

# environment_variables:              # List of environment variables to set in the container
# - "ENV_VARIABLE=VALUE"              # E.g. "PYTHONPATH=/path/to/python"

# port_mappings:
# - "host_portnum:container_portnum"  # List of port mappings to expose from the docker
                                      # E.g. "8888:8888" for JupyterLab

# volume_mappings:
# - "host_path:container_path"        # List of volume mappings to mount from the host
                                      # E.g. "/path/to/host:/path/to/container"

# docker_extra_run_flags: "run flags" # Additional flags to pass to the `docker run` command

Common patterns — uncomment/add as needed:

Scenario What to add
Package serves a web UI or API port_mappings: ["8080:8080"]
Package downloads large models volume_mappings: ["$PWD/workspace/.cache/huggingface:/root/.cache/huggingface"]
Package needs extra shared memory docker_extra_run_flags: "--shm-size=2g"
Package needs a build-time variable build_arguments: ["MY_VERSION=1.0"]
Package needs specific env vars at runtime environment_variables: ["HSA_OVERRIDE_GFX_VERSION=11.0.0"]
Package does NOT need GPU gpu_support: false
Package does NOT need X11 x11_display: false

3. test.sh (or test.py)

A quick smoke test that validates the package installed correctly. Should exit 0 on success, non-zero on failure.

Bash template (test.sh):

#!/bin/bash

# Copyright (C) 2026 Advanced Micro Devices, Inc. All rights reserved.
# SPDX-License-Identifier: MIT

echo "Running tests for <package_name>..."
<command_to_test_installation>
if [ $? -eq 0 ]; then
  echo "Tests passed!"
else
  echo "Tests failed!"
  exit 1
fi

Python template (test.py):

#!/usr/bin/env python3

# Copyright(C) 2026 Advanced Micro Devices, Inc. All rights reserved.
# SPDX-License-Identifier: MIT

import <package>
print(f"<package> version: {<package>.__version__}")
# Add a minimal functional check here

Guidelines:

  • Keep it fast — just verify the install, don't run full test suites.
  • Import the main module, print its version, maybe run one trivial operation.
  • For services (like ollama), start the server, wait briefly, then test the endpoint.

4. README.md

Template:

# <Package Name> Docker Setup

Brief description of what this package provides and what it's useful for.

## Build & Run

```sh
ryzers build <package_name>
ryzers run

References

Copyright(C) 2026 Advanced Micro Devices, Inc. All rights reserved.


---

## After Creating the Package

1. **Update the main `README.md`** — add a link to the new package in the "Supported Packages" table under the appropriate category row.

2. **Test locally** (if possible):
   ```bash
   ryzers build <package_name>
   ryzers run

Existing Categories

Category Directory What goes here
LLM packages/llm/ Large language models (ollama, llamacpp, etc.)
VLM packages/vlm/ Vision-language models (gemma3, phi4, etc.)
VLA packages/vla/ Vision-language-action models (openvla, gr00t, etc.)
Robotics packages/robotics/ Robotics frameworks (lerobot, act, genesis, etc.)
ROS packages/ros/ ROS 2 and related tools (ros, gazebo)
Vision packages/vision/ Computer vision (opencv, sam, ultralytics, etc.)
NPU packages/npu/ Ryzen AI NPU tools (xdna, iron, etc.)
Graphics packages/graphics/ 3D/graphics engines (o3de)
IDE packages/ide/ Development environments (jupyterlab)
Adaptive SoCs packages/adaptive-socs/ Adaptive SoC tools (pynq-remote)
Workshops packages/workshops/ Workshop demos

Create a new category directory if the package doesn't fit any of these.

Reference Examples

Study these existing packages for patterns:

  • Minimal package: packages/init/ryzer_blank/ — bare minimum Dockerfile
  • Typical package: packages/robotics/genesis/ — good all-around reference
  • Service with ports: packages/llm/ollama/ — port mappings, volume mounts, server test
  • Package with build args: packages/vision/opencv/ — uses ARG OPENCV_VERSION from config.yaml
  • Web UI package: packages/ide/jupyterlab/ — port mapping, environment variables