Add npx-based installation support (#75)

danielholanda · web-flow · commit c8d6fe12eead · 2026-06-23T17:16:55.000-07:00
diff --git a/README.md b/README.md
@@ -1,6 +1,3 @@
-> [!IMPORTANT]
-> **Tech Preview: Catalog under active development.** We’re building the catalog in the open, sharing progress as the foundations take shape. Expect frequent changes as skills, categories, and descriptions evolve.
-
 # AMD Skills
 
 <div align="center">
@@ -25,34 +22,43 @@ AMD Skills provide agents with knowledge, scripts, and conventions for working w
 
 Skills in this repository follow the standardized [Agent Skills](https://github.com/anthropics/skills) format and are designed to interoperate with the major coding agents like Cursor, Claude Code, OpenAI Codex, and Gemini CLI.
 
-## Installation
+> [!IMPORTANT]
+> **Tech Preview:** We’re building the catalog in the open, sharing progress as the foundations take shape. Expect frequent changes as skills, categories, and descriptions evolve.
 
-AMD Skills will soon be installable directly in Claude/Cursor/Codex and other agents through marketplace integration.
 
-While we work marketplace integration, please refer to our [Manual installation steps](#manual-installation).
 
-## What is a skill?
+## Installation
 
-A skill is a self-contained folder that bundles everything an agent needs to perform a focused task: instructions, helper scripts, prompts, templates, and references. At its core is a `SKILL.md` file with YAML frontmatter, a `name`, and a short `description` that tells the agent *when* the skill should activate, followed by the guidance the agent reads while the skill is in use.
+Install AMD Skills with the [`skills` CLI](https://github.com/vercel-labs/skills) via `npx`. No clone or manual copying required.
 
+```bash
+npx skills add amd/skills
 ```
-skills/
-  rocm-doctor/
-    SKILL.md
-    skill-card.md
-    scripts/
-    references/
+
+This prompts you to pick a skill and an install destination. To install a specific skill into specific agents, pass `--skill` with one or more `--agent` flags (e.g. `cursor`, `claude-code`, `codex`):
+
+```bash
+npx skills add amd/skills --skill local-ai-use --agent claude-code
 ```
 
-When an agent decides a skill is relevant (or you invoke it explicitly), it loads that `SKILL.md` and follows the instructions inside. Descriptions stay in context cheaply; the full body of a skill only loads when the task actually matches.
+Browse everything available before installing:
 
-Every skill also ships a `skill-card.md`: a short, human-facing governance card (Description, Owner, License) that tells a reviewer what the skill is and who stands behind it without reading the source. See [docs/skill-cards.md](docs/skill-cards.md).
+```bash
+npx skills add amd/skills --list
+```
 
-## Why a skill, not a doc?
+Prefer to do it by hand? See [Manual installation](#manual-installation).
 
-Documentation describes an API surface: every flag, every option, neutral by design. A skill encodes the opinionated path: which flags, which container image, which `gfx` target, which environment variables, in what order. It captures the decisions a senior AMD engineer makes without thinking, in a form the agent can apply consistently across teams and repositories.
+## Using a skill
 
-Skills earn their keep on repeated, opinionated workflows, exactly where the AMD stack lives.
+Once a skill is installed, reference it in plain language while talking to your agent. For example:
+
+- "Use AMD Skills to learn how to generate images locally instead of burning cloud tokens."
+- "Use AMD Skills to deploy this LLM for inference on my AMD Instinct GPUs."
+
+In most cases the agent picks the right skill on its own from the description; explicit invocation is a fallback, not a requirement.
+
+For hands-on, step-by-step guides that show a skill in action, see the [walkthroughs](walkthroughs/README.md).
 
 ## The catalog
 
@@ -75,7 +81,7 @@ Cross-stack skills, from client to cloud.
 | Skill | What it does | Source |
 | --- | --- | --- |
 | `rocm-doctor` | Diagnose ROCm / PyTorch / llama.cpp failures on AMD GPUs against a fixed list of known misconfigurations. | _planned_ |
-| `llm-kernel-optimizer` (`hyperloom`) | Autonomously optimizes LLM inference on AMD GPUs. | _planned_ |
+| `hyperloom-kernel-optimizer` | Autonomously optimizes LLM inference on AMD GPUs. | _planned_ |
 | `vllm-semantic-router` | Setup a vLLM router that semantically maps your request to the best available platform. | _planned_ |
 
 ### Server-Native
@@ -88,6 +94,29 @@ Run and optimize on AMD Instinct.
 | [`magpie-kernel-evaluator`](skills/magpie-kernel-evaluator/SKILL.md) | Evaluate GPU kernel correctness and performance, compare kernel implementations, and benchmark vLLM / SGLang inference with profiling, TraceLens, and torch-trace gap analysis. | [Magpie](https://github.com/AMD-AGI/Magpie) |
 | [`tracelens-analysis-orchestrator`](skills/tracelens-analysis-orchestrator/SKILL.md) | Orchestrate modular PyTorch profiler trace analysis with TraceLens: generate perf reports, run system-level and compute-kernel subagents in parallel, and write a prioritized stakeholder report. | [TraceLens](https://github.com/AMD-AGI/TraceLens) |
 
+## What is a skill?
+
+A skill is a self-contained folder that bundles everything an agent needs to perform a focused task: instructions, helper scripts, prompts, templates, and references. At its core is a `SKILL.md` file with YAML frontmatter, a `name`, and a short `description` that tells the agent *when* the skill should activate, followed by the guidance the agent reads while the skill is in use.
+
+```
+skills/
+  rocm-doctor/
+    SKILL.md
+    skill-card.md
+    scripts/
+    references/
+```
+
+When an agent decides a skill is relevant (or you invoke it explicitly), it loads that `SKILL.md` and follows the instructions inside. Descriptions stay in context cheaply; the full body of a skill only loads when the task actually matches.
+
+Every skill also ships a `skill-card.md`: a short, human-facing governance card (Description, Owner, License) that tells a reviewer what the skill is and who stands behind it without reading the source. See [docs/skill-cards.md](docs/skill-cards.md).
+
+## Why a skill, not a doc?
+
+Documentation describes an API surface: every flag, every option, neutral by design. A skill encodes the opinionated path: which flags, which container image, which `gfx` target, which environment variables, in what order. It captures the decisions a senior AMD engineer makes without thinking, in a form the agent can apply consistently across teams and repositories.
+
+Skills earn their keep on repeated, opinionated workflows, exactly where the AMD stack lives.
+
 
 ## A federated catalog
 
@@ -148,17 +177,6 @@ cp -r amd-skills/skills/local-ai-use <agent-skills-dir>/
 | Claude Code | `~/.claude/skills/` / `.claude/skills/` |
 | Codex | `$HOME/.agents/skills` / `$REPO_ROOT/.agents/skills` |
 
-## Using a skill
-
-Once a skill is installed, reference it in plain language while talking to your agent. For example:
-
-- "Use AMD Skills to integrate local AI capabilities into my app with Embeddable Lemonade."
-- "Use AMD Skills to convert these CUDA kernels and flag anything that needs manual review."
-
-In most cases the agent picks the right skill on its own from the description; explicit invocation is a fallback, not a requirement.
-
-For hands-on, step-by-step guides that show a skill in action, see the [walkthroughs](walkthroughs/README.md).
-
 ## Contributing a skill
 
 We welcome contributions from AMD engineers and selected partners. Two paths, matching how the catalog is organized:
diff --git a/walkthroughs/local-ai-app-integration.md b/walkthroughs/local-ai-app-integration.md
@@ -27,10 +27,12 @@ cd dictate
 
 ## Step 3 - Enabling claude to see `local-ai-app-integration`
 
-In the future this will be enabled directly through claude's marketplace. For now, we have to manually add it.
+* Install the skill with the [`skills` CLI](https://github.com/vercel-labs/skills):
+
+```bash
+npx skills add amd/skills --skill local-ai-app-integration --agent claude-code
+```
 
-* Clone `https://github.com/amd/skills`
-* Move the `local-ai-app-integration` skill from the repo to `.claude/skills/`
 * Run `claude "Which skills can you see?" --model opus`. You should see a list of skills that includes `local-ai-app-integration`.
 
 ## Step 4 - Running the skill
diff --git a/walkthroughs/local-ai-use.md b/walkthroughs/local-ai-use.md
@@ -10,10 +10,12 @@ The goal of this skill is to teach your AI agent to use image generation, text g
 
 ## Step 2 - Enabling claude to see `local-ai-use`
 
-In the future this will be enabled directly through claude's marketplace. For now, we have to manually add it.
+* Install the skill with the [`skills` CLI](https://github.com/vercel-labs/skills):
+
+```bash
+npx skills add amd/skills --skill local-ai-use --agent claude-code
+```
 
-* Clone `https://github.com/amd/skills`
-* Move the `local-ai-use` skill from the repo to `.claude/skills/`
 * Run `claude "Which skills can you see?" --model sonnet`. You should see a list of skills that includes `local-ai-use`.
 
 ## Step 3 - Running the skill
