Add issue template and refactor documentation

.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] <short outcome or skill name>"
+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

AUTHORING.md → 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/<skill-name>/`.
+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/<name>` 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`)

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/<skill-name>/`.
-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
 

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():