Add per-skill governance cards (skill cards) (#61)

danielholanda · web-flow · commit 2b7cb8e6ec8d · 2026-06-15T16:06:25.000-07:00
diff --git a/.github/scripts/import_external_skills.py b/.github/scripts/import_external_skills.py
@@ -17,10 +17,14 @@
    github.com URLs pinned to the imported commit, so the offline link
    checker doesn't flag them as missing local files. Links to files that
    were actually copied into the skill folder are left untouched.
-5. Updates `.claude-plugin/marketplace.json` with an entry per imported
+5. Synthesizes a minimal `skill-card.md` (Description, Owner, License)
+   from the source metadata when the upstream copy doesn't already ship
+   one, so the imported skill satisfies the card validation gate (see
+   docs/skill-cards.md).
+6. Updates `.claude-plugin/marketplace.json` with an entry per imported
    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`)
+7. Removes any previously imported skill (one with a `.federated.json`)
    that is no longer listed in `.github/scripts/sources.yml`.
 
 Usage:
@@ -53,6 +57,7 @@
 SKILLS_DIR = REPO_ROOT / "skills"
 CLAUDE_MARKETPLACE = REPO_ROOT / ".claude-plugin" / "marketplace.json"
 MARKER_FILENAME = ".federated.json"
+CARD_FILENAME = "skill-card.md"
 
 FRONTMATTER_RE = re.compile(
     r"\A---\s*\n(?P<frontmatter>.*?)\n---\s*\n?(?P<body>.*)\Z",
@@ -363,6 +368,32 @@ def write_marker(
     )
 
 
+def write_card(skill_dir: Path, source: Source, description: str) -> None:
+    """Write a minimal skill-card.md unless the upstream copy shipped one.
+
+    Federated skills are copied wholesale (`copy_skill` does rmtree +
+    copytree), so any card authored here would be wiped on re-import. When
+    upstream doesn't provide a card, synthesize one from the source metadata
+    so the imported skill still satisfies the card validation gate.
+    """
+    card = skill_dir / CARD_FILENAME
+    if card.exists():
+        return
+    owner_org = source.repo.split("/")[0]
+    license_text = source.license or f"See [{source.repo}](https://github.com/{source.repo})"
+    card.write_text(
+        "# Skill Card\n\n"
+        "## Description\n\n"
+        f"{description}\n\n"
+        "## Owner\n\n"
+        f"{owner_org} (federated from "
+        f"[{source.repo}](https://github.com/{source.repo}))\n\n"
+        "## License\n\n"
+        f"{license_text}\n",
+        encoding="utf-8",
+    )
+
+
 def update_marketplace(results: Iterable[ImportResult], dry_run: bool) -> bool:
     """Sync `.claude-plugin/marketplace.json` with the imported skills.
 
@@ -467,6 +498,7 @@ def import_source(
             if not dry_run:
                 copy_skill(src_skill, dest_skill)
                 write_marker(dest_skill, source, commit, relative_path)
+                write_card(dest_skill, source, marketplace_description)
                 rewrite_external_references(
                     dest_skill,
                     relative_path,
diff --git a/.github/scripts/validate_skills.py b/.github/scripts/validate_skills.py
@@ -13,6 +13,8 @@
     substrings, and matches the directory name
   - `description` is a non-empty string <=1024 chars
   - SKILL.md body is <=500 lines
+  - skill-card.md exists at the skill root and has non-empty
+    `## Description`, `## Owner`, and `## License` sections
 
 Also validates that `.claude-plugin/marketplace.json` is in sync with the
 skills on disk: every skill must have a marketplace entry, and every
@@ -61,6 +63,11 @@
 )
 RESERVED_NAME_SUBSTRINGS = ("anthropic", "claude")
 
+# Per-skill governance card (see docs/skill-cards.md). Each section must be a
+# top-level `##` heading followed by some non-empty body text.
+CARD_FILENAME = "skill-card.md"
+REQUIRED_CARD_SECTIONS = ("Description", "Owner", "License")
+
 
 @dataclass
 class SkillReport:
@@ -102,6 +109,7 @@ def validate_skill(skill_dir: Path) -> SkillReport:
     _validate_name(frontmatter.get("name"), skill_dir.name, report)
     _validate_description(frontmatter.get("description"), report)
     _validate_body(match.group("body"), report)
+    _validate_card(skill_dir, report)
     return report
 
 
@@ -157,6 +165,47 @@ def _validate_body(body: str, report: SkillReport) -> None:
         )
 
 
