Skip to content

Commit 0fd1f91

Browse files
adsahu-nvadsahu-nv
authored
Merge pull request #390 from NVIDIA-AI-IOT/feat/skills
Add agent skills for model catalog, build verification, and code samples
2 parents bbac8c7 + e112535 commit 0fd1f91

4 files changed

Lines changed: 304 additions & 0 deletions

File tree

‎.agents/skills/jetson-ai-lab-code-samples/SKILL.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
name: jetson-ai-lab-code-samples
3+
description: Place downloadable tutorial scripts under public/code-samples/ and link them from tutorial pages. Use when adding, moving, or linking downloadable scripts, assets, or code files for Jetson AI Lab tutorials.
4+
license: Apache-2.0
5+
compatibility: Requires Node.js and npm for optional build verification.
6+
---
7+
8+
# Jetson AI Lab: tutorial scripts and `public/code-samples/`
9+
10+
## Purpose
11+
12+
Runnable **Python**, **shell**, and other assets that users **download or curl** from tutorials must live under the repoΓÇÖs static asset tree:
13+
14+
**`public/code-samples/<topic-folder>/`**
15+
16+
Astro copies `public/` to the site root, so these files are served at:
17+
18+
**`https://www.jetson-ai-lab.com/code-samples/<topic-folder>/<file>`**
19+
20+
(path **`/code-samples/...`** on the deployed site).
21+
22+
Do **not** use a folder named `code-sample` (singular) or skip `public/` for files meant to be fetched by users from the live site.
23+
24+
---
25+
26+
## Layout (existing examples)
27+
28+
Group files by tutorial or feature area (kebab-case folder names, consistent with the repo today):
29+
30+
| Folder | Example files |
31+
|--------|----------------|
32+
| `public/code-samples/finetune/` | `full_sft_finetuning.py`, `lora_finetuning.py`, `qlora_finetuning.py` |
33+
| `public/code-samples/openclaw-orin-nano/` | `setup-openclaw-orin-nano.py`, `endurance-test.py`, `multi-agent-debate.py` |
34+
| `public/code-samples/openpi_on_thor/` | `download.sh`, `build_engine.sh`, `pytorch_to_onnx.py`, Dockerfiles, etc. |
35+
36+
List the current tree with your OS or `git ls-files public/code-samples` before adding new paths.
37+
38+
---
39+
40+
## What to do
41+
42+
1. **Add** new scripts or small assets under the appropriate **`public/code-samples/<topic>/`** directory (create the directory if it is new).
43+
2. **Reference** them from tutorial MD/MDX using either:
44+
- **Production URL:** `https://www.jetson-ai-lab.com/code-samples/<topic>/<filename>`
45+
Example in repo: `src/content/tutorials/model-optimization/finetune-on-jetson.mdx` (wget lines for `full_sft_finetuning.py`, etc.).
46+
- **Raw GitHub URL** (for `curl | bash` or pipe-to-python):
47+
`https://raw.githubusercontent.com/NVIDIA-AI-IOT/jetson-ai-lab/main/public/code-samples/<topic>/<filename>`
48+
Example in repo: `src/content/tutorials/applications/openclaw.md`, `src/content/tutorials/vla/openpi_on_thor.md`.
49+
50+
3. **Prefer** keeping long scripts in **`public/code-samples/`** and linking themΓÇöavoid embedding huge scripts only inside MDX unless there is a strong reason.
51+
52+
---
53+
54+
## What not to do
55+
56+
- Do not put user-downloadable tutorial scripts under `src/` alone (they would not be served at `/code-samples/...` unless additionally copied to `public/`).
57+
- Do not invent alternate roots like `static/code-sample/` for this siteΓÇÖs conventions.
58+
59+
---
60+
61+
## Verification
62+
63+
After adding or moving files under `public/code-samples/`:
64+
65+
1. Run **`npm run build`** from the repository root (see skill **`jetson-ai-lab-verify-build`**).
66+
2. Optionally run the dev server and open `/code-samples/<topic>/<file>` locally to confirm the file is served.
67+
68+
---
69+
70+
## Source of truth
71+
72+
| Item | Path |
73+
|------|------|
74+
| Asset root | `public/code-samples/` |
75+
| Finetune tutorial links | `src/content/tutorials/model-optimization/finetune-on-jetson.mdx` (~lines 107ΓÇô110 for wget URLs) |
76+
| OpenClaw raw GitHub links | `src/content/tutorials/applications/openclaw.md` |
77+
| OpenPI Thor links | `src/content/tutorials/vla/openpi_on_thor.md` |

