diff --git a/.github/ISSUE_TEMPLATE/skill-proposal.yml b/.github/ISSUE_TEMPLATE/skill-proposal.yml index 3aaf597..732d569 100644 --- a/.github/ISSUE_TEMPLATE/skill-proposal.yml +++ b/.github/ISSUE_TEMPLATE/skill-proposal.yml @@ -50,7 +50,7 @@ body: 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 `scripts/sources.yml`. + 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 `.github/scripts/sources.yml`. 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" diff --git a/scripts/check.sh b/.github/scripts/check.sh similarity index 58% rename from scripts/check.sh rename to .github/scripts/check.sh index 19603a8..588fe90 100755 --- a/scripts/check.sh +++ b/.github/scripts/check.sh @@ -2,14 +2,14 @@ # Validate every SKILL.md and that generated plugin manifests are up to date. # # Usage: -# ./scripts/check.sh Validate every skill and check manifests. -# ./scripts/check.sh -h|--help Print this help. +# ./.github/scripts/check.sh Validate every skill and check manifests. +# ./.github/scripts/check.sh -h|--help Print this help. # # Requires `uv` (https://github.com/astral-sh/uv). set -euo pipefail -ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" cd "$ROOT_DIR" usage() { @@ -18,8 +18,8 @@ usage() { case "${1:-}" in "") - uv run scripts/validate_skills.py - uv run scripts/generate_cursor_marketplace.py --check + uv run .github/scripts/validate_skills.py + uv run .github/scripts/generate_cursor_marketplace.py --check ;; -h|--help) usage diff --git a/scripts/generate_cursor_marketplace.py b/.github/scripts/generate_cursor_marketplace.py similarity index 94% rename from scripts/generate_cursor_marketplace.py rename to .github/scripts/generate_cursor_marketplace.py index 79c0cf4..d5a8555 100644 --- a/scripts/generate_cursor_marketplace.py +++ b/.github/scripts/generate_cursor_marketplace.py @@ -23,8 +23,8 @@ Cursor exposes exactly the same skills as Claude. Usage: - uv run scripts/generate_cursor_marketplace.py # write - uv run scripts/generate_cursor_marketplace.py --check # validate only + uv run .github/scripts/generate_cursor_marketplace.py # write + uv run .github/scripts/generate_cursor_marketplace.py --check # validate only `--check` fails if the generated file is stale or if the Claude marketplace top-level identity has drifted from `plugin-metadata.json`. @@ -37,7 +37,7 @@ import sys from pathlib import Path -ROOT = Path(__file__).resolve().parent.parent +ROOT = Path(__file__).resolve().parent.parent.parent PLUGIN_METADATA = ROOT / "plugin-metadata.json" CLAUDE_MARKETPLACE = ROOT / ".claude-plugin" / "marketplace.json" CURSOR_MARKETPLACE = ROOT / ".cursor-plugin" / "marketplace.json" @@ -142,7 +142,7 @@ def main(argv: list[str] | None = None) -> int: file=sys.stderr, ) print( - "Run: uv run scripts/generate_cursor_marketplace.py", + "Run: uv run .github/scripts/generate_cursor_marketplace.py", file=sys.stderr, ) return 1 diff --git a/scripts/import_external_skills.py b/.github/scripts/import_external_skills.py similarity index 97% rename from scripts/import_external_skills.py rename to .github/scripts/import_external_skills.py index 092866e..debcd48 100644 --- a/scripts/import_external_skills.py +++ b/.github/scripts/import_external_skills.py @@ -3,7 +3,7 @@ # requires-python = ">=3.10" # dependencies = ["pyyaml>=6.0"] # /// -"""Import skills from external repositories listed in `scripts/sources.yml`. +"""Import skills from external repositories listed in `.github/scripts/sources.yml`. For each source, the script: @@ -21,11 +21,11 @@ skill (using the SKILL.md `description` as the marketplace blurb, unless the source declares an override). 6. Removes any previously imported skill (one with a `.federated.json`) - that is no longer listed in `scripts/sources.yml`. + that is no longer listed in `.github/scripts/sources.yml`. Usage: - uv run scripts/import_external_skills.py # write changes - uv run scripts/import_external_skills.py --dry-run # report only + uv run .github/scripts/import_external_skills.py # write changes + uv run .github/scripts/import_external_skills.py --dry-run # report only The companion GitHub Actions workflow `import-external-skills` calls this script on manual dispatch and opens a pull request with the result. @@ -48,7 +48,7 @@ import yaml -REPO_ROOT = Path(__file__).resolve().parent.parent +REPO_ROOT = Path(__file__).resolve().parent.parent.parent CATALOG_FILE = Path(__file__).resolve().parent / "sources.yml" SKILLS_DIR = REPO_ROOT / "skills" CLAUDE_MARKETPLACE = REPO_ROOT / ".claude-plugin" / "marketplace.json" @@ -400,7 +400,7 @@ def update_marketplace(results: Iterable[ImportResult], dry_run: bool) -> bool: # Drop entries that point at skills that no longer exist on disk so # the importer also cleans up the marketplace when an entry is - # removed from `scripts/sources.yml`. + # removed from `.github/scripts/sources.yml`. existing_dirs = {p.name for p in SKILLS_DIR.iterdir() if p.is_dir()} pruned = [p for p in plugins if not isinstance(p, dict) or p.get("name") in existing_dirs] if len(pruned) != len(plugins): @@ -536,7 +536,7 @@ def main(argv: list[str] | None = None) -> int: if spec.folder in declared: raise ValueError( f"Skill name collision: {spec.folder!r} is listed by " - "more than one source in scripts/sources.yml." + "more than one source in .github/scripts/sources.yml." ) declared.add(spec.folder) all_results.extend(import_source(source, args.dry_run, log)) diff --git a/scripts/publish.sh b/.github/scripts/publish.sh similarity index 64% rename from scripts/publish.sh rename to .github/scripts/publish.sh index 479204e..2c97341 100644 --- a/scripts/publish.sh +++ b/.github/scripts/publish.sh @@ -3,9 +3,9 @@ # canonical marketplace + metadata sources. # # Usage: -# ./scripts/publish.sh Regenerate all derived artifacts. -# ./scripts/publish.sh --check Verify derived artifacts are up to date. -# ./scripts/publish.sh -h|--help Print this help. +# ./.github/scripts/publish.sh Regenerate all derived artifacts. +# ./.github/scripts/publish.sh --check Verify derived artifacts are up to date. +# ./.github/scripts/publish.sh -h|--help Print this help. # # Currently regenerates: # - .cursor-plugin/marketplace.json (mirror of .claude-plugin/marketplace.json @@ -13,14 +13,14 @@ # # `.claude-plugin/marketplace.json` is hand-maintained because its # human-facing plugin descriptions intentionally differ from the SKILL.md -# routing descriptions; ./scripts/check.sh enforces that the marketplace +# routing descriptions; ./.github/scripts/check.sh enforces that the marketplace # listing matches skills/ on disk. # # Requires `uv` (https://github.com/astral-sh/uv). set -euo pipefail -ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" cd "$ROOT_DIR" usage() { @@ -29,11 +29,11 @@ usage() { case "${1:-}" in "") - uv run scripts/generate_cursor_marketplace.py + uv run .github/scripts/generate_cursor_marketplace.py echo "Publish artifacts generated successfully." ;; --check) - uv run scripts/generate_cursor_marketplace.py --check + uv run .github/scripts/generate_cursor_marketplace.py --check ;; -h|--help) usage diff --git a/scripts/skillspector_gate.py b/.github/scripts/skillspector_gate.py similarity index 97% rename from scripts/skillspector_gate.py rename to .github/scripts/skillspector_gate.py index 7f7befe..f1c1de9 100644 --- a/scripts/skillspector_gate.py +++ b/.github/scripts/skillspector_gate.py @@ -23,7 +23,7 @@ Usage: - uv run scripts/skillspector_gate.py \ + uv run .github/scripts/skillspector_gate.py \ --report reports/rocm-doctor.md \ --skill rocm-doctor \ --allowlist .github/skillspector-allow.yml @@ -156,7 +156,7 @@ def main() -> int: parser.add_argument( "--allowlist", type=Path, - default=Path(__file__).resolve().parent.parent / ".github" / "skillspector-allow.yml", + default=Path(__file__).resolve().parent.parent / "skillspector-allow.yml", help="Path to the suppression allowlist (YAML).", ) args = parser.parse_args() diff --git a/scripts/sources.yml b/.github/scripts/sources.yml similarity index 100% rename from scripts/sources.yml rename to .github/scripts/sources.yml diff --git a/scripts/validate_skills.py b/.github/scripts/validate_skills.py similarity index 95% rename from scripts/validate_skills.py rename to .github/scripts/validate_skills.py index 9484790..f449703 100644 --- a/scripts/validate_skills.py +++ b/.github/scripts/validate_skills.py @@ -20,12 +20,12 @@ Run from the repo root: - ./scripts/check.sh # used locally; thin wrapper - uv run scripts/validate_skills.py # validate every skill + manifest - uv run scripts/validate_skills.py --skills-dir skills - uv run scripts/validate_skills.py --list # print skill names as JSON - uv run scripts/validate_skills.py --skill rocm-doctor # one skill only - uv run scripts/validate_skills.py --marketplace-only # manifest only + ./.github/scripts/check.sh # used locally; thin wrapper + uv run .github/scripts/validate_skills.py # validate every skill + manifest + uv run .github/scripts/validate_skills.py --skills-dir skills + uv run .github/scripts/validate_skills.py --list # print skill names as JSON + uv run .github/scripts/validate_skills.py --skill rocm-doctor # one skill only + uv run .github/scripts/validate_skills.py --marketplace-only # manifest only The `--list` / `--skill` options let CI validate each skill in its own job (see .github/workflows/validate.yml) so a single bad skill doesn't mask the @@ -45,7 +45,7 @@ import yaml -REPO_ROOT = Path(__file__).resolve().parent.parent +REPO_ROOT = Path(__file__).resolve().parent.parent.parent DEFAULT_SKILLS_DIR = REPO_ROOT / "skills" CLAUDE_MARKETPLACE = REPO_ROOT / ".claude-plugin" / "marketplace.json" diff --git a/.github/skillspector-allow.yml b/.github/skillspector-allow.yml index af73e55..49327cd 100644 --- a/.github/skillspector-allow.yml +++ b/.github/skillspector-allow.yml @@ -3,7 +3,7 @@ # SkillSpector's static scan is high-recall / moderate-precision and has no # native per-finding suppression. This file is the auditable place to record # findings that are genuinely false positives so the CI gate -# (scripts/skillspector_gate.py) does not fail on them. Everything not listed +# (.github/scripts/skillspector_gate.py) does not fail on them. Everything not listed # here still fails the build at HIGH/CRITICAL. # # Each entry suppresses ONE rule for ONE file within ONE skill: diff --git a/.github/workflows/import-external-skills.yml b/.github/workflows/import-external-skills.yml index 7209ea3..7094b04 100644 --- a/.github/workflows/import-external-skills.yml +++ b/.github/workflows/import-external-skills.yml @@ -1,7 +1,7 @@ name: import-external-skills # Manually-dispatched workflow that refreshes the federated portion of the -# catalog. It reads `scripts/sources.yml`, shallow-clones each declared +# catalog. It reads `.github/scripts/sources.yml`, shallow-clones each declared # source, vendors the named skills into `skills//`, updates # `.claude-plugin/marketplace.json`, regenerates the Cursor manifest, and # opens a pull request with the result. Every imported skill goes through @@ -42,22 +42,22 @@ jobs: git --version git config --global init.defaultBranch main - - name: Import skills declared in scripts/sources.yml + - name: Import skills declared in .github/scripts/sources.yml id: import run: | if [ "${{ inputs.dry_run }}" = "true" ]; then - uv run scripts/import_external_skills.py --dry-run + uv run .github/scripts/import_external_skills.py --dry-run else - uv run scripts/import_external_skills.py + uv run .github/scripts/import_external_skills.py fi - name: Regenerate Cursor marketplace manifest if: ${{ inputs.dry_run != true }} - run: uv run scripts/generate_cursor_marketplace.py + run: uv run .github/scripts/generate_cursor_marketplace.py - name: Validate skills and manifests if: ${{ inputs.dry_run != true }} - run: ./scripts/check.sh + run: ./.github/scripts/check.sh - name: Detect changes if: ${{ inputs.dry_run != true }} @@ -81,10 +81,10 @@ jobs: with: branch: bot/import-external-skills delete-branch: true - commit-message: "chore(catalog): refresh federated skills from scripts/sources.yml" + commit-message: "chore(catalog): refresh federated skills from .github/scripts/sources.yml" title: "Refresh federated skills" body: | - Automated import driven by `scripts/sources.yml`. + Automated import driven by `.github/scripts/sources.yml`. See the "A federated catalog" section of `README.md` for the design. Each vendored skill includes a `.federated.json` marker @@ -97,7 +97,7 @@ jobs: catalog automated add-paths: | - scripts/sources.yml + .github/scripts/sources.yml skills/** .claude-plugin/** .cursor-plugin/** diff --git a/.github/workflows/skillspector.yml b/.github/workflows/skillspector.yml index fdb5eb2..6650327 100644 --- a/.github/workflows/skillspector.yml +++ b/.github/workflows/skillspector.yml @@ -38,7 +38,7 @@ jobs: - name: List skills id: discover - run: echo "skills=$(uv run scripts/validate_skills.py --list)" >> "$GITHUB_OUTPUT" + run: echo "skills=$(uv run .github/scripts/validate_skills.py --list)" >> "$GITHUB_OUTPUT" scan-skill: name: Scan skill @@ -89,8 +89,8 @@ jobs: # Fail when any individual finding is HIGH or CRITICAL, except for # documented false positives recorded in .github/skillspector-allow.yml. # SkillSpector has no native suppression, so the gate applies the - # allowlist here (see scripts/skillspector_gate.py). - uv run scripts/skillspector_gate.py \ + # allowlist here (see .github/scripts/skillspector_gate.py). + uv run .github/scripts/skillspector_gate.py \ --report "$report" \ --skill "${{ matrix.skill }}" \ --allowlist .github/skillspector-allow.yml diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index f681de0..a0b7ac7 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -5,7 +5,7 @@ on: branches: [main] pull_request: paths: - - "scripts/**" + - ".github/scripts/**" - "**/*.md" - "skills/**" - ".claude-plugin/**" @@ -33,7 +33,7 @@ jobs: - name: List skills id: discover - run: echo "skills=$(uv run scripts/validate_skills.py --list)" >> "$GITHUB_OUTPUT" + run: echo "skills=$(uv run .github/scripts/validate_skills.py --list)" >> "$GITHUB_OUTPUT" validate-skill: name: Validate skill @@ -53,7 +53,7 @@ jobs: uses: astral-sh/setup-uv@v7 - name: Validate skill - run: uv run scripts/validate_skills.py --skill "${{ matrix.skill }}" + run: uv run .github/scripts/validate_skills.py --skill "${{ matrix.skill }}" # Repo-wide checks that aren't tied to a single skill: the generated plugin # manifests and internal markdown references. @@ -68,10 +68,10 @@ jobs: uses: astral-sh/setup-uv@v7 - name: Validate marketplace manifest - run: uv run scripts/validate_skills.py --marketplace-only + run: uv run .github/scripts/validate_skills.py --marketplace-only - name: Validate generated Cursor manifest - run: uv run scripts/generate_cursor_marketplace.py --check + run: uv run .github/scripts/generate_cursor_marketplace.py --check # Deterministic, offline-only reference check: relative paths and # heading anchors. External URLs are intentionally not checked here diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6deb0b7..37ec7e0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,20 +20,20 @@ Best for cross-cutting skills that do not have a natural product home. 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/marketplace.json + ./.github/scripts/publish.sh # writes .cursor-plugin/marketplace.json ``` 6. Validate the skill locally before pushing: ```bash - ./scripts/check.sh # validates every SKILL.md and that manifests are in sync + ./.github/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. +7. Open a pull request. The `validate` GitHub Actions workflow runs `./.github/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 (or extends) an entry in [`scripts/sources.yml`](scripts/sources.yml) — the master list — naming your repo, a pinned ref, the sub-path that holds skill folders, and your skill's folder name. +2. Open a pull request here that adds (or extends) an entry in [`.github/scripts/sources.yml`](.github/scripts/sources.yml) — the master list — naming your repo, a pinned ref, the sub-path that holds skill folders, and your skill's folder name. 3. Once the catalog change merges, dispatch the **Import external skills** workflow from the Actions tab. It shallow-clones your repo at the pinned ref, vendors the skill into `skills//`, updates `.claude-plugin/marketplace.json`, and opens a follow-up pull request. Validation then runs against the same rules as in-repo skills before merge. ## Is this task a good fit for a skill? @@ -182,14 +182,14 @@ Test the skill the way users will hit it: - [ ] Scripts handle expected errors and document their constants and dependencies - [ ] Prerequisites (ROCm version, GPU arch, container, env vars) are stated explicitly - [ ] Tested end-to-end on the target hardware against real prompts -- [ ] `./scripts/check.sh` passes (CI runs this on every PR) +- [ ] `./.github/scripts/check.sh` passes (CI runs this on every PR) ## Validating locally -The structural rules from this guide (frontmatter shape, name format, description length, and `SKILL.md` body size) are enforced by `scripts/validate_skills.py` and run on every pull request. Run them locally before pushing: +The structural rules from this guide (frontmatter shape, name format, description length, and `SKILL.md` body size) are enforced by `.github/scripts/validate_skills.py` and run on every pull request. Run them locally before pushing: ```bash -./scripts/check.sh # validates every skill and plugin manifests (same command CI runs) +./.github/scripts/check.sh # validates every skill and plugin manifests (same command CI runs) ``` The validator checks every skill under `skills/` for: @@ -202,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/marketplace.json` is up to date — it mirrors `.claude-plugin/marketplace.json` and pulls shared identity (name, description, version, author) from `plugin-metadata.json` (regenerate with `./scripts/publish.sh`) +- `.cursor-plugin/marketplace.json` is up to date — it mirrors `.claude-plugin/marketplace.json` and pulls shared identity (name, description, version, author) from `plugin-metadata.json` (regenerate with `./.github/scripts/publish.sh`) diff --git a/README.md b/README.md index 1ab541c..2fb202a 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,6 @@ +> [!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
@@ -24,11 +27,9 @@ Skills in this repository follow the standardized [Agent Skills](https://github. ## Installation -AMD Skills is built directly into Claude and Cursor. **No install. No setup** - -Just ask something like: `"Use AMD Skills to integrate local AI into my app"`. +AMD Skills will soon be installable directly in Claude/Cursor/Codex and other agents through marketplace integration. -> For other agents, see [Manual installation](#manual-installation). +While we work marketplace integration, please refer to our [Manual installation steps](#manual-installation). ## What is a skill? @@ -52,54 +53,37 @@ Skills earn their keep on repeated, opinionated workflows, exactly where the AMD ## The catalog -> [!IMPORTANT] -> **The catalog is under active development.** Skills, categories, and descriptions are changing fast. Expect entries to appear, move, and get renamed without notice. -> -> **Target: ready for testing by June 12.** Until then, treat anything below as a preview. - -The initial catalog is organized into four focus areas. - +The initial catalog is organized into three focus areas, spanning the full stack from client to cloud. This catalog is expected to grow significantly as more skills land. -### Application integration +### Client-Native -Embed AMD-optimized AI into end-user applications. +Run and optimize on Ryzen AI. | Skill | What it does | Source | | --- | --- | --- | -| [`local-ai-app-integration`](skills/local-ai-app-integration/SKILL.md) | Integrate local AI into cloud LLM apps for offline support, better privacy, and lower API costs. | in-repo | | [`local-ai-use`](skills/local-ai-use/SKILL.md) | Route image generation, text-to-speech, and speech-to-text through a local AI server to reduce token cost. | in-repo | +| [`local-ai-app-integration`](skills/local-ai-app-integration/SKILL.md) | Integrate local AI into cloud LLM apps for offline support, better privacy, and lower API costs. | in-repo | +| `apu-memory-tuner` | Inspect and tune the shared-vs-dedicated memory split (GTT / UMA Frame Buffer) on AMD Ryzen APUs. | _planned_ | -### Platform readiness +### Cross-Stack -Diagnose, configure, and ready AMD systems for AI workloads: drivers, BIOS, memory pools, `gfx` targets, and framework setup. +Cross-stack skills, from client to cloud. | Skill | What it does | Source | | --- | --- | --- | -| [`apu-memory-tuner`](skills/apu-memory-tuner/SKILL.md) | Inspect and tune the shared-vs-dedicated memory split (GTT / UMA Frame Buffer) on AMD Ryzen APUs. | in-repo | -| [`rocm-doctor`](skills/rocm-doctor/SKILL.md) | Diagnose ROCm / PyTorch / llama.cpp failures on AMD GPUs against a fixed list of known misconfigurations. | in-repo | -| `gfx-target-chooser` | Pick the right `gfx942` / `gfx90a` / `gfx1100` target and matching compiler flags. | _planned_ | -| `pytorch-rocm-setup` | Get a known-good PyTorch + ROCm stack running on a target node, end to end. | _planned_ | +| `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_ | +| `vllm-semantic-router` | Setup a vLLM router that semantically maps your request to the best available platform. | _planned_ | -### Cross-stack porting +### Server-Native -Bring existing workloads onto AMD. +Run and optimize on AMD Instinct. | Skill | What it does | Source | | --- | --- | --- | -| `cuda-to-hip` | Port CUDA kernels with `hipify` and flag anything that needs manual review. | _planned_ | -| `vllm-rocm` | Stand up vLLM on AMD with the right environment variables and model configurations. | _planned_ | | [`serving-llms-on-instinct`](skills/serving-llms-on-instinct/SKILL.md) | Deploy LLM inference on AMD Instinct GPUs end-to-end: detect hardware (or onboard via AMD Developer Cloud), validate model fit, apply the right vLLM recipe, and launch a benchmarked endpoint. SGLang and engine/backend selection in later phases. | in-repo | +| [`llm-kernel-evaluator` (`magpie`)](skills/magpie/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) | -### Performance & delivery - -Close the loop from trace to fix to ship. - -| Skill | What it does | Source | -| --- | --- | --- | -| [`magpie`](skills/magpie/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) | -| `hyperloom` | Autonomously optimizes LLM inference on AMD GPUs. | _planned_ | -| `omniperf-tune` | Run `omniperf`, locate the bottleneck, and suggest the fix. | _planned_ | -| `quark-quantize` | Quantize PyTorch / ONNX models with [AMD Quark](https://github.com/amd/Quark) and export for AMD deployment. | _planned_ | ## A federated catalog @@ -109,7 +93,7 @@ The AMD stack is large and moves fast. ROCm, HIP, Ryzen AI, and framework integr ┌─────────────────────────────────────────────────────┐ │ amd/skills (this repo) │ │ │ - │ skills/ scripts/ .*-plugin/ │ + │ skills/ .github/scripts/ .*-plugin/ │ │ in-repo skills sources.yml agent manifests │ └──────────────────────┬──────────────────────────────┘ │ one install @@ -124,20 +108,20 @@ The AMD stack is large and moves fast. ROCm, HIP, Ryzen AI, and framework integr gfx-target-... triton-amd-... ... integration/ repos ``` -This repo also acts as an **incubator**: a skill can start under `skills/` to iterate quickly, then graduate to its product repo and be re-pointed from `scripts/sources.yml` once it has a clear owner, with no change for installed users. +This repo also acts as an **incubator**: a skill can start under `skills/` to iterate quickly, then graduate to its product repo and be re-pointed from `.github/scripts/sources.yml` once it has a clear owner, with no change for installed users. ``` -skills/ # All skills the agent can load (in-repo + vendored copies of federated) -.claude-plugin/ # Claude Code marketplace manifest (one installable plugin per skill) -.cursor-plugin/ # Cursor marketplace manifest (generated mirror of the Claude catalog) -plugin-metadata.json # Shared, vendor-neutral identity/discovery metadata for all manifests -.github/workflows/ # CI for validating skills and the `import-external-skills` workflow -scripts/ # Tooling for publishing, regenerating manifests, and importing -scripts/sources.yml # Master list of external skill sources for federation +skills/ # All skills the agent can load +.claude-plugin/ # Claude Code marketplace manifest +.cursor-plugin/ # Cursor marketplace manifest +plugin-metadata.json # Vendor-neutral identity/discovery metadata +.github/workflows/ # CI for validating skills +.github/scripts/ # Internal repo scripts +.github/scripts/sources.yml # External skill sources for federation ``` In-repo skills are authored directly under `skills/`. Federated skills are -declared in [`scripts/sources.yml`](scripts/sources.yml) and vendored into +declared in [`.github/scripts/sources.yml`](.github/scripts/sources.yml) and vendored into `skills/` by the manually-dispatched `import-external-skills` workflow, which opens a pull request with the imported copies. Each vendored skill carries a `.federated.json` marker that records the upstream repo and @@ -146,32 +130,18 @@ in-repo skills. ## Manual Installation -AMD Skills are compatible with Cursor, Claude Code, OpenAI Codex, and Gemini CLI. The general flow: - -### Cursor - -Add this repository as a plugin marketplace through the Cursor plugin flow, then enable the skills you want. The repo ships a `.cursor-plugin/marketplace.json` that lists every skill as its own installable plugin, mirroring the Claude Code catalog. - -### Claude Code - -Register this repository as a plugin marketplace, then install individual skills: +Until marketplace integration lands, install skills manually: clone this repo, then copy (or symlink) the skill folders you want from `skills/` into your agent's skills directory. Each agent discovers `SKILL.md` automatically. ```bash -/plugin marketplace add amd/skills -/plugin install @amd/skills +git clone https://github.com/amd/skills.git amd-skills +cp -r amd-skills/skills/local-ai-use / ``` -### OpenAI Codex - -Copy or symlink the desired folders from `skills/` into one of Codex's standard skill locations (for example `$REPO_ROOT/.agents/skills` or `$HOME/.agents/skills`). Codex will discover the `SKILL.md` files automatically. - -### Gemini CLI - -A `gemini-extension.json` will be provided so the repo can be installed as a Gemini CLI extension: - -```bash -gemini extensions install https://github.com/amd/skills.git --consent -``` +| Agent | Skills directory (personal / project) | +| --- | --- | +| Cursor | `~/.cursor/skills/` / `.cursor/skills/` | +| Claude Code | `~/.claude/skills/` / `.claude/skills/` | +| Codex | `$HOME/.agents/skills` / `$REPO_ROOT/.agents/skills` | ## Using a skill @@ -182,12 +152,14 @@ Once a skill is installed, reference it in plain language while talking to your 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: -- **Path A — In-repo skills.** Authored directly under `skills/`. Best for cross-cutting workflows without a natural product home. -- **Path B — Product-repo skills.** Authored in a product repository and registered here through [`scripts/sources.yml`](scripts/sources.yml) with a pinned tag. Best for skills that should ship and version with a specific product. +- **Path A: In-repo skills.** Authored directly under `skills/`. Best for cross-cutting workflows without a natural product home. +- **Path B: Product-repo skills.** Authored in a product repository and registered here through [`.github/scripts/sources.yml`](.github/scripts/sources.yml) with a pinned tag. Best for skills that should ship and version with a specific product. See [CONTRIBUTING.md](CONTRIBUTING.md) for step-by-step instructions and the rules CI enforces.