+def _validate_card(skill_dir: Path, report: SkillReport) -> None:
+    """Require a skill-card.md with non-empty Description, Owner, License."""
+    card = skill_dir / CARD_FILENAME
+    if not card.exists():
+        report.errors.append(
+            f"Missing {CARD_FILENAME} (governance card). See docs/skill-cards.md; "
+            "it needs `## Description`, `## Owner`, and `## License` sections."
+        )
+        return
+
+    sections = _parse_card_sections(card.read_text(encoding="utf-8"))
+    for name in REQUIRED_CARD_SECTIONS:
+        body = sections.get(name.lower())
+        if body is None:
+            report.errors.append(f"{CARD_FILENAME} is missing a `## {name}` section.")
+        elif not body.strip():
+            report.errors.append(f"{CARD_FILENAME} `## {name}` section is empty.")
+
+
+def _parse_card_sections(text: str) -> dict[str, str]:
+    """Map each `##` heading (lowercased) to the text until the next heading."""
+    sections: dict[str, str] = {}
+    current: str | None = None
+    buffer: list[str] = []
+
+    def flush() -> None:
+        if current is not None:
+            sections[current] = "\n".join(buffer).strip()
+
+    for line in text.splitlines():
+        heading = re.match(r"^##\s+(?P<title>.+?)\s*$", line)
+        if heading:
+            flush()
+            current = heading.group("title").lower()
+            buffer = []
+        elif current is not None:
+            buffer.append(line)
+    flush()
+    return sections
+
+
 def discover_skills(root: Path) -> list[Path]:
     """List skill directories under `root`, ignoring dotfiles."""
     if not root.exists():
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -17,16 +17,17 @@ 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:
+4. Add a `skill-card.md` at the skill root with `## Description`, `## Owner`, and `## License` sections. This is the skill's governance card; see [Skill cards](#skill-cards) and [docs/skill-cards.md](docs/skill-cards.md).
+5. 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).
+6. Regenerate the Cursor manifest so it tracks the new skill:
    ```bash
    ./.github/scripts/publish.sh   # writes .cursor-plugin/marketplace.json
    ```
-6. Validate the skill locally before pushing:
+7. Validate the skill locally before pushing:
    ```bash
    ./.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 `./.github/scripts/check.sh` and must pass before merge. See [Validating locally](#validating-locally) for the full set of enforced rules.
+8. 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
 
@@ -114,6 +115,7 @@ Link from `SKILL.md` directly to reference files. Do not chain references throug
 ```
 skill-name/
   SKILL.md          # overview, quick start, links
+  skill-card.md     # governance card (Description, Owner, License)
   reference.md      # full API / flag reference
   examples.md       # worked examples
   scripts/          # executable utilities
@@ -153,6 +155,30 @@ Pre-made scripts beat generated code: more reliable, fewer tokens, consistent ac
 - **Make execution intent explicit.** Write *"Run `analyze.py`..."* (execute) or *"See `analyze.py` for the algorithm"* (read), never both.
 - **Use fully qualified MCP tool names.** `ServerName:tool_name`, e.g. `BigQuery:bigquery_schema`. Bare names fail when multiple servers are registered.
 
+## Skill cards
+
+Every skill ships a `skill-card.md` at its root: a short, human-facing governance record that tells a reviewer what the skill does, who owns it, and under what license it ships, without reading the source. It is not loaded by the agent.
+
+The AMD card is intentionally minimal. Three required sections, each a `##` heading with non-empty body text:
+
+```markdown
+# Skill Card
+
+## Description
+
+<one sentence: what the skill does, for whom>
+
+## Owner
+
+<team or org accountable for maintenance, e.g. AMD>
+
+## License
+
+<SPDX identifier or link, e.g. MIT>
+```
+
+The validator fails any skill whose card is missing or whose required sections are absent or empty. For the full guide, examples, and how federated skills get cards, see [docs/skill-cards.md](docs/skill-cards.md).
+
 ## AMD-specific guidance
 
 - **State prerequisites up front.** ROCm version, kernel version, GPU architecture (`gfx942`, `gfx90a`, `gfx1100`, ...), container image, driver branch.
@@ -172,6 +198,7 @@ Test the skill the way users will hit it:
 
 - [ ] Description states the user's goal and includes likely trigger phrases
 - [ ] Description is third person and under 1024 characters
+- [ ] `skill-card.md` exists with non-empty Description, Owner, and License sections
 - [ ] Skill name is lowercase-with-hyphens and ties to the outcome
 - [ ] `SKILL.md` body is under 500 lines
 - [ ] Reference files are linked one level deep from `SKILL.md`
@@ -198,6 +225,7 @@ The validator checks every skill under `skills/` for:
 - `name`: lowercase-with-hyphens, ≤ 64 characters, no `anthropic` / `claude` substrings, matches the directory name
 - `description`: non-empty, ≤ 1024 characters
 - `SKILL.md` body: ≤ 500 lines
+- `skill-card.md`: present at the skill root with non-empty `## Description`, `## Owner`, and `## License` sections
 
 It also checks the plugin manifests:
 
diff --git a/README.md b/README.md
@@ -39,12 +39,15 @@ A skill is a self-contained folder that bundles everything an agent needs to per
 skills/
   rocm-doctor/
     SKILL.md
+    skill-card.md
     scripts/
     references/
 ```
 
 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-cards.md](docs/skill-cards.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.
@@ -112,6 +115,7 @@ This repo also acts as an **incubator**: a skill can start under `skills/` to it
 
 ```
 skills/                  # All skills the agent can load
+docs/                    # Long-form documentation (e.g. skill-cards.md)
 .claude-plugin/          # Claude Code marketplace manifest
 .cursor-plugin/          # Cursor marketplace manifest 
 plugin-metadata.json     # Vendor-neutral identity/discovery metadata
