joySkills - OpenSkills 的增强替代品

> 100% 兼容 OpenSkills + 团队协作增强（版本锁定、团队 Registry、安全审计）


🔗 Links: npm Package | Git Repository

💡 为什么选择 joySkills？

joySkills 是 OpenSkills 的超集，提供：

$3

- ✅ 安装公开 skill（调用 openskills install）
- ✅ 生成 AGENTS.md（joySkills sync = openskills sync + 增强）
- ✅ 读取 skill 内容（joySkills read = openskills read）
- ✅ 100% 兼容 Claude Code / Cursor / Windsurf

$3

- ✅ 版本锁定：joySkills.lock 确保团队版本统一
- ✅ 团队 Registry：从 Git 仓库安装内部 skill
- ✅ 安全审计：自动检测废弃和有风险的 skill
- ✅ 状态管理：draft → review → approved → deprecated

✨ 核心特性

$3

``bash

安装公开 skill

joySkills install anthropics/skills/pdf

安装内部 skill（需配置 Registry）

joySkills install team://your-team/rc-onboarding

统一同步

joySkills sync # 生成 AGENTS.md + joySkills.lock
`

核心价值：
- ✅ 公开 + 内部 skill 统一管理，一个命令搞定
- ✅ 版本锁定（joySkills.lock），团队环境一致
- ✅ 100% 兼容 OpenSkills，随时可回退

路径设计：
| 安装方式 | joySkills | OpenSkills |
|---------|-----------|------------|
| 项目级 | .agent/skills | .agent/skills (--universal) |
| 全局 | ~/.agent/skills | ~/.claude/skills (--global) |

优先级：项目级 > 全局，不同项目可用不同版本

$3

- 项目级版本锁定，确保环境一致
- 自动记录安装历史
- 支持 semver 版本策略

$3

- draft → pending_review → approved → deprecated → archived
- 完整的状态机管理
- CI/CD 友好

$3

- public / restricted / internal 三级可见性
- 基于角色的访问控制（RBAC）
- 与 Git 权限无缝集成

$3

- 实时监控 skill 使用情况
- 安全风险预警
- 自动生成升级建议

$3

`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 一致

✅ 输出格式完全相同

`

🚀 快速开始

$3

`bash


1. 安装

npm install -g joyskills-cli

2. 安装公开 skill

joySkills install anthropics/skills/pdf
joySkills install @skillforge/code-review

3. 生成 AGENTS.md

joySkills sync

4. 查看已安装

joySkills list
`

$3

痛点：
- 😓 内部 skill 群里发 zip，手动下载 + 解压
- 😓 新人 onboarding，问“哪些 skill 必须装”
- 😓 skill 更新后，通知所有人重新下载

解决方案：
`bash


1. Tech Lead 搭建团队 Registry（Git 仓库）

mkdir team-skills && cd team-skills
mkdir rc-onboarding rc-commit-lint

将 SKILL.md 放入对应目录

git init && git add . && git commit -m "init"
git remote add origin https://git.yourcompany.com/team-skills.git
git push

2. 团队成员配置（一次）

cat > .joyskillrc << 'EOF'
{
"registries": [{
"id": "team://your-team",
"url": "https://git.yourcompany.com/team-skills.git",
"type": "git"
}]
}
EOF

3. 安装 skill（像 npm 一样）

joySkills install team://your-team/rc-onboarding
joySkills install team://your-team/rc-commit-lint
joySkills sync

4. 团队同步（自动化）

git add AGENTS.md joySkills.lock .joyskillrc
git commit -m "setup team skills"
git push

5. 新成员加入（1 分钟）

git clone
joySkills install # 自动安装所有锁定版本
`

效果对比：
| 场景 | 之前 | 现在 |
|------|------|------|
| 新人 onboarding | 群里找 8 个 zip，手动装（30分钟） | joySkills install（1分钟） |
| skill 更新 | 群发通知 + 手动更新（15分钟） | git pull && joySkills install（1分钟） |
| 版本不一致 | 频繁出现，难排查 | joySkills.lock 锁定，不会出现 |

$3

`bash


已经用 openskills 安装了很多 skills

openskills install skill-a
openskills install skill-b

切换到 joySkills（无需重装）

