CK Skills

AMD AI agent toolkit for Claude Code — specialized skills for Composable Kernel (CK) development, GPU profiling, and remote development.

What's Inside

Skills

Skill	Command	Description
CK Explorer	/ck-explorer	Query CK architecture — FMHA pipelines, GEMM configs, MFMA specs, tile distributions
CK Debug	/ck-debug	Systematic debugging for CK kernels — compile errors, numerical bugs, crashes
CK Perf	/ck-perf	Performance analysis and optimization — profiling, bottleneck diagnosis, tuning
CK Build	/ck-build	Build CK targets from natural language — auto-detects repo layout, resolves targets
CK Test	/ck-test	Run CK tests from natural language — resolves test targets, maps CLI arguments
CK Develop	/ck-develop	Multi-step CK feature development with design phases
CK Review	/ck-review	CK-aware code review — correctness, performance, architectural compliance
CK Port	/ck-port-to-monorepo	Port CK commits from dev repos to rocm-libraries monorepo
CK Automate	/ck-automate	Internal execution layer for commit-pinned workflows (not invoked directly)

A bootstrap skill (using-agent-tools) is injected at session start via hooks to route tasks to the correct skill automatically.

MCP Servers

Server	Description
remote-dev	Sync code and execute commands on remote machines via SSH or Docker
rocm-profiler	GPU profiling with rocprofv3 — kernel dispatch data, hardware counters, occupancy analysis
mcp-remote-executor	Remote command execution abstraction

Installation

Step 1: Clone the repo

git clone git@github.com:Jeff-Huang/ck-skills.git ~/work/ck-skills

Step 2: Install the Claude Code plugin

This gives you all the /ck-* skills and session hooks.

Option A — via marketplace:

claude plugin marketplace add https://github.com/Jeff-Huang/ck-skills

Option B — symlink from local clone:

# Global install (available in all projects)
ln -s ~/work/ck-skills ~/.claude/plugins/ck-skills

# OR project-level install (only in a specific project)
cd ~/work/aiter
mkdir -p .claude/plugins
ln -s ~/work/ck-skills .claude/plugins/ck-skills

Start a new session and use any /ck-* command.

Step 3: Install the MCP servers

The MCP servers provide remote execution and GPU profiling. Run the setup script:

/path/to/ck-skills/setup-mcp.sh

The script installs both servers (remote-dev and rocm-profiler) with their dependencies, then prints the MCP config to add to your Claude Code settings.

Copy the printed config into .claude/settings.local.json or .mcp.json.

Note: Replace /path/to/ck-skills with the actual path, which depends on how you installed:

Installation method	Path
Local clone	~/work/ck-skills (or wherever you cloned it)
Marketplace (claude plugin marketplace add)	~/.claude/plugins/ck-skills
Project-level symlink	.claude/plugins/ck-skills (resolves to clone location)

Usage

/ck-build and /ck-test — Build and Test CK Targets

These are the primary entry points for build and test tasks. They handle natural language target resolution, environment detection, and CLI argument mapping.

/ck-build fmha                       # Build FMHA kernel
/ck-build fp8 gemm                   # Build FP8 GEMM target
/ck-test batch prefill               # Run batch prefill tests
/ck-test fmha fp8                    # Run FMHA FP8 tests

/ck-explorer — Explore CK Architecture

/ck-explorer explain kpack           # Quick concept definition
/ck-explorer gemm 32x32x16 bf16     # GEMM configuration lookup
/ck-explorer mfma gfx942            # MFMA instruction reference
/ck-explorer fmha <kernel_name>     # Parse FMHA kernel name
/ck-explorer deep online-softmax    # Deep dive into a topic
/ck-explorer trace <kernel>         # Trace kernel to MFMA (dynamic)

Knowledge is organized in three layers:

• Concepts — Quick definitions and terminology
• Reference — Lookup tables and specifications (MFMA, GEMM config)
• Deep Dive — Detailed architectural analysis

/ck-debug — Systematic CK Debugging

/ck-debug <issue description>

Follows a mandatory 5-phase workflow:

1. Root Cause Investigation — Classify error, match patterns, gather diagnostics
2. Pattern Analysis — Find working examples, compare against references
3. Hypothesis & Testing — Form single hypothesis, test minimally
4. Discuss with User — Present findings, get approval before fixing
5. Implementation — Create test, implement single fix, verify

Includes a knowledge base of historical case studies and pattern matching guides.

/ck-perf — Performance Analysis & Optimization

/ck-perf diagnose <kernel>          # Analyze bottlenecks (no code changes)
/ck-perf optimize <kernel>          # Full optimization workflow

diagnose (5 phases): Context gathering, profiling with rocprofv3, bottleneck analysis, visualization (roofline/metrics charts), report.

optimize (8 phases): Extends diagnose with optimization planning, implementation, validation, and final report.

/ck-develop — Feature Development

/ck-develop <feature description>

Orchestrates multi-step CK feature work through 4 phases: reference research, architecture analysis, design synthesis, then handoff to implementation planning.

/ck-review — Code Review

/ck-review                          # Review current changes

CK-specific code review covering correctness, performance, and architectural compliance. Also auto-triggered after coding phases in /ck-debug, /ck-develop, and /ck-perf.

/ck-port-to-monorepo — Port to Monorepo

/ck-port-to-monorepo

Ports CK commits from dev repos (aiter submodule or standalone CK) to the rocm-libraries monorepo using git format-patch + git am with path remapping.

MCP Server Tools

remote-dev

Tool	Description
run	Execute command on remote with auto-sync
sync	Explicitly sync code to remote
read_remote / write_remote	Read/write files on the remote
download / upload	Transfer files between local and remote
sessions / add_session / remove_session	Manage remote sessions
list_containers	List Docker containers on a session's host
ck_port_gather / ck_port_apply	CK monorepo port operations

rocm-profiler

Tool	Description
profile	Profile a GPU command with rocprofv3 — kernel dispatch data, occupancy analysis
profile_counters	Collect PMC hardware performance counters — LDS conflicts, L2 hit rate, MFMA/VALU ratio

Skill Architecture

The skills are organized in four layers. Higher layers delegate to lower layers; users invoke the top two layers directly.

┌─────────────────────────────────────────────────────────────────────┐
│                        SESSION START                                │
│                     using-agent-tools                               │
│              (bootstrap router — auto-injected)                     │
│         Routes user intent to the correct skill below               │
└──────────────────────────┬──────────────────────────────────────────┘
                           │ routes to
       ┌───────────────────┼───────────────────────┐
       ▼                   ▼                       ▼
┌─────────────┐  ┌─────────────────┐  ┌──────────────────────────────┐
│ ENTRY POINTS│  │   WORKFLOWS     │  │  CROSS-REPO                  │
│ (Layer 1)   │  │   (Layer 2)     │  │  (Layer 3)                   │
│             │  │                 │  │                              │
│ /ck-build ──┼─>│ /ck-debug ──────┼─>│ /ck-port-to-monorepo         │
│    on fail  │  │   5-phase       │  │   gather → approve → apply   │
│             │  │   correctness   │  │                              │
│ /ck-test ───┼─>│                 │  │   Uses: ck_port_gather,      │
│    on fail  │  │ /ck-perf ·······│··│·· ck_port_apply MCP tools    │
│    on slow ─┼─>│   diagnose (5φ) │  │                              │
│             │  │   optimize (8φ) │  └──────────────────────────────┘
│ /ck-develop─┼─>│                 │
│   4 design  │  │ /ck-review <────┤ auto-triggered after coding
│   phases    │  │   advisory gate │ in debug, develop, perf
└─────────────┘  └─────────────────┘
       │                   │
       │    ┌──────────────┘
       ▼    ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    INTERNAL LAYERS (not invoked directly)            │