@@ -166,3 +170,5 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for step-by-step instructions and the rul
 ## License
 
 Released under the MIT License. See [LICENSE](LICENSE) for details.
+
+Copyright(C) 2026 Advanced Micro Devices, Inc. All rights reserved. 
diff --git a/docs/skill-cards.md b/docs/skill-cards.md
@@ -0,0 +1,55 @@
+# Skill cards
+
+Every skill in this catalog ships a `skill-card.md` next to its `SKILL.md`. The card is a short, human-facing governance record: it tells a reviewer *what* the skill is, *who* owns it, and *under what license* it ships, without making them read the source first.
+
+A `SKILL.md` is written for the agent (routing and instructions). A skill card is written for the people deciding whether to trust, install, or maintain the skill.
+
+## Required sections
+
+The AMD card is intentionally minimal. Three sections are required, each a top-level `##` heading with non-empty body text:
+
+| Section | Question it answers |
+| --- | --- |
+| Description | What does this skill do, in one sentence? |
+| Owner | Who is accountable for maintaining it? |
+| License | What license governs its use and redistribution? |
+
+The validator (`.github/scripts/validate_skills.py`) fails any skill whose card is missing or whose required sections are absent or empty.
+
+## Template
+
+Copy this into `skills/<your-skill>/skill-card.md`:
+
+```markdown
+# Skill Card
+
+## Description
+
+<one sentence: what the skill does, for whom>
+
+## Owner
+
+<team or org accountable for maintenance, e.g. AMD>
+
+## License
+
+<SPDX identifier or link, e.g. MIT>
+```
+
+## Writing a good Description
+
+Keep it to one sentence that states the outcome, matching the marketplace blurb. Avoid restating internal mechanics (that belongs in `SKILL.md`).
+
+```
+Good: Diagnose why ROCm, PyTorch, or llama.cpp isn't working on an AMD GPU
+      and propose the next step.
+Bad:  Runs a series of Python scripts that parse logs and apply regex rules.
+```
+
+## Federated skills
+
+Skills imported from a product repository (see [`.github/scripts/sources.yml`](../.github/scripts/sources.yml)) are vendored wholesale, so a card authored here would be overwritten on the next import. If upstream ships its own `skill-card.md`, it is kept as-is; otherwise the importer synthesizes a minimal card from the source metadata (description, owner repo, and license). To customize a federated skill's card, add a `skill-card.md` to the skill folder in the upstream repository.
+
+## Out of scope (for now)
+
+The card stays at Description, Owner, and License. Evaluation results, benchmark data, risk statements, and signing identifiers are not part of the AMD card today; sections can be added later without breaking the validation gate.
diff --git a/skills/apu-memory-tuner/skill-card.md b/skills/apu-memory-tuner/skill-card.md
@@ -0,0 +1,13 @@
+# Skill Card
+
+## 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.
+
+## Owner
+
+AMD
+
+## License
+
+MIT
diff --git a/skills/local-ai-app-integration/skill-card.md b/skills/local-ai-app-integration/skill-card.md
@@ -0,0 +1,13 @@
+# Skill Card
+
+## Description
+
+Integrate local AI into cloud LLM apps for offline support, better privacy, and lower API costs.
+
+## Owner
+
+AMD
+
+## License
+
+MIT
diff --git a/skills/local-ai-use/skill-card.md b/skills/local-ai-use/skill-card.md
@@ -0,0 +1,13 @@
+# Skill Card
+
+## Description
+
+Route image generation, text-to-speech, and speech-to-text through a local AI Server to reduce token/cost usage.
+
+## Owner
+
+AMD
+
+## License
+
+MIT
diff --git a/skills/magpie/skill-card.md b/skills/magpie/skill-card.md
@@ -0,0 +1,13 @@
+# Skill Card
+
+## Description
+
+Perform GPU kernel correctness and performance evaluation and LLM inference benchmarking with Magpie (HIP/CUDA/PyTorch kernels, vLLM/SGLang benchmarks, TraceLens, and torch-trace gap analysis).
+
+## Owner
+
+AMD-AGI (federated from [AMD-AGI/Magpie](https://github.com/AMD-AGI/Magpie))
+
+## License
+
+MIT
diff --git a/skills/rocm-doctor/skill-card.md b/skills/rocm-doctor/skill-card.md
@@ -0,0 +1,13 @@
+# Skill Card
+
+## Description
+
+Diagnose why ROCm, PyTorch, or llama.cpp isn't working on an AMD GPU by matching the symptom against a fixed list of known misconfigurations and proposing the next step.
+
+## Owner
+
+AMD
+
+## License
+
+MIT
diff --git a/skills/serving-llms-on-instinct/skill-card.md b/skills/serving-llms-on-instinct/skill-card.md
@@ -0,0 +1,13 @@
+# Skill Card
+
+## Description
+
+Serve LLMs on AMD Instinct GPUs (MI300X/MI325X/MI350X/MI355X) with vLLM on ROCm, handling GPU detection, environment validation, vLLM configuration, launch, and health verification.
+
+## Owner
+
+AMD
+
+## License
+
+MIT
