@ian2018cs/agenthub 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian2018cs/agenthub",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A web-based UI for AI Agents",
   "type": "module",
   "main": "server/index.js",

package/server/builtin-skills/deploy-frontend/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: deploy-frontend
+description: 将生成的 HTML 或前端页面部署到 Docker nginx 容器。用于快速部署和预览前端项目，自动配置端口隔离，返回可访问的内网 URL。使用场景：(1) 部署刚生成的 HTML/React/Vue 等前端项目 (2) 需要让用户通过浏览器查看前端页面 (3) 需要为不同项目分配独立的访问端口 (4) 清理或列出已部署的项目
+---
+
+# Deploy Frontend
+
+将前端项目部署到共享的 nginx Docker 容器，通过不同端口和配置文件实现项目隔离。
+
+## 配置
+
+默认 nginx 目录已配置为：`/home/xubuntu001/AI/nginx`
+
+如需修改，编辑脚本文件中的 `DEFAULT_NGINX_BASE_DIR` 变量：
+- `scripts/deploy.py` 第 14 行
+- `scripts/cleanup.py` 第 10 行
+
+## 工作原理
+
+- **单容器架构**：所有项目共享一个 nginx 容器（节省资源）
+- **配置隔离**：每个项目在 `config/conf.d/` 下有独立的 `.conf` 文件
+- **端口隔离**：自动分配不同端口（从 8080 开始递增）
+- **目录隔离**：每个项目的文件存放在 `html/project-{timestamp}/`
+
+## 部署前端项目
+
+使用 `scripts/deploy.py` 部署项目：
+
+```bash
+python scripts/deploy.py <前端项目目录>
+```
+
+**参数说明：**
+- `<前端项目目录>`：包含 index.html 等前端文件的目录（必需）
+
+默认使用 `/home/xubuntu001/AI/nginx` 作为 nginx 基础目录，无需额外指定。
+
+**脚本执行流程：**
+1. 生成唯一的项目 ID（project-{timestamp}）
+2. 查找可用端口（从 8080 开始）
+3. 复制前端文件到 `html/{project_id}/`
+4. 在 `config/conf.d/` 创建 nginx 配置文件
+5. 重新加载 nginx（如果容器未运行则启动）
+6. 返回访问 URL（内网IP:端口）
+7. 保存部署信息到 `deployments/{project_id}.json`
+
+**示例：**
+```bash
+# 部署前端项目（使用默认 nginx 目录）
+python .claude/skills/deploy-frontend/scripts/deploy.py ./my-frontend-app
+```
+
+**输出示例：**
+```
+✅ 部署成功!
+项目 ID: project-1738151234
+端口: 8080
+访问地址: http://192.168.1.100:8080
+HTML 目录: /path/to/nginx/html/project-1738151234
+配置文件: /path/to/nginx/config/conf.d/project-1738151234.conf
+```
+
+## 管理部署
+
+使用 `scripts/cleanup.py` 管理已部署的项目。
+
+### 列出所有部署
+
+```bash
+python scripts/cleanup.py list
+```
+
+### 清理指定项目
+
+```bash
+python scripts/cleanup.py <project_id>
+```
+
+会删除：
+- HTML 目录
+- nginx 配置文件
+- 部署信息文件
+
+并重新加载 nginx 配置。
+
+### 清理所有项目
+
+```bash
+python scripts/cleanup.py all
+```
+
+## 目录结构
+
+部署后的 nginx 基础目录结构：
+
+```
+nginx-base/
+├── docker-compose.yml          # nginx 容器配置
+├── html/                       # 前端文件
+│   ├── project-1738151234/    # 项目1
+│   │   ├── index.html
+│   │   └── ...
+│   └── project-1738151456/    # 项目2
+│       ├── index.html
+│       └── ...
+├── config/
+│   └── conf.d/                # nginx 配置
+│       ├── project-1738151234.conf
+│       └── project-1738151456.conf
+├── logs/                      # nginx 日志
+└── deployments/               # 部署信息
+    ├── project-1738151234.json
+    └── project-1738151456.json
+```
+
+## 使用流程
+
+### 典型工作流
+
+1. **生成前端代码**：创建 HTML/React/Vue 项目
+2. **调用部署脚本**：
+   ```python
+   from pathlib import Path
+   import subprocess
+
+   result = subprocess.run([
+       "python",
+       str(Path.home() / ".claude/skills/deploy-frontend/scripts/deploy.py"),
+       "./frontend-output"
+   ], capture_output=True, text=True)
+
+   print(result.stdout)
+   ```
+3. **提取访问 URL**：从输出中获取 URL 返回给用户
+4. **提醒用户访问**：告知用户可以通过浏览器访问该 URL
+
+### 在对话中使用
+
+当用户要求生成前端页面时：
+
+1. 生成前端代码（HTML/CSS/JS 等）
+2. 将文件写入临时目录
+3. 调用 deploy.py 部署
+4. 将访问 URL 返回给用户
+
+示例代码模式：
+```python
+# 1. 创建输出目录
+output_dir = Path("/tmp/frontend-{timestamp}")
+output_dir.mkdir(parents=True, exist_ok=True)
+
+# 2. 写入前端文件
+(output_dir / "index.html").write_text(html_content)
+(output_dir / "style.css").write_text(css_content)
+
+# 3. 部署
+deploy_script = Path.home() / ".claude/skills/deploy-frontend/scripts/deploy.py"
+result = subprocess.run(
+    ["python", str(deploy_script), str(output_dir)],
+    capture_output=True,
+    text=True
+)
+
+# 4. 提取 URL（从输出中解析）
+for line in result.stdout.split('\n'):
+    if line.startswith('访问地址:'):
+        url = line.split(':', 1)[1].strip()
+        print(f"您的前端页面已部署: {url}")
+```
+
+## 前置要求
+
+- Docker 和 docker-compose 已安装
+- nginx 基础目录位于 `/home/xubuntu001/AI/nginx`
+- docker-compose.yml 使用 `network_mode: host`
+- Python 3.6+
+
+## 故障排查
+
+**容器未启动**：脚本会自动执行 `docker-compose up -d`
+
+**端口冲突**：脚本会自动查找可用端口（8080-8179 范围）
+
+**配置未生效**：手动重新加载 nginx：
+```bash
+docker exec nginx-web nginx -s reload
+```
+
+**查看 nginx 日志**：
+```bash
+docker logs nginx-web
+```