‎.agents/skills/jetson-ai-lab-verify-build/SKILL.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
name: jetson-ai-lab-verify-build
3+
description: Run npm run build on jetson-ai-lab and triage Astro content collection / MDX failures after edits. Use when verifying the site builds after content, model, tutorial, or asset changes.
4+
license: Apache-2.0
5+
compatibility: Requires Node.js and npm. Run from the repository root where package.json lives.
6+
---
7+
8+
# Jetson AI Lab: verify the build
9+
10+
## When to run
11+
12+
Run a full static build **after** any change to:
13+
14+
- `src/content/models/*.md`
15+
- `src/content/tutorials/**/*.mdx` or `.md`
16+
- Other `src/content/` collections
17+
- `public/` (including `public/code-samples/`)
18+
19+
## Command
20+
21+
From the **repository root** (where `package.json` and `astro.config.mjs` live):
22+
23+
```bash
24+
npm run build
25+
```
26+
27+
Resolve all errors before merging. Do not assume ΓÇ£dev server onlyΓÇ¥ is enough for content-schema issuesΓÇö**production build** validates collections.
28+
29+
---
30+
31+
## Common failures
32+
33+
### Models collection (Zod / `superRefine`)
34+
35+
If you see an error on **`supported_inference_engines`** or a message like:
36+
37+
> Provide `supported_inference_engines` and/or `serving.entries` (non-empty), `one_shot_inference` commands, or set `hide_run_button: true`.
38+
39+
Fix the corresponding model file under **`src/content/models/`** per skill **`jetson-model-catalog-inference`** (`serving.entries` **or** `supported_inference_engines` **or** non-empty `one_shot_inference` command fields **or** `hide_run_button: true`).
40+
41+
### MDX / Astro parse errors
42+
43+
Tutorial files under **`src/content/tutorials/`** are MDX. Unescaped `$` or `~` inside **HTML** tags mixed with Markdown can break the MDX parser (use HTML entities in `<p>/<code>` where needed, or keep shell variables **inside fenced code blocks** only).
44+
45+
### Missing assets
46+
47+
Broken links to `/code-samples/...` usually mean the file is missing under **`public/code-samples/`**ΓÇösee skill **`jetson-ai-lab-code-samples`**.
48+
49+
---
50+
51+
## Source of truth
52+
53+
| Item | Path |
54+
|------|------|
55+
| Build script | `package.json` (`scripts.build`) |
56+
| Astro config | `astro.config.mjs` |
57+
| Model validation | `src/content/config.ts` (`models` collection `superRefine`) |
58+
| Model catalog skill | `skills/jetson-model-catalog-inference/SKILL.md` |
59+
| Code samples skill | `skills/jetson-ai-lab-code-samples/SKILL.md` |

