diff --git a/.github/ISSUE_TEMPLATE/skill-proposal.yml b/.github/ISSUE_TEMPLATE/skill-proposal.yml new file mode 100644 index 0000000..061012e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/skill-proposal.yml @@ -0,0 +1,74 @@ +name: Skill proposal +description: Propose a new skill for the AMD Skills catalog. +title: "[Skill proposal] " +labels: + - skill-proposal +body: + - type: markdown + attributes: + value: | + Thanks for proposing a skill! Skills earn their keep on **repeated, opinionated AMD workflows**. + Before filing, please skim `CONTRIBUTING.md` (especially *"Is this task a good fit for a skill?"* and the two contribution paths) so we can route this proposal quickly. + + Fill out the short fields below, then describe the skill in detail at the end. + + - type: input + id: name + attributes: + label: Proposed skill name + description: Use `lowercase-with-hyphens`, max 64 characters, action- or outcome-oriented (e.g. `porting-cuda-to-hip`, `tuning-mi300x`, `picking-rocm-container`). Avoid generic names like `helper` or `gpu-stuff`. + placeholder: e.g. tuning-mi300x-inference + validations: + required: true + + - type: dropdown + id: prior_art + attributes: + label: Does something like this already exist? + description: Help us avoid duplicating effort. If you pick a "Yes" option, link the prior art in the description below. + options: + - "No — new idea" + - "Yes — as documentation, a runbook, or internal guide" + - "Yes — as a similar skill in another catalog or repo" + - "Not sure — happy to discuss" + validations: + required: true + + - type: dropdown + id: home + attributes: + label: Where should this skill live? + description: See the two contribution paths in `CONTRIBUTING.md`. Path A skills are authored under `skills/` in this repo; Path B skills live in a product repo and are registered here via `catalog/`. + options: + - "Path A: incubated in this repo (may move to a product repo and continbue to be registered here)" + - "Path B: authored in a product repo (HIP, ROCm, Ryzen AI, Lemonade, ...) and registered here" + - "Not sure yet — needs discussion" + validations: + required: true + + - type: dropdown + id: focus_area + attributes: + label: Catalog focus area + description: Which focus area in the catalog best fits this skill? + options: + - "Application integration" + - "Hardware-native" + - "Cross-stack porting" + - "Profiling and delivery" + - "Other / not sure" + validations: + required: true + + - type: textarea + id: description + attributes: + label: Skill description + description: | + Describe the skill in as much detail as you can. Useful things to cover: + - **User goal**: what is the user trying to achieve when this skill should fire? + - **Trigger surface**: words, phrases, file extensions, error messages, product names that should route to this skill. + - **Platform Scope**: Is this for client? server? Both? + - **Inputs and outputs**: what does the agent receive, and what does it produce? + validations: + required: true diff --git a/AUTHORING.md b/CONTRIBUTING.md similarity index 79% rename from AUTHORING.md rename to CONTRIBUTING.md index 40a0c3f..d57c16b 100644 --- a/AUTHORING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,40 @@ -# Authoring AMD Skills +# Contributing to AMD Skills -A short guide for writing skills that agents pick up reliably and execute well. For repository structure and contribution paths, see the [README](README.md). For the full Anthropic reference, see [Skill authoring best practices](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills/best-practices). +This guide covers everything you need to ship a skill: how to choose a contribution path, what to validate locally, and the writing conventions every AMD skill should follow. + +For repository structure and the broader catalog model, see the [README](README.md). For the upstream reference, see Anthropic's [Skill authoring best practices](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills/best-practices). + +We welcome contributions from AMD engineers and selected partners. + +## Contribution paths + +There are two contribution paths, matching how the catalog is organized. + +### Path A: Skills authored in this repository + +Best for cross-cutting skills that do not have a natural product home. + +1. Copy an existing skill folder under `skills/` as a starting point and rename it. +2. Update the `SKILL.md` frontmatter so the `name` and `description` clearly explain *what* the skill does and *when* an agent should reach for it. +3. Add the supporting scripts, templates, and reference docs your instructions point to. Keep skills focused: one well-scoped task per skill is better than one mega-skill. +4. Register the skill in `.claude-plugin/marketplace.json` with a human-readable description (the marketplace description is for humans browsing the catalog; the `SKILL.md` description is what the agent uses for routing). +5. Regenerate the Cursor manifest so it tracks the new skill: + ```bash + ./scripts/publish.sh # writes .cursor-plugin/plugin.json + ``` +6. Validate the skill locally before pushing: + ```bash + ./scripts/check.sh # validates every SKILL.md and that manifests are in sync + ``` +7. Open a pull request. The `validate` GitHub Actions workflow runs `./scripts/check.sh` and must pass before merge. See [Validating locally](#validating-locally) for the full set of enforced rules. + +### Path B: Skills authored in a product repository + +Best for skills that should ship and version with a product (HIP, MIGraphX, Ryzen AI, Lemonade, etc.). + +1. Add the skill folder to your product repository; a common location is `.agents/skills//`. +2. Open a pull request here that adds an entry to `catalog/` pointing at the skill's location and pinning a tag. +3. CI will validate the linked skill against the same rules as in-repo skills, and the central plugin manifests will surface it through one install. ## Is this task a good fit for a skill? @@ -168,4 +202,4 @@ The validator checks every skill under `skills/` for: It also checks the plugin manifests: - every skill under `skills/` has a matching entry in `.claude-plugin/marketplace.json` (and vice versa), with `source` set to `./skills/` and a non-empty human-readable `description` -- `.cursor-plugin/plugin.json` is up to date with `.claude-plugin/plugin.json` and the discovered skills (regenerate with `./scripts/publish.sh`) (push longer reference material into sibling files) +- `.cursor-plugin/plugin.json` is up to date with `.claude-plugin/plugin.json` and the discovered skills (regenerate with `./scripts/publish.sh`) diff --git a/README.md b/README.md index 1a3d7d2..2d7c870 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,12 @@ 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 + +Zero setup is needed on `Claude` and `Cursor` (natively integrated). Simply ask your agent something like "Use AMD Skills to integrate local AI into my app". + +For integration with other agents, please refer to the [manual-installation](#manual-installation) section. + ## 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. @@ -46,26 +52,26 @@ Skills earn their keep on repeated, opinionated workflows, exactly where the AMD The initial catalog is organized into four focus areas. -### Hardware-native skills +### Application integration -Diagnose, configure, and tune AMD silicon directly. +Embed AMD-optimized AI into end-user applications. | Skill | What it does | | --- | --- | -| `rocm-doctor` | Detect driver / kernel / ROCm / framework mismatches and propose fixes. | -| `gfx-target-chooser` | Pick the right `gfx942` / `gfx90a` / `gfx1100` target and matching compiler flags. | -| `mi300x-tuner` | Opinionated training and inference tuning for MI300X, including TunableOp, FSDP, and FlashAttention. | -| `rocm-container-picker` | Map a workload to a known-good `rocm/*` container image. | -| `ryzen-ai-deploy` | Prepare, quantize, and deploy models to Ryzen AI NPUs across the ONNX, PyTorch, and hybrid CPU/NPU/iGPU paths. | +| `local-ai-app-integration` | Integrate local AI into cloud LLM apps for offline support, better privacy, and lower API costs. | +| `local-ai-use` | Route image generation, text-to-speech, and speech-to-text through a local AI Server to reduce token/cost usage. | -### Application integration +### Hardware-native skills -Embed AMD-optimized AI into end-user applications. +Diagnose, configure, and tune AMD devices directly. | Skill | What it does | | --- | --- | -| `local-ai-app-integration` | Integrate local AI into cloud LLM apps for offline support, better privacy, and lower API costs. | -| `local-ai-use` | Route image generation, text-to-speech, and speech-to-text through a local AI Server to reduce token/cost usage. | +| `rocm-doctor` | Detect driver / kernel / ROCm / framework mismatches and propose fixes. | +| `mi300x-tuner` | Opinionated training and inference tuning for MI300X, including TunableOp, FSDP, and FlashAttention. | +| `rocm-container-picker` | Map a workload to a known-good `rocm/*` container image. | +| `gfx-target-chooser` | Pick the right `gfx942` / `gfx90a` / `gfx1100` target and matching compiler flags. | + ### Cross-stack porting @@ -86,14 +92,13 @@ Close the loop from trace to fix to ship. | --- | --- | | `rocprof-capture` | Capture and interpret a `rocprof` trace for a workload. | | `omniperf-tune` | Run `omniperf`, locate the bottleneck, and suggest the fix. | -| `migraphx-deploy` | Compile an ONNX model with MIGraphX and benchmark it on a target. | -| `rocm-ci-template` | Drop-in GitHub Actions for AMD-targeted projects. | +| `quark-quantize` | Quantize PyTorch and ONNX models with [AMD Quark](https://github.com/amd/Quark) (INT4/INT8/FP8/MX), pick the right scheme and calibration, and export for AMD deployment. | > Skills land incrementally; see [Status](#status) for what is available today. ## A federated catalog -The AMD stack is large and moves fast. ROCm, HIP, MIGraphX, vLLM-AMD, Ryzen AI, and framework integrations each have their own team, release cadence, and validation matrix. A single monorepo of skills, maintained by one central team, would always be a step behind. +The AMD stack is large and moves fast. ROCm, HIP, Ryzen AI, and framework integrations each have their own team, release cadence, and validation matrix. A single monorepo of skills, maintained by one central team, would always be a step behind. So skills here are **federated**: each skill is owned and versioned by the team that owns the product it describes, and this repository is the **catalog** that brings them together. @@ -112,17 +117,10 @@ So skills here are **federated**: each skill is owned and versioned by the team ┌───────────────┬───────────────┼───────────────┬────────────────┐ │ │ │ │ │ ROCm/ROCm ROCm/HIP Ryzen AI repo lemonade-sdk ...more - rocm-doctor/ cuda-to-hip/ ryzen-ai-deploy/ local-ai-app- product + rocm-doctor/ cuda-to-hip/ ryzen-ai-tools/ local-ai-app- product gfx-target-... triton-amd-... ... integration/ repos ``` -Concretely: - -- The `cuda-to-hip` skill lives with the HIP project. -- `rocm-doctor` lives with the ROCm release tree. -- `ryzen-ai-deploy` ships with Ryzen AI. -- `local-ai-app-integration` is incubating in this repo today and will graduate to `lemonade-sdk/lemonade`. - Each skill stays close to the engineers who ship the underlying product, the CI that validates it, and the release tag that pins it. This repo also acts as an **incubator**: a skill can start its life under `skills/` here to iterate quickly, then graduate to its product repo and be re-pointed from `catalog/` once it has a clear owner, with no change for installed users. @@ -135,8 +133,10 @@ This repo also acts as an **incubator**: a skill can start its life under `skill ### What this means if you contribute -- **In-repo skills** (Path A below) are best for cross-cutting workflows that do not have a natural product home. -- **Product-repo skills** (Path B below) are best for skills that should live and version with a specific product. You add the skill folder to your product repo and open a small PR here that registers it in `catalog/` with a pinned tag. CI validates the linked skill against the same rules as in-repo skills, and the central plugin manifests surface it through the same one install. +- **In-repo skills** (Path A) are best for cross-cutting workflows that do not have a natural product home. +- **Product-repo skills** (Path B) are best for skills that should live and version with a specific product. You add the skill folder to your product repo and open a small PR here that registers it in `catalog/` with a pinned tag. CI validates the linked skill against the same rules as in-repo skills, and the central plugin manifests surface it through the same one install. + +See [CONTRIBUTING.md](CONTRIBUTING.md) for the step-by-step contribution flow for each path. ### Repository layout @@ -149,7 +149,7 @@ catalog/ # Manifest pointers to skills that live in product repositor scripts/ # Tooling for publishing and regenerating manifests ``` -## Installation +## Manual Installation AMD Skills are compatible with Cursor, Claude Code, OpenAI Codex, and Gemini CLI. The general flow: @@ -182,52 +182,20 @@ gemini extensions install https://github.com/amd/skills.git --consent Once a skill is installed, reference it in plain language while talking to your agent. For example: -- "Integrate local AI capabilities into my app with Embeddable Lemonade." -- "Use the `pytorch-rocm-setup` skill to get PyTorch running on this MI300X node." -- "Use the `cuda-to-hip` skill to convert these CUDA kernels and flag anything that needs manual review." -- "Use the `migraphx-deploy` skill to compile this ONNX model for `gfx942` and benchmark it." -- "Use the `omniperf-tune` skill to find the bottleneck in this training step." +- "Use AMD Skills to integrate local AI capabilities into my app with Embeddable Lemonade." +- "Use AMD Skills to get PyTorch running on this MI300X node." +- "Use AMD Skills to convert these CUDA kernels and flag anything that needs manual review." The agent loads the matching `SKILL.md` and any helper scripts, then carries out the task. In most cases the agent will pick the right skill on its own from the description; explicit invocation is a fallback, not a requirement. ## Contributing a skill -We welcome contributions from AMD engineers, partners, and the community. There are two contribution paths, matching how the catalog is organized. - -### Path A: Skills authored in this repository - -Best for cross-cutting skills that do not have a natural product home. - -1. Copy an existing skill folder under `skills/` as a starting point and rename it. -2. Update the `SKILL.md` frontmatter so the `name` and `description` clearly explain *what* the skill does and *when* an agent should reach for it. -3. Add the supporting scripts, templates, and reference docs your instructions point to. Keep skills focused: one well-scoped task per skill is better than one mega-skill. -4. Register the skill in `.claude-plugin/marketplace.json` with a human-readable description (the marketplace description is for humans browsing the catalog; the `SKILL.md` description is what the agent uses for routing). -5. Regenerate the Cursor manifest so it tracks the new skill: - ```bash - ./scripts/publish.sh # writes .cursor-plugin/plugin.json - ``` -6. Validate the skill locally before pushing: - ```bash - ./scripts/check.sh # validates every SKILL.md and that manifests are in sync - ``` -7. Open a pull request. The `validate` GitHub Actions workflow runs `./scripts/check.sh` and must pass before merge. See [AUTHORING.md](AUTHORING.md#validating-locally) for the full set of enforced rules. - -### Path B: Skills authored in a product repository - -Best for skills that should ship and version with a product (HIP, MIGraphX, Ryzen AI, vLLM-AMD, etc.). - -1. Add the skill folder to your product repository; a common location is `.agents/skills//`. -2. Open a pull request here that adds an entry to `catalog/` pointing at the skill's location and pinning a tag. -3. CI will validate the linked skill against the same rules as in-repo skills, and the central plugin manifests will surface it through one install. - -### Writing tips +We welcome contributions from AMD engineers and selected partners. There are two paths, matching how the catalog is organized: -See [AUTHORING.md](AUTHORING.md) for the full authoring guide, including when a task is a good fit for a skill, how to write a description that routes correctly, and the conventions every AMD skill should follow. The essentials: +- **Path A — In-repo skills.** Authored directly under `skills/` in this repository. Best for cross-cutting workflows that do not have a natural product home. +- **Path B — Product-repo skills.** Authored in a product repository and registered here through `catalog/` with a pinned tag. Best for skills that should ship and version with a specific product (HIP, ROCm, Ryzen AI, Lemonade, etc.). -- Optimize the `description` for *agent routing*, not marketing copy. Describe the user's goal, not how the skill works internally. -- Be explicit about prerequisites: ROCm version, kernel, GPU architecture, container image. -- Prefer scripts and runnable commands over prose where possible. -- Call out known pitfalls: driver mismatches, unsupported architectures, and environment variables that silently change behavior. +See [CONTRIBUTING.md](CONTRIBUTING.md) for step-by-step instructions, the full authoring guide, and the rules CI enforces on every pull request. ## Status diff --git a/scripts/validate_skills.py b/scripts/validate_skills.py index 55fbfb8..7567ba0 100644 --- a/scripts/validate_skills.py +++ b/scripts/validate_skills.py @@ -5,7 +5,7 @@ # /// """Validate AMD skills against the standardized Agent Skills format. -Enforces the rules documented in AUTHORING.md: +Enforces the rules documented in CONTRIBUTING.md: - SKILL.md exists at the skill root - YAML frontmatter is parseable @@ -42,7 +42,7 @@ DEFAULT_SKILLS_DIR = REPO_ROOT / "skills" CLAUDE_MARKETPLACE = REPO_ROOT / ".claude-plugin" / "marketplace.json" -# Limits from AUTHORING.md and the standardized Agent Skills format. +# Limits from CONTRIBUTING.md and the standardized Agent Skills format. MAX_NAME_LEN = 64 MAX_DESCRIPTION_LEN = 1024 MAX_BODY_LINES = 500 @@ -163,7 +163,7 @@ def validate_claude_marketplace(skill_dirs: list[Path]) -> list[str]: """Return error strings if marketplace entries don't match skills/ on disk. The marketplace's human-readable `description` is intentionally allowed - to differ from the SKILL.md description (per AUTHORING.md), so this only + to differ from the SKILL.md description (per CONTRIBUTING.md), so this only enforces that names and source paths line up. """ if not CLAUDE_MARKETPLACE.exists():