add the CC skill for running builds and tests in a docker container

[tenpercent]

Summary

This PR adds a Claude Code skill that enables automated build and test workflows in Docker containers with proper ROCm GPU support. This allows Claude Code to enter a feedback loop where it can compile code, run tests, examine errors, make fixes, and iterate until tests pass.

Motivation

When developing and testing GPU kernels for Composable Kernel, developers need:

• Consistent build environment with specific ROCm versions
• GPU access for running tests
• Quick iteration cycles for test-driven development
• Isolation to avoid conflicts between different development branches

The ck-docker skill provides a seamless way to build and test inside Docker containers while maintaining the convenience of editing code on the host system

Key Features

1. Automatic Container Management

• Smart naming: Auto-generates container names as ck_<username>_<branch> to prevent conflicts between users and branches
• Exact matching: Uses regex patterns to avoid substring collision (e.g., ck_user_dev won't match ck_user_dev_v2)
• Detached HEAD handling: Gracefully handles detached HEAD state and non-git directories
• Auto-start: Automatically starts containers when needed for build/test/shell commands

2. GPU Target Detection

• Auto-detects GPU architecture using rocminfo (e.g., gfx950, gfx942)
• Supports override via GPU_TARGET environment variable
• Falls back to gfx950 if detection fails

3. Build Management

• Automatic CMake configuration with detected GPU target
• Ninja-based parallel builds
• Uses ROCm LLVM clang++ compiler
• Incremental builds (only reconfigures CMake if needed)
• rebuild-cmake command for clean reconfiguration

4. Test Execution

• Auto-builds test executable if not found
• Supports all gtest command-line options
• Properly handles arguments with spaces and special characters
• Examples:
  • ck-docker test test_amdgcn_mma
  • ck-docker test test_ck_tile_gemm_pipeline_comp_async --gtest_filter=*/0.SmallM

5. Robust Error Handling

• set -e and set -o pipefail for proper error propagation
• Safe path handling with absolute paths in rm -rf operations
• Exit checks after directory changes to prevent dangerous operations
• Proper quoting of all variables to handle special characters

Environment Variables

# Override default container name
export CK_CONTAINER_NAME=my_custom_container

# Override Docker image
export CK_DOCKER_IMAGE=rocm/composable_kernel:ck_ub24.04_rocm7.0.1

# Override GPU target detection
export GPU_TARGET=gfx942

Usage

Command-line

  # Start container
  .claude/skills/ck-docker start

  # Build a test
  .claude/skills/ck-docker build test_amdgcn_mma

  # Run tests
  .claude/skills/ck-docker test test_amdgcn_mma
  .claude/skills/ck-docker test test_ck_tile_gemm_pipeline_comp_async --gtest_filter=*Fp16*

  # Open interactive shell
  .claude/skills/ck-docker shell

  # Check status
  .claude/skills/ck-docker status

  # Stop and remove container
  .claude/skills/ck-docker stop

Natural language with Claude Code

• "Start the docker container"
• "Build test_ck_tile_pk_fp4"
• "Run test_ck_tile_mx_scale"
• "Run the gemm test with Fp16 filter"

Corner Cases Handled

Container Name Generation

• Detached HEAD state: uses "detached" instead of "HEAD"
• Empty branch name after sanitization: defaults to "unknown"
• Missing $USER environment variable: falls back to whoami or "user"
• Branch names with special characters: sanitized to valid Docker names (slashes become underscores)

Container Matching

• Exact name matching to prevent substring collisions
• Pattern ^name$ ensures ck_user_dev doesn't match ck_user_dev_v2
• Applied consistently across all commands (start, build, test, shell, status, stop)

Argument Handling

• Test options stored in arrays to preserve spacing
• Proper shell quoting using printf '%q' for special characters
• All variables quoted in docker commands to handle names with spaces

Path Safety

• Absolute paths in rm -rf operations to prevent accidental deletion
• cd /workspace || exit 1 prevents operations in wrong directory
• Build directory always at /workspace/build
• CMake reconfiguration uses absolute paths throughout

Testing

Validated with multiple test suites on gfx950 (AMD Instinct MI350X):

GEMM Pipeline Tests:

• test_ck_tile_gemm_pipeline_comp_async: 56 tests, all passed (32 seconds)
  • Tested all layout combinations (RRR, RCR, CRR, CCR)
  • FP16 input/output with float accumulator
  • Validated with gtest filters: --gtest_filter=*/0.SmallM

Data Type Tests:

• test_ck_tile_pk_fp4: 6 tests, all passed (158 ms)
  • Packed FP4 numeric limits and conversions
  • Device and host-side conversion validation
• test_ck_tile_mx_scale: 5 tests, all passed (166 ms)
  • OCP scale numeric operations
  • Scaled conversion on device and host

Container Management:

• Multiple concurrent containers (different branches, different users)
• Container name collision prevention verified
• Auto-start functionality for stopped containers
• GPU detection working correctly

Benefits for Claude Code

This skill enables Claude Code to:

1. Automatically build and test code changes
2. Detect compilation errors and iterate on fixes
3. Run specific test filters to verify targeted functionality
4. Work in isolated environments per branch
5. Provide immediate feedback on code changes

This creates a tight feedback loop essential for AI-assisted development of complex GPU kernels.