‎.agents/skills/jetson-model-catalog-inference/SKILL.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
---
2+
name: jetson-model-catalog-inference
3+
description: Edit Jetson AI Lab model catalog Markdown so the Run on Jetson UI, serve matrix, and one-shot sections render correctly from frontmatter. Use when adding or editing model pages, inference engines, serve/run commands, or one-shot inference blocks.
4+
license: Apache-2.0
5+
compatibility: Requires Node.js and npm for build verification of model schema changes.
6+
---
7+
8+
# Jetson AI Lab: model catalog and inference frontmatter
9+
10+
## Reality check
11+
12+
- **Jetson AI Lab** is a **static Astro site**. It does **not** host inference APIs. Users copy commands from the site and run them on a Jetson (or other machine).
13+
- Model pages are **Markdown files** in the Astro content collection **`models`**: path pattern `src/content/models/<slug>.md`.
14+
- The file **`slug`** (filename without `.md`) becomes the URL segment: published route **`/models/<slug>`** (see page wiring in `src/pages/models/[slug].astro`).
15+
- Commands shown in **Serve the model**, **Call the model**, and **one-shot** modals come **only** from that fileΓÇÖs YAML frontmatter (and from shared layout/components that read it).
16+
17+
Do **not** invent a base URL for ΓÇ£the Jetson AI Lab inference APIΓÇ¥ΓÇöthere isnΓÇÖt one.
18+
19+
---
20+
21+
## Minimal anatomy
22+
23+
1. **File location:** `src/content/models/<slug>.md` (e.g. `qwen3-vl-8b.md` → `/models/qwen3-vl-8b`).
24+
2. **Frontmatter** must satisfy **`modelsSchema`** in `src/content/config.ts` (required fields include `title`, `short_description`, `vision_capable`, `memory_requirements`, `precision`, `model_size`, etc.).
25+
3. **`vision_capable`** (boolean, **required**): drives the hero line ΓÇ£Vision (VLM)ΓÇ¥ Yes/No on the model page (`src/pages/models/[slug].astro`). Set `true` for VLMs / models that accept image or video inputs; `false` for text-only catalog entries.
26+
27+
---
28+
29+
## Frontmatter tag reference
30+
31+
Every model page is driven by its YAML frontmatter. The table below lists every recognized tag, whether it is required, and what it controls.
32+
33+
### Always-include tags
34+
35+
These tags are either schema-required (build fails without them) or used by **every model in the repo** (schema-optional but expected in practice). Include all of them when adding a new model.
36+
37+
| Tag | Schema | What it does |
38+
|-----|--------|--------------|
39+
| `title` | **required** | Display name on the model page and catalog cards. |
40+
| `short_description` | **required** | One-line summary shown in the catalog grid. |
41+
| `vision_capable` | **required** | `true` for VLMs (image/video input); `false` for text-only. Drives the "Vision (VLM)" badge. |
42+
| `memory_requirements` | **required** | e.g. `"16GB RAM"`. Shown in the specs sidebar. |
43+
| `precision` | **required** | e.g. `"W4A16"`, `"Q4_K_M GGUF"`. Quantization / precision label. |
44+
| `model_size` | **required** | e.g. `"12GB"`. Download / disk size shown in specs. |
45+
| `model_id` | optional | Explicit model identifier (usually matches the filename slug). Used by 100% of models. |
46+
| `family` | optional | Groups related models in the catalog (e.g. `"OpenAI GPT OSS"`). Used by 100% of models. |
47+
| `icon` | optional | Emoji shown on catalog cards. Used by 100% of models. |
48+
| `is_new` | optional | Adds a "New" badge to catalog cards. Used by 100% of models (set `false` once the model is no longer new). |
49+
| `order` | optional | Controls sort position inside the catalog grid. Used by 100% of models. |
50+
| `type` | optional | Category label (e.g. `"Text"`, `"Multimodal"`). Used by 100% of models. |
51+
| `hf_checkpoint` | optional | HuggingFace model id used in commands (e.g. `"openai/gpt-oss-20b"`). Used by 100% of models. |
52+
| `huggingface_url` | optional | Link to the HuggingFace model card. Used by 100% of models. |
53+
| `minimum_jetson` | optional | Smallest Jetson that can run the model (e.g. `"AGX Orin"`, `"Orin Nano"`). Used by 100% of models. |
54+
55+
### Situational tags
56+
57+
Only add these when the model needs them. Most models do not.
58+
59+
| Tag | When to use | Repo usage |
60+
|-----|-------------|:----------:|
61+
| `build_nvidia_url` | Model has an NVIDIA Build page. | ~67% of models |
62+
| `matrix_modules_disabled` | Some matrix module tabs should be grayed out for this model. | ~10% of models |
63+
| `hide_run_button` | Hide the entire Run/Serve UI even though engine data exists (e.g. model not yet launchable). | ~5% of models |
64+
65+
### Inference blocks (at least one required unless `hide_run_button: true`)
66+
67+
| Block | Purpose |
68+
|-------|---------|
69+
| `supported_inference_engines` | Legacy engine array ΓÇö still works, used by most existing models. |
70+
| `serving.entries` | New-style engine list ΓÇö preferred for new models, overrides the legacy array. |
71+
| `one_shot_inference` | One-shot run commands (shell, python, per-module variants). |
72+
| `client_call` | Curl / Python snippet for calling a served model (shown in "Call the model"). |
73+
| `benchmark` | Per-platform performance numbers (orin / thor: concurrency1, concurrency8, ttftMs). |
74+
75+
76+
## Inference data: serve matrix (engines)
77+
78+
The UI builds the engine list with **`getSupportedInferenceEngines`** in `src/lib/modelFrontmatterAdapter.ts`:
79+
80+
- If **`serving.entries`** exists and has **one or more** entries, those entries are used (preferred for new work).
81+
- Otherwise **`supported_inference_engines`** (legacy array) is used.
82+
83+
Each engine row maps to **`SupportedEngineEntry`** in `src/lib/inferenceCommands.ts`. Prefer:
84+
85+
- **`serve_command_orin`** / **`serve_command_thor`** for long-running serve commands (vLLM, Ollama, etc.).
86+
- Legacy **`run_command_orin`** / **`run_command_thor`** still work as fallbacks for the serve matrix but are **deprecated** in favor of `serve_command_*` (see comments on `SupportedEngineEntry`).
87+
88+
Optional fields (non-exhaustive):
89+
90+
- **`modules_supported`**: array of **matrix module ids** this engine supports; others may appear grayed for that engine.
91+
- **`run_commands_by_module`**: map from module id → command string for **Run** matrix cells.
92+
- **`matrix_modules_disabled`** (top-level frontmatter): ids to show grayed / non-clickable across the matrix.
93+
94+
**Canonical module ids** and labels live in **`JETSON_MATRIX_MODULES`** in `src/lib/inferenceCommands.ts` (e.g. `thor_t5000`, `thor_t4000`, `orin_agx_64`, `orin_nx_16`, `orin_nano_8`). Use these ids in `modules_supported` / `matrix_modules_disabled` / `one_shot_inference.modules_supported`ΓÇödo not invent new ids unless you extend `JETSON_MATRIX_MODULES` in code (out of scope for a content-only change).
95+
96+
**Examples in repo:**
97+
98+
- Legacy-only matrix: `src/content/models/qwen3-vl-8b.md` (`supported_inference_engines` with `serve_command_orin` / `serve_command_thor`).
99+
- New **`serving.entries`** plus **`one_shot_inference`**: `src/content/models/ministral3-8b-reasoning.md`.
100+
- **`hide_run_button: true`**: hides the whole run block even if engines existΓÇöe.g. `src/content/models/cosmos-reason2-8b.md` (still has engine data for docs; button hidden).
101+
102+
---
103+
104+
## One-shot inference
105+
106+
Optional frontmatter block **`one_shot_inference`** (see schema in `src/content/config.ts`). Typical fields:
107+
108+
- **`run_command_orin`**, **`run_command_thor`**, and/or **`shell`**, **`python`**
109+
- **`shell_by_module`** / **`python_by_module`** (per matrix module)
110+
- **`modules_supported`**, **`intro`**
111+
112+
Visibility: `src/components/ModelOneShotSection.astro` shows the section when at least one of those command fields is non-empty (see its `hasContent` logic). Snippet/module resolution uses **`src/lib/evalRunModal.ts`**.
113+
114+
---
115+
116+
## Validation (build will fail if wrong)
117+
118+
`src/content/config.ts` **`superRefine`** on the models collection (unless **`hide_run_button: true`**):
119+
120+
You must provide **at least one** of:
121+
122+
1. Non-empty **`serving.entries`**, or
123+
2. Non-empty **`supported_inference_engines`**, or
124+
3. **`one_shot_inference`** with at least one **trimmed** command among `run_command_orin`, `run_command_thor`, `shell`, `python`, or values inside `shell_by_module` / `python_by_module`.
125+
126+
Otherwise Zod reports a custom error on `supported_inference_engines` asking you to provide engines and/or one-shot commands or set `hide_run_button: true`.
127+
128+
---
129+
130+
## Checklist before you finish
131+
132+
- [ ] Required model fields present (`title`, `short_description`, `vision_capable`, `memory_requirements`, `precision`, `model_size`, …).
133+
- [ ] Either `serving.entries` **or** `supported_inference_engines` **or** meaningful `one_shot_inference`, **or** `hide_run_button: true`.
134+
- [ ] `serve_command_*` preferred over deprecated `run_command_*` for serve flows.
135+
- [ ] Matrix ids match `JETSON_MATRIX_MODULES` in `src/lib/inferenceCommands.ts`.
136+
- [ ] Run **`npm run build`** (see skill **`jetson-ai-lab-verify-build`**).
137+
138+
---
139+
140+
## Source of truth (repo files)
141+
142+
| Purpose | Path |
143+
|--------|------|
144+
| Model schema + validation | `src/content/config.ts` (`modelsSchema`, `superRefine` ~L124ΓÇô145) |
145+
| Merge `serving.entries` vs legacy | `src/lib/modelFrontmatterAdapter.ts` (`getSupportedInferenceEngines`, `servingEntryToSupportedEngine`) |
146+
| Engine types, matrix ids, serve/run semantics | `src/lib/inferenceCommands.ts` (`SupportedEngineEntry`, `JETSON_MATRIX_MODULES`, matrix helpers) |
147+
| Model page layout | `src/pages/models/[slug].astro` |
148+
| Serve matrix UI | `src/components/ModelServeSection.astro` |
149+
| Call / client examples | `src/components/ModelCallSection.astro` |
150+
| One-shot UI | `src/components/ModelOneShotSection.astro` |
151+
| One-shot snippet logic | `src/lib/evalRunModal.ts` |
152+
| Benchmarks (optional) | `src/components/ModelBenchmarkSection.astro` + `benchmark` in schema |

