概述

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 平台支持的两种格式：

当技能包含依赖或工具引用时，转换引擎会自动生成 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

#### 错误处理系统

统一的错误处理系统包含多种专用错误类型：

资料来源：src/core/errors.ts:1-80

MCP 工具接口

可用工具列表

资料来源：README.md:50-85

完整导入工作流

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

配置与部署

环境变量

资料来源：README.md:25-30

部署方式

#### Kiro 平台

{
  "mcpServers": {
    "skill-loader": {
      "command": "npx",
      "args": ["-y", "@goldzulu/skill-loader-mcp-server"],
      "env": {
        "SKILLS_SH_API_KEY": "your-api-key-here"
      }
    }
  }
}

#### Claude Desktop

{
  "mcpServers": {
    "skill-loader": {
      "command": "skill-loader-mcp-server",
      "env": {
        "SKILLS_SH_API_KEY": "your-api-key-here"
      }
    }
  }
}

#### 独立运行

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

错误处理

所有工具返回统一格式的错误信息：

{
  "error": "错误描述",
  "tool": "工具名称",
  "timestamp": "ISO 时间戳"
}

常见错误场景：

资料来源：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

概述

Skill Loader MCP Server 提供了一套完整的MCP（Model Context Protocol）工具集，用于管理Claude Skills的生命周期。该工具集涵盖从技能发现、获取、验证、格式转换到完整导入的完整工作流程。资料来源：README.md

系统共包含8个MCP工具，按功能可分为三大类别：

资料来源：README.md

1. 架构概述

Skill Loader MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器应用，用于管理 Claude Skills 的导入、转换和验证。其核心架构采用分层设计，将功能职责分离到不同的模块中。

graph TD
    A[入口层<br/>index.ts / cli.ts] --> B[工具层<br/>MCP Tools]
    B --> C[核心服务层<br/>Core Services]
    C --> D[安全验证模块<br/>Security Validator]
    C --> E[转换引擎<br/>Conversion Engine]
    C --> F[错误处理模块<br/>Error System]
    C --> G[类型系统<br/>Type Definitions]
    
    H[外部服务<br/>skills.sh API<br/>GitHub API] --> B

架构分层说明：

资料来源：src/index.ts:1-50

2. 入口层架构

2.1 主入口 (index.ts)

index.ts 是 MCP 服务器的主入口点，负责初始化和配置服务器。

核心职责：

• 创建 MCP 服务器实例
• 注册所有工具处理器
• 配置 stdio 传输协议
• 处理服务器生命周期

代码结构：

// 服务器初始化伪代码
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

2.2 CLI 入口 (cli.ts)

cli.ts 提供命令行接口，支持独立运行服务器。

功能特性：

• 支持配置文件加载
• 环境变量配置
• 独立的进程启动

资料来源：src/cli.ts:1-50

3. 类型系统

3.1 类型定义概述

types.ts 定义了项目中使用的所有核心数据类型，确保类型安全和一致性。

主要类型分类：

资料来源：src/core/types.ts

3.2 技能数据结构

SkillFrontmatter 定义技能的元数据：

interface SkillFrontmatter {
  name: string;           // 技能名称
  description?: string;   // 技能描述
  dependencies?: string[];// 依赖列表
  // ...其他元数据字段
}

SkillSection 定义技能内容的结构化分段：

interface SkillSection {
  level: number;    // 标题层级 (1-6)
  heading: string;  // 标题文本
  content: string; // 段落内容
}

资料来源：src/core/types.ts

3.3 验证结果类型

ValidationResult 定义安全验证的结果：

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

4. 安全验证模块

4.1 模块概述

security-validator.ts 是系统的安全防线，负责扫描和检测技能内容中的潜在安全风险。

graph LR
    A[技能内容] --> B[危险命令检测]
    A --> C[可疑模式检测]
    A --> D[来源验证]
    B --> E[评估结果]
    C --> E
    D --> E

安全检测范围：

资料来源：src/core/security-validator.ts:1-100

4.2 验证流程

严重级别判定逻辑：

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

5. 转换引擎模块

5.1 模块概述

conversion-engine.ts 是核心的业务逻辑模块，负责将 Claude Skills 转换为 Kiro 格式（Steering 文件或 Power）。

转换引擎能力：

资料来源：src/core/conversion-engine.ts:1-150

5.2 转换为 Steering 文件

转换流程：

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 文件结构示例：

概述

类型定义系统是 Skill Loader MCP Server 的核心基础设施之一，为整个项目提供强类型的接口定义、数据模型和错误处理机制。该系统基于 TypeScript 编写，确保在 MCP 工具调用、数据流转和错误处理过程中具备类型安全性和编译时检查能力。

