joyskills-cli 0.1.1 → 0.1.3

package/README.md

@@ -1,29 +1,54 @@
-# joySkills - 新一代团队 Skill 治理平台
+# joySkills - OpenSkills 的增强替代品
 
-> 在协议层兼容 open skill / Claude Skills，在能力层扩展企业级治理能力
+> 100% 兼容 OpenSkills + 团队协作增强（版本锁定、团队 Registry、安全审计）
 
 [![npm version](https://badge.fury.io/js/joyskills-cli.svg)](https://www.npmjs.com/package/joyskills-cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 **🔗 Links:** [npm Package](https://www.npmjs.com/package/joyskills-cli) | [Git Repository](https://github.com/your-org/joyskills-cli)
 
-## 💡 为什么需要 joySkills？
+## 💡 为什么选择 joySkills？
 
-在 AI 原生开发时代，**Skill**（技能）成为了比 function 更友好的能力抽象单元。然而当团队规模扩大，单纯的本地 skill 管理会遇到：
+**joySkills 是 OpenSkills 的超集**，提供：
 
-- ❌ **版本混乱**：不同项目使用不同版本的 skill，难以统一升级
-- ❌ **安全风险**：无法及时发现和处理已废弃或有风险的 skill 版本
-- ❌ **缺乏治理**：谁在用什么 skill？如何审批新版本？
-- ❌ **协作困难**：团队成员各自维护 skill，无法共享和复用
+### 🎯 OpenSkills 的全部能力
+- ✅ 安装公开 skill（调用 `openskills install`）
+- ✅ 生成 AGENTS.md（`joySkills sync` = `openskills sync` + 增强）
+- ✅ 读取 skill 内容（`joySkills read` = `openskills read`）
+- ✅ 100% 兼容 Claude Code / Cursor / Windsurf
 
-joySkills 提供了一套**完整的团队级 Skill 治理方案**，同时保持与现有生态的 100% 兼容。
+### 🚀 团队协作增强（OpenSkills 缺失的）
+- ✅ **版本锁定**：joySkills.lock 确保团队版本统一
+- ✅ **团队 Registry**：基于 Git 的内部 skill 仓库
+- ✅ **安全审计**：自动检测废弃和有风险的 skill
+- ✅ **状态管理**：draft → review → approved → deprecated
+- ✅ **使用追踪**：了解哪些 skill 被使用、被谁使用
 
 ## ✨ 核心特性
 
-### 📦 统一 Skill 源（Registry）
-- 团队/组织级 Skill 仓库
-- 基于 Git 的版本管理
-- 支持私有部署和权限控制
+### 📦 公开 + 内部 Skill 统一管理
+```bash
+# 项目级安装（默认）
+joySkills install team://your-team/rc-onboarding
+# → 安装到 .agent/skills/rc-onboarding
+
+# 全局安装
+joySkills install -g anthropics/skills/pdf
+# → 安装到 ~/.agent/skills/pdf
+
+# 统一同步（扫描所有路径）
+joySkills sync
+# 扫描: .agent/skills, ~/.agent/skills, .claude/skills, ~/.claude/skills
+# 生成: AGENTS.md + joySkills.lock
+```
+
+**路径设计**：
+| 安装方式 | joySkills | OpenSkills |
+|---------|-----------|------------|
+| 项目级 | `.agent/skills` | `.agent/skills` (--universal) |
+| 全局 | `~/.agent/skills` | `~/.claude/skills` (--global) |
+
+**优先级**：项目级 > 全局，不同项目可用不同版本
 
 ### 🔒 版本锁定（joySkills.lock）
 - 项目级版本锁定，确保环境一致
@@ -45,112 +70,157 @@ joySkills 提供了一套**完整的团队级 Skill 治理方案**，同时保
 - 安全风险预警
 - 自动生成升级建议
 
-### 🤝 100% 兼容现有生态
-- 兼容 Claude Code / Cursor / Windsurf / Aider
-- 不改变 `skills/` 目录结构
-- 不改变 `SKILL.md` 文件格式
+### 📋 OpenSkills 兼容命令
+```bash
+# sync 命令（扫描所有路径 + 生成 AGENTS.md）
+joySkills sync
+# 扫描路径：.agent/skills, ~/.agent/skills, .claude/skills, ~/.claude/skills
+# ✅ 生成 AGENTS.md（与 openskills sync 格式相同）
+# ✅ 额外生成 joySkills.lock（版本锁定）
+
+# read 命令（按优先级读取 skill）
+joySkills read rc-onboarding
+# ✅ 路径查找优先级与 openskills read 一致
+# ✅ 输出格式完全相同
+```
 
 ## 🚀 快速开始
 
-### 安装
-
-joySkills 支持**全局安装**和**项目级安装**两种方式：
+### 场景 1：个人开发者（替代 OpenSkills）
 
 ```bash
-# 全局安装
+# 1. 安装
 npm install -g joyskills-cli
-joySkills --version
 
-# 或：项目级安装
-npm install joyskills-cli
-npx joySkills --version
+# 2. 安装公开 skill
+joySkills install anthropics/skills/pdf
+joySkills install @skillforge/code-review
+
+# 3. 生成 AGENTS.md
+joySkills sync
+
+# 4. 查看已安装
+joySkills list
 ```
 
-### 5 分钟上手
+### 场景 2：团队协作（内部 skill）
 
 ```bash
-# 1. 进入你的项目目录
-cd your-project
+# 1. 安装
+npm install -g joyskills-cli
 
-# 2. 安装一个 skill
-joySkills install web-search
-# 或使用 npx（如果是项目级安装）
-npx joySkills install web-search
+# 2. 配置团队 Registry
+echo '{
+  "registries": [{
+    "id": "team://your-team",
+    "url": "https://your-git/team-skills.git",
+    "type": "git"
+  }]
+}' > .joyskillrc
 
-# 3. 查看已安装的 skills
-joySkills list
+# 3. 安装团队 skill
+joySkills install team://your-team/rc-onboarding
 
-# 4. 检查状态
-joySkills status
+# 4. 生成 AGENTS.md + joySkills.lock
+joySkills sync
 
-# 5. 审计安全性
-joySkills audit
+# 5. 团队成员同步
+git pull  # 拉取 joySkills.lock
+joySkills install  # 自动安装锁定版本
 ```
 
-完成！你的 Claude Code / Cursor 等编辑器会自动识别 `skills/` 目录中的技能。
+### 场景 3：从 OpenSkills 迁移
+
+```bash
+# 已经用 openskills 安装了很多 skills
+openskills install skill-a
+openskills install skill-b
+
+# 切换到 joySkills（无需重装）
+joySkills sync
+# ✅ 自动识别已有 skills
+# ✅ 生成 joySkills.lock
+# ✅ 后续用 joySkills install 安装新 skill
+```
 
 ## 📋 完整命令参考
 
-### `joySkills list`
-列出可用的 skills
+### OpenSkills 兼容命令
+
+#### `joySkills sync`
+生成 AGENTS.md（100% 兼容 `openskills sync` + 增强）
 
-**选项：**
-- `-a, --all-versions` - 显示所有版本
-- `-c, --category <category>` - 按分类过滤
-- `-s, --search <query>` - 搜索 skill 名称或描述
-- `-i, --installed` - 只显示已安装的 skills
-- `-l, --local` - 只显示本地 skills
-- `-r, --registry <name>` - 显示指定 registry 的 skills
+```bash
+joySkills sync
+# ✅ 扫描 skills/ 目录
+# ✅ 生成 AGENTS.md（OpenSkills 兼容格式）
+# ✅ 生成 joySkills.lock（版本锁定）
+# ✅ 版本一致性检查
+```
 
-### `joySkills install <skill>`
-安装一个 skill
+#### `joySkills read <skill-name>`
+读取 skill 内容（100% 兼容 `openskills read`）
 
 ```bash
-# 安装最新版本
-joySkills install web-search
+joySkills read rc-onboarding
+# ✅ 路径查找优先级与 openskills 一致
+# ✅ 输出格式完全相同
+```
+
+### joySkills 增强命令
 
-# 安装指定版本
-joySkills install web-search@1.0.0
+#### `joySkills install <skill>`
+安装 skill（公开 + 团队 + 本地）
 
-# 从指定 registry 安装
-joySkills install web-search --registry my-team
+```bash
+# 公开 skill（自动调用 openskills）
+joySkills install anthropics/skills/pdf
+
+# 团队 skill
+joySkills install team://your-team/rc-onboarding
+
+# 本地 skill
+joySkills install ./my-local-skill
+
+# 指定版本
+joySkills install team://your-team/rc-onboarding@1.2.0
 ```
 
-### `joySkills remove <skill>`
+#### `joySkills list`
+列出可用的 skills
+
+```bash
+joySkills list
+joySkills list --installed  # 只显示已安装
+joySkills list --search "web"  # 搜索
+```
+
+#### `joySkills remove <skill>`
 删除已安装的 skill
 
 ```bash
-joySkills remove web-search
+joySkills remove rc-onboarding
 ```
 
-### `joySkills team <subcommand>`
+#### `joySkills team`
 管理团队 registry
 
 ```bash
-# 添加团队 registry
 joySkills team add my-team /path/to/registry
-
-# 列出所有 registries
 joySkills team list
-
-# 删除 registry
 joySkills team remove my-team
 ```
 
-### `joySkills status`
+#### `joySkills status`
 显示当前项目的 skills 状态
 
 ```bash
 joySkills status
 ```
 
-### `joySkills audit`
+#### `joySkills audit`
 审计已安装 skills 的安全性和弃用状态
 
-```bash
-joySkills audit
-```
-
 ## 📖 核心概念
 
 ### Skill Registry（技能注册表）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "joyskills-cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Team-level skill governance compatible with open skill / Claude Skills",
   "main": "src/index.js",
   "bin": {

package/src/commands/install.js

@@ -4,6 +4,7 @@ import { LockfileManager } from '../lockfile.js';
 import { RegistryManager } from '../registry.js';
 import * as fs from 'fs';
 import * as path from 'path';
+import { execSync } from 'child_process';
 
 export function installCommand(program) {
   program
@@ -11,10 +12,11 @@ export function installCommand(program) {
     .description('Install a skill')
     .option('-v, --version <version>', 'Specify version to install')
     .option('-r, --registry <name>', 'Install from specific registry')
+    .option('-g, --global', 'Install globally (~/.agent/skills)')
     .option('--force', 'Force installation even if version is not recommended')
     .action(async (skillName, options) => {
       const projectRoot = process.cwd();
-      const localManager = new LocalManager(projectRoot);
+      const localManager = new LocalManager(projectRoot, { global: options.global });
       const lockfileManager = new LockfileManager(projectRoot);
 
       console.log(`Installing skill: ${skillName}`);
@@ -26,57 +28,126 @@ export function installCommand(program) {
         // Check if skill already exists
         if (localManager.hasSkill(skillName)) {
           console.log(`⚠️  Skill ${skillName} already exists locally.`);
-          console.log('   Use "joyskill remove <skill>" first if you want to reinstall.');
+          console.log('   Use "joySkills remove <skill>" first if you want to reinstall.');
           return;
         }
 
-        // Check for registry
-        let registryManager = null;
-        const registryPath = path.join(projectRoot, '.joyskill/registry');
-
-        if (fs.existsSync(registryPath)) {
-          try {
-            registryManager = new RegistryManager(registryPath);
-            await registryManager.load();
-          } catch (error) {
-            console.error('Warning: Could not load registry:', error.message);
-          }
+        // 判断 skill 类型
+        const skillType = detectSkillType(skillName);
+        
+        if (skillType === 'public') {
+          // 公开 skill：调用 openskills install
+          await installPublicSkill(skillName, options, localManager, lockfileManager);
+        } else if (skillType === 'team') {
+          // 团队 skill：从团队 Registry 安装
+          await installTeamSkill(skillName, options, projectRoot, localManager, lockfileManager);
+        } else if (skillType === 'local') {
+          // 本地 skill：直接复制
+          await installLocalSkill(skillName, options, localManager, lockfileManager);
         }
 
-        // Determine version to install
-        let targetVersion = options.version || '1.0.0';
-        let versionSource = 'default';
-
-        if (registryManager && registryManager.hasSkill(skillName)) {
-          if (!options.version) {
-            // Get recommended version from registry
-            const recommended = registryManager.getRecommendedVersion(skillName);
-            if (recommended) {
-              targetVersion = recommended.version;
-              versionSource = 'registry';
-            }
-          }
-
-          // Validate version
-          const validation = registryManager.validateVersion(skillName, targetVersion);
-          if (!validation.valid && !options.force) {
-            console.error(`❌ Version validation failed: ${validation.error}`);
-            return;
-          }
-
-          if (validation.warning && !options.force) {
-            console.log(`⚠️  Warning: ${validation.warning}`);
-            console.log('   Use --force to install anyway.');
-            return;
-          }
-
-          console.log(`Installing ${skillName} v${targetVersion} from registry`);
-        } else {
-          console.log(`Installing ${skillName} v${targetVersion} (local/custom)`);
-        }
+      } catch (error) {
+        console.error(`❌ Failed to install ${skillName}:`, error);
+      }
+    });
+}
+
+/**
+ * 检测 skill 类型
+ */
+function detectSkillType(skillName) {
+  if (skillName.startsWith('team://')) {
+    return 'team';
+  } else if (skillName.startsWith('./') || skillName.startsWith('../')) {
+    return 'local';
+  } else {
+    // anthropics/skills/pdf, @skillforge/xxx
+    return 'public';
+  }
+}
+
+/**
+ * 安装公开 skill（使用 openskills）
+ */
+async function installPublicSkill(skillName, options, localManager, lockfileManager) {
+  console.log(`📦 Installing public skill: ${skillName}`);
+  console.log(`💡 Using openskills install...\n`);
+
+  try {
+    // 调用 openskills install
+    const cmd = `npx openskills install ${skillName}`;
+    execSync(cmd, { stdio: 'inherit' });
+
+    // 更新 lockfile
+    lockfileManager.updateSkill(skillName, {
+      version: options.version || 'latest',
+      source: 'public',
+      installedAt: new Date().toISOString()
+    });
 
-        // Create sample SKILL.md content
-        const skillMdContent = `---
+    await lockfileManager.save();
+
+    console.log(`\n✅ Successfully installed public skill: ${skillName}`);
+    console.log(`💡 Run 'joySkills sync' to update AGENTS.md`);
+
+  } catch (error) {
+    throw new Error(`openskills install failed: ${error.message}`);
+  }
+}
+
+/**
+ * 安装团队 skill（从团队 Registry）
+ */
+async function installTeamSkill(skillName, options, projectRoot, localManager, lockfileManager) {
+  console.log(`🏢 Installing team skill: ${skillName}`);
+
+  // Check for registry
+  let registryManager = null;
+  const registryPath = path.join(projectRoot, '.joyskill/registry');
+
+  if (fs.existsSync(registryPath)) {
+    try {
+      registryManager = new RegistryManager(registryPath);
+      await registryManager.load();
+    } catch (error) {
+      console.error('Warning: Could not load registry:', error.message);
+    }
+  }
+
+  // Determine version to install
+  let targetVersion = options.version || '1.0.0';
+  let versionSource = 'default';
+
+  if (registryManager && registryManager.hasSkill(skillName)) {
+    if (!options.version) {
+      // Get recommended version from registry
+      const recommended = registryManager.getRecommendedVersion(skillName);
+      if (recommended) {
+        targetVersion = recommended.version;
+        versionSource = 'registry';
+      }
+    }
+
+    // Validate version
+    const validation = registryManager.validateVersion(skillName, targetVersion);
+    if (!validation.valid && !options.force) {
+      console.error(`❌ Version validation failed: ${validation.error}`);
+      return;
+    }
+
+    if (validation.warning && !options.force) {
+      console.log(`⚠️  Warning: ${validation.warning}`);
+      console.log('   Use --force to install anyway.');
+      return;
+    }
+
+    console.log(`Installing ${skillName} v${targetVersion} from registry`);
+  } else {
+    console.log(`Installing ${skillName} v${targetVersion} (local/custom)`);
+  }
+
+  // Create sample SKILL.md content
+  const skillMdContent = `---
 name: ${skillName}
 description: Auto-generated skill for ${skillName}
 version: ${targetVersion}
@@ -84,7 +155,7 @@ version: ${targetVersion}
 
 # ${skillName}
 
-This skill was automatically generated by joyskill.
+This skill was automatically generated by joySkills.
 
 ## Examples
 - Example usage 1
@@ -95,25 +166,58 @@ This skill was automatically generated by joyskill.
 - Guideline 2
 `;
 
-        // Install the skill
-        localManager.installSkill(skillName, skillMdContent);
+  // Install the skill
+  localManager.installSkill(skillName, skillMdContent);
 
-        // Update lockfile
-        lockfileManager.updateSkill(skillName, {
-          version: targetVersion,
-          registry: options.registry || 'local',
-          installedAt: new Date().toISOString()
-        });
+  // Update lockfile
+  lockfileManager.updateSkill(skillName, {
+    version: targetVersion,
+    source: 'team',
+    registry: options.registry || 'local',
+    installedAt: new Date().toISOString()
+  });
 
-        await lockfileManager.save();
+  await lockfileManager.save();
 
-        console.log(`✅ Successfully installed ${skillName} v${targetVersion}`);
+  console.log(`✅ Successfully installed ${skillName} v${targetVersion}`);
 
-        if (versionSource === 'registry') {
-          console.log('   Version selected from registry recommendations.');
-        }
-      } catch (error) {
-        console.error(`❌ Failed to install ${skillName}:`, error);
-      }
-    });
+  if (versionSource === 'registry') {
+    console.log('   Version selected from registry recommendations.');
+  }
+}
+
+/**
+ * 安装本地 skill（直接复制）
+ */
+async function installLocalSkill(skillName, options, localManager, lockfileManager) {
+  console.log(`📁 Installing local skill: ${skillName}`);
+
+  const sourcePath = path.resolve(skillName);
+  
+  if (!fs.existsSync(sourcePath)) {
+    throw new Error(`Local path not found: ${sourcePath}`);
+  }
+
+  const skillMdPath = path.join(sourcePath, 'SKILL.md');
+  if (!fs.existsSync(skillMdPath)) {
+    throw new Error(`SKILL.md not found in ${sourcePath}`);
+  }
+
+  const skillMdContent = fs.readFileSync(skillMdPath, 'utf-8');
+  const skillBaseName = path.basename(sourcePath);
+
+  // Install the skill
+  localManager.installSkill(skillBaseName, skillMdContent);
+
+  // Update lockfile
+  lockfileManager.updateSkill(skillBaseName, {
+    version: options.version || 'local',
+    source: 'local',
+    path: sourcePath,
+    installedAt: new Date().toISOString()
+  });
+
+  await lockfileManager.save();
+
+  console.log(`✅ Successfully installed local skill: ${skillBaseName}`);
 }

package/src/commands/read.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * joySkills read 命令
+ * 
+ * 功能：
+ * 读取指定 skill 的完整内容（YAML frontmatter + Markdown）
+ * 
+ * 设计原则：
+ * - 100% 兼容 OpenSkills read 的输出格式
+ * - 路径查找优先级与 openskills sync 一致
+ * - 供 AI 编辑器解析使用
+ * 
+ * 路径查找优先级：
+ * 1. 项目级 .agent/skills（--universal）
+ * 2. 全局 ~/.agent/skills
+ * 3. 项目级 .claude/skills（--project）
+ * 4. 全局 ~/.claude/skills（--global）
+ */
+
+export async function readCommand(skillName) {
+  if (!skillName) {
+    console.error('❌ 错误：请指定要读取的 skill 名称');
+    console.log('\n用法: joySkills read <skill-name>\n');
+    console.log('示例: joySkills read rc-onboarding\n');
+    process.exit(1);
+  }
+
+  try {
+    // 查找 skill 路径
+    const skillPath = findSkillPath(skillName);
+    
+    if (!skillPath) {
+      console.error(`❌ 找不到 skill: ${skillName}`);
+      console.log('\n💡 提示:');
+      console.log(`   1. 检查 skill 名称是否正确`);
+      console.log(`   2. 执行 joySkills list 查看已安装的 skills\n`);
+      process.exit(1);
+    }
+
+    // 读取 SKILL.md
+    const skillMdPath = path.join(skillPath, 'SKILL.md');
+    if (!fs.existsSync(skillMdPath)) {
+      console.error(`❌ ${skillName} 缺少 SKILL.md 文件`);
+      process.exit(1);
+    }
+
+    const content = fs.readFileSync(skillMdPath, 'utf-8');
+    
+    // 输出到 stdout（供 AI 编辑器解析）
+    console.log(content);
+
+  } catch (error) {
+    console.error('❌ 读取失败:', error.message);
+    process.exit(1);
+  }
+}
+
+/**
+ * 查找 skill 路径（按优先级）
+ * 
+ * 优先级与 OpenSkills sync 一致：
+ * 1. 项目 .agent > 全局 .agent
+ * 2. 项目 .claude > 全局 .claude
+ */
+function findSkillPath(skillName) {
+  const homeDir = process.env.HOME || process.env.USERPROFILE;
+  const cwd = process.cwd();
+
+  const searchPaths = [
+    // 1. 项目级 .agent/skills（joySkills 默认 / OpenSkills --universal）
+    path.join(cwd, '.agent', 'skills', skillName),
+    
+    // 2. 全局 ~/.agent/skills（joySkills --global）
+    path.join(homeDir, '.agent', 'skills', skillName),
+    
+    // 3. 项目级 .claude/skills（OpenSkills --project）
+    path.join(cwd, '.claude', 'skills', skillName),
+    
+    // 4. 全局 ~/.claude/skills（OpenSkills --global）
+    path.join(homeDir, '.claude', 'skills', skillName),
+  ];
+
+  for (const searchPath of searchPaths) {
+    if (fs.existsSync(searchPath)) {
+      return searchPath;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * 列出所有可读取的 skills（辅助命令）
+ */
+export function listReadableSkills() {
+  const homeDir = process.env.HOME || process.env.USERPROFILE;
+  const cwd = process.cwd();
+
+  const searchDirs = [
+    path.join(cwd, '.agent', 'skills'),
+    path.join(homeDir, '.agent', 'skills'),
+    path.join(cwd, '.claude', 'skills'),
+    path.join(homeDir, '.claude', 'skills'),
+  ];
+
+  const skills = new Set();
+
+  for (const dir of searchDirs) {
+    if (!fs.existsSync(dir)) continue;
+
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+
+      const skillMdPath = path.join(dir, entry.name, 'SKILL.md');
+      if (fs.existsSync(skillMdPath)) {
+        skills.add(entry.name);
+      }
+    }
+  }
+
+  return Array.from(skills).sort();
+}

package/src/commands/sync.js

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * joySkills sync 命令
+ * 
+ * 功能：
+ * 1. 扫描 skills/ 目录
+ * 2. 生成/更新 AGENTS.md（与 openskills sync 格式一致）
+ * 3. 更新 joySkills.lock（记录扫描到的所有 skill）
+ * 4. 验证版本一致性
+ * 
+ * 设计原则：
+ * - 100% 兼容 OpenSkills 生成的 AGENTS.md
+ * - 在 OpenSkills 基础上增强（版本锁定 + 一致性检查）
+ */
+
+export async function syncCommand() {
+  console.log('🔄 正在同步 skills 到 AGENTS.md...\n');
+
+  try {
+    // 1. 扫描所有可能的 skills 目录（按优先级）
+    const cwd = process.cwd();
+    const homeDir = process.env.HOME || process.env.USERPROFILE;
+    
+    const searchDirs = [
+      path.join(cwd, '.agent', 'skills'),      // joySkills 项目级
+      path.join(homeDir, '.agent', 'skills'),  // joySkills 全局
+      path.join(cwd, '.claude', 'skills'),     // OpenSkills --project
+      path.join(homeDir, '.claude', 'skills'), // OpenSkills --global
+    ];
+
+    const allSkills = [];
+    for (const dir of searchDirs) {
+      if (fs.existsSync(dir)) {
+        const skills = scanSkills(dir);
+        allSkills.push(...skills);
+      }
+    }
+
+    // 去重（按 id）
+    const uniqueSkills = [];
+    const seenIds = new Set();
+    for (const skill of allSkills) {
+      if (!seenIds.has(skill.id)) {
+        seenIds.add(skill.id);
+        uniqueSkills.push(skill);
+      }
+    }
+
+    console.log(`📦 扫描到 ${uniqueSkills.length} 个 skills:\n`);
+    uniqueSkills.forEach(skill => {
+      console.log(`   - ${skill.id} (${skill.version || 'unknown'})`);
+    });
+    console.log('');
+
+    // 2. 生成 AGENTS.md（OpenSkills 兼容格式）
+    const agentsMdContent = generateAgentsMd(uniqueSkills);
+    const agentsMdPath = path.join(process.cwd(), 'AGENTS.md');
+    fs.writeFileSync(agentsMdPath, agentsMdContent, 'utf-8');
+    console.log(`✅ 已生成 AGENTS.md\n`);
+
+    // 3. 更新 joySkills.lock（joySkills 增强功能）
+    await updateLockfile(uniqueSkills);
+
+    // 4. 验证版本一致性（joySkills 增强功能）
+    await verifyConsistency(uniqueSkills);
+
+    console.log('✨ 同步完成！\n');
+    console.log('💡 提示：');
+    console.log('   - AGENTS.md 已生成，AI 编辑器会自动识别');
+    console.log('   - joySkills.lock 已更新，确保版本锁定\n');
+
+  } catch (error) {
+    console.error('❌ 同步失败:', error.message);
+    process.exit(1);
+  }
+}
+
+/**
+ * 扫描 skills 目录
+ */
+function scanSkills(skillsDir) {
+  const skills = [];
+  const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+
+    const skillPath = path.join(skillsDir, entry.name);
+    const skillMdPath = path.join(skillPath, 'SKILL.md');
+
+    if (!fs.existsSync(skillMdPath)) {
+      console.log(`⚠️  跳过 ${entry.name}（缺少 SKILL.md）`);
+      continue;
+    }
+
+    // 解析 SKILL.md
+    const skillContent = fs.readFileSync(skillMdPath, 'utf-8');
+    const metadata = parseSkillMetadata(skillContent);
+
+    skills.push({
+      id: entry.name,
+      path: skillPath,
+      ...metadata
+    });
+  }
+
+  return skills;
+}
+
+/**
+ * 解析 SKILL.md 的 YAML frontmatter
+ */
+function parseSkillMetadata(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return {};
+
+  const yaml = match[1];
+  const metadata = {};
+
+  // 简单的 YAML 解析（关键字段）
+  const lines = yaml.split('\n');
+  for (const line of lines) {
+    const [key, ...valueParts] = line.split(':');
+    if (!key || !valueParts.length) continue;
+
+    const value = valueParts.join(':').trim().replace(/^["']|["']$/g, '');
+    metadata[key.trim()] = value;
+  }
+
+  return metadata;
+}
+
+/**
+ * 生成 AGENTS.md（OpenSkills 兼容格式）
+ */
+function generateAgentsMd(skills) {
+  let content = `# AI Agent Skills\n\n`;
+  content += `> 此文件由 joySkills sync 自动生成\n`;
+  content += `> 兼容 OpenSkills 格式，所有 AI 编辑器均可识别\n\n`;
+
+  content += `## 已安装的 Skills (${skills.length})\n\n`;
+
+  for (const skill of skills) {
+    content += `### ${skill.name || skill.id}\n\n`;
+    content += `**ID**: \`${skill.id}\`\n`;
+    if (skill.version) {
+      content += `**Version**: ${skill.version}\n`;
+    }
+    if (skill.description) {
+      content += `**Description**: ${skill.description}\n`;
+    }
+    content += `**Path**: \`skills/${skill.id}\`\n\n`;
+
+    // 添加 XML 片段（供 AI 编辑器解析）
+    content += `\`\`\`xml\n`;
+    content += `<skill id="${skill.id}">\n`;
+    content += `  <name>${skill.name || skill.id}</name>\n`;
+    if (skill.version) {
+      content += `  <version>${skill.version}</version>\n`;
+    }
+    content += `  <path>skills/${skill.id}/SKILL.md</path>\n`;
+    content += `</skill>\n`;
+    content += `\`\`\`\n\n`;
+  }
+
+  content += `---\n\n`;
+  content += `生成时间: ${new Date().toISOString()}\n`;
+  content += `生成工具: joySkills ${getVersion()}\n`;
+
+  return content;
+}
+
+/**
+ * 更新 joySkills.lock（joySkills 增强功能）
+ */
+async function updateLockfile(skills) {
+  const lockfilePath = path.join(process.cwd(), 'joySkills.lock');
+  
+  let lockData = {
+    lockVersion: 1,
+    projectId: path.basename(process.cwd()),
+    generatedAt: new Date().toISOString(),
+    skills: {}
+  };
+
+  // 读取现有 lockfile
+  if (fs.existsSync(lockfilePath)) {
+    const existingContent = fs.readFileSync(lockfilePath, 'utf-8');
+    try {
+      lockData = JSON.parse(existingContent);
+    } catch (e) {
+      console.log('⚠️  joySkills.lock 格式错误，将重新生成');
+    }
+  }
+
+  // 更新 skills 信息
+  for (const skill of skills) {
+    const existingSkill = lockData.skills[skill.id] || {};
+    
+    lockData.skills[skill.id] = {
+      version: skill.version || existingSkill.version || 'unknown',
+      installedAt: existingSkill.installedAt || new Date().toISOString(),
+      lastSyncAt: new Date().toISOString()
+    };
+  }
+
+  // 写入 lockfile
+  fs.writeFileSync(
+    lockfilePath,
+    JSON.stringify(lockData, null, 2),
+    'utf-8'
+  );
+
+  console.log('✅ 已更新 joySkills.lock');
+}
+
+/**
+ * 验证版本一致性（joySkills 增强功能）
+ */
+async function verifyConsistency(skills) {
+  const lockfilePath = path.join(process.cwd(), 'joySkills.lock');
+  if (!fs.existsSync(lockfilePath)) return;
+
+  const lockData = JSON.parse(fs.readFileSync(lockfilePath, 'utf-8'));
+  let hasWarning = false;
+
+  for (const skill of skills) {
+    const lockedSkill = lockData.skills[skill.id];
+    if (!lockedSkill) continue;
+
+    if (skill.version && lockedSkill.version !== skill.version) {
+      if (!hasWarning) {
+        console.log('\n⚠️  版本不一致警告:\n');
+        hasWarning = true;
+      }
+      console.log(`   ${skill.id}:`);
+      console.log(`   - Lock 文件: ${lockedSkill.version}`);
+      console.log(`   - 实际版本: ${skill.version}`);
+      console.log(`   💡 建议: joySkills upgrade ${skill.id}\n`);
+    }
+  }
+
+  if (!hasWarning) {
+    console.log('✅ 版本一致性检查通过');
+  }
+}
+
+/**
+ * 获取 joySkills 版本
+ */
+function getVersion() {
+  try {
+    const packagePath = path.join(__dirname, '../../package.json');
+    const pkg = JSON.parse(fs.readFileSync(packagePath, 'utf-8'));
+    return pkg.version;
+  } catch (e) {
+    return 'unknown';
+  }
+}

package/src/index.js

@@ -7,6 +7,8 @@ import { removeCommand } from './commands/remove.js';
 import { teamCommand } from './commands/team.js';
 import { auditCommand } from './commands/audit.js';
 import { statusCommand } from './commands/status.js';
+import { syncCommand } from './commands/sync.js';
+import { readCommand } from './commands/read.js';
 
 const program = new Command();
 
@@ -23,5 +25,16 @@ teamCommand(program);
 auditCommand(program);
 statusCommand(program);
 
+// OpenSkills compatible commands
+program
+  .command('sync')
+  .description('Sync skills to AGENTS.md (OpenSkills compatible)')
+  .action(syncCommand);
+
+program
+  .command('read <skill-name>')
+  .description('Read skill content (OpenSkills compatible)')
+  .action(readCommand);
+
 // Parse arguments
 program.parse();

package/src/local.js

@@ -3,15 +3,22 @@ import * as path from 'path';
 import { LocalSkill } from './types.js';
 
 export class LocalManager {
-  constructor(projectRoot) {
+  constructor(projectRoot, options = {}) {
     this.projectRoot = projectRoot;
+    this.global = options.global || false;
   }
 
   /**
    * Get local skills directory path
+   * 默认项目级：.agent/skills
+   * 全局：~/.agent/skills
    */
   getSkillsDir() {
-    return path.join(this.projectRoot, 'skills');
+    if (this.global) {
+      const homeDir = process.env.HOME || process.env.USERPROFILE;
+      return path.join(homeDir, '.agent', 'skills');
+    }
+    return path.join(this.projectRoot, '.agent', 'skills');
   }
 
   /**