package/server/builtin-skills/deploy-frontend/scripts/cleanup.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+"""
+清理部署的前端项目
+"""
+import subprocess
+import sys
+from pathlib import Path
+import shutil
+import json
+
+# 默认 nginx 基础目录（与 deploy.py 保持一致）
+DEFAULT_NGINX_BASE_DIR = "/home/xubuntu001/AI/nginx"
+
+def cleanup_deployment(project_id, nginx_base_dir=None):
+    """
+    清理指定部署
+
+    Args:
+        project_id: 项目 ID
+        nginx_base_dir: nginx 基础目录，默认为 DEFAULT_NGINX_BASE_DIR
+    """
+    if nginx_base_dir is None:
+        nginx_base_dir = Path(DEFAULT_NGINX_BASE_DIR)
+    else:
+        nginx_base_dir = Path(nginx_base_dir)
+
+    deployments_dir = nginx_base_dir / "deployments"
+    info_file = deployments_dir / f"{project_id}.json"
+
+    if not info_file.exists():
+        print(f"❌ 项目不存在: {project_id}")
+        return False
+
+    try:
+        with open(info_file) as f:
+            info = json.load(f)
+
+        # 删除 HTML 目录
+        html_dir = Path(info['html_dir'])
+        if html_dir.exists():
+            print(f"删除 HTML 目录: {html_dir}")
+            shutil.rmtree(html_dir)
+
+        # 删除 nginx 配置文件
+        conf_file = Path(info['conf_file'])
+        if conf_file.exists():
+            print(f"删除配置文件: {conf_file}")
+            conf_file.unlink()
+
+        # 重新加载 nginx
+        print("重新加载 nginx 配置...")
+        subprocess.run(
+            ["docker", "exec", "nginx-web", "nginx", "-s", "reload"],
+            check=True
+        )
+
+        # 删除部署信息文件
+        info_file.unlink()
+
+        print(f"✅ 清理完成: {project_id}")
+        return True
+
+    except Exception as e:
+        print(f"❌ 清理失败: {e}")
+        import traceback
+        traceback.print_exc()
+        return False
+
+def list_deployments(nginx_base_dir=None):
+    """列出所有部署"""
+    if nginx_base_dir is None:
+        nginx_base_dir = Path(DEFAULT_NGINX_BASE_DIR)
+    else:
+        nginx_base_dir = Path(nginx_base_dir)
+
+    deployments_dir = nginx_base_dir / "deployments"
+
+    if not deployments_dir.exists() or not list(deployments_dir.glob("*.json")):
+        print("没有找到部署")
+        return
+
+    print("\n当前部署:")
+    print("-" * 80)
+
+    for info_file in sorted(deployments_dir.glob("*.json")):
+        with open(info_file) as f:
+            info = json.load(f)
+
+        print(f"项目 ID: {info['project_id']}")
+        print(f"  部署时间: {info.get('deployed_at', 'N/A')}")
+        print(f"  访问地址: {info['url']}")
+        print(f"  HTML 目录: {info['html_dir']}")
+        print()
+
+def cleanup_all(nginx_base_dir=None):
+    """清理所有部署"""
+    if nginx_base_dir is None:
+        nginx_base_dir = Path(DEFAULT_NGINX_BASE_DIR)
+    else:
+        nginx_base_dir = Path(nginx_base_dir)
+
+    deployments_dir = nginx_base_dir / "deployments"
+
+    if not deployments_dir.exists():
+        print("没有找到部署")
+        return
+
+    for info_file in deployments_dir.glob("*.json"):
+        project_id = info_file.stem
+        print(f"\n清理项目: {project_id}")
+        cleanup_deployment(project_id, nginx_base_dir)
+
+def main():
+    if len(sys.argv) < 2:
+        print("用法:")
+        print(f"  默认 nginx 目录: {DEFAULT_NGINX_BASE_DIR}")
+        print("  列出所有部署: python cleanup.py list [nginx基础目录]")
+        print("  清理指定项目: python cleanup.py <project_id> [nginx基础目录]")
+        print("  清理所有项目: python cleanup.py all [nginx基础目录]")
+        sys.exit(1)
+
+    command = sys.argv[1]
+    nginx_base_dir = sys.argv[2] if len(sys.argv) > 2 else None
+
+    if command == "list":
+        list_deployments(nginx_base_dir)
+    elif command == "all":
+        cleanup_all(nginx_base_dir)
+    else:
+        cleanup_deployment(command, nginx_base_dir)
+
+if __name__ == "__main__":
+    main()