类型定义系统的主要职责包括：

• 数据结构定义：为 skills.sh API 响应、技能元数据、导入结果等核心数据定义清晰的结构
• MCP 工具接口：为 8 个 MCP 工具提供输入输出参数的类型规范
• 错误类型体系：建立分层分类的错误类型系统，支持精确的错误定位和恢复建议
• 安全验证模型：定义安全检查项和验证结果的数据结构

资料来源：README.md:1-20

系统架构

模块组成

类型定义系统由以下几个核心模块组成：

架构层次图

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 目录中的基本单位，包含以下关键字段：

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

技能内容类型

技能内容用于存储解析后的完整技能信息：

interface SkillContent {
  frontmatter: {
    name: string;
    description?: string;
    dependencies?: string[];
    [key: string]: any;
  };
  body: string;           // 技能正文内容
  sections: SkillSection[];
}

资料来源：src/core/conversion-engine.ts:1-30

技能解析结果

技能解析函数返回的结果包含元数据和解析状态：

interface ParsedSkill {
  frontmatter: Record<string, any>;
  body: string;
  sections: Array<{
    heading: string;
    level: number;
    content: string;
  }>;
}

错误类型体系

基类设计

错误系统采用继承层级结构，基类 SkillLoaderError 提供通用功能：

export class SkillLoaderError extends Error {
  public readonly timestamp: Date;
  public readonly context: Record<string, any>;

  constructor(message: string, context: Record<string, any> = {}) {
    super(message);
    this.name = this.constructor.name;
    this.timestamp = new Date();
    this.context = context;
  }
}

资料来源：src/core/errors.ts:1-30

错误子类层级

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)

用于处理网络相关故障：

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<string, any>;
    } = {}
  );
}

资料来源：src/core/errors.ts:80-100

错误处理建议：

验证错误 (ValidationError)

用于处理格式、安全和模式验证失败：

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<string, any>;
    } = {}
  );
}

资料来源：src/core/errors.ts:180-200

文件系统错误 (FileSystemError)

用于处理文件系统操作错误：

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

常见系统错误代码：

MCP 工具类型定义

工具参数类型

系统为 8 个 MCP 工具定义了严格的输入参数类型：

资料来源：README.md:1-80

列表技能工具类型

interface ListSkillsParams {
  page?: number;       // 页码，默认1
  pageSize?: number;   // 每页数量，默认50，最大100
}

interface ListSkillsResult {
  skills: SkillShEntry[];
  total: number;
  page: number;
  pageSize: number;
}

搜索技能工具类型

interface SearchSkillsParams {
  query: string;       // 搜索关键词
  limit?: number;      // 最大返回数量，默认20
}

interface SearchSkillsResult {
  skills: SkillShEntry[];
  query: string;
  count: number;
}

获取排行榜工具类型

interface GetLeaderboardParams {
  timeframe?: 'all' | '24h';  // 时间范围，默认 'all'
  limit?: number;             // 最大结果数，默认20，最大50
}

interface GetLeaderboardResult {
  skills: Array<SkillShEntry & {
    rank: number;
    trending: boolean;
  }>;
  timeframe: string;
  count: number;
}

验证技能工具类型

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

安全验证类型

验证问题类型

安全验证模块定义了多种检查类型：

type ValidationIssueType = 
  | 'dangerous_command'    // 危险命令
  | 'suspicious_pattern'   // 可疑模式
  | 'untrusted_source';    // 不受信任的源

验证结果级别

type ValidationSeverity = 'safe' | 'warning' | 'unsafe';

安全级别判定逻辑：

资料来源：src/core/security-validator.ts:1-50

危险命令检测

系统检测以下危险命令模式：

• rm -rf 系列删除命令
• sudo 特权命令
• eval 和 exec 代码执行命令

可疑模式检测

检测以下可疑代码模式：

• 模板注入：${...} 或 $(...)
• 系统路径访问：/etc/、/usr/、/bin/
• 敏感配置文件访问

转换结果类型

转换为转向文件结果

interface ConvertToSteeringResult {
  content: string;           // 转换后的内容
  filename: string;          // 生成的文件名
  metadata: {
    originalSkill: string;
    sourceUrl?: string;
    importedAt: string;
  };
}

转换为 Power 结果

interface ConvertToPowerResult {
  files: Array<{
    path: string;
    content: string;
  }>;
  metadata: {
    skillName: string;
    sourceUrl?: string;
    filesGenerated: number;
  };
}

