Skip to content

Commit 0c71555

Browse files
Merge pull request #39 from amd/dholanda/apex
Implement federated import mechanism + Add Apex skills
2 parents 6fb003a + 7e42a77 commit 0c71555

34 files changed

Lines changed: 26786 additions & 14 deletions

File tree

.claude-plugin/marketplace.json

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,12 +8,36 @@
88
"version": "0.1.0"
99
},
1010
"plugins": [
11+
{
12+
"name": "aiter-reflection",
13+
"source": "./skills/aiter-reflection",
14+
"skills": "./",
15+
"description": "This skill should be used when optimizing AMD GPU kernels on MI300 using the aiter project, including running op tests, benchmarking, iterating on kernel changes, and recording results in the kernel experiment database."
16+
},
1117
{
1218
"name": "apu-memory-tuner",
1319
"source": "./skills/apu-memory-tuner",
1420
"skills": "./",
1521
"description": "Inspect and tune the shared-vs-dedicated memory split (GTT / UMA Frame Buffer) on AMD Ryzen APUs so larger LLMs and image models fit on the iGPU."
1622
},
23+
{
24+
"name": "gpu-architecture-fundamentals",
25+
"source": "./skills/gpu-architecture-fundamentals",
26+
"skills": "./",
27+
"description": "This skill should be used when reasoning about GPU architecture fundamentals to guide kernel optimization choices such as memory hierarchy usage, execution model mapping, block sizing, and latency-aware tuning across HIP, Triton, and PyTorch."
28+
},
29+
{
30+
"name": "hip-kernel-optimization",
31+
"source": "./skills/hip-kernel-optimization",
32+
"skills": "./",
33+
"description": "This skill should be used when writing or tuning HIP kernels on AMD/NVIDIA GPUs, covering memory coalescing, shared-memory tiling, bank conflict avoidance, warp primitives, occupancy, vectorization, async ops, loop unrolling, and profiling."
34+
},
35+
{
36+
"name": "kernel-exp-history",
37+
"source": "./skills/kernel-exp-history",
38+
"skills": "./",
39+
"description": "This skill should be used when optimizing kernels in this repo and needing to consult past optimization experiments, or when recording the current optimization iteration back into the kernel experiment database."
40+
},
1741
{
1842
"name": "local-ai-app-integration",
1943
"source": "./skills/local-ai-app-integration",
@@ -26,11 +50,47 @@
2650
"skills": "./",
2751
"description": "Route image generation, text-to-speech, and speech-to-text through a local AI Server to reduce token/cost usage."
2852
},
53+
{
54+
"name": "mi300-hip-programming-insights",
55+
"source": "./skills/mi300-hip-programming-insights",
56+
"skills": "./",
57+
"description": "CDNA3/MI300 HIP programming insights—chiplet/cache model, Infinity Cache, memory coherency, matrix cores, sparsity, and best practices."
58+
},
59+
{
60+
"name": "pytorch-kernel-optimization",
61+
"source": "./skills/pytorch-kernel-optimization",
62+
"skills": "./",
63+
"description": "This skill should be used when optimizing PyTorch models and kernels, including efficient tensor operations, torch.compile, custom autograd/CUDA/Triton extensions, mixed precision, memory and data pipeline tuning, model optimization techniques, CUDA graphs, and profiling."
64+
},
2965
{
3066
"name": "rocm-doctor",
3167
"source": "./skills/rocm-doctor",
3268
"skills": "./",
3369
"description": "Diagnose why ROCm, PyTorch, or llama.cpp isn't working on an AMD GPU. Matches the symptom against a fixed list of twelve known misconfigurations and proposes the next step."
70+
},
71+
{
72+
"name": "rocprof-compute",
73+
"source": "./skills/rocprof-compute",
74+
"skills": "./",
75+
"description": "This skill should be used when profiling AMD GPU kernels with rocprof-compute to collect metrics, roofline data, and analyze bottlenecks for HIP kernels."
76+
},
77+
{
78+
"name": "triton-hip-reference-kernel-search",
79+
"source": "./skills/triton-hip-reference-kernel-search",
80+
"skills": "./",
81+
"description": "Search and adapt Triton/HIP kernel patterns from a corpus to optimize AMD GPUs; use to find similar ops and reuse tiling/occupancy strategies."
82+
},
83+
{
84+
"name": "triton-kernel-optimization",
85+
"source": "./skills/triton-kernel-optimization",
86+
"skills": "./",
87+
"description": "This skill should be used when writing or tuning Triton GPU kernels, including autotuning block sizes, coalesced accesses, tiled matmul, fused ops, reductions, flash-attention style kernels, quantization, custom gradients, and profiling."
88+
},
89+
{
90+
"name": "triton-kernel-reflection-prompts",
91+
"source": "./skills/triton-kernel-reflection-prompts",
92+
"skills": "./",
93+
"description": "Reflection/self-critique prompts for reviewing and fixing AMD-targeted Triton kernels after generation or test failures."
3494
}
3595
]
3696
}

