Skillsmith

Skillsmith

共享技能，为生产环境保驾护航。

当不止一个团队开始发布 Agent 技能时，问题就不再是如何找到它们，而是如何管理它们。这些技能面向哪个团队？哪些位置安装了哪个版本？它们是否已被安全扫描标记？对于无人维护的技能，该如何处理？

Skillsmith 是一个用于在团队间共享、扫描和跟踪 Agent 技能的注册表。技能会发布到面向团队的注册表，并采用不可变版本管理，因此安装之间的版本偏差会清晰可见，而不是悄无声息。被标记或可疑的技能会被隔离，等待安全审查。对于逐渐过时的技能，可以将其弃用，而不是任由它们在某人的代码库中悄然腐朽。

安装

快速设置（MCP）

Skillsmith 兼容 MCP——选择适用于你的 Agent 的代码片段。 SMI-4580：代码片段取自 packages/cli/src/templates/mcp-server.template.snippets.ts，确保此 README 与网站文档保持一致。

{
  "mcpServers": {
    "@skillsmith/mcp-server": {
      "command": "npx",
      "args": ["-y", "@skillsmith/mcp-server"],
      "env": {
        "SKILLSMITH_API_KEY": "sk_live_..."
      }
    }
  }
}

{
  "mcpServers": {
    "@skillsmith/mcp-server": {
      "command": "<paste output of: which skillsmith-mcp (macOS/Linux) or where skillsmith-mcp (Windows)>",
      "env": {
        "SKILLSMITH_API_KEY": "sk_live_...",
        "SKILLSMITH_CLIENT": "cursor"
      }
    }
  }
}

{
  "mcpServers": {
    "@skillsmith/mcp-server": {
      "command": "npx",
      "args": ["-y", "@skillsmith/mcp-server"],
      "env": {
        "SKILLSMITH_API_KEY": "sk_live_..."
      }
    }
  }
}

{
  "mcpServers": {
    "@skillsmith/mcp-server": {
      "command": "npx",
      "args": ["-y", "@skillsmith/mcp-server"],
      "env": {
        "SKILLSMITH_API_KEY": "${env:SKILLSMITH_API_KEY}"
      }
    }
  }
}

[mcp_servers.@skillsmith/mcp-server]
command = "npx"
args = ["-y", "@skillsmith/mcp-server"]

[mcp_servers.@skillsmith/mcp-server.env]
SKILLSMITH_API_KEY = "sk_live_..."

{
  "mcpServers": {
    "@skillsmith/mcp-server": {
      "command": "npx",
      "args": ["-y", "@skillsmith/mcp-server"],
      "env": {
        "SKILLSMITH_API_KEY": "sk_live_..."
      }
    }
  }
}

将配置添加到 MCP 客户端设置并重启后，即可立即搜索技能。

API 密钥配置（可选）

如需更高的速率限制和用量跟踪，请使用 API 密钥进行身份验证。

最简单的方式 — 使用 CLI 登录（交互式）：

npm install -g @skillsmith/cli
skillsmith login

这会在浏览器中打开 skillsmith.app/account/cli-token。生成密钥、复制，然后在提示时粘贴。密钥会安全地存储在操作系统密钥环中。

MCP 服务配置 — 将密钥添加到设置中：

上方针对各客户端的代码片段已经包含 env.SKILLSMITH_API_KEY 槽位 — 将 sk_live_... 占位符替换为 skillsmith login 返回的值。

在 skillsmith.app/account/cli-token 获取 API 密钥。

配额说明： 月度配额仅在启用强制执行时才是硬性限制。边缘函数仅对社区版强制执行月度配额，且只有在 ENFORCE_COMMUNITY_QUOTA 为 'true' 时才会启用。MCP 服务自身的月度配额仅统计 skill_suggest 和受套餐等级限制的工具，并默认对这些工具实施硬性限制（SKILLSMITH_ENFORCE_MCP_QUOTA=false 可关闭此限制）。

如果未设置密钥，MCP 服务会回退到内置公钥，因此无密钥的 MCP 使用受社区速率限制，并与其他所有无密钥客户端共用每个边缘端点（search、get、recommend 等）一个 30 次/分钟的额度桶。每个 IP 的 10 次试用（100 次/分钟）适用于未能成功通过身份验证的直接 HTTP 请求，包括凭据格式错误或已过期的请求；正常的无密钥 MCP 请求会使用内置密钥通过身份验证，不会触发此限制。启用后，该共用密钥还可能受每个 IP 的每日额度限制（ENFORCE_ANON_BUDGET；默认关闭）。