joySkills sync

✅ 自动识别已有 skills

✅ 生成 joySkills.lock

✅ 后续用 joySkills install 安装新 skill

`

📋 完整命令参考

$3

#### joySkills sync
生成 AGENTS.md（100% 兼容 openskills sync + 增强）

`bash
joySkills sync


✅ 扫描 .agent/skills, ~/.agent/skills, .claude/skills, ~/.claude/skills

✅ 生成 AGENTS.md（OpenSkills 兼容格式）

✅ 生成 joySkills.lock（版本锁定）

✅ 版本一致性检查

`

#### joySkills read
读取 skill 内容（100% 兼容 openskills read）

`bash
joySkills read rc-onboarding


✅ 路径查找优先级与 openskills 一致

✅ 输出格式完全相同

`

$3

#### joySkills install
安装 skill（公开 + 团队 + 本地）

`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 list
列出可用的 skills

`bash
joySkills list
joySkills list --installed # 只显示已安装
joySkills list --search "web" # 搜索
`

#### joySkills remove
删除已安装的 skill

`bash
joySkills remove rc-onboarding
`

#### joySkills team
管理团队 registry

`bash
joySkills team add my-team /path/to/registry
joySkills team list
joySkills team remove my-team
`

#### joySkills status
显示当前项目的 skills 状态

`bash
joySkills status
`

#### joySkills audit
审计已安装 skills 的安全性和弃用状态

📖 核心概念

$3

Registry 是团队统一管理 skill 的 Git 仓库，像 npm 私有源一样。

目录结构：
`
team-skills/ # Git 仓库
├── registry.yaml # 版本配置（可选）
├── rc-onboarding/
│ ├── SKILL.md # 必须
│ ├── scripts/ # 可选：脚本
│ └── templates/ # 可选：模板
└── rc-commit-lint/
└── SKILL.md
`

registry.yaml 示例（可选，用于版本管理）：
`yaml
registryVersion: 1
registryId: team://your-team
skills:
- id: rc-onboarding
name: "搜推团队 Onboarding"
visibility: internal # internal / public / restricted
versions:
- version: 1.2.0
state: approved # draft / pending_review / approved / deprecated
recommended: true
- version: 1.1.0
state: deprecated
`

使用场景：
- ✅ 内部业务 skill（如 rc-onboarding、rc-commit-lint）
- ✅ 公司级通用 skill（如 code-review、test-helper）
- ✅ 项目级定制 skill（如 project-specific-tools）

$3

项目级锁文件，记录实际使用的 skill 版本：

`yaml
lockVersion: 1
projectId: "your-project"
skills:
web-search:
version: 1.2.0
registry: team://your-team
installedAt: 2026-02-02T10:00:00Z
`

$3

`
draft → pending_review → approved → deprecated → archived
↓ ↓ ↓ ↓ ↓
开发中 待审核 可用 不推荐 归档
`

🏗️ 项目结构

`
joySkills/
├── src/
│ ├── index.js # CLI 入口点
│ ├── types.js # 类型定义
│ ├── registry.js # Registry 管理
│ ├── lockfile.js # 锁文件操作
│ ├── local.js # 本地 skill 管理
│ └── commands/ # CLI 命令
│ ├── list.js # 列出 skills
│ ├── install.js # 安装 skill
│ ├── remove.js # 删除 skill
│ ├── team.js # Registry 管理
│ ├── status.js # 状态检查
│ └── audit.js # 安全审计
├── spec/ # 规范文档
│ ├── cli-spec.md # CLI 规范
│ ├── registry-spec.md # Registry 规范
│ └── lockfile-spec.md # 锁文件规范
├── test/ # 测试文件
├── .joyskill/ # 示例 registry
├── package.json
├── INSTALL.md
└── README.md
`

🤝 贡献指南

$3

`bash


克隆仓库

git clone https://github.com/your-org/joyskills-cli.git
cd joyskills-cli

安装依赖

npm install

本地开发链接

npm link

测试命令

joySkills --version
joySkills list
`

$3

`bash


运行 registry 测试

node test/test-registry.js

测试 CLI 命令

joySkills list --search "test"
joySkills list --category "utility"
``

📝 License

MIT © joySkills Team