.github/ISSUE_TEMPLATE/skill-proposal.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ body:
5050
id: home
5151
attributes:
5252
label: Where should this skill live?
53-
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/`.
53+
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`.
5454
options:
5555
- "Path A: incubated in this repo (may move to a product repo and continbue to be registered here)"
5656
- "Path B: authored in a product repo (HIP, ROCm, Ryzen AI, Lemonade, ...) and registered here"
Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
name: import-external-skills
2+
3+
# Manually-dispatched workflow that refreshes the federated portion of the
4+
# catalog. It reads `scripts/sources.yml`, shallow-clones each declared
5+
# source, vendors the named skills into `skills/<name>/`, updates
6+
# `.claude-plugin/marketplace.json`, regenerates the Cursor manifest, and
7+
# opens a pull request with the result. Every imported skill goes through
8+
# the same `validate` checks as in-repo skills before it lands on `main`.
9+
#
10+
# See the "A federated catalog" section of `README.md` for the design.
11+
12+
on:
13+
workflow_dispatch:
14+
inputs:
15+
dry_run:
16+
description: "Resolve sources and print planned changes without committing."
17+
required: false
18+
type: boolean
19+
default: false
20+
21+
permissions:
22+
contents: write
23+
pull-requests: write
24+
25+
concurrency:
26+
group: import-external-skills
27+
cancel-in-progress: false
28+
29+
jobs:
30+
import:
31+
name: Import external skills
32+
runs-on: ubuntu-latest
33+
steps:
34+
- name: Check out repository
35+
uses: actions/checkout@v4
36+
37+
- name: Set up uv
38+
uses: astral-sh/setup-uv@v7
39+
40+
- name: Configure git for sparse-checkout
41+
run: |
42+
git --version
43+
git config --global init.defaultBranch main
44+
45+
- name: Import skills declared in scripts/sources.yml
46+
id: import
47+
run: |
48+
if [ "${{ inputs.dry_run }}" = "true" ]; then
49+
uv run scripts/import_external_skills.py --dry-run
50+
else
51+
uv run scripts/import_external_skills.py
52+
fi
53+
54+
- name: Regenerate Cursor plugin manifest
55+
if: ${{ inputs.dry_run != true }}
56+
run: uv run scripts/generate_cursor_plugin.py
57+
58+
- name: Validate skills and manifests
59+
if: ${{ inputs.dry_run != true }}
60+
run: ./scripts/check.sh
61+
62+
- name: Detect changes
63+
if: ${{ inputs.dry_run != true }}
64+
id: changes
65+
run: |
66+
if [ -z "$(git status --porcelain)" ]; then
67+
echo "changed=false" >> "$GITHUB_OUTPUT"
68+
echo "No changes to import. Skipping PR."
69+
else
70+
echo "changed=true" >> "$GITHUB_OUTPUT"
71+
git status --short
72+
fi
73+
74+
# Use the GitHub-maintained action to push to a dedicated branch and
75+
# open a PR. PRs (rather than direct commits to main) keep imported
76+
# changes reviewable and let the standard `validate` workflow gate
77+
# them.
78+
- name: Open pull request with imported skills
79+
if: ${{ inputs.dry_run != true && steps.changes.outputs.changed == 'true' }}
80+
uses: peter-evans/create-pull-request@v7
81+
with:
82+
branch: bot/import-external-skills
83+
delete-branch: true
84+
commit-message: "chore(catalog): refresh federated skills from scripts/sources.yml"
85+
title: "Refresh federated skills"
86+
body: |
87+
Automated import driven by `scripts/sources.yml`.
88+
89+
See the "A federated catalog" section of `README.md` for the
90+
design. Each vendored skill includes a `.federated.json` marker
91+
recording the source repo, pinned ref, and resolved commit at
92+
import time.
93+
94+
Triggered by @${{ github.actor }} via the `import-external-skills`
95+
workflow ([run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})).
96+
labels: |
97+
catalog
98+
automated
99+
add-paths: |
100+
scripts/sources.yml
101+
skills/**
102+
.claude-plugin/**
103+
.cursor-plugin/**

CONTRIBUTING.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,8 +33,8 @@ Best for cross-cutting skills that do not have a natural product home.
3333
Best for skills that should ship and version with a product (HIP, MIGraphX, Ryzen AI, Lemonade, etc.).
3434

3535
1. Add the skill folder to your product repository; a common location is `.agents/skills/<skill-name>/`.
36-
2. Open a pull request here that adds an entry to `catalog/` pointing at the skill's location and pinning a tag.
37-
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.
36+
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.
37+
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/<name>/`, 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.
3838

3939
## Is this task a good fit for a skill?
4040

README.md

Lines changed: 19 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -107,8 +107,8 @@ So skills here are **federated**: each skill is owned and versioned by the team
107107
┌─────────────────────────────────────────────────────┐
108108
│ amd/skills (this repo) │
109109
│ │
110-
│ skills/ catalog/ .*-plugin/
111-
│ in-repo skills pointers agent manifests
110+
│ skills/ scripts/ .*-plugin/ │
111+
│ in-repo skills sources.yml agent manifests │
112112
└──────────────────────┬──────────────────────────────┘
113113
│ one install
114114
@@ -124,7 +124,7 @@ So skills here are **federated**: each skill is owned and versioned by the team
124124

125125
Each skill stays close to the engineers who ship the underlying product, the CI that validates it, and the release tag that pins it.
126126

127-
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.
127+
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 `scripts/sources.yml` once it has a clear owner, with no change for installed users.
128128

129129
### What this means for you
130130

@@ -135,21 +135,29 @@ This repo also acts as an **incubator**: a skill can start its life under `skill
135135
### What this means if you contribute
136136

137137
- **In-repo skills** (Path A) are best for cross-cutting workflows that do not have a natural product home.
138-
- **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.
138+
- **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 `scripts/sources.yml` 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.
139139

140140
See [CONTRIBUTING.md](CONTRIBUTING.md) for the step-by-step contribution flow for each path.
141141

142142
### Repository layout
143143

144144
```
145-
skills/ # Skills authored in this repository
146-
catalog/ # Manifest pointers to skills that live in product repositories
147-
.cursor-plugin/ # Cursor plugin manifest
148-
.claude-plugin/ # Claude Code marketplace manifest
149-
.github/workflows/ # CI for validating skills and manifests
150-
scripts/ # Tooling for publishing and regenerating manifests
145+
skills/ # All skills the agent can load (in-repo + vendored copies of federated)
146+
.cursor-plugin/ # Cursor plugin manifest
147+
.claude-plugin/ # Claude Code marketplace manifest
148+
.github/workflows/ # CI for validating skills and the `import-external-skills` workflow
149+
scripts/ # Tooling for publishing, regenerating manifests, and importing
150+
scripts/sources.yml # Master list of external skill sources for federation
151151
```
152152

153+
In-repo skills are authored directly under `skills/`. Federated skills are
154+
declared in [`scripts/sources.yml`](scripts/sources.yml) and vendored into
155+
`skills/` by the manually-dispatched `import-external-skills` workflow,
156+
which opens a pull request with the imported copies. Each vendored skill
157+
carries a `.federated.json` marker that records the upstream repo and
158+
pinned commit, so the importer can refresh or remove it without disturbing
159+
in-repo skills.
160+
153161
## Manual Installation
154162

155163
AMD Skills are compatible with Cursor, Claude Code, OpenAI Codex, and Gemini CLI. The general flow:
@@ -194,7 +202,7 @@ The agent loads the matching `SKILL.md` and any helper scripts, then carries out
194202
We welcome contributions from AMD engineers and selected partners. There are two paths, matching how the catalog is organized:
195203

196204
- **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.
197-
- **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.).
205+
- **Path B: Product-repo skills.** Authored in a product repository and registered here through `scripts/sources.yml` with a pinned tag. Best for skills that should ship and version with a specific product (HIP, ROCm, Ryzen AI, Lemonade, etc.).
198206

199207
See [CONTRIBUTING.md](CONTRIBUTING.md) for step-by-step instructions, the full authoring guide, and the rules CI enforces on every pull request.
200208

0 commit comments

Comments
 (0)