注意： 切勿在聊天中粘贴 API 密钥。请仅通过 settings.json 配置。

CLI 安装（开发）

CLI 可用于本地开发：

# From the repository root
npm run build
node packages/cli/dist/index.js search "testing"

四个问题

当不止一个团队在发布技能时，以下问题至关重要：

1. 这是为哪个团队设置的范围？ 注册表中的每项技能都限定在某个团队范围内。
2. 这里安装的是哪个版本？ 版本不可变；skill_diff（个人版）和 skill_outdated 会报告运行它们的机器上已安装内容的偏差。
3. 它是否已被安全扫描标记？ 从公共索引获取的技能会自动评分；被标记或可疑的技能会被隔离，等待审核 — 未被标记不代表经过正式批准。每项技能都有八个信任等级之一，从官方到未验证（安全指南）。
4. 对于无人维护的技能，会如何处理？ 过时的技能可以弃用，而不是任其在某人的代码仓库中悄然腐朽。

工作原理

• 发布 — 技能会发布到限定在团队范围内的注册表中，并以不可变版本进行管理。
• 版本管理 — 每次发布都会创建一个新的不可变版本；不会就地覆盖任何内容。
• 偏差检测 — skill_diff（个人版）和 skill_outdated 会在检查时显示已安装的内容以及落后的部分。
• 弃用 — 过时的技能可以弃用，而不是任其在某人的代码仓库中悄然腐朽。

范围与权限

技能限定在团队的注册表范围内。团队所有者和管理员可以控制谁能发布和管理技能；成员可以安装和搜索。

从个人使用开始

免费为自己搜索、安装和管理技能。当团队需要使用同一项技能时，注册表已经就绪。

MCP 工具

Skillsmith 注册了 43 个工具。其中 43 个工具里有 19 个可在免费社区版中使用。更高等级增加版本跟踪、团队功能和企业控制。超出你当前等级的工具会返回升级提示。定价。

社区版（免费）

个人版

团队版

Enterprise

自动会话启动命名空间审计是 Team 和 Enterprise 功能。上述审计和重命名工具可在任何套餐中手动运行。

以本地优先为设计理念。 Skillsmith 会将注册表缓存到本地 SQLite 数据库 ~/.skillsmith/skills.db，供 MCP 服务、CLI 和 VS Code 扩展共享。默认使用 FTS5（SQLite 内置的关键词搜索）进行搜索；语义搜索为可选功能（SKILLSMITH_USE_HNSW=true），基于本地 ONNX 嵌入运行（这是一种可在 CPU 上运行的开源 ML 模型格式，无需 API 调用）。本地技能数据库内部机制介绍了架构、FTS5 / HNSW 搜索路径，以及 sync（Team+ 套餐功能）如何保持缓存最新。

架构

Skillsmith 使用 Model Context Protocol（MCP）：

┌─────────────────────────────────────────────────────┐
│  MCP Client (Claude Code, Cursor, etc.)             │
│  ┌─────────────────────────────────────────────────┐│
│  │  Skillsmith MCP Server                          ││
│  │  └── @skillsmith/mcp-server                     ││
│  │      ├── search, get_skill, skill_compare       ││
│  │      ├── install_skill, uninstall_skill         ││
│  │      ├── skill_recommend, skill_validate        ││
│  │      ├── skill_outdated, skill_diff, ...        ││
│  │      └── 43 tools across four tiers             ││
│  └─────────────────────────────────────────────────┘│
│                          │                          │
│                          ▼                          │
│  ┌─────────────────────────────────────────────────┐│
│  │  ~/.skillsmith/skills.db (SQLite + FTS5)        ││
│  │  ~/.claude/skills/ (installed skills)           ││
│  └─────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────┘

使用方法

配置完成后，MCP 客户端即可使用 Skillsmith 工具：

"Search for testing skills"
→ Uses search tool to find testing-related skills

"Show me details for community/jest-helper"
→ Uses get_skill tool to retrieve full skill information

"Install the jest-helper skill"
→ Uses install_skill tool to add it to ~/.claude/skills

"Compare jest-helper and vitest-helper"
→ Uses skill_compare tool to show side-by-side comparison

"Are any of my installed skills out of date?"
→ Uses skill_outdated tool to check for staleness and missing dependencies

"Do any of my skills clash with each other?"
→ Uses skill_inventory_audit tool to find name collisions and suggest renames

CLI 用法（开发）