package/server/builtin-skills/deploy-frontend/scripts/deploy.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+"""
+部署前端项目到共享的 nginx 容器（通过 conf.d 配置隔离）
+"""
+import os
+import sys
+import subprocess
+import socket
+from pathlib import Path
+import shutil
+import json
+import time
+
+# 默认 nginx 基础目录（可在这里修改）
+DEFAULT_NGINX_BASE_DIR = "/home/xubuntu001/AI/nginx"
+
+def find_available_port(start_port=8080, max_attempts=100):
+    """查找可用端口"""
+    for port in range(start_port, start_port + max_attempts):
+        try:
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                s.bind(('', port))
+                return port
+        except OSError:
+            continue
+    raise RuntimeError(f"无法在 {start_port}-{start_port + max_attempts} 范围内找到可用端口")
+
+def get_local_ip():
+    """获取本机内网 IP"""
+    try:
+        s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        s.connect(("8.8.8.8", 80))
+        ip = s.getsockname()[0]
+        s.close()
+        return ip
+    except Exception:
+        return "localhost"
+
+def generate_project_id():
+    """生成项目 ID"""
+    return f"project-{int(time.time())}"
+
+def create_nginx_conf(project_id, port, nginx_base_dir):
+    """创建项目的 nginx 配置文件"""
+    config_content = f"""server {{
+    listen {port};
+    server_name localhost;
+
+    root /usr/share/nginx/html/{project_id};
+    index index.html index.htm;
+
+    location / {{
+        try_files $uri $uri/ /index.html;
+    }}
+
+    # 启用 gzip 压缩
+    gzip on;
+    gzip_types text/plain text/css application/json application/javascript text/xml application/xml text/javascript;
+
+    # 缓存静态资源
+    location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2|ttf|eot)$ {{
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+    }}
+}}
+"""
+    conf_dir = nginx_base_dir / "config" / "conf.d"
+    conf_dir.mkdir(parents=True, exist_ok=True)
+
+    conf_file = conf_dir / f"{project_id}.conf"
+    conf_file.write_text(config_content)
+    return conf_file
+
+def reload_nginx(nginx_base_dir):
+    """重新加载 nginx 配置"""
+    compose_file = nginx_base_dir / "docker-compose.yml"
+    if not compose_file.exists():
+        raise RuntimeError(f"docker-compose.yml 不存在: {compose_file}")
+
+    # 检查容器是否运行
+    result = subprocess.run(
+        ["docker", "ps", "--filter", "name=nginx-web", "--format", "{{.Names}}"],
+        capture_output=True,
+        text=True,
+        cwd=nginx_base_dir
+    )
+
+    if "nginx-web" not in result.stdout:
+        # 容器未运行，启动它
+        print("启动 nginx 容器...")
+        subprocess.run(
+            ["docker-compose", "up", "-d"],
+            cwd=nginx_base_dir,
+            check=True
+        )
+    else:
+        # 重新加载配置
+        print("重新加载 nginx 配置...")
+        subprocess.run(
+            ["docker", "exec", "nginx-web", "nginx", "-s", "reload"],
+            check=True
+        )
+
+def deploy_frontend(source_dir, nginx_base_dir=None):
+    """
+    部署前端项目
+
+    Args:
+        source_dir: 源代码目录路径
+        nginx_base_dir: nginx docker-compose 所在目录，默认为 DEFAULT_NGINX_BASE_DIR
+
+    Returns:
+        dict: 包含部署信息的字典
+    """
+    source_path = Path(source_dir).resolve()
+    if not source_path.exists():
+        raise ValueError(f"源目录不存在: {source_dir}")
+
+    # 设置 nginx 基础目录
+    if nginx_base_dir is None:
+        nginx_base_dir = Path(DEFAULT_NGINX_BASE_DIR)
+    else:
+        nginx_base_dir = Path(nginx_base_dir).resolve()
+
+    # 生成项目信息
+    project_id = generate_project_id()
+
+    # 查找可用端口
+    port = find_available_port()
+
+    # 复制前端文件到 html/project-id/
+    html_dir = nginx_base_dir / "html" / project_id
+    if html_dir.exists():
+        shutil.rmtree(html_dir)
+    shutil.copytree(source_path, html_dir)
+
+    # 创建 nginx 配置
+    conf_file = create_nginx_conf(project_id, port, nginx_base_dir)
+
+    # 重新加载 nginx
+    reload_nginx(nginx_base_dir)
+
+    # 获取访问 URL
+    local_ip = get_local_ip()
+    url = f"http://{local_ip}:{port}"
+
+    # 保存部署信息到部署目录
+    deployments_dir = nginx_base_dir / "deployments"
+    deployments_dir.mkdir(exist_ok=True)
+
+    deploy_info = {
+        "project_id": project_id,
+        "port": port,
+        "url": url,
+        "html_dir": str(html_dir),
+        "conf_file": str(conf_file),
+        "source_dir": str(source_path),
+        "deployed_at": time.strftime("%Y-%m-%d %H:%M:%S")
+    }
+
+    info_file = deployments_dir / f"{project_id}.json"
+    info_file.write_text(json.dumps(deploy_info, indent=2, ensure_ascii=False))
+
+    return deploy_info
+
+def main():
+    if len(sys.argv) < 2:
+        print("用法: python deploy.py <前端项目目录> [nginx基础目录]")
+        print(f"默认 nginx 目录: {DEFAULT_NGINX_BASE_DIR}")
+        print("示例: python deploy.py ./my-app")
+        sys.exit(1)
+
+    source_dir = sys.argv[1]
+    nginx_base_dir = sys.argv[2] if len(sys.argv) > 2 else None
+
+    try:
+        info = deploy_frontend(source_dir, nginx_base_dir)
+        print(f"\n✅ 部署成功!")
+        print(f"项目 ID: {info['project_id']}")
+        print(f"端口: {info['port']}")
+        print(f"访问地址: {info['url']}")
+        print(f"HTML 目录: {info['html_dir']}")
+        print(f"配置文件: {info['conf_file']}")
+    except Exception as e:
+        print(f"\n❌ 部署失败: {e}")
+        import traceback
+        traceback.print_exc()
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

