What is a skill?

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/
  <skill-name>/
    SKILL.md
    skill-card.md
    scripts/       # optional
    references/    # optional

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-requirements.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.

Catalog federation#

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. 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.

                ┌─────────────────────────────────────────────────────┐
                │                amd/skills (this repo)               │
                │                                                     │
                │   skills/         .github/         .*-plugin/       │
                │   vendored copies federation.json  agent manifests  │
                └──────────────────────┬──────────────────────────────┘
                                       │  one install
                                       ▼
                              your AI coding agent
                                       ▲
                                       │  resolves pointers to
       ┌───────────────┬───────────────┼───────────────┬────────────────┐
       │               │               │               │                │
   ROCm/ROCm       ROCm/HIP        Ryzen AI repo   lemonade-sdk    ...more
  rocm-doctor/    cuda-to-hip/    ryzen-ai-tools/   local-ai-app-   product
   gfx-target-...  triton-amd-...  ...               integration/    repos

.github/federation.json is the whole registry: each entry names a source repo and the exact path of every skill folder to vendor from it.

The federate-skills workflow runs nightly and on demand. It clones each declared repo, compares a content hash of the upstream skill folder against the hash recorded in the vendored copy’s .federated.json, and re-vendors only the skills that actually changed. For each skill that did change it regenerates the agent manifests and opens a separate pull request titled Bump <skill> to <short commit>, where the usual validate checks apply as they would to any other pull request. A quiet night produces no diff and therefore no pull request, so every bump that lands is a reviewed commit.

A vendored skill mirrors its upstream folder, evals/ included, so the datasets this repo grades a federated skill against are maintained in its product repo. Files over 100 KB, such as trace archives, stay upstream.

See CONTRIBUTING.md to register a repo.

See the full catalog for the current list of available and planned skills.

Contents