# From the repository, after building
node packages/cli/dist/index.js search "testing" --tier verified --min-score 80
node packages/cli/dist/index.js get community/jest-helper
node packages/cli/dist/index.js install community/jest-helper

文档

• 安全指南 - 了解技能信任、安全性和防护措施
• 5 分钟快速设置 - 快速入门指南
• 配置指南 - 完整的设置和使用说明
• 状态 - Skillsmith 核心服务的实时状态和正常运行时间历史记录

开发

Skillsmith 采用 Docker 优先开发。所有命令都在 Docker 内运行，以确保所有平台上的原生模块支持一致。

前置条件

• Docker Desktop（v24+）或带有 Docker Compose 的 Docker Engine
• Git（用于克隆仓库）
• Node.js（可选，仅用于 Docker 外的本地工具）

快速开始

# 1. Clone the repository
git clone https://github.com/smith-horn/skillsmith.git
cd skillsmith

# 2. Create your local environment file
cp .env.example .env

# 3. Start the development container
docker compose --profile dev up -d

# 4. Install dependencies (first time only)
docker exec -w /app skillsmith-dev-1 sh -c 'sh scripts/lib/node-modules-mount-gate.sh && npm install'

# 5. Build and test
docker exec skillsmith-dev-1 npm run build
docker exec skillsmith-dev-1 npm test

在 Docker 中运行命令

所有 npm 命令都应在 Docker 容器内运行：

容器管理

# Start development container
docker compose --profile dev up -d

# Check container status
docker ps | grep skillsmith

# View container logs
docker logs skillsmith-dev-1

# Stop container
docker compose --profile dev down

# Restart after Dockerfile changes
docker compose --profile dev down
docker compose --profile dev build --no-cache
docker compose --profile dev up -d

拉取更改后

拉取更改后，如果 package.json 或 package-lock.json 有修改：

docker exec -w /app skillsmith-dev-1 sh -c 'sh scripts/lib/node-modules-mount-gate.sh && npm install'
docker exec skillsmith-dev-1 npm run build

故障排查

容器无法启动

docker compose --profile dev down
docker volume rm skillsmith_node_modules
docker compose --profile dev up -d

擦除操作不会阻止容器通过入口点的 node_modules 预检查启动——根卷会从镜像重新填充，因此检查会通过，而不是导致退出（SMI-6674）；后续启动步骤则另当别论。擦除操作会留下混杂的依赖状态，因此不要紧接着直接运行安装命令。请打印并遵循有序的刷新流程（ADR-158；SMI-6614）：

( cd <main-checkout-path> && sh scripts/lib/print-deps-refresh-advice.sh <main-checkout-path> )

原生模块错误（ERR_DLOPEN_FAILED）

better-sqlite3 和 onnxruntime-node 等原生模块可能需要重新构建：

docker exec -w /app skillsmith-dev-1 sh -c 'sh scripts/lib/node-modules-mount-gate.sh && npm rebuild'

测试因共享库错误而失败

如果看到有关 ld-linux-aarch64.so.1 或类似内容的错误，请确保在 Docker 中运行（而非本地运行）：

# Wrong - don't run locally
npm test

# Correct - run in Docker
docker exec skillsmith-dev-1 npm test

为什么使用 Docker？

Skillsmith 使用需要 glibc 的原生 Node.js 模块（better-sqlite3、onnxruntime-node）。Docker 提供了基于 Debian 且包含 glibc 的一致环境，可避免在使用 musl libc 的系统（如 Alpine Linux）上出现兼容性问题。

如需了解完整的开发工作流和技能配置，请参阅 CLAUDE.md。

技术栈

• 运行时：Node.js >=22.22（使用 glibc 的 Docker）
• 协议：MCP（Model Context Protocol）
• 数据库：SQLite 和 FTS5
• 嵌入模型：通过 onnxruntime-node 使用 all-MiniLM-L6-v2
• 测试：Vitest
• CI/CD：GitHub Actions

许可证

Skillsmith 根据 Elastic License 2.0 提供源代码。

你可以：

• 将 Skillsmith 用于个人或内部业务用途
• 修改源代码供自己使用
• 为团队自托管
• 贡献错误修复和改进

你不可以：

• 将 Skillsmith 作为托管服务提供给第三方
• 绕过许可证密钥强制执行功能

完整许可证文本请参阅 LICENSE 文件。

作者

Smith Horn Group Ltd

Skillsmith 与 Anthropic 无关。Claude 和 Claude Code 是 Anthropic 的商标。