package/server/cli.js

@@ -74,10 +74,11 @@ function loadEnvFile() {
 // Get the database path (same logic as db.js)
 function getDatabasePath() {
     loadEnvFile();
-    // Resolve relative paths from project root (one level up from server/)
+    const projectRoot = path.join(__dirname, '..');
+    const dataDir = process.env.DATA_DIR || path.join(projectRoot, 'data');
     return process.env.DATABASE_PATH
-        ? path.resolve(path.join(__dirname, '..'), process.env.DATABASE_PATH)
-        : path.join(__dirname, 'database', 'auth.db');
+        ? path.resolve(projectRoot, process.env.DATABASE_PATH)
+        : path.join(dataDir, 'auth.db');
 }
 
 // Get the installation directory
@@ -205,7 +206,7 @@ function isNewerVersion(v1, v2) {
 async function checkForUpdates(silent = false) {
     try {
         const { execSync } = await import('child_process');
-        const latestVersion = execSync('npm show @siteboon/claude-code-ui version', { encoding: 'utf8' }).trim();
+        const latestVersion = execSync('npm show @ian2018cs/agenthub version', { encoding: 'utf8' }).trim();
         const currentVersion = packageJson.version;
 
         if (isNewerVersion(latestVersion, currentVersion)) {
@@ -238,11 +239,11 @@ async function updatePackage() {
         }
 
         console.log(`${c.info('[INFO]')} Updating from ${currentVersion} to ${latestVersion}...`);
-        execSync('npm update -g @siteboon/claude-code-ui', { stdio: 'inherit' });
+        execSync('npm update -g @ian2018cs/agenthub', { stdio: 'inherit' });
         console.log(`${c.ok('[OK]')} Update complete! Restart cloudcli to use the new version.`);
     } catch (e) {
         console.error(`${c.error('[ERROR]')} Update failed: ${e.message}`);
-        console.log(`${c.tip('[TIP]')} Try running manually: npm update -g @siteboon/claude-code-ui`);
+        console.log(`${c.tip('[TIP]')} Try running manually: npm update -g @ian2018cs/agenthub`);
     }
 }
 

package/server/database/db.js

@@ -21,25 +21,25 @@ const c = {
     dim: (text) => `${colors.dim}${text}${colors.reset}`,
 };
 
-// Use DATABASE_PATH environment variable if set, otherwise use default location
-// Resolve relative paths from project root (one level up from server/)
+// Use DATABASE_PATH environment variable if set, otherwise use DATA_DIR/auth.db
+// DATA_DIR defaults to ./data relative to project root
+const PROJECT_ROOT = path.join(__dirname, '../..');
+const DATA_DIR = process.env.DATA_DIR || path.join(PROJECT_ROOT, 'data');
 const DB_PATH = process.env.DATABASE_PATH
-  ? path.resolve(path.join(__dirname, '../..'), process.env.DATABASE_PATH)
-  : path.join(__dirname, 'auth.db');
+  ? path.resolve(PROJECT_ROOT, process.env.DATABASE_PATH)
+  : path.join(DATA_DIR, 'auth.db');
 const INIT_SQL_PATH = path.join(__dirname, 'init.sql');
 
-// Ensure database directory exists if custom path is provided
-if (process.env.DATABASE_PATH) {
-  const dbDir = path.dirname(DB_PATH);
-  try {
-    if (!fs.existsSync(dbDir)) {
-      fs.mkdirSync(dbDir, { recursive: true });
-      console.log(`Created database directory: ${dbDir}`);
-    }
-  } catch (error) {
-    console.error(`Failed to create database directory ${dbDir}:`, error.message);
-    throw error;
+// Ensure database directory exists
+const dbDir = path.dirname(DB_PATH);
+try {
+  if (!fs.existsSync(dbDir)) {
+    fs.mkdirSync(dbDir, { recursive: true });
+    console.log(`Created database directory: ${dbDir}`);
   }
+} catch (error) {
+  console.error(`Failed to create database directory ${dbDir}:`, error.message);
+  throw error;
 }
 
 // Create database connection
@@ -50,6 +50,7 @@ const appInstallPath = path.join(__dirname, '../..');
 console.log('');
 console.log(c.dim('═'.repeat(60)));
 console.log(`${c.info('[INFO]')} App Installation: ${c.bright(appInstallPath)}`);
+console.log(`${c.info('[INFO]')} Data Directory: ${c.dim(path.relative(appInstallPath, DATA_DIR))}`);
 console.log(`${c.info('[INFO]')} Database: ${c.dim(path.relative(appInstallPath, DB_PATH))}`);
 if (process.env.DATABASE_PATH) {
   console.log(`       ${c.dim('(Using custom DATABASE_PATH from environment)')}`);

package/server/routes/skills.js

@@ -5,6 +5,7 @@ import { spawn } from 'child_process';
 import multer from 'multer';
 import AdmZip from 'adm-zip';
 import { getUserPaths, getPublicPaths, DATA_DIR } from '../services/user-directories.js';
+import { markBuiltinSkillRemoved, isBuiltinSkillPath } from '../services/builtin-skills.js';
 
 const router = express.Router();
 
@@ -238,6 +239,8 @@ router.get('/', async (req, res) => {
             if (repoMatch) {
               repository = `${repoMatch[1]}/${repoMatch[2]}`;
             }
+          } else if (realPath.includes('/builtin-skills/')) {
+            source = 'builtin';
           }
         }
 
@@ -374,12 +377,14 @@ router.delete('/:name', async (req, res) => {
     // Check the symlink target to determine source
     let realPath = null;
     let isImported = false;
+    let isBuiltin = false;
 
     try {
       const stat = await fs.lstat(linkPath);
       if (stat.isSymbolicLink()) {
         realPath = await fs.realpath(linkPath);
         isImported = realPath.includes('/skills-import/');
+        isBuiltin = isBuiltinSkillPath(realPath);
       }
     } catch (err) {
       return res.status(404).json({ error: 'Skill not found' });
@@ -395,6 +400,9 @@ router.delete('/:name', async (req, res) => {
       } catch (err) {
         console.error('Error removing imported skill files:', err);
       }
+    } else if (isBuiltin) {
+      // Mark as removed so it won't be re-added on next sync
+      await markBuiltinSkillRemoved(userUuid, name);
     }
 
     res.json({ success: true, message: 'Skill deleted' });

package/server/services/builtin-skills.js

@@ -0,0 +1,147 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { getUserPaths } from './user-directories.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Path to built-in skills directory
+const BUILTIN_SKILLS_DIR = path.join(__dirname, '../builtin-skills');
+
+// State file version for future migrations
+const STATE_VERSION = 1;
+
+/**
+ * Get list of all available built-in skills
+ */
+export async function getBuiltinSkills() {
+  const skills = [];
+
+  try {
+    const entries = await fs.readdir(BUILTIN_SKILLS_DIR, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (entry.isDirectory() && !entry.name.startsWith('.')) {
+        const skillPath = path.join(BUILTIN_SKILLS_DIR, entry.name);
+
+        // Check for SKILLS.md or SKILL.md
+        const skillsFile = path.join(skillPath, 'SKILLS.md');
+        const skillFile = path.join(skillPath, 'SKILL.md');
+
+        try {
+          // Try SKILLS.md first, then SKILL.md
+          let found = false;
+          try {
+            await fs.access(skillsFile);
+            found = true;
+          } catch {
+            await fs.access(skillFile);
+            found = true;
+          }
+
+          if (found) {
+            skills.push({
+              name: entry.name,
+              path: skillPath
+            });
+          }
+        } catch {
+          // Skip if neither file exists
+        }
+      }
+    }
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      console.error('Error reading builtin skills:', err);
+    }
+  }
+
+  return skills;
+}
+
+/**
+ * Get path to user's builtin skills state file
+ */
+function getStatePath(userUuid) {
+  const userPaths = getUserPaths(userUuid);
+  return path.join(userPaths.claudeDir, '.builtin-skills-state.json');
+}
+
+/**
+ * Load user's builtin skills state
+ */
+export async function loadBuiltinSkillsState(userUuid) {
+  try {
+    const statePath = getStatePath(userUuid);
+    const content = await fs.readFile(statePath, 'utf-8');
+    return JSON.parse(content);
+  } catch {
+    return {
+      version: STATE_VERSION,
+      removedSkills: []
+    };
+  }
+}
+
+/**
+ * Save user's builtin skills state
+ */
+export async function saveBuiltinSkillsState(userUuid, state) {
+  const statePath = getStatePath(userUuid);
+  await fs.writeFile(statePath, JSON.stringify(state, null, 2));
+}
+
+/**
+ * Initialize built-in skills for a user
+ * Creates symlinks for all built-in skills not in user's removed list
+ */
+export async function initBuiltinSkills(userUuid) {
+  const userPaths = getUserPaths(userUuid);
+  const builtinSkills = await getBuiltinSkills();
+  const state = await loadBuiltinSkillsState(userUuid);
+
+  for (const skill of builtinSkills) {
+    // Skip if user has explicitly removed this skill
+    if (state.removedSkills.includes(skill.name)) {
+      continue;
+    }
+
+    const linkPath = path.join(userPaths.skillsDir, skill.name);
+
+    try {
+      // Check if link already exists
+      await fs.lstat(linkPath);
+      // Link exists, skip
+    } catch {
+      // Link doesn't exist, create it
+      try {
+        await fs.symlink(skill.path, linkPath);
+        console.log(`Created builtin skill symlink: ${skill.name}`);
+      } catch (err) {
+        console.error(`Error creating builtin skill symlink ${skill.name}:`, err);
+      }
+    }
+  }
+}
+
+/**
+ * Mark a built-in skill as removed by user
+ */
+export async function markBuiltinSkillRemoved(userUuid, skillName) {
+  const state = await loadBuiltinSkillsState(userUuid);
+
+  if (!state.removedSkills.includes(skillName)) {
+    state.removedSkills.push(skillName);
+    await saveBuiltinSkillsState(userUuid, state);
+  }
+}
+
+/**
+ * Check if a path is a built-in skill
+ */
+export function isBuiltinSkillPath(realPath) {
+  return realPath?.includes('/builtin-skills/') ?? false;
+}
+
+export { BUILTIN_SKILLS_DIR };

package/server/services/user-directories.js

@@ -1,5 +1,6 @@
 import { promises as fs } from 'fs';
 import path from 'path';
+import { initBuiltinSkills } from './builtin-skills.js';
 
 // Base data directory (configurable via env)
 const DATA_DIR = process.env.DATA_DIR || path.join(process.cwd(), 'data');
@@ -85,6 +86,9 @@ export async function initUserDirectories(userUuid) {
   await fs.writeFile(usageScanStatePath, JSON.stringify(scanState, null, 2));
   console.log(`Created .usage-scan-state.json for user ${userUuid}`);
 
+  // Initialize built-in skills
+  await initBuiltinSkills(userUuid);
+
   return paths;
 }