Contributor Guide

Claude Skills

View as Markdown

AICR ships a set of agent skills under .agents/skills/ (.claude/skills is a symlink to it, so Claude Code discovers the same skills; other agents such as Codex and Cursor read .agents/skills directly). A skill is a self-contained, model-invocable procedure: a SKILL.md with YAML frontmatter (name, description) plus any supporting files (templates, skeletons). When a request matches a skill’s description, Claude Code loads it and follows it directly — so the skills encode the project’s preferred way to do recurring, judgment-heavy tasks instead of re-deriving the steps each time.

These are repo-scoped: they live in the codebase, are versioned with it, and are available to any contributor running Claude Code in this working tree. They complement — they do not replace — the coding rules in CLAUDE.md.

Available Skills

SkillUse it when you want to…
aicr-analyzing-snapshotsAnalyze a snapshot YAML — cluster identity, provider characteristics, GPU/network topology, node health, software stack — and produce a structured assessment report.
aicr-auditing-docsAudit the Markdown docs for duplication, drift, bloat, and gaps, producing a prioritized findings report (research, not edits) across README, docs/, demos, and governance files.
aicr-cross-reviewMulti-agent PR review using Claude Code, Codex, and CodeRabbit with integration impact analysis, 2-of-3 consensus, and adversarial verification. Claude Code only — uses Workflow/Agent tools unavailable in other agents.
aicr-creating-guided-demosScaffold an interactive guided demo script (demos/*.sh) — live or self-paced — using the Frame → Tell → Show → Close narrative pattern.
aicr-creating-slide-decksBuild a self-contained HTML slide deck (demos/*.html) — inline CSS/SVG, no build step — to present or teach a concept full-screen or projected.
aicr-managing-openvexAdd, update, or remove CVE/GHSA suppressions in .openvex.json, the OpenVEX document consumed by the weekly image vulnerability scan.
aicr-release-notesDraft the human-readable GitHub release-notes summary for an upcoming release by grouping commits since the last tag into thematic highlights.
aicr-triageTriage the NVIDIA AICR project board (project 248): classify new issues, promote P2→P1, demote Ready→Backlog, and propose closures — with per-bucket confirmation before applying.
aicr-uat-reportReport UAT health across service x GPU x intent combinations from the UAT Run workflow, classifying failures as product vs infra signal, and download the per-run cluster debug bundles to triage them.

How Skills Are Invoked

Skills are matched against their description frontmatter. There are two paths:

  • Automatic. When a request matches a skill’s triggers, Claude Code loads the skill before responding. The description field is the matcher — it lists the phrases and intents that should activate the skill, so write it for recall.
  • Explicit. A contributor can name a skill directly to force its use. The syntax differs by agent: Claude Code uses /skill-name (for example, /aicr-triage); Codex uses $skill-name (for example, $aicr-triage).

Never read a SKILL.md with a plain file read to “follow it” — invoke it so its supporting files and conventions load as intended.

Adding a Skill

  1. Create .agents/skills/<skill-name>/SKILL.md with name and description frontmatter. The name must match the directory.
  2. Write the description for matching: enumerate the triggers (phrases, file paths, intents) that should activate it. This is the single most important field — a skill that never matches is dead weight.
  3. Keep the body a procedure, not prose: when to use, when not to use, and the concrete steps. Add supporting files (skeletons, templates) alongside SKILL.md and reference them by relative path.
  4. Add a row to the Available Skills table above so contributors can discover it.

Skills are design-time tooling for working on AICR — they are not part of the shipped product and do not affect generated artifacts.