Power 格式可能生成的文件：

资料来源：src/core/conversion-engine.ts:50-100

API 响应类型

Skills.sh API v1 响应类型

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 类型守卫以提供精确的类型缩小：

function isNetworkError(error: unknown): error is NetworkError {
  return error instanceof NetworkError;
}

function isValidationError(error: unknown): error is ValidationError {
  return error instanceof ValidationError;
}

错误恢复流程

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 入口和配置管理提供了坚实的类型支撑。

核心职责

技能解析器的主要职责包括：

资料来源：README.md:1-50

解析流程

技能解析器遵循标准化的解析流程，确保从远程获取的技能内容能够被准确处理和转换。

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，提取以下元数据字段：

解析后的结构化数据包含 frontmatter 和 body 两个主要部分：

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

验证结果级别

资料来源：src/core/security-validator.ts:35-50

错误处理机制

技能解析器实现了完善的错误处理机制，针对不同类型的故障提供精确的错误分类：

错误类型分类

资料来源：src/core/errors.ts:1-80

HTTP 状态码处理

解析器针对常见的 HTTP 错误状态码提供了用户友好的错误消息和建议：

if (statusCode === 404) {
  // 验证技能名称是否正确
  // 检查仓库是否存在于 GitHub
  // 尝试使用 owner/repo 格式
} else if (statusCode === 403) {
  // 可能触发了 GitHub 频率限制
  // 等待几分钟后重试
} else if (statusCode >= 500) {
  // 服务器端问题
  // 稍后重试
}

资料来源：src/core/errors.ts:60-90

转换引擎协作

技能解析器与转换引擎协同工作，将解析后的技能内容转换为目标格式：

支持的目标格式

Power 格式生成规则

转换引擎根据技能内容特征决定生成哪些文件：

1. 基础文件: 始终生成 POWER.md
2. MCP 配置: 当技能包含依赖项或工具引用时生成 mcp.json
3. 转向目录: 当技能包含 3 个或以上复杂章节时生成 steering/ 目录

资料来源：src/core/conversion-engine.ts:80-120

转换测试验证

