# https://github.com/goldzulu/skill-loader-mcp-server 项目说明书
生成时间：2026-05-13 18:01:33 UTC
## 目录
- [项目介绍](#page-project-intro)
- [MCP工具详解](#page-mcp-tools)
- [核心模块架构](#page-core-modules)
- [类型定义系统](#page-type-system)
- [技能解析器](#page-skill-resolver)
- [技能获取器](#page-skill-fetcher)
- [转换引擎](#page-conversion-engine)
- [安全验证器](#page-security-validator)
- [缓存机制](#page-caching)
- [命令行工具](#page-cli-usage)
## 项目介绍
### 相关页面
相关主题：[MCP工具详解](#page-mcp-tools)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)
- [examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)
- [src/core/conversion-engine.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)
- [src/core/security-validator.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)
- [src/core/errors.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts)
- [CHANGELOG.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CHANGELOG.md)
- [CONTRIBUTING.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CONTRIBUTING.md)
# 项目介绍
## 概述
Skill Loader MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器项目，用于管理 Claude Skills 的导入、转换和验证工作流。该项目由 GoldZulu 开发维护，提供了与 skills.sh 市场平台集成的完整工具链，使用户能够安全地发现、获取和导入 Claude 技能。资料来源：[README.md:1]()
## 核心功能
### 技能发现与管理
该项目支持从 skills.sh 平台发现和管理 Claude Skills，提供以下核心能力：
- **技能搜索**：通过关键词搜索 skills.sh 目录，无需 API 密钥即可使用
- **技能列表**：分页浏览所有可用技能，需要 API 密钥
- **排行榜**：获取热门或安装量最高的技能，支持 24 小时和全部时间维度
资料来源：[README.md:35-50]()
### 安全验证
内置多层安全验证机制，确保导入的技能不会危害系统安全：
- **危险命令检测**：识别 `rm -rf`、`sudo`、`eval`、`exec` 等高风险命令
- **可疑文件操作检测**：检测访问 `/etc/`、`/usr/`、`/bin/` 等系统目录的操作
- **代码注入防护**：识别 `${...}` 和 `$(...)` 等代码注入模式
- **来源验证**：仅允许来自 GitHub 的可信来源
资料来源：[src/core/security-validator.ts:1-50]()
### 格式转换
支持将 Claude Skills 转换为 Kiro 平台支持的两种格式：
| 格式类型 | 描述 | 输出文件 |
|---------|------|---------|
| Steering | Kiro 转向文件格式 | `.kiro/steering/{skill-name}.md` |
| Power | Kiro Power 格式 | `POWER.md` + 可选的 `mcp.json` 和 `steering/` 目录 |
当技能包含依赖或工具引用时，转换引擎会自动生成 `mcp.json` 配置文件。当技能包含 3 个以上复杂章节时，会生成 `steering/` 目录结构。资料来源：[README.md:60-75]()
## 架构设计
### 模块结构
```
skill-loader-mcp-server/
├── src/
│ ├── core/ # 核心功能模块
│ │ ├── conversion-engine.ts # 技能格式转换引擎
│ │ ├── security-validator.ts # 安全验证器
│ │ └── errors.ts # 错误处理
│ ├── tools/ # MCP 工具实现
│ ├── utils/ # 工具函数
│ ├── index.ts # 主入口点
│ └── cli.ts # CLI 入口点
├── examples/ # 使用示例
├── dist/ # 编译输出
└── tests/ # 测试文件
```
资料来源：[CONTRIBUTING.md:10-25]()
### 核心组件
#### 转换引擎 (Conversion Engine)
转换引擎负责将 Claude Skills 解析并转换为目标格式，主要功能包括：
- **解析技能**：提取 YAML frontmatter 和 Markdown 正文内容
- **生成 Steering 文件**：转换为 Kiro 转向文件格式
- **生成 Power 文件**：转换为 Kiro Power 格式，包含元数据和导入信息
- **kebab-case 命名**：自动将技能名称转换为标准的 kebab-case 格式
资料来源：[src/core/conversion-engine.ts:1-100]()
#### 安全验证器 (Security Validator)
安全验证器扫描技能内容中的潜在安全风险：
- **问题类型分类**：区分 `dangerous_command`、`suspicious_pattern`、`untrusted_source`、`code_injection` 四类问题
- **严重级别判定**：根据问题类型返回 `safe`、`warning`、`unsafe` 三级判定
- **行号定位**：精确定位问题所在的代码行
资料来源：[src/core/security-validator.ts:100-150]()
#### 错误处理系统
统一的错误处理系统包含多种专用错误类型：
| 错误类型 | 用途 | Requirement ID |
|---------|------|----------------|
| `SkillLoaderError` | 基类错误 | 8.1 |
| `NetworkError` | 网络请求失败 | 8.2 |
| `ValidationError` | 技能验证失败 | 8.3 |
| `FileSystemError` | 文件系统操作失败 | 8.4 |
资料来源：[src/core/errors.ts:1-80]()
## MCP 工具接口
### 可用工具列表
| 工具名称 | 功能描述 | 认证要求 |
|---------|---------|---------|
| `search_skills` | 按关键词搜索技能 | 无需认证 |
| `list_skills` | 分页列出所有技能 | 需要 API Key |
| `get_leaderboard` | 获取热门技能排行 | 需要 API Key |
| `fetch_skill` | 从 GitHub 获取技能内容 | 无需认证 |
| `validate_skill` | 验证技能安全性 | 无需认证 |
| `convert_to_steering` | 转换为 Steering 格式 | 无需认证 |
| `convert_to_power` | 转换为 Power 格式 | 无需认证 |
| `import_skill` | 完整导入工作流 | 无需认证 |
资料来源：[README.md:50-85]()
### 完整导入工作流
```mermaid
graph TD
A[import_skill 调用] --> B[fetch_skill 获取技能]
B --> C{跳过验证?}
C -->|否| D[validate_skill 安全验证]
C -->|是| E[convert_to_steering/power 格式转换]
D --> F{验证通过?}
F -->|否| G[返回错误,阻止导入]
F -->|是| E
E --> H[返回转换结果]
```
资料来源：[examples/usage-examples.md:1-50]()
## 配置与部署
### 环境变量
| 变量名 | 必填 | 描述 |
|-------|------|------|
| `SKILLS_SH_API_KEY` | 仅 list_skills 和 get_leaderboard | skills.sh API 密钥 |
资料来源：[README.md:25-30]()
### 部署方式
#### Kiro 平台
```json
{
"mcpServers": {
"skill-loader": {
"command": "npx",
"args": ["-y", "@goldzulu/skill-loader-mcp-server"],
"env": {
"SKILLS_SH_API_KEY": "your-api-key-here"
}
}
}
}
```
#### Claude Desktop
```json
{
"mcpServers": {
"skill-loader": {
"command": "skill-loader-mcp-server",
"env": {
"SKILLS_SH_API_KEY": "your-api-key-here"
}
}
}
}
```
#### 独立运行
```bash
skill-loader-mcp-server
```
资料来源：[README.md:100-125]()
## 技术特性
### 缓存机制
服务器内置内存缓存，用于存储 skills.sh 搜索结果：
- **缓存时长**：1 小时 TTL
- **自动刷新**：过期后自动重新获取
- **适用场景**：仅 `list_skills` 和 `get_leaderboard` 调用
资料来源：[README.md:130-135]()
### 重试机制
网络请求采用指数退避策略进行重试，提高系统可靠性：
- **适用场景**：所有外部 API 调用
- **策略**：指数增长的重试间隔
资料来源：[CHANGELOG.md:20-25]()
### 依赖更新
项目已更新至 `@modelcontextprotocol/sdk` v1.29，确保与最新 MCP 协议兼容。资料来源：[README.md:1-5]()
## 错误处理
所有工具返回统一格式的错误信息：
```json
{
"error": "错误描述",
"tool": "工具名称",
"timestamp": "ISO 时间戳"
}
```
常见错误场景：
| 错误类型 | 可能原因 | 解决方案 |
|---------|---------|---------|
| 网络错误 | 网络连接问题 | 检查互联网连接和 GitHub 可用性 |
| 资源未找到 | 技能名称错误 | 验证技能名称和仓库地址 |
| 验证错误 | 安全问题 | 导入前审查安全问题 |
| 解析错误 | 格式问题 | 检查技能格式和 YAML 语法 |
资料来源：[examples/usage-examples.md:100-120]()
## 贡献指南
项目欢迎各类贡献：
- **Bug 修复**：修复现有代码问题
- **新功能**：添加新的 MCP 工具
- **文档**：改进 README 或代码注释
- **测试**：提高测试覆盖率
- **性能优化**：优化现有代码
- **重构**：提升代码质量
代码规范要求使用 TypeScript，遵循现有代码风格，避免使用 `any` 类型。资料来源：[CONTRIBUTING.md:30-55]()
## 版本历史
### v1.1.0 (当前版本)
- Skills.sh 集成不再依赖脆弱的 HTML 解析
- 新增 `SkillsShV1Response` 和 `SkillsShV1Entry` 类型
- 支持 `id`、`skillId`、`source` 字段
- 新增 `listSkills()` 方法支持认证分页列表
- Power 转换支持 `mcp.json` 和 `steering/` 目录生成
### v1.0.0 (初始版本)
- 发布 9 个 MCP 工具
- 实现安全验证功能
- 内置内存缓存和重试逻辑
- 支持 stdio 传输
- 兼容 Kiro 和 Claude Desktop
资料来源：[CHANGELOG.md:1-35]()
---
## MCP工具详解
### 相关页面
相关主题：[项目介绍](#page-project-intro), [技能获取器](#page-skill-fetcher), [转换引擎](#page-conversion-engine)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tools/list-skills.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/list-skills.ts)
- [src/tools/search-skills.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/search-skills.ts)
- [src/tools/get-leaderboard.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/get-leaderboard.ts)
- [src/tools/fetch-skill.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/fetch-skill.ts)
- [src/tools/validate-skill.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/validate-skill.ts)
- [src/tools/convert-to-steering.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/convert-to-steering.ts)
- [src/tools/convert-to-power.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/convert-to-power.ts)
- [src/tools/import-skill.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/import-skill.ts)
# MCP工具详解
## 概述
Skill Loader MCP Server 提供了一套完整的MCP（Model Context Protocol）工具集，用于管理Claude Skills的生命周期。该工具集涵盖从技能发现、获取、验证、格式转换到完整导入的完整工作流程。资料来源：[README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)
系统共包含8个MCP工具，按功能可分为三大类别：
| 类别 | 工具 | 核心功能 |
|------|------|----------|
| **发现工具** | `list_skills` | 分页列出技能市场所有技能 |
| | `search_skills` | 关键词搜索技能 |
| | `get_leaderboard` | 获取热门/趋势技能榜单 |
| **获取与验证工具** | `fetch_skill` | 从GitHub获取原始技能内容 |
| | `validate_skill` | 安全扫描与格式验证 |
| **转换与导入工具** | `convert_to_steering` | 转换为Kiro Steering格式 |
| | `convert_to_power` | 转换为Kiro Power格式 |
| | `import_skill` | 端到端导入工作流 |
资料来源：[README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)
---
## 架构概览
### 工具调用流程
```mermaid
graph TD
A[用户请求] --> B{选择工具类型}
B -->|发现类| C[list_skills
search_skills
get_leaderboard]
B -->|获取类| D[fetch_skill]
B -->|验证类| E[validate_skill]
B -->|转换类| F[convert_to_steering
convert_to_power]
B -->|导入类| G[import_skill]
C --> H[skills.sh API]
D --> I[GitHub Raw]
E --> J[安全验证器]
F --> K[转换引擎]
G --> L[完整工作流]
L --> D
L --> E
L --> F
H --> M[返回结果]
I --> M
J --> M
K --> M
```
### 核心模块依赖关系
```mermaid
graph LR
A[tools/*.ts] --> B[core/skill-resolver.ts]
A --> C[core/conversion-engine.ts]
A --> D[core/security-validator.ts]
A --> E[core/errors.ts]
B --> F[skills.sh API]
C --> E
D --> E
```
---
## 发现类工具
### 1. list_skills
分页列出skills.sh技能市场中的所有可用技能。资料来源：[examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)
**参数说明：**
| 参数 | 类型 | 必需 | 默认值 | 说明 |
|------|------|------|--------|------|
| `page` | number | 否 | 1 | 页码，从1开始 |
| `pageSize` | number | 否 | 50 | 每页数量，最大100 |
**返回值结构：**
```json
{
"skills": [
{
"name": "pdf-extractor",
"description": "Extract text from PDF files",
"owner": "anthropics",
"repo": "skills",
"installs": 30400
}
],
"total": 150,
"page": 1,
"pageSize": 10
}
```
**环境要求：** 需要 `SKILLS_SH_API_KEY` 环境变量进行身份验证。资料来源：[README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)
---
### 2. search_skills
通过关键词搜索skills.sh技能市场。该工具使用公开搜索API，无需API密钥。资料来源：[examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)
**参数说明：**
| 参数 | 类型 | 必需 | 默认值 | 说明 |
|------|------|------|--------|------|
| `query` | string | 是 | - | 搜索关键词 |
| `limit` | number | 否 | 5 | 返回结果数量限制 |
**返回值结构：**
```json
{
"skills": [
{
"name": "pdf-extractor",
"description": "Extract text from PDF files",
"owner": "anthropics",
"repo": "skills",
"installs": 30400,
"relevance": 5
}
],
"query": "pdf",
"count": 5
}
```
---
### 3. get_leaderboard
获取热门或趋势技能榜单，支持按时间范围筛选。资料来源：[examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)
**参数说明：**
| 参数 | 类型 | 必需 | 默认值 | 说明 |
|------|------|------|--------|------|
| `timeframe` | string | 否 | "all" | 时间范围：`"all"`或`"24h"` |
| `limit` | number | 否 | 20 | 返回结果数量，最大50 |
**返回值结构：**
```json
{
"skills": [
{
"name": "pdf-extractor",
"description": "Extract text from PDF files",
"owner": "anthropics",
"repo": "skills",
"installs": 30400,
"rank": 1,
"trending": true
}
],
"timeframe": "24h",
"count": 10
}
```
**环境要求：** 需要 `SKILLS_SH_API_KEY` 环境变量。资料来源：[README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)
---
## 获取与验证工具
### 4. fetch_skill
从GitHub获取原始技能内容。支持多种标识符格式。资料来源：[examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)
**参数说明：**
| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `identifier` | string | 是 | 技能名称或`owner/repo`格式 |
**支持的标识符格式：**
| 格式 | 示例 | 说明 |
|------|------|------|
| 纯名称 | `pdf-extractor` | 从skills.sh目录解析 |
| owner/repo | `anthropics/pdf-extractor` | 直接指定GitHub位置 |
| 完整路径 | `owner/repo/skill-path` | 指定具体路径 |
**返回值结构：**
```json
{
"content": "---\nname: PDF Extractor\ndescription: Extract text from PDF files\n---\n\n# PDF Extractor\n\n...",
"url": "https://raw.githubusercontent.com/anthropics/skills/main/skills/pdf-extractor/SKILL.md",
"metadata": {
"name": "pdf-extractor",
"owner": "anthropics",
"repo": "skills",
"skillPath": "skills/pdf-extractor",
"fetchedAt": "2024-01-15T10:30:00.000Z"
}
}
```
---
### 5. validate_skill
对技能内容进行安全扫描和格式验证，检测潜在的安全风险。资料来源：[src/core/security-validator.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)
**参数说明：**
| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `content` | string | 是 | 待验证的技能内容 |
| `url` | string | 否 | 来源URL用于额外验证 |
**安全检测类型：**
| 类型 | 标识符 | 严重程度 | 说明 |
|------|--------|----------|------|
| 危险命令 | `dangerous_command` | unsafe | `rm -rf`、`sudo`、`eval`、`exec`等 |
| 可疑文件操作 | `suspicious_file_operation` | unsafe | 访问`/etc/`、`/usr/`、`/bin/`等系统目录 |
| 代码注入 | `code_injection` | unsafe | `${...}`、`$(...)`等注入模式 |
| 不信任源 | `untrusted_source` | unsafe | 非GitHub来源的URL |
**返回值结构：**
```json
{
"isValid": false,
"issues": [
{
"type": "dangerous_command",
"description": "Dangerous recursive delete command (rm -rf)",
"location": "Line 7: rm -rf /"
}
],
"severity": "unsafe"
}
```
**安全等级判定逻辑：**
```mermaid
graph TD
A[检测到问题?] --> B{问题类型}
B -->|untrusted_source| C[unsafe]
B -->|dangerous_command| C
B -->|其他| D[warning]
A -->|无问题| E[safe]
```
资料来源：[src/core/security-validator.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)
---
## 转换与导入工具
### 6. convert_to_steering
将Claude Skill转换为Kiro Steering文件格式。资料来源：[examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)
**参数说明：**
| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `content` | string | 是 | 技能原始内容 |
| `sourceUrl` | string | 否 | 原始来源URL |
**转换特性：**
- 提取技能名称并转换为kebab-case格式作为文件名
- 保留技能描述和正文内容
- 添加依赖列表（如有）
- 在文件末尾附加导入元数据
- 包含原始技能名称和来源信息
**输出格式：**
```yaml
---
original_skill: PDF Extractor
source_url: https://raw.githubusercontent.com/...
imported_at: '2024-01-15T10:30:00.000Z'
---
# PDF Extractor
Extract text from PDF files
# PDF Extractor
Extract text content from PDF documents...
---
*Imported from Claude Skills via Skill Loader Power*
```
**返回值结构：**
```json
{
"steeringContent": "...",
"filename": "pdf-extractor.md",
"metadata": {
"originalSkill": "PDF Extractor",
"sourceUrl": "https://...",
"importedAt": "2024-01-15T10:30:00.000Z"
}
}
```
---
### 7. convert_to_power
将Claude Skill转换为Kiro Power格式。这是更高级的转换选项，会生成额外的配置文件。资料来源：[examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)
**参数说明：**
| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `content` | string | 是 | 技能原始内容 |
| `sourceUrl` | string | 否 | 原始来源URL |
**生成的文件：**
| 条件 | 生成文件 | 说明 |
|------|----------|------|
| 始终 | `POWER.md` | 主技能内容文件 |
| 有依赖或工具引用 | `mcp.json` | MCP服务器配置 |
| 3+复杂章节 | `steering/`目录 | 多章节内容目录 |
**mcp.json生成逻辑：**
当技能包含依赖或MCP工具引用时，系统自动生成`mcp.json`配置文件，用于定义MCP服务器连接。资料来源：[CHANGELOG.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CHANGELOG.md)
**steering目录生成逻辑：**
当技能包含3个或以上复杂章节（级别≥2，内容>200字符）时，系统会将这些章节提取到独立的`steering/`目录中。资料来源：[CHANGELOG.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CHANGELOG.md)
---
### 8. import_skill
完整的端到端导入工作流，集成了获取、验证和转换三个步骤。资料来源：[examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)
**参数说明：**
| 参数 | 类型 | 必需 | 默认值 | 说明 |
|------|------|------|--------|------|
| `identifier` | string | 是 | - | 技能标识符 |
| `outputFormat` | string | 是 | - | 输出格式：`"steering"`或`"power"` |
| `skipValidation` | boolean | 否 | false | 是否跳过安全验证 |
**工作流程：**
```mermaid
graph TD
A[import_skill调用] --> B[fetch_skill获取内容]
B --> C{skipValidation?}
C -->|否| D[validate_skill安全验证]
C -->|是| E[跳过验证]
D --> F{验证通过?}
F -->|是| G[转换格式]
F -->|否| H[返回错误]
E --> G
G --> I{outputFormat?}
I -->|steering| J[convert_to_steering]
I -->|power| K[convert_to_power]
J --> L[返回结果]
K --> L
```
**返回值结构：**
```json
{
"success": true,
"content": "...",
"filename": "pdf-extractor.md",
"targetPath": ".kiro/steering/pdf-extractor.md",
"metadata": {
"skillName": "PDF Extractor",
"sourceUrl": "https://...",
"outputFormat": "steering",
"validationResult": {
"isValid": true,
"issues": [],
"severity": "safe"
}
}
}
```
**错误处理：**
当安全验证失败时，返回详细的错误信息：
```json
{
"success": false,
"content": "...",
"metadata": {
"validationResult": {
"isValid": false,
"issues": [
{
"type": "dangerous_command",
"description": "Dangerous recursive delete command (rm -rf)",
"location": "Line 10: rm -rf /"
}
],
"severity": "unsafe"
}
},
"error": "Security validation failed: Dangerous recursive delete command (rm -rf)"
}
```
---
## 常用工作流
### 发现并导入技能
```mermaid
graph LR
A[search_skills] --> B[fetch_skill]
B --> C[validate_skill]
C --> D{安全?}
D -->|是| E[import_skill]
D -->|否| F[放弃]
```
**具体步骤：**
1. **搜索技能**
```json
{ "tool": "search_skills", "arguments": { "query": "pdf", "limit": 5 } }
```
2. **获取技能详情**
```json
{ "tool": "fetch_skill", "arguments": { "identifier": "anthropics/pdf-extractor" } }
```
3. **导入技能**
```json
{ "tool": "import_skill", "arguments": { "identifier": "anthropics/pdf-extractor", "outputFormat": "steering" } }
```
### 浏览趋势技能并导入
1. **获取24小时热门榜单**
```json
{ "tool": "get_leaderboard", "arguments": { "timeframe": "24h", "limit": 20 } }
```
2. **导入热门技能**
```json
{ "tool": "import_skill", "arguments": { "identifier": "owner/skill-name", "outputFormat": "power" } }
```
### 先验证后导入
```mermaid
graph TD
A[fetch_skill] --> B[validate_skill]
B --> C{isValid?}
C -->|true| D[convert_to_steering]
C -->|false| E[审查issues]
E --> F{可接受?}
F -->|是| D
F -->|否| G[使用其他技能]
```
---
## 错误处理
所有工具返回的错误遵循统一格式：资料来源：[src/core/errors.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts)
```json
{
"error": "Error message describing what went wrong",
"tool": "tool_name",
"timestamp": "2024-01-15T10:30:00.000Z"
}
```
**常见错误类型：**
| 错误类型 | 触发场景 | 解决方案 |
|----------|----------|----------|
| 网络错误 | GitHub访问失败 | 检查网络连接 |
| 未找到错误 | 技能名称错误 | 验证技能名称和仓库 |
| 验证错误 | 安全扫描失败 | 审查安全问题后再操作 |
| 解析错误 | 格式问题 | 检查YAML语法 |
---
## 缓存机制
skills.sh搜索结果在内存中缓存1小时，以减少API调用并提高性能。缓存过期后自动刷新。资料来源：[README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)
---
## 安全特性
系统提供多层次的安全保护：
| 层级 | 机制 | 说明 |
|------|------|------|
| 验证层 | 危险命令检测 | 阻止`rm -rf`、`sudo`、`eval`等 |
| 验证层 | 文件操作限制 | 禁止访问系统目录 |
| 验证层 | 注入模式识别 | 检测代码注入尝试 |
| 验证层 | 来源验证 | 仅允许GitHub来源 |
| 验证层 | 跳过选项 | 可选的`skipValidation`参数 |
资料来源：[README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)
---
## 核心模块架构
### 相关页面
相关主题：[类型定义系统](#page-type-system), [缓存机制](#page-caching)
相关源码文件
以下源码文件用于生成本页说明：
- [src/index.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/index.ts)
- [src/cli.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/cli.ts)
- [src/core/types.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/types.ts)
- [src/core/conversion-engine.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)
- [src/core/security-validator.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)
- [src/core/errors.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts)
# 核心模块架构
本文档详细介绍 Skill Loader MCP Server 的核心模块架构，包括各模块的职责、数据流转、以及模块间的协作关系。
## 1. 架构概述
Skill Loader MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器应用，用于管理 Claude Skills 的导入、转换和验证。其核心架构采用分层设计，将功能职责分离到不同的模块中。
```mermaid
graph TD
A[入口层
index.ts / cli.ts] --> B[工具层
MCP Tools]
B --> C[核心服务层
Core Services]
C --> D[安全验证模块
Security Validator]
C --> E[转换引擎
Conversion Engine]
C --> F[错误处理模块
Error System]
C --> G[类型系统
Type Definitions]
H[外部服务
skills.sh API
GitHub API] --> B
```
**架构分层说明**：
| 层级 | 组件 | 职责 |
|------|------|------|
| 入口层 | `index.ts`, `cli.ts` | 服务器初始化、传输协议配置 |
| 工具层 | MCP Tools | 暴露给客户端的 API 接口 |
| 核心服务层 | 核心模块 | 业务逻辑处理 |
| 类型系统 | `types.ts` | 统一数据类型定义 |
资料来源：[src/index.ts:1-50](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/index.ts)
## 2. 入口层架构
### 2.1 主入口 (index.ts)
`index.ts` 是 MCP 服务器的主入口点，负责初始化和配置服务器。
**核心职责**：
- 创建 MCP 服务器实例
- 注册所有工具处理器
- 配置 stdio 传输协议
- 处理服务器生命周期
**代码结构**：
```typescript
// 服务器初始化伪代码
const server = new Server(
{
name: 'skill-loader',
version: '1.1.0',
},
{
capabilities: {
tools: {},
},
}
);
// 注册工具
server.setRequestHandler(ListToolsRequestSchema, async () => ({
tools: [/* 工具列表 */]
}));
server.setRequestHandler(CallToolRequestSchema, async (request) => {
// 路由到对应工具处理器
});
```
资料来源：[src/index.ts:1-100](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/index.ts)
### 2.2 CLI 入口 (cli.ts)
`cli.ts` 提供命令行接口，支持独立运行服务器。
**功能特性**：
- 支持配置文件加载
- 环境变量配置
- 独立的进程启动
资料来源：[src/cli.ts:1-50](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/cli.ts)
## 3. 类型系统
### 3.1 类型定义概述
`types.ts` 定义了项目中使用的所有核心数据类型，确保类型安全和一致性。
**主要类型分类**：
| 类型分类 | 说明 |
|----------|------|
| 技能相关类型 | Skill、SkillFrontmatter、SkillSection |
| API 响应类型 | SkillsShResponse、SkillShEntry、LeaderboardResponse |
| 验证相关类型 | ValidationResult、ValidationIssue |
| 转换相关类型 | ConversionResult、PowerFiles |
| 错误类型 | SkillLoaderError 子类 |
资料来源：[src/core/types.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/types.ts)
### 3.2 技能数据结构
**SkillFrontmatter** 定义技能的元数据：
```typescript
interface SkillFrontmatter {
name: string; // 技能名称
description?: string; // 技能描述
dependencies?: string[];// 依赖列表
// ...其他元数据字段
}
```
**SkillSection** 定义技能内容的结构化分段：
```typescript
interface SkillSection {
level: number; // 标题层级 (1-6)
heading: string; // 标题文本
content: string; // 段落内容
}
```
资料来源：[src/core/types.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/types.ts)
### 3.3 验证结果类型
**ValidationResult** 定义安全验证的结果：
```typescript
interface ValidationResult {
isValid: boolean; // 是否通过验证
issues: ValidationIssue[];// 发现的问题列表
severity: 'safe' | 'warning' | 'unsafe'; // 严重程度
}
interface ValidationIssue {
type: 'dangerous_command' | 'suspicious_pattern' | 'untrusted_source';
description: string; // 问题描述
location?: string; // 问题位置
}
```
资料来源：[src/core/security-validator.ts:50-80](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)
## 4. 安全验证模块
### 4.1 模块概述
`security-validator.ts` 是系统的安全防线，负责扫描和检测技能内容中的潜在安全风险。
```mermaid
graph LR
A[技能内容] --> B[危险命令检测]
A --> C[可疑模式检测]
A --> D[来源验证]
B --> E[评估结果]
C --> E
D --> E
```
**安全检测范围**：
| 检测类型 | 描述 | 严重级别 |
|----------|------|----------|
| 危险命令 | `rm -rf`, `sudo`, `eval`, `exec` | unsafe |
| 可疑文件操作 | `/etc/`, `/usr/`, `/bin/` 路径访问 | warning |
| 代码注入 | `${...}`, `$(...)` 模式 | warning |
| 不信任来源 | 非 GitHub URL | unsafe |
资料来源：[src/core/security-validator.ts:1-100](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)
### 4.2 验证流程
**严重级别判定逻辑**：
```typescript
private determineSeverity(issues: Issue[]): 'safe' | 'warning' | 'unsafe' {
if (issues.length === 0) {
return 'safe';
}
// 如果存在不信任来源或危险命令，标记为不安全
const hasUntrustedSource = issues.some(issue => issue.type === 'untrusted_source');
const hasDangerousCommand = issues.some(issue => issue.type === 'dangerous_command');
if (hasUntrustedSource || hasDangerousCommand) {
return 'unsafe';
}
// 否则，可疑模式为警告级别
return 'warning';
}
```
资料来源：[src/core/security-validator.ts:200-220](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)
## 5. 转换引擎模块
### 5.1 模块概述
`conversion-engine.ts` 是核心的业务逻辑模块，负责将 Claude Skills 转换为 Kiro 格式（Steering 文件或 Power）。
**转换引擎能力**：
| 功能 | 说明 |
|------|------|
| 格式转换 | SKILL.md → Steering 文件 / Power |
| 依赖处理 | 生成 `mcp.json` 配置文件 |
| 复杂内容拆分 | 生成 `steering/` 目录结构 |
| 元数据保留 | 保留原始技能信息和导入来源 |
资料来源：[src/core/conversion-engine.ts:1-150](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)
### 5.2 转换为 Steering 文件
**转换流程**：
```mermaid
graph TD
A[解析 SKILL.md] --> B[提取 frontmatter]
B --> C[处理 body 内容]
C --> D{是否有复杂章节?}
D -->|是| E[生成 steering/ 目录]
D -->|否| F[直接生成 .md 文件]
E --> G[添加导入元数据]
F --> G
G --> H[输出 Steering 文件]
```
**Steering 文件结构示例**：
```markdown
---
original_skill: PDF Extractor
source_url: https://github.com/...
imported_at: 2024-01-15T10:30:00.000Z
---
# PDF Extractor
[技能内容...]
---
*Imported from Claude Skills via Skill Loader Power*
```
资料来源：[src/core/conversion-engine.ts:80-120](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)
### 5.3 转换为 Power 格式
**Power 格式特点**：
- 使用 `POWER.md` 作为主文件
- 可选生成 `mcp.json`（当技能有依赖或工具引用时）
- 可选生成 `steering/` 目录（当技能有 3+ 复杂章节时）
**生成条件判断**：
```typescript
// 是否应生成 mcp.json
private shouldGenerateMcpJson(skill: Skill): boolean {
return (
(skill.frontmatter.dependencies && skill.frontmatter.dependencies.length > 0) ||
this.hasToolReferences(skill)
);
}
// 是否应生成 steering/ 目录
private shouldGenerateSteeringDir(skill: Skill): boolean {
const complexSections = skill.sections.filter(
s => s.level >= 2 && s.content.length > 200
);
return complexSections.length >= 3;
}
```
资料来源：[src/core/conversion-engine.ts:180-200](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)
### 5.4 关键字提取
转换引擎包含关键字提取功能，用于技能分类和搜索优化：
```typescript
private extractKeywords(description: string): string[] {
const stopWords = new Set([
'the', 'and', 'for', 'with', 'this', 'that', 'from', 'into',
'when', 'what', 'where', 'how', 'why', 'can', 'will', 'should'
// ...更多停用词
]);
// 提取 3+ 字符的非停用词，最多返回 5 个
const words = description
.toLowerCase()
.replace(/[^a-z0-9\s]/g, ' ')
.split(/\s+/)
.filter(word => word.length >= 3 && !stopWords.has(word))
.slice(0, 5);
return words;
}
```
资料来源：[src/core/conversion-engine.ts:150-175](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)
## 6. 错误处理系统
### 6.1 错误类层次结构
`errors.ts` 定义了完整的错误类型体系：
```mermaid
graph TD
A[SkillLoaderError
基类]
A --> B[ValidationError
验证错误]
A --> C[FileSystemError
文件系统错误]
A --> D[NetworkError
网络错误]
A --> E[ParseError
解析错误]
```
**基类特性**：
```typescript
export class SkillLoaderError extends Error {
public readonly code: string;
public readonly timestamp: Date;
public readonly context: Record;
constructor(message: string, context?: Record) {
super(message);
this.code = this.getDefaultCode();
this.timestamp = new Date();
this.context = context || {};
}
}
```
资料来源：[src/core/errors.ts:1-100](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts)
### 6.2 验证错误 (ValidationError)
专门处理技能验证失败的错误类型：
```typescript
export class ValidationError extends SkillLoaderError {
public readonly validationType: 'security' | 'format' | 'content';
getUserMessage(): string {
// 返回用户友好的错误信息和恢复建议
}
}
```
**错误消息包含**：
- 错误描述
- 验证类型
- 具体的恢复建议
资料来源：[src/core/errors.ts:50-80](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts)
### 6.3 文件系统错误 (FileSystemError)
处理文件读写操作相关的错误：
```typescript
export class FileSystemError extends SkillLoaderError {
public readonly operation: 'read' | 'write' | 'delete' | 'access';
public readonly filePath: string;
public readonly systemError?: string;
getUserMessage(): string {
// 根据错误码提供具体的修复建议
}
}
```
**系统错误处理**：
| 错误码 | 建议 |
|--------|------|
| EACCES/EPERM | 检查文件权限 |
| ENOSPC | 释放磁盘空间 |
| ENOENT | 验证目录存在 |
| EEXIST | 使用 --overwrite 标志 |
资料来源：[src/core/errors.ts:100-150](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts)
## 7. MCP 工具层
### 7.1 工具列表
系统提供 8 个 MCP 工具：
| 工具名称 | 功能 | 认证要求 |
|----------|------|----------|
| `search_skills` | 关键词搜索技能 | 不需要 |
| `list_skills` | 分页列出所有技能 | 需要 API Key |
| `get_leaderboard` | 获取排行榜 | 需要 API Key |
| `fetch_skill` | 获取技能内容 | 不需要 |
| `validate_skill` | 安全验证 | 不需要 |
| `convert_to_steering` | 转为 Steering 格式 | 不需要 |
| `convert_to_power` | 转为 Power 格式 | 不需要 |
| `import_skill` | 完整导入流程 | 不需要 |
资料来源：[README.md:50-150](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)
### 7.2 工具调用流程
**import_skill 完整工作流**：
```mermaid
graph TD
A[import_skill 调用] --> B[fetch_skill
获取技能内容]
B --> C{skipValidation?}
C -->|否| D[validate_skill
安全验证]
C -->|是| E[跳过验证]
D --> F{验证通过?}
F -->|否| G[返回错误]
F -->|是| H[convert_to_power
格式转换]
E --> H
H --> I[返回转换结果]
```
资料来源：[examples/usage-examples.md:1-100](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)
## 8. 数据流与状态管理
### 8.1 技能数据流转
```mermaid
sequenceDiagram
participant Client as 客户端
participant Server as MCP Server
participant Fetcher as 技能获取器
participant Validator as 安全验证器
participant Converter as 转换引擎
participant GitHub as GitHub API
Client->>Server: import_skill(identifier)
Server->>Fetcher: fetchSkill(identifier)
Fetcher->>GitHub: GET raw skill content
GitHub-->>Fetcher: SKILL.md content
Fetcher-->>Server: skill content
Server->>Validator: validateSkill(content)
Validator-->>Server: ValidationResult
Server->>Converter: convertToPower(content)
Converter-->>Server: ConversionResult
Server-->>Client: import result
```
### 8.2 缓存策略
系统使用内存缓存来优化 skills.sh API 调用：
| 缓存项 | TTL | 说明 |
|--------|-----|------|
| 搜索结果 | 1 小时 | 减少 API 调用 |
| 目录列表 | 1 小时 | 提升分页性能 |
资料来源：[README.md:180-200](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)
## 9. 配置与环境
### 9.1 环境变量
| 变量名 | 必需 | 说明 |
|--------|------|------|
| `SKILLS_SH_API_KEY` | 仅 list_skills/get_leaderboard | skills.sh API 密钥 |
### 9.2 MCP 服务器配置
```json
{
"mcpServers": {
"skill-loader": {
"command": "npx",
"args": ["-y", "@goldzulu/skill-loader-mcp-server"],
"env": {
"SKILLS_SH_API_KEY": "your-api-key-here"
}
}
}
}
```
资料来源：[README.md:30-60](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)
## 10. 模块依赖关系
```mermaid
graph TD
index_ts[index.ts] --> cli_ts[cli.ts]
index_ts --> types_ts[types.ts]
tools[Tools Layer] --> conversion_engine[conversion-engine.ts]
tools --> security_validator[security-validator.ts]
tools --> errors_ts[errors.ts]
conversion_engine --> types_ts
security_validator --> types_ts
errors_ts --> types_ts
conversion_engine --> errors_ts
security_validator --> errors_ts
subgraph core[核心模块]
conversion_engine
security_validator
errors_ts
types_ts
end
```
**依赖关系说明**：
| 依赖方向 | 说明 |
|----------|------|
| tools → core | 工具层依赖核心服务处理业务逻辑 |
| core 内部 | 核心模块相互依赖，types 作为共享基础 |
| errors 被广泛依赖 | 所有模块在出错时使用错误系统 |
## 11. 总结
Skill Loader MCP Server 的核心模块架构采用清晰的分层设计：
1. **入口层** 负责服务器初始化和协议配置
2. **工具层** 暴露统一的 MCP 接口
3. **核心服务层** 包含安全验证、格式转换、错误处理等关键功能
4. **类型系统** 确保整个项目的类型安全
该架构具有良好的可扩展性，便于添加新的工具、转换格式或验证规则。
---
## 类型定义系统
### 相关页面
相关主题：[核心模块架构](#page-core-modules), [技能获取器](#page-skill-fetcher)
相关源码文件
以下源码文件用于生成本页说明：
- [src/core/types.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/types.ts)
- [src/core/errors.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts)
- [src/core/conversion-engine.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)
- [src/core/security-validator.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)
- [examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)
- [README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)
# 类型定义系统
## 概述
类型定义系统是 Skill Loader MCP Server 的核心基础设施之一，为整个项目提供强类型的接口定义、数据模型和错误处理机制。该系统基于 TypeScript 编写，确保在 MCP 工具调用、数据流转和错误处理过程中具备类型安全性和编译时检查能力。
类型定义系统的主要职责包括：
- **数据结构定义**：为 skills.sh API 响应、技能元数据、导入结果等核心数据定义清晰的结构
- **MCP 工具接口**：为 8 个 MCP 工具提供输入输出参数的类型规范
- **错误类型体系**：建立分层分类的错误类型系统，支持精确的错误定位和恢复建议
- **安全验证模型**：定义安全检查项和验证结果的数据结构
资料来源：[README.md:1-20]()
## 系统架构
### 模块组成
类型定义系统由以下几个核心模块组成：
| 模块 | 文件路径 | 职责 |
|------|----------|------|
| 基础类型 | `src/core/types.ts` | 定义核心数据结构和接口 |
| 错误类型 | `src/core/errors.ts` | 实现分层错误类体系 |
| 转换引擎类型 | `src/core/conversion-engine.ts` | 技能转换相关类型 |
| 安全验证类型 | `src/core/security-validator.ts` | 安全检查数据结构 |
### 架构层次图
```mermaid
graph TD
A[类型定义系统] --> B[基础类型层]
A --> C[错误类型层]
A --> D[业务类型层]
B --> B1[SkillShEntry]
B --> B2[SkillContent]
B --> B3[API响应类型]
C --> C1[SkillLoaderError]
C --> C2[NetworkError]
C --> C3[ValidationError]
C --> C4[FileSystemError]
D --> D1[工具参数类型]
D --> D2[转换结果类型]
D --> D3[验证结果类型]
```
## 基础数据类型
### 技能条目类型
技能条目是 skills.sh 目录中的基本单位，包含以下关键字段：
```typescript
interface SkillShEntry {
name: string; // 技能名称（kebab-case格式）
description: string; // 技能描述
owner: string; // 仓库所有者
repo: string; // 仓库名称
installs: number; // 安装次数
skillId?: string; // 技能唯一标识
source?: string; // 来源信息
relevance?: number; // 搜索相关性得分
rank?: number; // 排行榜排名
trending?: boolean; // 是否为热门技能
}
```
资料来源：[examples/usage-examples.md:1-50]()
### 技能内容类型
技能内容用于存储解析后的完整技能信息：
```typescript
interface SkillContent {
frontmatter: {
name: string;
description?: string;
dependencies?: string[];
[key: string]: any;
};
body: string; // 技能正文内容
sections: SkillSection[];
}
```
资料来源：[src/core/conversion-engine.ts:1-30]()
### 技能解析结果
技能解析函数返回的结果包含元数据和解析状态：
```typescript
interface ParsedSkill {
frontmatter: Record;
body: string;
sections: Array<{
heading: string;
level: number;
content: string;
}>;
}
```
## 错误类型体系
### 基类设计
错误系统采用继承层级结构，基类 `SkillLoaderError` 提供通用功能：
```typescript
export class SkillLoaderError extends Error {
public readonly timestamp: Date;
public readonly context: Record;
constructor(message: string, context: Record = {}) {
super(message);
this.name = this.constructor.name;
this.timestamp = new Date();
this.context = context;
}
}
```
资料来源：[src/core/errors.ts:1-30]()
### 错误子类层级
```mermaid
graph TD
A[SkillLoaderError] --> B[NetworkError]
A --> C[ValidationError]
A --> D[FileSystemError]
A --> E[ParsingError]
B --> B1[HTTP状态码]
B --> B2[重试次数]
C --> C1[验证类型]
C --> C2[问题详情]
D --> D1[操作类型]
D --> D2[文件路径]
```
### 网络错误 (NetworkError)
用于处理网络相关故障：
```typescript
export class NetworkError extends SkillLoaderError {
public readonly url: string;
public readonly statusCode?: number;
public readonly retryCount: number;
constructor(
message: string,
url: string,
options: {
statusCode?: number;
retryCount?: number;
context?: Record;
} = {}
);
}
```
资料来源：[src/core/errors.ts:80-100]()
**错误处理建议**：
| 状态码 | 建议措施 |
|--------|----------|
| 404 | 验证技能名称是否正确，检查仓库是否存在 |
| 403 | 可能是 GitHub 速率限制，等待后重试 |
| >= 500 | 服务器端问题，稍后重试 |
### 验证错误 (ValidationError)
用于处理格式、安全和模式验证失败：
```typescript
export class ValidationError extends SkillLoaderError {
public readonly validationType: 'format' | 'security' | 'schema' | 'content';
public readonly lineNumber?: number;
public readonly details: string[];
constructor(
message: string,
validationType: 'format' | 'security' | 'schema' | 'content',
options: {
lineNumber?: number;
details?: string[];
context?: Record;
} = {}
);
}
```
资料来源：[src/core/errors.ts:180-200]()
### 文件系统错误 (FileSystemError)
用于处理文件系统操作错误：
```typescript
export class FileSystemError extends SkillLoaderError {
public readonly operation: 'read' | 'write' | 'delete' | 'access';
public readonly filePath: string;
public readonly systemError?: string;
}
```
资料来源：[src/core/errors.ts:120-150]()
**常见系统错误代码**：
| 错误代码 | 含义 | 恢复建议 |
|----------|------|----------|
| EACCES/EPERM | 权限不足 | 检查文件权限，使用适当权限运行 |
| ENOSPC | 磁盘空间不足 | 清理磁盘空间，选择其他输出位置 |
| ENOENT | 路径不存在 | 验证目录存在，检查路径正确性 |
| EEXIST | 文件已存在 | 使用 --overwrite 标志替换 |
## MCP 工具类型定义
### 工具参数类型
系统为 8 个 MCP 工具定义了严格的输入参数类型：
| 工具名称 | 必需参数 | 可选参数 |
|----------|----------|----------|
| `list_skills` | - | `page`, `pageSize` |
| `search_skills` | `query` | `limit` |
| `get_leaderboard` | - | `timeframe`, `limit` |
| `fetch_skill` | `identifier` | - |
| `validate_skill` | `content` | `url` |
| `convert_to_steering` | `content` | `sourceUrl` |
| `convert_to_power` | `content` | `sourceUrl` |
| `import_skill` | `identifier`, `outputFormat` | `skipValidation` |
资料来源：[README.md:1-80]()
### 列表技能工具类型
```typescript
interface ListSkillsParams {
page?: number; // 页码，默认1
pageSize?: number; // 每页数量，默认50，最大100
}
interface ListSkillsResult {
skills: SkillShEntry[];
total: number;
page: number;
pageSize: number;
}
```
### 搜索技能工具类型
```typescript
interface SearchSkillsParams {
query: string; // 搜索关键词
limit?: number; // 最大返回数量，默认20
}
interface SearchSkillsResult {
skills: SkillShEntry[];
query: string;
count: number;
}
```
### 获取排行榜工具类型
```typescript
interface GetLeaderboardParams {
timeframe?: 'all' | '24h'; // 时间范围，默认 'all'
limit?: number; // 最大结果数，默认20，最大50
}
interface GetLeaderboardResult {
skills: Array;
timeframe: string;
count: number;
}
```
### 验证技能工具类型
```typescript
interface ValidateSkillParams {
content: string; // 待验证的技能内容
url?: string; // 源URL用于验证
}
interface ValidationIssue {
type: 'dangerous_command' | 'suspicious_pattern' | 'untrusted_source';
description: string;
location?: string;
}
interface ValidateSkillResult {
isValid: boolean;
issues: ValidationIssue[];
severity: 'safe' | 'warning' | 'unsafe';
}
```
资料来源：[examples/usage-examples.md:80-120]()
## 安全验证类型
### 验证问题类型
安全验证模块定义了多种检查类型：
```typescript
type ValidationIssueType =
| 'dangerous_command' // 危险命令
| 'suspicious_pattern' // 可疑模式
| 'untrusted_source'; // 不受信任的源
```
### 验证结果级别
```typescript
type ValidationSeverity = 'safe' | 'warning' | 'unsafe';
```
安全级别判定逻辑：
| 问题类型 | 严重级别 |
|----------|----------|
| `untrusted_source` | unsafe |
| `dangerous_command` | unsafe |
| `suspicious_pattern` | warning |
| 无问题 | safe |
资料来源：[src/core/security-validator.ts:1-50]()
### 危险命令检测
系统检测以下危险命令模式：
- `rm -rf` 系列删除命令
- `sudo` 特权命令
- `eval` 和 `exec` 代码执行命令
### 可疑模式检测
检测以下可疑代码模式：
- 模板注入：`${...}` 或 `$(...)`
- 系统路径访问：`/etc/`、`/usr/`、`/bin/`
- 敏感配置文件访问
## 转换结果类型
### 转换为转向文件结果
```typescript
interface ConvertToSteeringResult {
content: string; // 转换后的内容
filename: string; // 生成的文件名
metadata: {
originalSkill: string;
sourceUrl?: string;
importedAt: string;
};
}
```
### 转换为 Power 结果
```typescript
interface ConvertToPowerResult {
files: Array<{
path: string;
content: string;
}>;
metadata: {
skillName: string;
sourceUrl?: string;
filesGenerated: number;
};
}
```
Power 格式可能生成的文件：
| 文件类型 | 条件 | 路径 |
|----------|------|------|
| POWER.md | 始终生成 | `~/.kiro/powers/{skill-name}/POWER.md` |
| mcp.json | 技能有依赖或工具引用 | 同目录 |
| steering/ | 技能有3+复杂章节 | 同目录 |
资料来源：[src/core/conversion-engine.ts:50-100]()
## API 响应类型
### Skills.sh API v1 响应类型
```typescript
interface SkillsShV1Response {
skills: SkillsShV1Entry[];
total: number;
page: number;
}
interface SkillsShV1Entry {
id: string;
skillId: string;
name: string;
description: string;
owner: string;
repo: string;
installs: number;
source: string;
}
```
资料来源：[CHANGELOG.md:1-30]()
## 类型使用最佳实践
### 类型守卫
系统支持 TypeScript 类型守卫以提供精确的类型缩小：
```typescript
function isNetworkError(error: unknown): error is NetworkError {
return error instanceof NetworkError;
}
function isValidationError(error: unknown): error is ValidationError {
return error instanceof ValidationError;
}
```
### 错误恢复流程
```mermaid
graph TD
A[发生错误] --> B{错误类型?}
B -->|NetworkError| C[检查状态码]
B -->|ValidationError| D[检查验证类型]
B -->|FileSystemError| E[检查系统错误]
C --> C1{404?}
C1 -->|是| C2[验证技能名称]
C1 -->|否| C3{403?}
C3 -->|是| C4[等待重试]
C3 -->|否| C5[检查连接]
D --> D1{security?}
D1 -->|是| D2[拒绝导入]
D1 -->|否| D3{format?}
D3 -->|是| D4[检查YAML格式]
E --> E1{EACCES?}
E1 -->|是| E2[检查权限]
E1 -->|否| E3{ENOSPC?}
E3 -->|是| E4[清理磁盘]
```
## 总结
类型定义系统为 Skill Loader MCP Server 提供了：
1. **完整的类型安全**：从 API 响应到错误处理，全链路类型覆盖
2. **清晰的错误分类**：四级错误类型体系，支持精确的问题定位
3. **规范的工具接口**：8 个 MCP 工具的输入输出类型一致性保证
4. **安全验证模型**：结构化的安全检查和问题报告机制
该系统是项目架构的基础层，为上层的工具实现、CLI 入口和配置管理提供了坚实的类型支撑。
---
## 技能解析器
### 相关页面
相关主题：[技能获取器](#page-skill-fetcher), [MCP工具详解](#page-mcp-tools)
相关源码文件
以下源码文件用于生成本页说明：
- [src/core/conversion-engine.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)
- [src/core/security-validator.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)
- [src/core/errors.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts)
- [examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)
- [README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)
- [src/core/conversion-engine.test.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.test.ts)
# 技能解析器
技能解析器（Skill Resolver）是 Skill Loader MCP Server 的核心组件之一，负责从 GitHub 仓库解析、提取和处理 Claude Skills 内容。该模块在技能导入工作流中扮演着关键角色，与安全验证器、转换引擎协同工作，确保技能能够安全、高效地转换为 Kiro 格式。
## 核心职责
技能解析器的主要职责包括：
| 职责类别 | 具体功能 |
|---------|---------|
| 内容获取 | 从 GitHub 远程仓库获取原始技能内容 |
| 标识解析 | 支持 `owner/repo` 和纯技能名称两种格式的标识符解析 |
| 元数据提取 | 解析 YAML frontmatter 中的名称、描述、依赖等信息 |
| 内容验证 | 调用安全验证器检查潜在风险 |
| 格式转换 | 将解析后的内容传递给转换引擎生成目标格式 |
资料来源：[README.md:1-50]()
## 解析流程
技能解析器遵循标准化的解析流程，确保从远程获取的技能内容能够被准确处理和转换。
```mermaid
graph TD
A[输入: 技能标识符] --> B[标识符标准化]
B --> C{格式判断}
C -->|owner/repo 格式| D[构建 GitHub URL]
C -->|纯名称格式| E[查询 skills.sh 目录]
D --> F[获取原始内容]
E --> F
F --> G[解析 YAML Frontmatter]
G --> H[提取 body 内容]
H --> I[结构化输出]
I --> J[传递给转换引擎]
```
资料来源：[examples/usage-examples.md:30-60]()
## 标识符解析规则
技能解析器支持两种标识符格式，具有不同的处理逻辑：
### owner/repo 格式
当提供完整的所有者/仓库格式时（如 `anthropics/pdf-extractor`），解析器直接构建 GitHub 原始内容 URL：
```
https://raw.githubusercontent.com/{owner}/{repo}/main/skills/{skill-name}/SKILL.md
```
### 纯名称格式
当提供纯技能名称时（如 `pdf-extractor`），解析器会查询 skills.sh 目录获取完整的仓库信息，然后构建获取路径。 资料来源：[examples/usage-examples.md:45-55]()
## YAML Frontmatter 解析
技能解析器能够准确解析 Claude Skills 标准格式的 YAML frontmatter，提取以下元数据字段：
| 字段 | 类型 | 说明 |
|-----|------|-----|
| `name` | string | 技能唯一标识名称 |
| `description` | string | 技能功能描述 |
| `dependencies` | string[] | 技能依赖列表 |
| `version` | string | 技能版本号（可选） |
解析后的结构化数据包含 `frontmatter` 和 `body` 两个主要部分：
```typescript
interface ParsedSkill {
frontmatter: {
name: string;
description?: string;
dependencies?: string[];
[key: string]: any;
};
body: string;
}
```
资料来源：[src/core/conversion-engine.ts:1-30]()
## 技能验证集成
技能解析器与安全验证器紧密集成，在解析过程中自动进行安全检查：
### 危险命令检测
解析器会扫描技能内容中的危险命令模式：
- `rm -rf` — 递归删除命令
- `sudo` — 管理员权限执行
- `eval` / `exec` — 代码执行函数
### 可疑文件操作检测
检测访问敏感系统路径的操作：
- `/etc/` — 系统配置目录
- `/usr/` — 用户程序目录
- `/bin/` — 二进制程序目录
### 代码注入检测
识别潜在的代码注入攻击模式：
- `${...}` — 模板字符串注入
- `$(...)` — 命令替换注入
资料来源：[src/core/security-validator.ts:1-40]()
### 验证结果级别
| 安全级别 | 条件 | 处理方式 |
|---------|------|---------|
| `safe` | 无安全问题 | 正常处理 |
| `warning` | 存在可疑模式 | 警告但允许 |
| `unsafe` | 包含危险命令或非信任来源 | 阻止导入 |
资料来源：[src/core/security-validator.ts:35-50]()
## 错误处理机制
技能解析器实现了完善的错误处理机制，针对不同类型的故障提供精确的错误分类：
### 错误类型分类
| 错误类型 | 触发场景 | 恢复建议 |
|---------|---------|---------|
| `NetworkError` | 网络连接失败、GitHub 不可达 | 检查网络连接，等待后重试 |
| `NotFoundError` | 技能或仓库不存在 (404) | 验证技能名称，检查仓库存在性 |
| `RateLimitError` | GitHub API 频率限制 (403) | 等待几分钟后重试 |
| `ValidationError` | 安全验证失败、格式错误 | 审查安全问题，使用信任来源 |
| `FileSystemError` | 文件读写失败、权限问题 | 检查文件路径和权限设置 |
资料来源：[src/core/errors.ts:1-80]()
### HTTP 状态码处理
解析器针对常见的 HTTP 错误状态码提供了用户友好的错误消息和建议：
```typescript
if (statusCode === 404) {
// 验证技能名称是否正确
// 检查仓库是否存在于 GitHub
// 尝试使用 owner/repo 格式
} else if (statusCode === 403) {
// 可能触发了 GitHub 频率限制
// 等待几分钟后重试
} else if (statusCode >= 500) {
// 服务器端问题
// 稍后重试
}
```
资料来源：[src/core/errors.ts:60-90]()
## 转换引擎协作
技能解析器与转换引擎协同工作，将解析后的技能内容转换为目标格式：
### 支持的目标格式
| 格式 | 输出文件 | 说明 |
|-----|---------|------|
| `steering` | `.md` 文件 | Kiro 方向盘文件格式 |
| `power` | `POWER.md` + `mcp.json` | Kiro 能力格式 |
### Power 格式生成规则
转换引擎根据技能内容特征决定生成哪些文件：
1. **基础文件**: 始终生成 `POWER.md`
2. **MCP 配置**: 当技能包含依赖项或工具引用时生成 `mcp.json`
3. **转向目录**: 当技能包含 3 个或以上复杂章节时生成 `steering/` 目录
资料来源：[src/core/conversion-engine.ts:80-120]()
### 转换测试验证
```typescript
describe('toPower', () => {
it('converts parsed skill to power format', () => {
const content = `---
name: my-power
description: A powerful skill
---
# Instructions
Do power stuff.`;
const parsed = engine.parseSkill(content);
const power = engine.toPower(parsed, 'https://example.com');
expect(power.powerName).toBe('my-power');
expect(power.files.length).toBeGreaterThanOrEqual(1);
expect(power.files[0].path).toBe('POWER.md');
});
it('generates mcp.json when skill has dependencies', () => {
const content = `---
name: dep-power
dependencies:
- express
- cors
---
# Body`;
const parsed = engine.parseSkill(content);
const power = engine.toPower(parsed);
const mcpFile = power.files.find(f => f.path === 'mcp.json');
expect(mcpFile).toBeDefined();
});
});
```
资料来源：[src/core/conversion-engine.test.ts:60-100]()
## 导入工作流
完整的技能导入工作流将解析器、验证器和转换器整合为一个端到端的流程：
```mermaid
graph LR
A[用户请求导入] --> B[fetch_skill]
B --> C{成功?}
C -->|否| D[返回错误]
C -->|是| E[validate_skill]
E --> F{安全?}
F -->|否| G[阻止或警告]
F -->|是| H[convert_to_power/steering]
H --> I[返回转换结果]
```
### 完整导入示例
```json
{
"tool": "import_skill",
"arguments": {
"identifier": "anthropics/pdf-extractor",
"outputFormat": "power",
"skipValidation": false
}
}
```
响应包含转换后的文件和元数据：
```json
{
"success": true,
"content": "---\nname: pdf-extractor\ndisplayName: PDF Extractor\n...",
"filename": "POWER.md",
"targetPath": "~/.kiro/powers/pdf-extractor/POWER.md",
"metadata": {
"skillName": "pdf-extractor",
"sourceUrl": "https://raw.githubusercontent.com/...",
"outputFormat": "power"
}
}
```
资料来源：[examples/usage-examples.md:80-120]()
## 性能优化
技能解析器实现了多项性能优化策略：
### 缓存机制
skills.sh 目录搜索结果在内存中缓存 1 小时，减少 API 调用并提升响应速度。缓存过期后自动刷新。
### 重试机制
网络请求采用指数退避重试策略，应对临时性网络故障：
```typescript
// 初始延迟: 1秒
// 最大延迟: 30秒
// 最大重试次数: 3次
```
### 并发控制
解析请求支持并发处理，但限制最大并发数避免资源耗尽。
资料来源：[README.md:100-120]()
## 总结
技能解析器是 Skill Loader MCP Server 的核心模块，承担着从远程 GitHub 仓库获取技能内容、解析 YAML 元数据、进行安全验证以及与转换引擎协作的重要职责。通过完善的错误处理机制、安全扫描集成和性能优化策略，确保技能导入过程的可靠性、安全性和高效性。开发者可以通过扩展解析规则和验证逻辑来支持更多技能格式和来源。
---
## 技能获取器
### 相关页面
相关主题：[技能解析器](#page-skill-resolver), [安全验证器](#page-security-validator)
相关源码文件
以下源码文件用于生成本页说明：
- [src/core/skill-fetcher.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/skill-fetcher.ts)
- [src/tools/fetch-skill.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/fetch-skill.ts)
- [src/core/skill-resolver.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/skill-resolver.ts)
- [src/core/conversion-engine.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)
- [examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)
- [README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)
# 技能获取器
技能获取器（Skill Fetcher）是 Skill Loader MCP Server 的核心组件之一，负责从 GitHub 仓库获取 Claude Skills 的原始内容。该模块在技能导入工作流中扮演着数据源的角色，为后续的安全验证和格式转换提供原材料。
## 核心定位
在 Skill Loader MCP Server 的整体架构中，技能获取器处于工作流的最上游位置。用户的完整导入流程为：**获取技能 → 安全验证 → 格式转换 → 导入完成**。技能获取器仅负责完成第一步，即从 GitHub 获取技能的原始 Markdown 内容。
技能获取器支持两种标识符格式：
| 标识符格式 | 示例 | 说明 |
|-----------|------|------|
| `owner/repo` | `anthropics/pdf-extractor` | 标准格式，明确指定所有者仓库和技能名称 |
| 纯技能名称 | `pdf-extractor` | 简写格式，自动使用 `anthropics/skills` 作为默认仓库 |
资料来源：[examples/usage-examples.md:61-67]()
## 架构设计
### 模块分层
技能获取器采用分层架构设计，主要分为两个层次：
```
┌─────────────────────────────────────┐
│ MCP 工具层 (fetch-skill.ts) │ ← MCP 协议接口
├─────────────────────────────────────┤
│ 核心服务层 (skill-fetcher.ts) │ ← 业务逻辑
├─────────────────────────────────────┤
│ 解析层 (skill-resolver.ts) │ ← API 交互
└─────────────────────────────────────┘
```
**工具层**负责处理 MCP 协议层面的参数解析和响应格式化；**核心服务层**实现技能获取的业务逻辑；**解析层**负责与外部 API（skills.sh 和 GitHub）进行实际的网络通信。
资料来源：[src/tools/fetch-skill.ts]()
### 获取流程
```mermaid
graph TD
A[接收 identifier] --> B{identifier 格式判断}
B -->|包含 /| C[解析 owner/repo]
B -->|纯名称| D[使用默认仓库 anthropics/skills]
C --> E[构建 GitHub URL]
D --> E
E --> F[发起 HTTP 请求]
F --> G{响应状态}
G -->|200| H[返回技能内容]
G -->|404| I[抛出 NotFoundError]
G -->|网络错误| J[抛出 NetworkError]
G -->|其他| K[抛出 FetchError]
```
资料来源：[src/core/conversion-engine.ts:75-89]()
## 核心功能
### fetch_skill 工具
`fetch_skill` 是 MCP 服务器暴露给外部的唯一工具接口，用于获取存储在 GitHub 上的原始技能内容。
**参数定义：**
| 参数名 | 类型 | 必需 | 默认值 | 说明 |
|-------|------|------|--------|------|
| `identifier` | string | 是 | - | 技能标识符，格式为 `owner/repo` 或纯技能名称 |
**请求示例：**
```json
{
"tool": "fetch_skill",
"arguments": {
"identifier": "anthropics/pdf-extractor"
}
}
```
资料来源：[examples/usage-examples.md:53-67]()
**响应结构：**
| 字段 | 类型 | 说明 |
|------|------|------|
| `content` | string | 技能的原始 Markdown 内容 |
| `url` | string | 实际获取内容的原始 URL |
| `metadata` | object | 技能的元数据信息 |
| `metadata.name` | string | 技能名称 |
| `metadata.owner` | string | 仓库所有者 |
| `metadata.repo` | string | 仓库名称 |
| `metadata.skillPath` | string | 仓库中的技能路径 |
| `metadata.fetchedAt` | string | ISO 格式的获取时间 |
资料来源：[examples/usage-examples.md:68-79]()
### 响应示例
```json
{
"content": "---\nname: PDF Extractor\ndescription: Extract text from PDF files\n---\n\n# PDF Extractor\n\n...",
"url": "https://raw.githubusercontent.com/anthropics/skills/main/skills/pdf-extractor/SKILL.md",
"metadata": {
"name": "pdf-extractor",
"owner": "anthropics",
"repo": "skills",
"skillPath": "skills/pdf-extractor",
"fetchedAt": "2024-01-15T10:30:00.000Z"
}
}
```
资料来源：[examples/usage-examples.md:69-79]()
## URL 构建规则
技能获取器使用固定的 URL 模板从 GitHub 获取原始内容。URL 构建遵循以下规则：
```
https://raw.githubusercontent.com/{owner}/{repo}/main/skills/{skillName}/SKILL.md
```
**URL 组件解析：**
| 组件 | 来源 | 说明 |
|------|------|------|
| `owner` | identifier 前半部分或 `anthropics` | 仓库所有者 |
| `repo` | identifier 后半部分或 `skills` | 仓库名称 |
| `skillName` | identifier 最后部分 | 技能名称（小写） |
| 分支 | 固定为 `main` | GitHub 仓库分支 |
| 文件路径 | 固定为 `skills/{skillName}/SKILL.md` | 标准技能文件结构 |
资料来源：[src/core/conversion-engine.ts:75-89]()
## 错误处理
技能获取器定义了多种错误类型以应对不同的失败场景。
### 错误类型
| 错误类型 | 触发条件 | HTTP 状态码 |
|----------|----------|-------------|
| `NotFoundError` | 技能不存在或路径错误 | 404 |
| `NetworkError` | 网络连接失败或超时 | - |
| `FetchError` | HTTP 请求失败（非 200） | 4xx/5xx |
资料来源：[src/core/errors.ts]()
### 错误响应格式
所有工具错误返回统一格式：
```json
{
"error": "Error message describing what went wrong",
"tool": "tool_name",
"timestamp": "2024-01-15T10:30:00.000Z"
}
```
资料来源：[examples/usage-examples.md:189-195]()
### 常见错误场景
| 错误场景 | 错误消息示例 | 解决方案 |
|---------|-------------|---------|
| 技能不存在 | `Skill not found: unknown/skill` | 检查 identifier 拼写 |
| 网络连接失败 | `Failed to connect to GitHub` | 检查网络连接 |
| 仓库不可访问 | `Repository not found` | 确认仓库公开状态 |
资料来源：[README.md:77-85]()
## 重试机制
技能获取器内置重试逻辑以提高网络请求的可靠性。
**重试策略：**
| 参数 | 配置 |
|------|------|
| 最大重试次数 | 3 次 |
| 重试间隔 | 指数退避 |
| 初始延迟 | 1000ms |
| 最大延迟 | 5000ms |
指数退避公式：`delay = min(initialDelay * 2^attempt, maxDelay)`
资料来源：[README.md:73]()
## 与其他模块的集成
### 在导入工作流中的角色
技能获取器是 `import_skill` 工具的底层依赖。`import_skill` 工具的执行流程如下：
```mermaid
graph LR
A[fetch_skill] --> B[validate_skill]
B --> C[convert_to_steering 或 convert_to_power]
C --> D[返回导入结果]
A -.->|数据源| B
B -.->|验证通过| C
```
资料来源：[README.md:50-60]()
### 配合安全验证
获取到的原始内容会立即传递给安全验证模块进行检查。安全验证器会扫描以下危险模式：
- **危险命令**：`rm -rf`、`sudo`、`eval`、`exec`
- **可疑文件操作**：`/etc/`、`/usr/`、`/bin/`
- **代码注入模式**：`${...}`、`$(...)`
- **不可信来源**：非 GitHub URL
资料来源：[README.md:71-73]()
## 使用限制
| 限制项 | 值 | 说明 |
|--------|---|------|
| 内容大小 | 无明确限制 | 受 GitHub 响应大小限制 |
| 并发请求 | 无限制 | 但建议限制频率以避免触发限流 |
| 缓存 | 1 小时 TTL | 仅对 skills.sh 搜索结果缓存，获取操作不缓存 |
资料来源：[README.md:74-76]()
## 总结
技能获取器作为 Skill Loader MCP Server 的数据入口，提供了一个简洁可靠的接口从 GitHub 仓库获取 Claude Skills 的原始内容。它支持灵活的标识符格式，内置完善的错误处理和重试机制，并为后续的安全验证和格式转换模块提供稳定的数据源。该模块的稳定性直接影响整个导入工作流的可靠性。
---
## 转换引擎
### 相关页面
相关主题：[安全验证器](#page-security-validator), [MCP工具详解](#page-mcp-tools)
相关源码文件
以下源码文件用于生成本页说明：
- [src/core/conversion-engine.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)
- [src/core/conversion-engine.test.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.test.ts)
- [src/tools/convert-to-steering.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/convert-to-steering.ts)
- [src/tools/convert-to-power.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/convert-to-power.ts)
# 转换引擎
转换引擎（Conversion Engine）是 Skill Loader MCP Server 的核心模块，负责将 Claude Skills 格式的内容转换为 Kiro 平台所需的两种格式：**Steering 文件格式** 和 **Power 格式**。该引擎封装了所有与格式转换相关的逻辑，为 MCP 工具层提供统一的转换接口。
## 核心职责
转换引擎的主要职责包括：
1. **解析 Skill 内容** — 解析 YAML frontmatter 和 Markdown 正文，提取元数据、标题层级和正文内容
2. **格式转换** — 将解析后的技能数据转换为 steering 文件或 power 格式
3. **文件名生成** — 将技能名称转换为 kebab-case 格式作为输出文件名
4. **元数据注入** — 在转换后的文件中添加原始技能信息、来源 URL 和导入时间戳
5. **条件生成** — 根据技能内容特征判断是否需要生成额外的 `mcp.json` 或 `steering/` 目录
资料来源：[src/core/conversion-engine.ts:1-50]()
## 架构概览
```mermaid
graph TD
A[原始 Skill 内容] --> B[ConversionEngine]
B --> C{parseSkill}
C --> D[ParsedSkill 数据结构]
D --> E[toSteeringFile]
D --> F[toPower]
E --> G[Steering 文件]
F --> H[POWER.md]
F --> I{shouldGenerateMcpJson?}
F --> J{shouldGenerateSteeringDir?}
I -->|是| K[mcp.json]
J -->|是| L[steering/ 目录]
G --> M[转换结果]
H --> N[files 数组]
K --> N
L --> N
```
## 核心类与接口
### ConversionEngine 类
`ConversionEngine` 是转换引擎的核心类，提供所有转换操作的入口方法。
| 方法名 | 参数 | 返回值 | 功能说明 |
|--------|------|--------|----------|
| `parseSkill` | `content: string` | `ParsedSkill` | 解析 Skill 内容，返回结构化数据 |
| `toSteeringFile` | `skill: ParsedSkill, sourceUrl?: string` | `SteeringResult` | 转换为 Steering 文件格式 |
| `toPower` | `skill: ParsedSkill, sourceUrl?: string` | `PowerResult` | 转换为 Power 格式 |
| `toKebabCase` | `str: string` | `string` | 字符串转 kebab-case |
| `extractKeywords` | `description: string` | `string[]` | 从描述中提取关键词 |
| `shouldGenerateMcpJson` | `skill: ParsedSkill` | `boolean` | 判断是否需要生成 mcp.json |
| `generateMcpJson` | `skill: ParsedSkill` | `McpJsonConfig` | 生成 mcp.json 配置内容 |
| `shouldGenerateSteeringDir` | `skill: ParsedSkill` | `boolean` | 判断是否需要生成 steering/ 目录 |
| `generateSteeringContent` | `skill: ParsedSkill` | `string` | 生成 steering/ 目录内容 |
资料来源：[src/core/conversion-engine.ts:1-100]()
### ParsedSkill 数据结构
解析后的技能数据结构包含以下字段：
```typescript
interface ParsedSkill {
frontmatter: {
name: string; // 技能名称
description: string; // 技能描述
dependencies?: string[]; // 依赖列表（可选）
[key: string]: any; // 其他 frontmatter 字段
};
body: string; // 原始正文内容
sections: Array<{ // 解析后的章节列表
heading: string; // 章节标题
level: number; // 标题层级（1-6）
content: string; // 章节内容
}>;
}
```
资料来源：[src/core/conversion-engine.ts:50-80]()
## 解析流程
`parseSkill` 方法负责将原始 Markdown 内容解析为结构化数据：
```mermaid
graph TD
A[原始内容] --> B{内容为空?}
B -->|是| C[抛出 ValidationError]
B -->|否| D[解析 YAML Frontmatter]
D --> E{name 存在?}
E -->|否| F[使用 'Untitled Skill']
E -->|是| G[提取 name 字段]
D --> H{description 存在?}
H -->|否| I[抛出 ValidationError]
H -->|是| J[提取 description 字段]
G --> K[构建 frontmatter 对象]
F --> K
I --> K
K --> L[解析 Markdown 章节]
L --> M[构建 sections 数组]
M --> N[返回 ParsedSkill]
```
### 解析规则
- **空内容检测**：空字符串会抛出 `ValidationError`，错误消息包含 "empty" 关键词
- **必填字段验证**：缺少 `name` 或 `description` 会抛出错误
- **章节解析**：使用标题行（`#`、`##`、`###` 等）分割正文，构建层级化的 sections 数组
- **容错处理**：缺少 frontmatter 时，使用默认值 `name: 'Untitled Skill'`
资料来源：[src/core/conversion-engine.test.ts:20-80]()
## Steering 文件转换
Steering 文件是 Kiro 平台的轻量级格式，用于在 `.kiro/steering/` 目录下存储技能指南。
### 输出格式
```markdown
---
original_skill: {技能名称}
source_url: {来源URL}
imported_at: {ISO时间戳}
---
# {技能名称}
{正文内容}
## Dependencies
- {依赖1}
- {依赖2}
---
*Imported from Claude Skills via Skill Loader Power*
```
### 转换结果结构
```typescript
interface SteeringResult {
steeringContent: string; // Steering 文件内容
filename: string; // 文件名（kebab-case）
targetPath: string; // 目标路径 .kiro/steering/{filename}
metadata: {
skillName: string;
sourceUrl?: string;
outputFormat: 'steering';
validationResult: ValidationResult;
};
}
```
资料来源：[src/tools/convert-to-steering.ts]()
## Power 格式转换
Power 格式是 Kiro 平台的高级格式，支持更复杂的技能配置。当技能具有依赖或工具引用时，会自动生成额外的配置文件。
### 输出结构
```mermaid
graph TD
A[PowerResult] --> B[files: Array]
B --> C[POWER.md]
B --> D[mcp.json?]
B --> E[steering/?]
C --> F[displayName, body, Dependencies, Import Metadata]
D --> G[dependencies 数组]
E --> H[详细章节内容]
```
### 生成条件
| 条件 | 生成文件 | 说明 |
|------|----------|------|
| `dependencies` 存在且非空 | `mcp.json` | 包含依赖列表 |
| 存在 MCP server 工具引用 | `mcp.json` | 包含 MCP 服务器配置 |
| 3+ 个复杂章节（层级≥2，内容>200字符） | `steering/` 目录 | 存储详细指南内容 |
### PowerResult 结构
```typescript
interface PowerResult {
powerName: string; // Power 名称（kebab-case）
displayName: string; // 显示名称（原始格式）
files: Array<{
path: string; // 文件路径
content: string; // 文件内容
}>;
}
```
资料来源：[src/core/conversion-engine.ts:100-200]()
## kebab-case 转换
转换引擎提供了 `toKebabCase` 方法，将任意字符串转换为标准的 kebab-case 格式（用于 Kiro powers 和 steering 文件的标准命名规范）。
### 转换规则
1. 转换为小写
2. 空格和下划线替换为连字符
3. 移除特殊字符（仅保留 a-z、0-9 和连字符）
4. 折叠多个连续连字符为一个
5. 移除首尾连字符
### 转换示例
| 输入 | 输出 |
|------|------|
| `PDF Extractor` | `pdf-extractor` |
| `React_Best_Practices` | `react-best-practices` |
| `My Skill!!` | `my-skill` |
资料来源：[src/core/conversion-engine.ts:60-100]()
## 关键词提取
`extractKeywords` 方法从技能描述中提取最多 5 个有意义的关键词：
### 过滤规则
- 移除停用词集合中的常见词（`the`, `and`, `for`, `with`, `this`, `that`, `from`, `into` 等）
- 仅保留长度 ≥ 3 的单词
- 移除特殊字符后按空格分割
```typescript
private extractKeywords(description: string): string[] {
const stopWords = new Set([
'the', 'and', 'for', 'with', 'this', 'that', 'from', 'into',
'when', 'what', 'where', 'how', 'why', 'can', 'will', 'should',
'would', 'could', 'has', 'have', 'had', 'are', 'was', 'were',
'been', 'being', 'you', 'your', 'use', 'used', 'using'
]);
// ... 实现逻辑
}
```
资料来源：[src/core/conversion-engine.ts:200-250]()
## MCP 工具集成
转换引擎通过两个 MCP 工具与外部交互：
### convert_to_steering
将原始 Skill 内容转换为 Steering 文件格式：
```typescript
interface ConvertToSteeringInput {
content: string; // 必填：Skill 内容
sourceUrl?: string; // 可选：原始来源 URL
}
```
资料来源：[src/tools/convert-to-steering.ts]()
### convert_to_power
将原始 Skill 内容转换为 Power 格式：
```typescript
interface ConvertToPowerInput {
content: string; // 必填：Skill 内容
sourceUrl?: string; // 可选：原始来源 URL
}
```
**自动生成逻辑**：当技能包含依赖或工具引用时，自动在 `files` 数组中添加 `mcp.json`；当技能有 3+ 个复杂章节时，添加 `steering/` 目录。
资料来源：[src/tools/convert-to-power.ts]()
## 完整导入流程
转换引擎通常在 `import_skill` 工具中被调用，作为完整导入工作流的一部分：
```mermaid
graph LR
A[fetch_skill] --> B[validate_skill]
B --> C{验证通过?}
C -->|否| D[返回错误]
C -->|是| E[ConversionEngine.parseSkill]
E --> F{outputFormat}
F -->|steering| G[ConversionEngine.toSteeringFile]
F -->|power| H[ConversionEngine.toPower]
G --> I[SteeringResult]
H --> J[PowerResult]
I --> K[输出到 .kiro/steering/]
J --> L[输出到 ~/.kiro/powers/]
```
资料来源：[README.md]()，[src/core/conversion-engine.test.ts]()
## 测试覆盖
转换引擎拥有完整的单元测试覆盖，测试文件为 `src/core/conversion-engine.test.ts`。
### 测试场景
| 测试用例 | 验证内容 |
|----------|----------|
| `parses valid skill with frontmatter and body` | 正确解析包含 frontmatter 和正文的技能 |
| `throws on empty content` | 空内容抛出 ValidationError |
| `throws on missing name in frontmatter` | 缺少 name 字段时抛出错误 |
| `throws on missing description in frontmatter` | 缺少 description 字段时抛出错误 |
| `handles content without frontmatter` | 无 frontmatter 时使用默认值 |
| `converts parsed skill to steering format` | Steering 文件格式转换正确 |
| `includes dependencies in steering file` | 依赖项正确包含在 Steering 文件中 |
| `converts parsed skill to power format` | Power 格式转换正确 |
| `generates mcp.json when skill has dependencies` | 有依赖时正确生成 mcp.json |
| `does not generate mcp.json when skill has no dependencies` | 无依赖时不生成 mcp.json |
资料来源：[src/core/conversion-engine.test.ts:1-150]()
## 依赖关系
```mermaid
graph TD
A[conversion-engine.ts] --> B[errors.ts]
A --> C[ParsedSkill 类型定义]
C --> D[frontmatter 类型]
C --> E[section 类型]
B --> F[SkillLoaderError]
B --> G[ValidationError]
B --> H[FileSystemError]
I[convert-to-steering.ts] --> A
J[convert-to-power.ts] --> A
K[import_skill 工具] --> I
K --> J
```
## 扩展点
如需扩展转换引擎功能，可考虑以下方向：
1. **新增输出格式**：添加新的转换方法（如 `toPrompt` 或 `toAgentConfig`）
2. **自定义元数据**：扩展 frontmatter 的解析和注入逻辑
3. **高级章节处理**：增强 `shouldGenerateSteeringDir` 的判断逻辑
4. **模板支持**：引入模板引擎以支持自定义输出格式
---
## 安全验证器
### 相关页面
相关主题：[技能获取器](#page-skill-fetcher), [转换引擎](#page-conversion-engine)
相关源码文件
以下源码文件用于生成本页说明：
- [src/core/security-validator.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)
- [src/core/security-validator.test.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.test.ts)
- [src/core/conversion-engine.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)
- [src/core/errors.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts)
- [examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)
# 安全验证器
## 概述
安全验证器（Security Validator）是 Skill Loader MCP Server 的核心安全组件，负责在导入外部技能（Skill）之前对其内容进行全面的安全扫描和风险评估。该组件能够检测危险命令、可疑文件操作、代码注入模式和不受信任的来源，从而保护用户系统免受潜在恶意代码的侵害。
安全验证器的主要职责包括：
- 扫描技能内容中的危险系统命令
- 检测可疑的文件路径访问
- 识别代码注入模式（如变量展开和命令替换）
- 验证技能来源的可信度
- 提供详细的验证结果和修复建议
资料来源：[src/core/security-validator.ts:1-50]()
## 架构设计
### 模块位置
安全验证器位于 `src/core/security-validator.ts`，是核心模块的重要组成部分。项目的目录结构如下：
```
skill-loader-mcp-server/
├── src/
│ ├── core/ # 核心功能模块
│ │ ├── security-validator.ts # 安全验证器
│ │ ├── conversion-engine.ts # 转换引擎
│ │ └── errors.ts # 错误处理
│ ├── tools/ # MCP 工具实现
│ ├── utils/ # 工具函数
│ └── index.ts # 主入口点
├── tests/ # 测试文件
└── examples/ # 使用示例
```
资料来源：[CONTRIBUTING.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CONTRIBUTING.md)
### 验证流程
安全验证器采用多阶段验证流程，对技能内容进行逐层安全检查：
```mermaid
graph TD
A[接收技能内容] --> B[扫描危险命令]
B --> C{检测到危险命令?}
C -->|是| D[标记为 unsafe]
C -->|否| E[检查可疑文件路径]
E --> F{检测到可疑路径?}
F -->|是| G[标记为 unsafe]
F -->|否| H[检测代码注入模式]
H --> I{检测到注入模式?}
I -->|是| J[标记为 warning]
I -->|否| K[验证来源可信度]
K --> L{来源可信?}
L -->|是| M[标记为 safe]
L -->|否| N[标记为 unsafe]
D --> O[返回验证结果]
G --> O
J --> O
M --> O
N --> O
```
资料来源：[src/core/security-validator.ts:30-45]()
## 验证规则
### 危险命令检测
安全验证器会扫描技能内容中的危险系统命令，这些命令可能对系统造成不可逆的损害。
| 命令模式 | 描述 | 严重级别 |
|---------|------|---------|
| `rm -rf` | 递归强制删除命令 | unsafe |
| `sudo` | 超级用户权限执行 | unsafe |
| `eval` | 动态代码执行 | unsafe |
| `exec` | 命令执行函数 | unsafe |
```typescript
// 危险命令检测逻辑示例
const dangerousCommands = ['rm -rf', 'sudo', 'eval', 'exec'];
dangerousCommands.forEach(cmd => {
if (content.includes(cmd)) {
issues.push({
type: 'dangerous_command',
description: `危险命令: ${cmd}`,
location: `Line ${getLineNumber(content, index)}`
});
}
});
```
资料来源：[src/core/security-validator.ts:50-80]()
### 可疑文件路径检测
验证器会检查技能内容中是否包含对系统关键目录的访问企图。
| 路径模式 | 描述 | 风险级别 |
|---------|------|---------|
| `/etc/` | 系统配置文件目录 | warning |
| `/usr/` | 系统程序目录 | warning |
| `/bin/` | 二进制可执行文件目录 | warning |
这些路径的访问通常不是普通技能所需的，可能表明存在恶意意图。
资料来源：[src/core/security-validator.ts:80-100]()
### 代码注入模式检测
安全验证器能够识别多种代码注入攻击模式。
| 注入类型 | 模式示例 | 描述 |
|---------|---------|------|
| 变量展开 | `${VARIABLE}` | 模板变量展开可能执行任意代码 |
| 命令替换 | `$(command)` | Shell 命令替换语法 |
```typescript
// 代码注入检测
if (content.includes('${')) {
issues.push({
type: 'code_injection',
description: '检测到变量展开模式'
});
}
if (content.includes('$(')) {
issues.push({
type: 'command_substitution',
description: '检测到命令替换模式'
});
}
```
资料来源：[src/core/security-validator.ts:100-130]()
### 来源可信度验证
安全验证器会验证技能来源的可靠性。只有来自受信任来源的技能才会被标记为安全。
| 来源类型 | 可信状态 | 说明 |
|---------|---------|------|
| GitHub URL | 可信 | GitHub 是主要的技能托管平台 |
| 其他 URL | 不可信 | 存在安全风险 |
```typescript
if (url && !url.includes('github.com')) {
issues.push({
type: 'untrusted_source',
description: '技能来源不是受信任的 GitHub URL',
location: 'Source URL'
});
}
```
资料来源：[src/core/security-validator.ts:130-150]()
## API 接口
### validate_skill 工具
`validate_skill` 是 MCP 服务器提供的安全验证工具，用于验证技能内容的安全性。
**参数定义：**
| 参数名 | 类型 | 必需 | 描述 |
|-------|------|------|------|
| content | string | 是 | 要验证的技能内容 |
| url | string | 否 | 来源 URL 用于验证 |
**返回值结构：**
```json
{
"isValid": true,
"issues": [
{
"type": "dangerous_command",
"description": "危险递归删除命令 (rm -rf)",
"location": "Line 7: rm -rf /"
}
],
"severity": "unsafe"
}
```
**使用示例：**
```json
{
"tool": "validate_skill",
"arguments": {
"content": "---\nname: Test\n---\n\n# Test",
"url": "https://example.com/skill.md"
}
}
```
资料来源：[examples/usage-examples.md:1-30]()
### 验证结果对象
验证完成后，系统返回一个结构化的验证结果对象。
```typescript
interface ValidationResult {
isValid: boolean; // 是否通过验证
issues: ValidationIssue[]; // 发现的问题列表
severity: 'safe' | 'warning' | 'unsafe'; // 整体严重级别
}
```
**严重级别判定规则：**
| 条件 | 判定结果 |
|-----|---------|
| 存在 `untrusted_source` 或 `dangerous_command` | unsafe |
| 仅存在 `suspicious_pattern` | warning |
| 无任何问题 | safe |
资料来源：[src/core/security-validator.ts:200-220]()
## 错误处理
### ValidationError 类
当验证过程发生错误时，系统会抛出 `ValidationError` 异常。
```typescript
export class ValidationError extends SkillLoaderError {
public readonly validationType: 'format' | 'security' | 'schema' | 'content';
public readonly lineNumber?: number;
public readonly details: string[];
}
```
**错误类型：**
| 类型 | 描述 | 恢复建议 |
|-----|------|---------|
| format | 格式错误 | 验证 YAML frontmatter 格式是否正确 |
| security | 安全问题 | 手动检查技能内容，使用可信来源的技能 |
| schema | 结构错误 | 验证技能是否符合 Agent Skills 标准 |
| content | 内容错误 | 检查内容语法，向技能作者报告问题 |
资料来源：[src/core/errors.ts:80-120]()
### 错误消息格式
```typescript
getUserMessage(): string {
let msg = `Validation Error: ${this.message}\n`;
msg += `Type: ${this.validationType}\n`;
if (this.lineNumber) {
msg += `Line: ${this.lineNumber}\n`;
}
msg += '\nDetails:\n';
for (const detail of this.details) {
msg += `- ${detail}\n`;
}
// 根据验证类型添加恢复建议
if (this.validationType === 'security') {
msg += '\nSuggestions:\n';
msg += '- Review the skill content manually\n';
msg += '- Contact the skill author about security concerns\n';
msg += '- Use a different skill from a trusted source\n';
}
return msg;
}
```
资料来源：[src/core/errors.ts:120-150]()
## 测试覆盖
安全验证器拥有完整的单元测试覆盖，确保各项安全检测功能的准确性。
### 测试用例列表
| 测试用例 | 测试目标 | 预期结果 |
|---------|---------|---------|
| 检测危险删除命令 | `rm -rf /` | 发现问题 |
| 检测提权命令 | `sudo rm` | 发现问题 |
| 检测 eval 使用 | `eval $var` | 发现问题 |
| 检测代码注入 | `${VARIABLE}` | 发现问题 |
| 检测命令替换 | `$(whoami)` | 发现问题 |
| 检测可疑模式 | `~/. hidden` | 警告级别 |
资料来源：[src/core/security-validator.test.ts:1-50]()
### 测试实现示例
```typescript
it('detects dangerous commands', () => {
const content = makeContent('rm -rf /');
const result = validator.validate(content);
expect(result.issues.some(i => i.type === 'dangerous_command')).toBe(true);
});
it('detects code injection patterns', () => {
const content = makeContent('Use ${VARIABLE} in template');
const result = validator.validate(content);
expect(result.issues.some(i => i.description.includes('Variable expansion'))).toBe(true);
});
it('returns warning for suspicious patterns only', () => {
const content = makeContent('Access ~/. hidden files');
const result = validator.validate(content);
expect(result.isValid).toBe(true);
expect(result.severity).toBe('warning');
});
```
资料来源：[src/core/security-validator.test.ts:30-60]()
## 与转换引擎的集成
安全验证器是转换引擎（Conversion Engine）工作流程的重要组成部分。在将技能转换为 Kiro 格式之前，系统会自动进行安全验证。
```mermaid
graph LR
A[fetch_skill] --> B[validate_skill]
B --> C{验证通过?}
C -->|是| D[convert_to_steering]
C -->|否| E[返回错误]
D --> F[导入完成]
E --> G[跳过或报告]
```
资料来源：[src/core/conversion-engine.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)
### import_skill 工具
`import_skill` 工具提供了完整的导入工作流程，包含自动安全验证：
```json
{
"tool": "import_skill",
"arguments": {
"identifier": "anthropics/pdf-extractor",
"outputFormat": "power",
"skipValidation": false
}
}
```
**参数说明：**
| 参数 | 类型 | 必需 | 默认值 | 描述 |
|-----|------|------|-------|------|
| identifier | string | 是 | - | 技能标识符 |
| outputFormat | string | 是 | - | 输出格式：`steering` 或 `power` |
| skipValidation | boolean | 否 | false | 是否跳过安全验证 |
**响应示例：**
```json
{
"success": true,
"targetPath": "~/.kiro/powers/pdf-extractor/POWER.md",
"metadata": {
"validationResult": {
"isValid": true,
"issues": [],
"severity": "safe"
}
}
}
```
资料来源：[examples/usage-examples.md:80-120]()
## 配置与使用建议
### 何时跳过验证
在某些情况下，用户可能需要跳过安全验证：
| 场景 | 建议 | 风险等级 |
|-----|------|---------|
| 内部可信技能 | 可跳过 | 低 |
| 已人工审查的技能 | 可跳过 | 低 |
| 来自不可信来源 | 建议保留验证 | 高 |
| 包含系统命令的技能 | 必须保留验证 | 高 |
### 验证流程建议
建议的技能导入流程如下：
1. **获取技能信息**：使用 `fetch_skill` 获取原始内容
2. **验证安全性**：使用 `validate_skill` 检查安全问题
3. **审查结果**：检查返回的 issues 列表
4. **转换格式**：使用 `convert_to_steering` 或 `convert_to_power` 转换
5. **导入技能**：根据验证结果决定是否继续
资料来源：[examples/usage-examples.md:120-150]()
## 安全特性总结
安全验证器提供了多层次的安全保护机制：
| 安全功能 | 实现状态 | 描述 |
|---------|---------|------|
| 危险命令检测 | ✅ 已实现 | 检测 rm -rf, sudo, eval, exec |
| 可疑路径检测 | ✅ 已实现 | 检测 /etc/, /usr/, /bin/ |
| 代码注入检测 | ✅ 已实现 | 检测 ${} 和 $() 模式 |
| 来源验证 | ✅ 已实现 | 仅允许 GitHub 来源 |
| 严重级别评估 | ✅ 已实现 | safe/warning/unsafe 三级 |
| 详细错误信息 | ✅ 已实现 | 包含行号和修复建议 |
资料来源：[src/core/security-validator.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)
---
## 缓存机制
### 相关页面
相关主题：[核心模块架构](#page-core-modules), [技能获取器](#page-skill-fetcher)
相关源码文件
以下源码文件用于生成本页说明：
- [src/utils/cache.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/utils/cache.ts)
- [README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)
- [CHANGELOG.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CHANGELOG.md)
# 缓存机制
## 概述
Skill Loader MCP Server 实现了一套内存缓存系统，用于提升 API 调用效率并减少网络请求次数。缓存机制的核心设计目标是：
- 减少对 skills.sh 目录 API 的重复调用
- 提升搜索和列表查询的响应速度
- 通过 TTL（Time-To-Live）机制确保数据的时效性
缓存系统在项目架构中属于基础工具层，被核心业务模块调用。资料来源：[src/utils/cache.ts:1-20]()
## 核心组件
### CacheEntry 接口
泛型缓存条目接口，存储数据及其时间戳：
| 字段 | 类型 | 描述 |
|------|------|------|
| `data` | `T` | 缓存的数据内容 |
| `timestamp` | `number` | 缓存创建时间戳（毫秒） |
资料来源：[src/utils/cache.ts:6-10]()
### Cache 类
通用内存缓存类，支持 TTL 过期机制：
```typescript
export class Cache {
private cache: Map> = new Map();
private ttl: number;
}
```
| 属性 | 类型 | 描述 |
|------|------|------|
| `cache` | `Map>` | 内部缓存存储结构 |
| `ttl` | `number` | 缓存有效期（毫秒） |
资料来源：[src/utils/cache.ts:14-17]()
## API 参考
### 构造函数
```typescript
constructor(ttl: number)
```
| 参数 | 类型 | 描述 |
|------|------|------|
| `ttl` | `number` | 缓存存活时间（毫秒） |
资料来源：[src/utils/cache.ts:19-24]()
### get 方法
从缓存中获取值，若不存在或已过期则返回 `undefined`：
```typescript
get(key: string): T | undefined
```
**执行流程：**
```mermaid
graph TD
A[调用 get 方法] --> B{查找 key 是否存在}
B -->|不存在| C[返回 undefined]
B -->|存在| D{检查是否过期}
D -->|已过期| E[删除 key 并返回 undefined]
D -->|未过期| F[返回缓存数据]
```
资料来源：[src/utils/cache.ts:31-50]()
### set 方法
将数据存入缓存，自动记录当前时间戳：
```typescript
set(key: string, data: T): void
```
| 参数 | 类型 | 描述 |
|------|------|------|
| `key` | `string` | 缓存键名 |
| `data` | `T` | 要缓存的数据 |
资料来源：[src/utils/cache.ts:57-66]()
### has 方法
检查指定键是否存在且未过期：
```typescript
has(key: string): boolean
```
**返回值说明：**
| 返回值 | 含义 |
|--------|------|
| `true` | 键存在且未过期 |
| `false` | 键不存在或已过期 |
资料来源：[src/utils/cache.ts:73-86]()
## 过期检测机制
缓存条目通过时间戳与当前时间的差值判断是否过期：
```typescript
if (Date.now() - entry.timestamp > this.ttl) {
this.cache.delete(key);
return undefined;
}
```
- **当前时间**：`Date.now()` 返回自 1970-01-01 以来的毫秒数
- **时间差**：当前时间减去缓存创建时间
- **过期判定**：时间差大于 `ttl` 值时视为过期
资料来源：[src/utils/cache.ts:44-47]()
## 实际应用场景
### skills.sh 目录缓存
项目在生产环境中使用 1 小时 TTL 对 skills.sh 目录搜索结果进行缓存：
> The server caches skills.sh search results in memory for 1 hour to reduce API calls and improve performance. The cache is automatically refreshed when expired.
资料来源：[README.md:95-97]()
### 缓存优势
| 优势 | 说明 |
|------|------|
| 减少 API 调用 | 避免重复请求 skills.sh 目录 |
| 提升响应速度 | 命中缓存时直接返回，无需网络请求 |
| 自动刷新 | TTL 过期后自动清除，确保数据时效性 |
资料来源：[CHANGELOG.md:10-12]()
## 架构位置
缓存模块位于项目的工具层，被核心业务模块依赖：
```
skill-loader-mcp-server/
├── src/
│ ├── core/ # 核心业务逻辑
│ ├── tools/ # MCP 工具实现
│ ├── utils/ # 工具函数（包含 cache.ts）
│ ├── index.ts # 主入口
│ └── cli.ts # CLI 入口
├── examples/ # 使用示例
├── dist/ # 编译输出
└── tests/ # 测试文件
```
资料来源：[CONTRIBUTING.md:10-18]()
## 使用限制
当前缓存实现为**进程级内存缓存**，存在以下限制：
| 限制 | 说明 |
|------|------|
| 进程生命周期 | 服务重启后缓存丢失 |
| 单实例 | 分布式环境下各实例独立缓存 |
| 内存占用 | 大数据量缓存可能影响内存使用 |
> **注意**：此缓存工具类为未来扩展性提供，项目当前主要依赖 SkillResolver 类的内置缓存功能。
资料来源：[src/utils/cache.ts:3-6]()
## 扩展建议
如需更强的缓存能力，可考虑：
1. **持久化缓存**：接入 Redis 或 Memcached
2. **分布式缓存**：支持多实例共享
3. **缓存预热**：服务启动时主动加载热门数据
4. **缓存统计**：添加命中率和性能指标监控
---
## 命令行工具
### 相关页面
相关主题：[项目介绍](#page-project-intro)
相关源码文件
以下源码文件用于生成本页说明：
- [src/cli.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/cli.ts)
- [test-server.js](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/test-server.js)
- [examples/mcp-config.json](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/mcp-config.json)
- [README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CONTRIBUTING.md)
# 命令行工具
Skill Loader MCP Server 提供了一套完整的命令行工具，用于管理 Claude Skills 的导入、转换和验证操作。本页面详细说明服务器的命令行使用方式、配置参数以及与 Claude Desktop 和 Kiro 的集成方法。
## 概述
Skill Loader MCP Server 的命令行工具是连接 Claude Desktop 与技能仓库的桥梁。通过 MCP（Model Context Protocol）协议，服务器提供了 9 个核心工具函数，涵盖技能发现、获取、验证、格式转换和导入等完整工作流程。资料来源：[README.md:1-50]()
### 支持的运行环境
| 运行方式 | 说明 | 环境变量要求 |
|---------|------|-------------|
| Claude Desktop | 通过配置文件集成 | 可选 |
| Kiro | 通过 mcp.json 配置 | 可选 |
| 独立运行 | 直接执行二进制 | 可选 |
| npx | 在线执行 | 可选 |
## 快速开始
### 通过 npx 运行
使用 npx 可以直接运行最新版本的服务器，无需本地安装：
```bash
npx -y @goldzulu/skill-loader-mcp-server
```
资料来源：[README.md:60-65]()
### 独立安装运行
```bash
# 全局安装
npm install -g skill-loader-mcp-server
# 直接运行
skill-loader-mcp-server
```
资料来源：[README.md:70-75]()
## Claude Desktop 集成
### 配置文件位置
根据操作系统不同，配置文件位于：
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
### 配置示例
在 Claude Desktop 配置文件中添加以下内容：
```json
{
"mcpServers": {
"skill-loader": {
"command": "npx",
"args": ["-y", "@goldzulu/skill-loader-mcp-server"],
"env": {
"SKILLS_SH_API_KEY": "your-api-key-here"
},
"description": "Skill Loader MCP Server for managing Claude skills"
}
}
}
```
资料来源：[README.md:35-50]()
### 使用可执行文件路径
如果已全局安装，也可以直接指定可执行文件路径：
```json
{
"mcpServers": {
"skill-loader": {
"command": "skill-loader-mcp-server",
"env": {
"SKILLS_SH_API_KEY": "your-api-key-here"
}
}
}
}
```
## 环境变量配置
### SKILLS_SH_API_KEY
此环境变量用于访问 skills.sh 的高级 API 功能，包括分页列出所有技能和获取排行榜数据。
| 配置状态 | 影响的功能 |
|---------|-----------|
| 未设置 | 可使用 search_skills、fetch_skill、validate_skill、convert_*、import_skill |
| 已设置 | 额外解锁 list_skills、get_leaderboard 功能 |
资料来源：[README.md:90-95]()
### 配置方式
环境变量可以通过配置文件中的 `env` 块设置，也可以在 shell 中预先导出：
```bash
export SKILLS_SH_API_KEY="your-api-key-here"
```
## MCP 工具列表
服务器提供了 9 个 MCP 工具，按功能可分为以下几类：
### 技能发现类
| 工具名称 | 功能 | 认证要求 |
|---------|------|---------|
| search_skills | 按关键词搜索技能 | 不需要 |
| list_skills | 分页列出所有技能 | 需要 API Key |
| get_leaderboard | 获取热门/趋势技能 | 需要 API Key |
资料来源：[README.md:85-120]()
### 技能获取类
| 工具名称 | 功能 | 认证要求 |
|---------|------|---------|
| fetch_skill | 从 GitHub 获取技能原始内容 | 不需要 |
### 技能验证类
| 工具名称 | 功能 | 认证要求 |
|---------|------|---------|
| validate_skill | 验证技能内容安全性 | 不需要 |
### 格式转换类
| 工具名称 | 功能 | 认证要求 |
|---------|------|---------|
| convert_to_steering | 转换为 Kiro 转向文件格式 | 不需要 |
| convert_to_power | 转换为 Kiro Power 格式 | 不需要 |
### 导入操作类
| 工具名称 | 功能 | 认证要求 |
|---------|------|---------|
| import_skill | 完整导入工作流（获取+验证+转换） | 不需要 |
## 安全验证机制
命令行工具内置了安全验证功能，会在导入前自动扫描技能内容：
### 检测的威胁类型
| 威胁类型 | 示例 | 严重级别 |
|---------|------|---------|
| 危险命令 | `rm -rf`、`sudo`、`eval`、`exec` | 不安全 |
| 可疑文件操作 | `/etc/`、`/usr/`、`/bin/` | 警告 |
| 代码注入模式 | `${...}`、`$(...)` | 警告 |
| 不信任来源 | 非 GitHub URL | 不安全 |
资料来源：[README.md:175-185]()
### 验证响应示例
```json
{
"isValid": false,
"issues": [
{
"type": "dangerous_command",
"description": "Dangerous recursive delete command (rm -rf)",
"location": "Line 7: rm -rf /"
}
],
"severity": "unsafe"
}
```
## 典型工作流程
### 流程一：搜索并导入技能
```mermaid
graph TD
A[search_skills 查询关键词] --> B{找到目标技能?}
B -->|是| C[fetch_skill 获取内容]
B -->|否| D[调整搜索条件]
D --> A
C --> E[validate_skill 安全验证]
E --> F{验证通过?}
F -->|是| G[convert_to_steering 或 convert_to_power]
F -->|否| H[输出安全警告]
G --> I[技能已转换]
H --> J[中止导入]
```
### 流程二：使用 list_skills（需 API Key）
```mermaid
graph TD
A[list_skills 分页获取] --> B{还有更多页面?}
B -->|是| C[请求下一页]
C --> A
B -->|否| D[get_leaderboard 获取趋势]
D --> E[fetch_skill 获取技能]
E --> F[import_skill 完整导入]
```
## 完整导入示例
### 导入为 Steering 文件
```json
{
"tool": "import_skill",
"arguments": {
"identifier": "anthropics/pdf-extractor",
"outputFormat": "steering",
"skipValidation": false
}
}
```
响应示例：
```json
{
"success": true,
"content": "---\noriginal_skill: PDF Extractor\n...",
"filename": "pdf-extractor.md",
"targetPath": ".kiro/steering/pdf-extractor.md",
"metadata": {
"skillName": "PDF Extractor",
"validationResult": {
"isValid": true,
"issues": [],
"severity": "safe"
}
}
}
```
### 导入为 Power
```json
{
"tool": "import_skill",
"arguments": {
"identifier": "anthropics/pdf-extractor",
"outputFormat": "power",
"skipValidation": false
}
}
```
## 缓存机制
服务器内置了智能缓存功能：
| 缓存对象 | TTL | 说明 |
|---------|-----|------|
| skills.sh 搜索结果 | 1 小时 | 自动刷新过期缓存 |
资料来源：[README.md:195-200]()
## 错误处理
所有工具返回的错误遵循统一格式：
```json
{
"error": "Error message describing what went wrong",
"tool": "tool_name",
"timestamp": "2024-01-15T10:30:00.000Z"
}
```
### 常见错误场景
| 错误类型 | 原因 | 解决方案 |
|---------|------|---------|
| 网络错误 | 互联网连接问题 | 检查网络和 GitHub 可用性 |
| 未找到错误 | 技能名称或仓库错误 | 验证技能标识符 |
| 验证错误 | 安全问题 | 导入前审查安全问题 |
| 解析错误 | 格式问题 | 检查技能格式和 YAML 语法 |
## 传输协议
服务器支持 **stdio 传输协议**，这是 Claude Desktop 和 Kiro 集成的标准方式。stdio 传输通过标准输入输出流进行进程间通信，确保了与 Claude Desktop 的无缝集成。
资料来源：[CONTRIBUTING.md:25-30]()
## 开发调试
### 本地运行测试服务器
项目中提供了 `test-server.js` 用于本地调试和测试。开发者可以使用该脚本启动一个本地测试环境，验证工具行为是否符合预期。
### 本地开发模式
```bash
# 安装依赖
npm install
# 构建项目
npm run build
# 运行测试
npm test
# 启动服务器
npm start
```
资料来源：[CONTRIBUTING.md:10-15]()
## 输出格式
### Steering 格式输出
当 `outputFormat` 为 `steering` 时，输出包含以下字段：
| 字段 | 类型 | 说明 |
|-----|------|------|
| steeringContent | string | 转向文件完整内容 |
| filename | string | 建议的文件名（kebab-case） |
| metadata | object | 元数据对象 |
| metadata.originalSkill | string | 原始技能名称 |
| metadata.sourceUrl | string | 来源 URL |
| metadata.importedAt | string | ISO 时间戳 |
### Power 格式输出
当 `outputFormat` 为 `power` 时，输出包含多个文件：
| 文件路径 | 内容说明 |
|---------|---------|
| POWER.md | Power 主文件，包含导入元数据 |
| mcp.json | 可选，技能有依赖或工具引用时生成 |
| steering/ | 可选目录，技能有 3+ 复杂章节时生成 |
## 相关文档
- [使用示例](./examples/usage-examples.md) - 各工具的详细使用案例
- [安全验证](./src/core/security-validator.ts) - 安全机制实现细节
- [错误处理](./src/core/errors.ts) - 错误类定义和使用
---
---
## Doramagic 踩坑日志
项目：goldzulu/skill-loader-mcp-server
摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。
## 1. 配置坑 · 可能修改宿主 AI 配置
- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
- 证据：capability.host_targets | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | host_targets=mcp_host, claude
## 2. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | README/documentation is current enough for a first validation pass.
## 3. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | last_activity_observed missing
## 4. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | no_demo; severity=medium
## 5. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | no_demo; severity=medium
## 6. 安全/权限坑 · 来源证据：v1.0.0 - Initial Release
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.0.0 - Initial Release
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_fb2ea148b03e4fb5993d3b2db08b43f6 | https://github.com/goldzulu/skill-loader-mcp-server/releases/tag/v1.0.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。
## 7. 安全/权限坑 · 来源证据：v1.1.0 — skills.sh API migration & Power format update
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.1.0 — skills.sh API migration & Power format update
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_78c48e3f6caa41a9bf94d3dba01baf0c | https://github.com/goldzulu/skill-loader-mcp-server/releases/tag/v1.1.0 | 来源类型 github_release 暴露的待验证使用条件。
## 8. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | issue_or_pr_quality=unknown
## 9. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | release_recency=unknown