│                                                                     │
│  /ck-automate ─── Execution Abstraction (Layer 4)                   │
│  ┌────────────────────────────────────────────────────────────┐     │
│  │ primitives/         │ workflows/          │ knowledge/     │     │
│  │  environment.md     │  benchmark.md       │  target-       │     │
│  │  git-ops.md         │  reproduce-bug.md   │  registry.md   │     │
│  │  build-aiter.md     │  regression.md      │  repo-layout   │     │
│  │  build-ck.md        │                     │  profiles/     │     │
│  │  run-test.md        │                     │                │     │
│  └────────────────────────────────────────────────────────────┘     │
│                             │                                       │
│  /ck-explorer ─── Knowledge Base (Foundation)                       │
│  ┌────────────────────────────────────────────────────────────┐     │
│  │ concepts/           │ reference/          │ deep-dive/     │     │
│  │  memory, execution  │  mfma-gfx942/950   │  pipelines     │     │
│  │  gemm-hierarchy     │  gemm-config       │  fp8, softmax  │     │
│  │  tile-ops, fmha     │  kernel-naming     │  paged-kv      │     │
│  │  aiter-overview     │  pipeline-select   │  lds, api      │     │
│  └────────────────────────────────────────────────────────────┘     │
│                                                                     │
├─────────────────────────────────────────────────────────────────────┤
│  MCP SERVERS (execution infrastructure)                             │
│                                                                     │
│  remote-dev ········· run, sync, read/write, upload/download        │
│  rocm-profiler ······ profile, profile_counters                     │
│  mcp-remote-executor · remote command execution                     │
└─────────────────────────────────────────────────────────────────────┘

Data flow examples

Build + test a kernel:

User: "build and test fmha"
  → using-agent-tools routes to /ck-build
    → ck-automate: detect repo, resolve target from registry
      → remote-dev MCP: run build command
  → then /ck-test
    → ck-automate: resolve test target
      → remote-dev MCP: run test command
    → on failure: suggest /ck-debug

Debug a crash:

User: "my kernel crashes with NaN"
  → using-agent-tools routes to /ck-debug
    → ck-automate: confirm commit version, detect environment
    → ck-explorer: look up kernel family patterns
    → remote-dev MCP: reproduce crash
    → 5 phases: investigate → analyze → hypothesize → discuss → fix
    → ck-review: auto-triggered after fix (advisory)

Profile and optimize:

User: "fmha is too slow"
  → using-agent-tools routes to /ck-perf
    → ck-automate: confirm commit, check GPU availability
    → rocm-profiler MCP: profile kernel, collect hardware counters
    → ck-explorer: look up architecture specs for analysis
    → 8 phases: context → profile → analyze → visualize → plan → implement → validate → report
    → ck-review: auto-triggered after optimization (advisory)

Repository Structure

ck-skills/
├── .claude-plugin/           # Claude Code plugin manifest
│   └── plugin.json
├── hooks/                    # Session startup hooks
│   ├── hooks.json
│   └── session-start.sh      # Injects using-agent-tools on session start
├── skills/                   # Self-contained skills
│   ├── using-agent-tools/    # Bootstrap skill (master router)
│   ├── ck-explorer/          # CK architecture explorer + knowledge/
│   ├── ck-debug/             # CK debugging + knowledge/
│   ├── ck-perf/              # CK perf + knowledge/ + scripts/
│   ├── ck-build/             # Build target resolution
│   ├── ck-test/              # Test target resolution
│   ├── ck-develop/           # Feature development + references/
│   ├── ck-review/            # Code review + knowledge/
│   ├── ck-port-to-monorepo/  # Monorepo porting + knowledge/
│   └── ck-automate/          # Execution layer + primitives/ + workflows/
├── mcp-servers/              # MCP servers (separate install)
│   ├── remote-dev/           # Remote development server
│   ├── rocm-profiler/        # GPU profiling with rocprofv3
│   └── mcp-remote-executor/  # Remote command execution
├── tests/claude-code/        # Skill tests
└── README.md

Each skill under skills/ is self-contained — all knowledge files, scripts, and references are inside the skill directory.

Development

Adding a New Skill

1. Create skills/<skill-name>/SKILL.md with YAML frontmatter:

   ---
   name: skill-name
   description: Use when [triggering condition]
   ---

2. Add knowledge files under skills/<skill-name>/knowledge/
3. Update skills/using-agent-tools/SKILL.md to list the new skill
4. Bump version in .claude-plugin/plugin.json

Running Skill Tests

cd tests/claude-code
./run-skill-tests.sh

Running MCP Server Tests

cd mcp-servers/remote-dev
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
python -m pytest tests/ -v

License

MIT