describe('toPower', () => {
  it('converts parsed skill to power format', () => {
    const content = `---
name: my-power
description: A powerful skill

核心定位

在 Skill Loader MCP Server 的整体架构中，技能获取器处于工作流的最上游位置。用户的完整导入流程为：获取技能 → 安全验证 → 格式转换 → 导入完成。技能获取器仅负责完成第一步，即从 GitHub 获取技能的原始 Markdown 内容。

技能获取器支持两种标识符格式：

资料来源：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

获取流程

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 上的原始技能内容。

参数定义：

请求示例：

{
  "tool": "fetch_skill",
  "arguments": {
    "identifier": "anthropics/pdf-extractor"
  }
}

资料来源：examples/usage-examples.md:53-67

响应结构：

资料来源：examples/usage-examples.md:68-79

响应示例

{
  "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 组件解析：

资料来源：src/core/conversion-engine.ts:75-89

错误处理

技能获取器定义了多种错误类型以应对不同的失败场景。

错误类型

资料来源：src/core/errors.ts

错误响应格式

所有工具错误返回统一格式：

{
  "error": "Error message describing what went wrong",
  "tool": "tool_name",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

资料来源：examples/usage-examples.md:189-195

常见错误场景

资料来源：README.md:77-85

重试机制

技能获取器内置重试逻辑以提高网络请求的可靠性。

重试策略：

指数退避公式：delay = min(initialDelay * 2^attempt, maxDelay)

资料来源：README.md:73

与其他模块的集成

在导入工作流中的角色

技能获取器是 import_skill 工具的底层依赖。import_skill 工具的执行流程如下：

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

使用限制

资料来源：README.md:74-76

总结

技能获取器作为 Skill Loader MCP Server 的数据入口，提供了一个简洁可靠的接口从 GitHub 仓库获取 Claude Skills 的原始内容。它支持灵活的标识符格式，内置完善的错误处理和重试机制，并为后续的安全验证和格式转换模块提供稳定的数据源。该模块的稳定性直接影响整个导入工作流的可靠性。

核心职责

转换引擎的主要职责包括：

1. 解析 Skill 内容 — 解析 YAML frontmatter 和 Markdown 正文，提取元数据、标题层级和正文内容
2. 格式转换 — 将解析后的技能数据转换为 steering 文件或 power 格式
3. 文件名生成 — 将技能名称转换为 kebab-case 格式作为输出文件名
4. 元数据注入 — 在转换后的文件中添加原始技能信息、来源 URL 和导入时间戳
5. 条件生成 — 根据技能内容特征判断是否需要生成额外的 mcp.json 或 steering/ 目录

资料来源：src/core/conversion-engine.ts:1-50

架构概览

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 是转换引擎的核心类，提供所有转换操作的入口方法。

资料来源：src/core/conversion-engine.ts:1-100

ParsedSkill 数据结构

解析后的技能数据结构包含以下字段：

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 内容解析为结构化数据：

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/ 目录下存储技能指南。

输出格式

概述

安全验证器（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

验证流程

安全验证器采用多阶段验证流程，对技能内容进行逐层安全检查：

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

验证规则

危险命令检测

安全验证器会扫描技能内容中的危险系统命令，这些命令可能对系统造成不可逆的损害。

// 危险命令检测逻辑示例
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

可疑文件路径检测

验证器会检查技能内容中是否包含对系统关键目录的访问企图。

这些路径的访问通常不是普通技能所需的，可能表明存在恶意意图。

资料来源：src/core/security-validator.ts:80-100

代码注入模式检测

安全验证器能够识别多种代码注入攻击模式。

// 代码注入检测
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

来源可信度验证

安全验证器会验证技能来源的可靠性。只有来自受信任来源的技能才会被标记为安全。

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 服务器提供的安全验证工具，用于验证技能内容的安全性。

参数定义：

返回值结构：

{
  "isValid": true,
  "issues": [
    {
      "type": "dangerous_command",
      "description": "危险递归删除命令 (rm -rf)",
      "location": "Line 7: rm -rf /"
    }
  ],
  "severity": "unsafe"
}

使用示例：

{
  "tool": "validate_skill",
  "arguments": {
    "content": "---\nname: Test\n---\n\n# Test",
    "url": "https://example.com/skill.md"
  }
}

资料来源：examples/usage-examples.md:1-30

验证结果对象

验证完成后，系统返回一个结构化的验证结果对象。

interface ValidationResult {
  isValid: boolean;           // 是否通过验证
  issues: ValidationIssue[];  // 发现的问题列表
  severity: 'safe' | 'warning' | 'unsafe';  // 整体严重级别
}

严重级别判定规则：

资料来源：src/core/security-validator.ts:200-220

错误处理

ValidationError 类

当验证过程发生错误时，系统会抛出 ValidationError 异常。

export class ValidationError extends SkillLoaderError {
  public readonly validationType: 'format' | 'security' | 'schema' | 'content';
  public readonly lineNumber?: number;
  public readonly details: string[];
}

错误类型：

资料来源：src/core/errors.ts:80-120

错误消息格式

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

测试覆盖

安全验证器拥有完整的单元测试覆盖，确保各项安全检测功能的准确性。

测试用例列表

资料来源：src/core/security-validator.test.ts:1-50

测试实现示例

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 格式之前，系统会自动进行安全验证。

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

import_skill 工具

import_skill 工具提供了完整的导入工作流程，包含自动安全验证：

{
  "tool": "import_skill",
  "arguments": {
    "identifier": "anthropics/pdf-extractor",
    "outputFormat": "power",
    "skipValidation": false
  }
}

参数说明：

响应示例：

{
  "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

安全特性总结

安全验证器提供了多层次的安全保护机制：

资料来源：src/core/security-validator.ts

概述

Skill Loader MCP Server 实现了一套内存缓存系统，用于提升 API 调用效率并减少网络请求次数。缓存机制的核心设计目标是：

• 减少对 skills.sh 目录 API 的重复调用
• 提升搜索和列表查询的响应速度
• 通过 TTL（Time-To-Live）机制确保数据的时效性

缓存系统在项目架构中属于基础工具层，被核心业务模块调用。资料来源：src/utils/cache.ts:1-20

核心组件

CacheEntry 接口

泛型缓存条目接口，存储数据及其时间戳：

资料来源：src/utils/cache.ts:6-10

Cache 类

通用内存缓存类，支持 TTL 过期机制：

export class Cache<T> {
  private cache: Map<string, CacheEntry<T>> = new Map();
  private ttl: number;
}

资料来源：src/utils/cache.ts:14-17

API 参考

构造函数

constructor(ttl: number)

资料来源：src/utils/cache.ts:19-24

get 方法

从缓存中获取值，若不存在或已过期则返回 undefined：

get(key: string): T | undefined

执行流程：

graph TD
    A[调用 get 方法] --> B{查找 key 是否存在}
    B -->|不存在| C[返回 undefined]
    B -->|存在| D{检查是否过期}
    D -->|已过期| E[删除 key 并返回 undefined]
    D -->|未过期| F[返回缓存数据]

资料来源：src/utils/cache.ts:31-50

set 方法

将数据存入缓存，自动记录当前时间戳：

set(key: string, data: T): void

资料来源：src/utils/cache.ts:57-66

has 方法

检查指定键是否存在且未过期：

has(key: string): boolean

返回值说明：

资料来源：src/utils/cache.ts:73-86

过期检测机制

缓存条目通过时间戳与当前时间的差值判断是否过期：

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

缓存优势

资料来源：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. 缓存统计：添加命中率和性能指标监控

概述

Skill Loader MCP Server 的命令行工具是连接 Claude Desktop 与技能仓库的桥梁。通过 MCP（Model Context Protocol）协议，服务器提供了 9 个核心工具函数，涵盖技能发现、获取、验证、格式转换和导入等完整工作流程。资料来源：README.md:1-50

支持的运行环境

快速开始

通过 npx 运行

使用 npx 可以直接运行最新版本的服务器，无需本地安装：

npx -y @goldzulu/skill-loader-mcp-server

资料来源：README.md:60-65

独立安装运行

# 全局安装
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 配置文件中添加以下内容：

{
  "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

使用可执行文件路径

如果已全局安装，也可以直接指定可执行文件路径：

{
  "mcpServers": {
    "skill-loader": {
      "command": "skill-loader-mcp-server",
      "env": {
        "SKILLS_SH_API_KEY": "your-api-key-here"
      }
    }
  }
}

环境变量配置

SKILLS_SH_API_KEY

此环境变量用于访问 skills.sh 的高级 API 功能，包括分页列出所有技能和获取排行榜数据。

资料来源：README.md:90-95

配置方式

环境变量可以通过配置文件中的 env 块设置，也可以在 shell 中预先导出：

export SKILLS_SH_API_KEY="your-api-key-here"

MCP 工具列表

服务器提供了 9 个 MCP 工具，按功能可分为以下几类：

技能发现类

资料来源：README.md:85-120

技能获取类

技能验证类

格式转换类

导入操作类

安全验证机制

命令行工具内置了安全验证功能，会在导入前自动扫描技能内容：

检测的威胁类型

资料来源：README.md:175-185

验证响应示例

{
  "isValid": false,
  "issues": [
    {
      "type": "dangerous_command",
      "description": "Dangerous recursive delete command (rm -rf)",
      "location": "Line 7: rm -rf /"
    }
  ],
  "severity": "unsafe"
}

典型工作流程

流程一：搜索并导入技能

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）

graph TD
    A[list_skills 分页获取] --> B{还有更多页面?}
    B -->|是| C[请求下一页]
    C --> A
    B -->|否| D[get_leaderboard 获取趋势]
    D --> E[fetch_skill 获取技能]
    E --> F[import_skill 完整导入]

完整导入示例

导入为 Steering 文件

{
  "tool": "import_skill",
  "arguments": {
    "identifier": "anthropics/pdf-extractor",
    "outputFormat": "steering",
    "skipValidation": false
  }
}

响应示例：

{
  "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

{
  "tool": "import_skill",
  "arguments": {
    "identifier": "anthropics/pdf-extractor",
    "outputFormat": "power",
    "skipValidation": false
  }
}

缓存机制

服务器内置了智能缓存功能：

资料来源：README.md:195-200

错误处理

所有工具返回的错误遵循统一格式：

{
  "error": "Error message describing what went wrong",
  "tool": "tool_name",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

常见错误场景

传输协议

服务器支持 stdio 传输协议，这是 Claude Desktop 和 Kiro 集成的标准方式。stdio 传输通过标准输入输出流进行进程间通信，确保了与 Claude Desktop 的无缝集成。

资料来源：CONTRIBUTING.md:25-30

开发调试

本地运行测试服务器

项目中提供了 test-server.js 用于本地调试和测试。开发者可以使用该脚本启动一个本地测试环境，验证工具行为是否符合预期。

本地开发模式

# 安装依赖
npm install

# 构建项目
npm run build

# 运行测试
npm test

# 启动服务器
npm start

资料来源：CONTRIBUTING.md:10-15

输出格式

Steering 格式输出

当 outputFormat 为 steering 时，输出包含以下字段：

Power 格式输出

当 outputFormat 为 power 时，输出包含多个文件：

相关文档

• 使用示例 - 各工具的详细使用案例
• 安全验证 - 安全机制实现细节
• 错误处理 - 错误类定义和使用

Pitfall Log / 踩坑日志

项目：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