feat(ccw-litellm): enhance status checks and add file preview functionality

ccw/frontend/src/components/api-settings/CcwLitellmStatus.tsx

@@ -13,6 +13,7 @@ import {
   XCircle,
   Loader2,
   Package,
+  AlertTriangle,
 } from 'lucide-react';
 import { Button } from '@/components/ui/Button';
 import { Card, CardContent } from '@/components/ui/Card';
@@ -71,6 +72,8 @@ export function CcwLitellmStatus() {
 
   const installed = status?.installed ?? false;
   const version = status?.version;
+  const systemPythonInstalled = status?.checks?.systemPython?.installed === true;
+  const showSystemPythonMismatch = !isLoading && !installed && systemPythonInstalled;
 
   return (
     <>
@@ -86,6 +89,12 @@ export function CcwLitellmStatus() {
               <p className="text-xs text-muted-foreground">
                 {formatMessage({ id: 'apiSettings.ccwLitellm.description' })}
               </p>
+              {showSystemPythonMismatch && (
+                <div className="mt-1 flex items-start gap-2 text-xs text-warning-foreground/80">
+                  <AlertTriangle className="w-4 h-4 text-warning flex-shrink-0 mt-0.5" />
+                  <p>{formatMessage({ id: 'apiSettings.ccwLitellm.systemPythonMismatch' })}</p>
+                </div>
+              )}
             </div>
           </div>
 

ccw/frontend/src/components/shared/SkillDetailPanel.tsx

@@ -3,7 +3,7 @@
 // ========================================
 // Right-side slide-out panel for viewing skill details
 
-import { useEffect } from 'react';
+import { useEffect, useState, useMemo, useCallback } from 'react';
 import { useIntl } from 'react-intl';
 import {
   X,
@@ -15,12 +15,21 @@ import {
   Tag,
   MapPin,
   Code,
+  ChevronRight,
+  ChevronDown,
+  Eye,
+  Loader2,
+  Maximize2,
 } from 'lucide-react';
 import { cn } from '@/lib/utils';
 import { Button } from '@/components/ui/Button';
 import { Badge } from '@/components/ui/Badge';
 import { Card } from '@/components/ui/Card';
 import type { Skill } from '@/lib/api';
+import { buildSkillFileTree, getDefaultExpandedPaths } from '@/utils/skill-files';
+import type { FileSystemNode } from '@/types/file-explorer';
+import { readSkillFile } from '@/lib/api';
+import { useWorkflowStore, selectProjectPath } from '@/stores/workflowStore';
 
 export interface SkillDetailPanelProps {
   skill: Skill | null;
@@ -42,6 +51,15 @@ export function SkillDetailPanel({
   isLoading = false,
 }: SkillDetailPanelProps) {
   const { formatMessage } = useIntl();
+  const projectPath = useWorkflowStore(selectProjectPath);
+  const [cliMode] = useState<'claude' | 'codex'>('claude');
+
+  // Tree view state
+  const [expandedPaths, setExpandedPaths] = useState<Set<string>>(new Set());
+  const [selectedFile, setSelectedFile] = useState<string | null>(null);
+  const [previewContent, setPreviewContent] = useState<string | null>(null);
+  const [isPreviewLoading, setIsPreviewLoading] = useState(false);
+  const [showPreviewPanel, setShowPreviewPanel] = useState(false);
 
   // Prevent body scroll when panel is open
   useEffect(() => {
@@ -55,6 +73,56 @@ export function SkillDetailPanel({
     };
   }, [isOpen]);
 
+  // Build file tree from supportingFiles
+  const fileTree = useMemo(() => {
+    if (!skill?.supportingFiles) return [];
+    return buildSkillFileTree(skill.supportingFiles);
+  }, [skill?.supportingFiles]);
+
+  // Initialize expanded paths when skill changes
+  useEffect(() => {
+    if (fileTree.length > 0) {
+      setExpandedPaths(getDefaultExpandedPaths(fileTree));
+    }
+  }, [fileTree]);
+
+  // Load file content for preview
+  const loadFilePreview = useCallback(async (filePath: string) => {
+    if (!skill) return;
+
+    setIsPreviewLoading(true);
+    setShowPreviewPanel(true);
+    setSelectedFile(filePath);
+    setPreviewContent(null);
+
+    try {
+      const data = await readSkillFile({
+        skillName: skill.folderName || skill.name,
+        fileName: filePath,
+        location: skill.location || 'project',
+        projectPath: projectPath,
+        cliType: cliMode,
+      });
+      setPreviewContent(data.content);
+    } catch (error) {
+      console.error('Failed to load file preview:', error);
+      setPreviewContent(`Error loading preview: ${error instanceof Error ? error.message : String(error)}`);
+    } finally {
+      setIsPreviewLoading(false);
+    }
+  }, [skill, projectPath, cliMode]);
+
+  const handleClosePreview = () => {
+    setShowPreviewPanel(false);
+  };
+
+  // Close preview on panel close
+  useEffect(() => {
+    if (!isOpen) {
+      handleClosePreview();
+    }
+  }, [isOpen]);
+
   if (!isOpen || !skill) {
     return null;
   }
@@ -67,6 +135,19 @@ export function SkillDetailPanel({
     onEditFile?.(folderName, fileName, skill.location || 'project');
   };
 
+  // Toggle directory expanded state
+  const togglePath = (path: string) => {
+    setExpandedPaths(prev => {
+      const next = new Set(prev);
+      if (next.has(path)) {
+        next.delete(path);
+      } else {
+        next.add(path);
+      }
+      return next;
+    });
+  };
+
   return (
     <>
       {/* Overlay */}
@@ -206,58 +287,67 @@ export function SkillDetailPanel({
                   <Folder className="w-4 h-4 text-muted-foreground" />
                   {formatMessage({ id: 'skills.files' })}
                 </h4>
-                <div className="space-y-2">
+                <div className="space-y-3">
                   {/* SKILL.md (main file) */}
                   <div className="flex items-center justify-between p-3 bg-primary/5 border border-primary/20 rounded-lg hover:bg-primary/10 transition-colors">
                     <div className="flex items-center gap-2">
                       <FileText className="w-4 h-4 text-primary" />
                       <span className="text-sm font-mono text-foreground font-medium">SKILL.md</span>
                     </div>
-                    {onEditFile && (
+                    <div className="flex items-center gap-1">
                       <Button
                         variant="ghost"
                         size="sm"
                         className="h-7 px-2 text-primary hover:bg-primary/20"
-                        onClick={() => handleEditFile('SKILL.md')}
+                        onClick={() => loadFilePreview('SKILL.md')}
                       >
-                        <Edit className="w-3.5 h-3.5" />
+                        <Eye className="w-3.5 h-3.5" />
                       </Button>
-                    )}
+                      {onEditFile && (
+                        <Button
+                          variant="ghost"
+                          size="sm"
+                          className="h-7 px-2 text-primary hover:bg-primary/20"
+                          onClick={() => handleEditFile('SKILL.md')}
+                        >
+                          <Edit className="w-3.5 h-3.5" />
+                        </Button>
+                      )}
+                    </div>
                   </div>
 
-                  {/* Supporting Files */}
+                  {/* Supporting Files Tree */}
-                  {hasSupportingFiles && skill.supportingFiles!.map((file) => {
+                  {hasSupportingFiles && fileTree.length > 0 && (
-                    const isDir = file.endsWith('/');
+                    <div className="border border-border rounded-lg p-2 bg-muted/30">
-                    const displayName = isDir ? file.slice(0, -1) : file;
+                      <SkillFileTree
-                    return (
+                        nodes={fileTree}
-                      <div
+                        expandedPaths={expandedPaths}
-                        key={file}
+                        onTogglePath={togglePath}
-                        className="flex items-center justify-between p-3 bg-muted/50 rounded-lg hover:bg-muted transition-colors"
+                        onEditFile={handleEditFile}
-                      >
+                        onPreviewFile={loadFilePreview}
-                        <div className="flex items-center gap-2">
+                        depth={0}
-                          {isDir ? (
+                      />
-                            <Folder className="w-4 h-4 text-muted-foreground" />
+                    </div>
-                          ) : (
+                  )}
-                            <FileText className="w-4 h-4 text-muted-foreground" />
+
-                          )}
+                  {/* Empty state */}
-                          <span className="text-sm font-mono text-foreground">{displayName}</span>
+                  {hasSupportingFiles && fileTree.length === 0 && (
-                        </div>
+                    <div className="text-sm text-muted-foreground p-3">
-                        {!isDir && onEditFile && (
+                      {formatMessage({ id: 'skills.files.empty' })}
-                          <Button
+                    </div>
-                            variant="ghost"
+                  )}
-                            size="sm"
-                            className="h-7 px-2"
-                            onClick={() => handleEditFile(file)}
-                          >
-                            <Edit className="w-3.5 h-3.5" />
-                          </Button>
-                        )}
-                      </div>
-                    );
-                  })}
                 </div>
               </section>
 
+              {/* File Preview Modal */}
+              <FilePreviewModal
+                fileName={selectedFile}
+                content={previewContent}
+                isLoading={isPreviewLoading}
+                isOpen={showPreviewPanel}
+                onClose={handleClosePreview}
+              />
+
               {/* Path */}
               {skill.path && (
                 <section>
@@ -309,4 +399,243 @@ export function SkillDetailPanel({
   );
 }
 
+// ========================================
+// SkillFileTree Component
+// ========================================
+// Recursive tree view for skill files
+
+interface SkillFileTreeNodeProps {
+  node: FileSystemNode;
+  depth: number;
+  expandedPaths: Set<string>;
+  onTogglePath: (path: string) => void;
+  onEditFile: (fileName: string) => void;
+  onPreviewFile: (fileName: string) => void;
+}
+
+function SkillFileTreeNode({
+  node,
+  depth,
+  expandedPaths,
+  onTogglePath,
+  onEditFile,
+  onPreviewFile,
+}: SkillFileTreeNodeProps) {
+  const isDirectory = node.type === 'directory';
+  const isExpanded = expandedPaths.has(node.path);
+  const hasChildren = node.children && node.children.length > 0;
+
+  const handleClick = (e: React.MouseEvent) => {
+    e.stopPropagation();
+    if (isDirectory) {
+      onTogglePath(node.path);
+    } else {
+      // Preview file on click
+      onPreviewFile(node.path);
+    }
+  };
+
+  return (
+    <div className="select-none group">
+      <div
+        className={cn(
+          'flex items-center gap-2 px-2 py-1.5 rounded-sm hover:bg-muted transition-colors cursor-pointer',
+          isDirectory && 'font-medium'
+        )}
+        style={{ paddingLeft: `${depth * 16 + 8}px` }}
+        onClick={handleClick}
+      >
+        {/* Chevron for directories */}
+        {isDirectory && (
+          <span className="w-4 h-4 flex items-center justify-center text-muted-foreground">
+            {hasChildren && (
+              isExpanded ? (
+                <ChevronDown className="w-3.5 h-3.5" />
+              ) : (
+                <ChevronRight className="w-3.5 h-3.5" />
+              )
+            )}
+          </span>
+        )}
+
+        {/* Icon */}
+        {isDirectory ? (
+          <Folder className={cn(
+            'w-4 h-4 flex-shrink-0',
+            isExpanded ? 'text-blue-500' : 'text-blue-400'
+          )} />
+        ) : (
+          <FileText className="w-4 h-4 flex-shrink-0 text-muted-foreground" />
+        )}
+
+        {/* Name */}
+        <span className="text-sm font-mono flex-1 truncate">{node.name}</span>
+
+        {/* Preview button for files */}
+        {!isDirectory && (
+          <div className="flex items-center gap-1 opacity-0 group-hover:opacity-100 transition-opacity">
+            <Button
+              variant="ghost"
+              size="sm"
+              className="h-6 w-6 p-0 hover:bg-primary/20 hover:text-primary"
+              onClick={(e) => {
+                e.stopPropagation();
+                onPreviewFile(node.path);
+              }}
+              title="Preview file"
+            >
+              <Eye className="w-3.5 h-3.5" />
+            </Button>
+            <Button
+              variant="ghost"
+              size="sm"
+              className="h-6 w-6 p-0 hover:bg-primary/20 hover:text-primary"
+              onClick={(e) => {
+                e.stopPropagation();
+                onEditFile(node.path);
+              }}
+              title="Edit file"
+            >
+              <Edit className="w-3.5 h-3.5" />
+            </Button>
+          </div>
+        )}
+      </div>
+
+      {/* Children */}
+      {isDirectory && isExpanded && hasChildren && (
+        <div className="border-l border-border ml-4">
+          {node.children!.map((child) => (
+            <SkillFileTreeNode
+              key={child.path}
+              node={child}
+              depth={depth + 1}
+              expandedPaths={expandedPaths}
+              onTogglePath={onTogglePath}
+              onEditFile={onEditFile}
+              onPreviewFile={onPreviewFile}
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+interface SkillFileTreeProps {
+  nodes: FileSystemNode[];
+  expandedPaths: Set<string>;
+  onTogglePath: (path: string) => void;
+  onEditFile: (fileName: string) => void;
+  onPreviewFile: (fileName: string) => void;
+  depth: number;
+}
+
+function SkillFileTree({
+  nodes,
+  expandedPaths,
+  onTogglePath,
+  onEditFile,
+  onPreviewFile,
+  depth,
+}: SkillFileTreeProps) {
+  return (
+    <div className="space-y-0.5" role="tree">
+      {nodes.map((node) => (
+        <SkillFileTreeNode
+          key={node.path}
+          node={node}
+          depth={depth}
+          expandedPaths={expandedPaths}
+          onTogglePath={onTogglePath}
+          onEditFile={onEditFile}
+          onPreviewFile={onPreviewFile}
+        />
+      ))}
+    </div>
+  );
+}
+
+// ========================================
+// File Preview Modal Component
+// ========================================
+
+interface FilePreviewModalProps {
+  fileName: string | null;
+  content: string | null;
+  isLoading: boolean;
+  isOpen: boolean;
+  onClose: () => void;
+}
+
+function FilePreviewModal({ fileName, content, isLoading, isOpen, onClose }: FilePreviewModalProps) {
+  const { formatMessage } = useIntl();
+
+  if (!isOpen) return null;
+
+  return (
+    <>
+      {/* Overlay */}
+      <div
+        className="fixed inset-0 bg-black/50 z-50 transition-opacity"
+        onClick={onClose}
+      />
+
+      {/* Modal */}
+      <div className="fixed inset-0 z-50 flex items-center justify-center p-4">
+        <div className="bg-background rounded-lg shadow-2xl w-full max-w-3xl max-h-[80vh] flex flex-col animate-in fade-in zoom-in duration-200">
+          {/* Header */}
+          <div className="flex items-center justify-between px-4 py-3 border-b border-border">
+            <div className="flex items-center gap-2">
+              <FileText className="w-4 h-4 text-primary" />
+              <span className="text-sm font-mono font-medium">{fileName}</span>
+            </div>
+            <div className="flex items-center gap-2">
+              <Button
+                variant="ghost"
+                size="sm"
+                onClick={() => {
+                  // Full screen toggle could be implemented here
+                }}
+                className="h-8 w-8 p-0"
+              >
+                <Maximize2 className="w-4 h-4" />
+              </Button>
+              <Button variant="ghost" size="sm" onClick={onClose} className="h-8 w-8 p-0">
+                <X className="w-4 h-4" />
+              </Button>
+            </div>
+          </div>
+
+          {/* Content */}
+          <div className="flex-1 overflow-auto p-4 min-h-[300px]">
+            {isLoading ? (
+              <div className="flex items-center justify-center h-full">
+                <Loader2 className="w-8 h-8 animate-spin text-muted-foreground" />
+              </div>
+            ) : content ? (
+              <Card className="p-4 bg-muted/30">
+                <pre className="text-xs font-mono whitespace-pre-wrap break-words text-foreground">
+                  {content}
+                </pre>
+              </Card>
+            ) : (
+              <div className="text-sm text-muted-foreground py-8 text-center">
+                {formatMessage({ id: 'skills.files.preview.empty' })}
+              </div>
+            )}
+          </div>
+
+          {/* Footer */}
+          <div className="px-4 py-3 border-t border-border flex justify-end">
+            <Button onClick={onClose}>
+              {formatMessage({ id: 'common.actions.close' })}
+            </Button>
+          </div>
+        </div>
+      </div>
+    </>
+  );
+}
+
 export default SkillDetailPanel;

ccw/frontend/src/lib/api.ts

@@ -5968,10 +5968,31 @@ export async function previewYamlConfig(): Promise<{ success: boolean; config: s
 
 // ========== CCW-LiteLLM Package Management ==========
 
+export interface CcwLitellmEnvCheck {
+  python: string;
+  installed: boolean;
+  version?: string;
+  error?: string;
+}
+
+export interface CcwLitellmStatus {
+  /**
+   * Whether ccw-litellm is installed in the CodexLens venv.
+   * This is the environment used for the LiteLLM embedding backend.
+   */
+  installed: boolean;
+  version?: string;
+  error?: string;
+  checks?: {
+    codexLensVenv: CcwLitellmEnvCheck;
+    systemPython?: CcwLitellmEnvCheck;
+  };
+}
+
 /**
  * Check ccw-litellm status
  */
-export async function checkCcwLitellmStatus(refresh = false): Promise<{ installed: boolean; version?: string; error?: string }> {
+export async function checkCcwLitellmStatus(refresh = false): Promise<CcwLitellmStatus> {
   return fetchApi(`/api/litellm-api/ccw-litellm/status${refresh ? '?refresh=true' : ''}`);
 }
 

ccw/frontend/src/locales/en/api-settings.json

@@ -322,6 +322,7 @@
   "ccwLitellm": {
     "title": "CCW-LiteLLM Package",
     "description": "Manage ccw-litellm Python package installation",
+    "systemPythonMismatch": "Detected ccw-litellm installed in system Python, but not in the CodexLens venv (~/.codexlens/venv). Click Install to install it into the venv.",
     "status": {
       "installed": "Installed",
       "notInstalled": "Not Installed",

ccw/frontend/src/locales/zh/api-settings.json

@@ -322,6 +322,7 @@
   "ccwLitellm": {
     "title": "CCW-LiteLLM 包",
     "description": "管理 ccw-litellm Python 包安装",
+    "systemPythonMismatch": "检测到 ccw-litellm 已安装在系统 Python 中，但未安装到 CodexLens 虚拟环境（~/.codexlens/venv）里，所以这里显示未安装。点击“安装”即可安装到虚拟环境中。",
     "status": {
       "installed": "已安装",
       "notInstalled": "未安装",

ccw/frontend/src/utils/skill-files.ts

@@ -0,0 +1,160 @@
+// ========================================
+// Skill File Tree Utilities
+// ========================================
+// Convert flat supportingFiles array to tree structure
+
+import type { FileSystemNode } from '@/types/file-explorer';
+
+/**
+ * Build a file tree from a flat array of file paths
+ *
+ * @param supportingFiles - Array of file paths (e.g., ['components/', 'components/Button.tsx'])
+ * @returns Tree structure of files and directories
+ */
+export function buildSkillFileTree(supportingFiles: string[]): FileSystemNode[] {
+  // Map to store all nodes by their path
+  const nodeMap = new Map<string, FileSystemNode>();
+
+  for (const entry of supportingFiles) {
+    const isDirectoryMarker = entry.endsWith('/');
+    const cleanPath = isDirectoryMarker ? entry.slice(0, -1) : entry;
+    const parts = cleanPath.split('/');
+
+    if (!cleanPath || parts.length === 0) continue;
+
+    // Build the path hierarchy for this entry
+    let currentPath = '';
+
+    // Process all parts except the last one (these are intermediate directories)
+    for (let i = 0; i < parts.length - 1; i++) {
+      const part = parts[i];
+      const parentPath = currentPath;
+      currentPath = currentPath ? `${currentPath}/${part}` : part;
+
+      // Create directory node if it doesn't exist
+      if (!nodeMap.has(currentPath)) {
+        nodeMap.set(currentPath, {
+          name: part,
+          path: currentPath,
+          type: 'directory',
+          children: [],
+        });
+      }
+
+      // Add to parent's children
+      if (parentPath) {
+        const parent = nodeMap.get(parentPath);
+        if (parent && parent.type === 'directory') {
+          const existingChild = parent.children!.find(c => c.path === currentPath);
+          if (!existingChild) {
+            parent.children!.push(nodeMap.get(currentPath)!);
+          }
+        }
+      }
+    }
+
+    // Process the final part (file or empty directory marker)
+    const finalName = parts[parts.length - 1];
+    const finalPath = cleanPath;
+
+    // Create or update the final node
+    const existingNode = nodeMap.get(finalPath);
+    const finalNode: FileSystemNode = existingNode
+      ? { ...existingNode, name: finalName }  // Keep children if already exists
+      : {
+          name: finalName,
+          path: finalPath,
+          type: isDirectoryMarker ? 'directory' : 'file',
+          children: isDirectoryMarker ? [] : undefined,
+        };
+
+    nodeMap.set(finalPath, finalNode);
+
+    // Add final node to parent's children
+    const parentPath = parts.length > 1 ? parts.slice(0, -1).join('/') : '';
+    if (parentPath) {
+      const parent = nodeMap.get(parentPath);
+      if (parent && parent.type === 'directory') {
+        const existingChild = parent.children!.find(c => c.path === finalPath);
+        if (!existingChild) {
+          parent.children!.push(finalNode);
+        } else {
+          // Update existing child if this is a file (not just a directory marker)
+          if (!isDirectoryMarker) {
+            existingChild.type = 'file';
+            existingChild.children = undefined;
+          }
+        }
+      }
+    }
+  }
+
+  // Collect root-level nodes (nodes with single-segment paths)
+  const result: FileSystemNode[] = [];
+  for (const [path, node] of nodeMap.entries()) {
+    if (!path.includes('/')) {
+      result.push(node);
+    }
+  }
+
+  // Sort: directories first, then files, alphabetically
+  result.sort((a, b) => {
+    if (a.type === 'directory' && b.type === 'file') return -1;
+    if (a.type === 'file' && b.type === 'directory') return 1;
+    return a.name.localeCompare(b.name);
+  });
+
+  // Sort children recursively
+  const sortChildren = (node: FileSystemNode) => {
+    if (node.type === 'directory' && node.children) {
+      node.children.sort((a, b) => {
+        if (a.type === 'directory' && b.type === 'file') return -1;
+        if (a.type === 'file' && b.type === 'directory') return 1;
+        return a.name.localeCompare(b.name);
+      });
+      node.children.forEach(sortChildren);
+    }
+  };
+
+  result.forEach(sortChildren);
+
+  return result;
+}
+
+/**
+ * Get default expanded paths for a file tree
+ * Expands all directories by default for skill details
+ *
+ * @param nodes - File tree nodes
+ * @returns Set of all directory paths
+ */
+export function getDefaultExpandedPaths(nodes: FileSystemNode[]): Set<string> {
+  const expanded = new Set<string>();
+
+  const collectDirectories = (node: FileSystemNode) => {
+    if (node.type === 'directory') {
+      expanded.add(node.path);
+      node.children?.forEach(collectDirectories);
+    }
+  };
+
+  nodes.forEach(collectDirectories);
+
+  return expanded;
+}
+
+/**
+ * Format file path for display
+ */
+export function formatFilePath(path: string): string {
+  const parts = path.split('/');
+  return parts[parts.length - 1];
+}
+
+/**
+ * Get file extension
+ */
+export function getFileExtension(path: string): string {
+  const parts = path.split('.');
+  return parts.length > 1 ? parts.pop()! : '';
+}

ccw/src/core/routes/litellm-api-routes.ts

@@ -80,9 +80,89 @@ import { getContextCacheStore } from '../../tools/context-cache-store.js';
 import { getLiteLLMClient } from '../../tools/litellm-client.js';
 import { testApiKeyConnection, getDefaultApiBase } from '../services/api-key-tester.js';
 
+interface CcwLitellmEnvCheck {
+  python: string;
+  installed: boolean;
+  version?: string;
+  error?: string;
+}
+
+interface CcwLitellmStatusResponse {
+  /**
+   * Whether ccw-litellm is installed in the CodexLens venv.
+   * This is the environment used for the LiteLLM embedding backend.
+   */
+  installed: boolean;
+  version?: string;
+  error?: string;
+  checks?: {
+    codexLensVenv: CcwLitellmEnvCheck;
+    systemPython?: CcwLitellmEnvCheck;
+  };
+}
+
+function checkCcwLitellmImport(
+  pythonCmd: string,
+  options: { timeout: number; shell?: boolean }
+): Promise<CcwLitellmEnvCheck> {
+  const { timeout, shell = false } = options;
+
+  const sanitizePythonError = (stderrText: string): string | undefined => {
+    const trimmed = stderrText.trim();
+    if (!trimmed) return undefined;
+    const lines = trimmed
+      .split(/\r?\n/g)
+      .map((line) => line.trim())
+      .filter(Boolean);
+    // Prefer the final exception line (avoids leaking full traceback + file paths)
+    return lines[lines.length - 1] || undefined;
+  };
+
+  return new Promise((resolve) => {
+    const child = spawn(pythonCmd, ['-c', 'import ccw_litellm; print(ccw_litellm.__version__)'], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout,
+      windowsHide: true,
+      shell,
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout?.on('data', (data: Buffer) => {
+      stdout += data.toString();
+    });
+
+    child.stderr?.on('data', (data: Buffer) => {
+      stderr += data.toString();
+    });
+
+    child.on('close', (code: number | null) => {
+      const version = stdout.trim();
+      const error = sanitizePythonError(stderr);
+
+      if (code === 0 && version) {
+        resolve({ python: pythonCmd, installed: true, version });
+        return;
+      }
+
+      if (code === null) {
+        resolve({ python: pythonCmd, installed: false, error: `Timed out after ${timeout}ms` });
+        return;
+      }
+
+      resolve({ python: pythonCmd, installed: false, error: error || undefined });
+    });
+
+    child.on('error', (err) => {
+      resolve({ python: pythonCmd, installed: false, error: err.message });
+    });
+  });
+}
+
 // Cache for ccw-litellm status check
 let ccwLitellmStatusCache: {
-  data: { installed: boolean; version?: string; error?: string } | null;
+  data: CcwLitellmStatusResponse | null;
   timestamp: number;
   ttl: number;
 } = {
@@ -849,51 +929,29 @@ export async function handleLiteLLMApiRoutes(ctx: RouteContext): Promise<boolean
       return true;
     }
 
-    // Async check - use CodexLens venv Python for reliable detection
     try {
-      let result: { installed: boolean; version?: string; error?: string } = { installed: false };
-
-      // Check ONLY in CodexLens venv (where UV installs packages)
-      // Do NOT fallback to system pip - we want isolated venv dependencies
       const uv = createCodexLensUvManager();
       const venvPython = uv.getVenvPython();
       const statusTimeout = process.platform === 'win32' ? 15000 : 10000;
+      const codexLensVenv = uv.isVenvValid()
+        ? await checkCcwLitellmImport(venvPython, { timeout: statusTimeout })
+        : { python: venvPython, installed: false, error: 'CodexLens venv not valid' };
 
-      if (uv.isVenvValid()) {
+      // Diagnostics only: if not installed in venv, also check system python so users understand mismatches.
-        try {
+      // NOTE: `installed` flag remains the CodexLens venv status (we want isolated venv dependencies).
-          result = await new Promise<{ installed: boolean; version?: string }>((resolve) => {
+      const systemPython = !codexLensVenv.installed
-            const child = spawn(venvPython, ['-c', 'import ccw_litellm; print(ccw_litellm.__version__)'], {
+        ? await checkCcwLitellmImport(getSystemPython(), { timeout: statusTimeout, shell: true })
-              stdio: ['ignore', 'pipe', 'pipe'],
+        : undefined;
-              timeout: statusTimeout,
+
-              windowsHide: true,
+      const result: CcwLitellmStatusResponse = {
-            });
+        installed: codexLensVenv.installed,
-            let stdout = '';
+        version: codexLensVenv.version,
-            child.stdout.on('data', (data: Buffer) => { stdout += data.toString(); });
+        error: codexLensVenv.error,
-            child.on('close', (code: number | null) => {
+        checks: {
-              if (code === 0) {
+          codexLensVenv,
-                const version = stdout.trim();
+          ...(systemPython ? { systemPython } : {}),
-                if (version) {
+        },
-                  console.log(`[ccw-litellm status] Found in CodexLens venv: ${version}`);
+      };
-                  resolve({ installed: true, version });
-                  return;
-                }
-              }
-              console.log('[ccw-litellm status] Not found in CodexLens venv');
-              resolve({ installed: false });
-            });
-            child.on('error', () => {
-              console.log('[ccw-litellm status] Spawn error checking venv');
-              resolve({ installed: false });
-            });
-          });
-        } catch (venvErr) {
-          console.log('[ccw-litellm status] Not found in CodexLens venv');
-          result = { installed: false };
-        }
-      } else {
-        console.log('[ccw-litellm status] CodexLens venv not valid');
-        result = { installed: false };
-      }
 
       // Update cache
       ccwLitellmStatusCache = {

ccw/src/core/routes/skills-routes.ts

@@ -279,27 +279,37 @@ function parseSkillFrontmatter(content: string): ParsedSkillFrontmatter {
 }
 
 /**
- * Get list of supporting files for a skill
+ * Get list of supporting files for a skill (recursive)
  * @param {string} skillDir
- * @returns {string[]}
+ * @returns {string[]} Array of relative paths (directories end with '/')
  */
 function getSupportingFiles(skillDir: string): string[] {
   const files: string[] = [];
-  try {
+
-    const entries = readdirSync(skillDir, { withFileTypes: true });
+  function readDirRecursive(dirPath: string, relativePath: string = '') {
-    for (const entry of entries) {
+    try {
-      // Exclude SKILL.md and SKILL.md.disabled from supporting files
+      const entries = readdirSync(dirPath, { withFileTypes: true });
-      if (entry.name !== 'SKILL.md' && entry.name !== 'SKILL.md.disabled') {
+      for (const entry of entries) {
-        if (entry.isFile()) {
+        // Exclude SKILL.md and SKILL.md.disabled from supporting files
-          files.push(entry.name);
+        if (entry.name !== 'SKILL.md' && entry.name !== 'SKILL.md.disabled') {
-        } else if (entry.isDirectory()) {
+          const entryRelativePath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
-          files.push(entry.name + '/');
+
+          if (entry.isFile()) {
+            files.push(entryRelativePath);
+          } else if (entry.isDirectory()) {
+            // Add directory marker
+            files.push(entryRelativePath + '/');
+            // Recurse into subdirectory
+            readDirRecursive(join(dirPath, entry.name), entryRelativePath);
+          }
         }
       }
+    } catch (e) {
+      // Ignore errors
     }
-  } catch (e) {
-    // Ignore errors
   }
+
+  readDirRecursive(skillDir);
   return files;
 }