Use uv run as default execution path for automatic dependency management

- Automatically detect and use uv if available in container
- Fall back to python3 if uv not found (backward compatible)
- Leverage PEP 723 metadata for zero-config dependency installation
- Update documentation with uv installation instructions

Benefits:
- Zero manual dependency installation with uv
- Isolated dependency environment (no system pollution)
- Fast dependency caching for subsequent runs
- Automatic dependency resolution from PEP 723 metadata

Tested with:
- uv 0.9.25: Auto-installs jinja2 from PEP 723 metadata
- python3: Falls back when uv unavailable (requires python3-jinja2)

Installation:
  docker exec <container> bash -c "curl -LsSf https://astral.sh/uv/install.sh | sh"

Co-Authored-By: Claude <noreply@anthropic.com>

.claude/skills/ck-build-analysis

@@ -179,14 +179,28 @@ echo "Generating analysis report..."
 docker cp "${SCRIPT_DIR}/analyze_build_trace.py" "${CONTAINER_NAME}:/tmp/analyze_build_trace.py"
 docker cp "${SCRIPT_DIR}/templates" "${CONTAINER_NAME}:/tmp/ck_build_analysis_templates"
 
-# Run analysis
-docker exec "${CONTAINER_NAME}" python3 /tmp/analyze_build_trace.py \
-    "${TRACE_FILE}" \
-    "/workspace/${OUTPUT_FILE}" \
-    "${TARGET}" \
-    "${GRANULARITY}" \
-    "${BUILD_TIME}" \
-    "/tmp/ck_build_analysis_templates"
+# Check if uv is available and use it for PEP 723 dependency management
+# Check both PATH and common install locations
+if docker exec "${CONTAINER_NAME}" bash -c "command -v uv >/dev/null 2>&1 || test -x \$HOME/.local/bin/uv"; then
+    echo "Using uv run for automatic dependency management..."
+    # Ensure uv is in PATH (handles ~/.local/bin installation)
+    docker exec "${CONTAINER_NAME}" bash -c "export PATH=\"\$HOME/.local/bin:\$PATH\" && uv run --no-project /tmp/analyze_build_trace.py \
+        ${TRACE_FILE} \
+        /workspace/${OUTPUT_FILE} \
+        ${TARGET} \
+        ${GRANULARITY} \
+        ${BUILD_TIME} \
+        /tmp/ck_build_analysis_templates"
+else
+    echo "uv not found, using python3 (requires python3-jinja2 pre-installed)..."
+    docker exec "${CONTAINER_NAME}" python3 /tmp/analyze_build_trace.py \
+        "${TRACE_FILE}" \
+        "/workspace/${OUTPUT_FILE}" \
+        "${TARGET}" \
+        "${GRANULARITY}" \
+        "${BUILD_TIME}" \
+        "/tmp/ck_build_analysis_templates"
+fi
 
 # Copy report back to host
 docker cp "${CONTAINER_NAME}:/workspace/${OUTPUT_FILE}" "${PROJECT_ROOT}/${OUTPUT_FILE}"

.claude/skills/ck-build-analysis.md

@@ -113,7 +113,7 @@ The report includes:
 
 ## Implementation Details
 
-### PEP 723 Compliance
+### PEP 723 Compliance with Automatic Dependency Management
 
 The analysis script (`analyze_build_trace.py`) is PEP 723 compliant with inline dependency metadata:
 
@@ -126,26 +126,47 @@ The analysis script (`analyze_build_trace.py`) is PEP 723 compliant with inline
 # ///
 ```
 
-This allows tools like `pipx run` or `uv run` to automatically manage dependencies:
+**The skill automatically uses `uv run` if available**, which provides:
+- ✅ Zero-configuration dependency management
+- ✅ Automatic installation of jinja2 from PEP 723 metadata
+- ✅ Isolated dependency environment (no system pollution)
+- ✅ Fast caching for subsequent runs
 
+### Installation Options
+
+**Option 1: Install uv (Recommended)**
 ```bash
-# Run standalone with pipx (auto-installs dependencies)
-pipx run .claude/skills/analyze_build_trace.py trace.json report.md target 100 22 templates/
-
-# Or with uv
-uv run .claude/skills/analyze_build_trace.py trace.json report.md target 100 22 templates/
+# Install uv in the Docker container (one-time setup)
+docker exec ck_<container_name> bash -c "curl -LsSf https://astral.sh/uv/install.sh | sh"
 ```
 
+After installing `uv`, the skill will automatically use it for dependency management.
+
+**Option 2: Use system python3 + jinja2**
+```bash
+# If uv is not available, install jinja2 manually
+docker exec ck_<container_name> apt-get install -y python3-jinja2
+```
+
+The skill automatically detects which method is available and uses the appropriate one.
+
 ### Components
 
 - **ck-build-analysis** - Main bash script that orchestrates Docker, CMake, and analysis
 - **analyze_build_trace.py** - PEP 723 compliant Python script for trace analysis
 - **templates/build_analysis_report.md.jinja** - Jinja2 template for report generation
 
-### Requirements
+### Standalone Usage
 
-In Docker container:
-- `python3-jinja2` (installed via `apt-get install python3-jinja2`)
+The Python script can also be run independently:
 
-For standalone use:
-- Python 3.8+ with `jinja2>=3.0.0` (auto-managed if using `pipx` or `uv`)
+```bash
+# With uv (recommended - auto-installs dependencies)
+uv run .claude/skills/analyze_build_trace.py trace.json report.md target 100 22 templates/
+
+# With pipx (alternative - auto-installs dependencies)
+pipx run .claude/skills/analyze_build_trace.py trace.json report.md target 100 22 templates/
+
+# With python3 (requires jinja2 pre-installed)
+python3 .claude/skills/analyze_build_trace.py trace.json report.md target 100 22 templates/
+```