‎.agents/skills/skills.yaml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Jetson AI Lab — agent skills index.
2+
# Published to the NVIDIA Skills Catalog: https://github.com/NVIDIA/skills
3+
# Follows the Agent Skills specification: https://agentskills.io/specification
4+
5+
skills:
6+
- name: jetson-model-catalog-inference
7+
path: .agents/skills/jetson-model-catalog-inference/SKILL.md
8+
description: Edit model catalog frontmatter for Serve/Run matrix, vision_capable, serving vs legacy engines, one_shot_inference, and Zod validation rules. Use when adding or editing model pages, inference engines, serve/run commands, or one-shot inference blocks.
9+
10+
- name: jetson-ai-lab-verify-build
11+
path: .agents/skills/jetson-ai-lab-verify-build/SKILL.md
12+
description: Run npm run build and triage model collection / MDX / asset errors after content changes. Use when verifying the site builds after content, model, tutorial, or asset changes.
13+
14+
- name: jetson-ai-lab-code-samples
15+
path: .agents/skills/jetson-ai-lab-code-samples/SKILL.md
16+
description: Place downloadable tutorial scripts under public/code-samples/ and link via production or raw GitHub URLs. Use when adding, moving, or linking downloadable scripts, assets, or code files for Jetson AI Lab tutorials.

0 commit comments

Comments
 (0)