{
"canonical_name": "goldzulu/skill-loader-mcp-server",
"compilation_id": "pack_162c83ab3a8c4c8186f922a00eafc82c",
"created_at": "2026-05-13T19:05:14.434375+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `npm install -g @goldzulu/skill-loader-mcp-server` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "npm install -g @goldzulu/skill-loader-mcp-server",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_4ca87e0f553b4fee92c7cc7a1d5d567d"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_a0734382f8b24dbab92c1106fb762b5a",
"canonical_name": "goldzulu/skill-loader-mcp-server",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/goldzulu/skill-loader-mcp-server",
"slug": "skill-loader-mcp-server",
"source_packet_id": "phit_786cbafb85b14e6f8245190b26b7b3a7",
"source_validation_id": "dval_8ce4d558491d446bb0dcf2ba3b02b025"
},
"merchandising": {
"best_for": "需要工具连接与集成能力，并使用 mcp_host的用户",
"github_forks": 0,
"github_stars": 0,
"one_liner_en": "MCP server for discovering, fetching, validating, and converting Claude skills from skills.sh and GitHub repositories",
"one_liner_zh": "MCP server for discovering, fetching, validating, and converting Claude skills from skills.sh and GitHub repositories",
"primary_category": {
"category_id": "tool-integrations",
"confidence": "high",
"name_en": "Tool Integrations",
"name_zh": "工具连接与集成",
"reason": "matched_keywords:mcp, server, github"
},
"target_user": "使用 mcp_host, claude 等宿主 AI 的用户",
"title_en": "skill-loader-mcp-server",
"title_zh": "skill-loader-mcp-server 能力包",
"visible_tags": [
{
"label_en": "MCP Tools",
"label_zh": "MCP 工具",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-mcp-tools",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Structured Extraction",
"label_zh": "结构化提取",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-structured-extraction",
"type": "core_capability"
},
{
"label_en": "Node-based Workflow",
"label_zh": "节点式流程编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-node-based-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_786cbafb85b14e6f8245190b26b7b3a7",
"page_model": {
"artifacts": {
"artifact_slug": "skill-loader-mcp-server",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "npm install -g @goldzulu/skill-loader-mcp-server",
"label": "Node.js / npm · 官方安装入口",
"source": "https://github.com/goldzulu/skill-loader-mcp-server#readme",
"verified": true
}
],
"display_tags": [
"MCP 工具",
"知识库问答",
"结构化提取",
"节点式流程编排",
"评测体系"
],
"eyebrow": "工具连接与集成",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要工具连接与集成能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "MCP server for discovering, fetching, validating, and converting Claude skills from skills.sh and GitHub repositories"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host, claude",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。",
"category": "配置坑",
"evidence": [
"capability.host_targets | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | host_targets=mcp_host, claude"
],
"severity": "medium",
"suggested_check": "列出会写入的配置文件、目录和卸载/回滚步骤。",
"title": "可能修改宿主 AI 配置",
"user_impact": "安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.0.0 - Initial Release",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_fb2ea148b03e4fb5993d3b2db08b43f6 | https://github.com/goldzulu/skill-loader-mcp-server/releases/tag/v1.0.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.0.0 - Initial Release",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.1.0 — skills.sh API migration & Power format update",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_78c48e3f6caa41a9bf94d3dba01baf0c | https://github.com/goldzulu/skill-loader-mcp-server/releases/tag/v1.1.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.1.0 — skills.sh API migration & Power format update",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 1,
"forks": 0,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 0
},
"source_url": "https://github.com/goldzulu/skill-loader-mcp-server",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "MCP server for discovering, fetching, validating, and converting Claude skills from skills.sh and GitHub repositories",
"title": "skill-loader-mcp-server 能力包",
"trial_prompt": "# skill-loader-mcp-server - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 skill-loader-mcp-server 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client / claude\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: MCP server for discovering, fetching, validating, and converting Claude skills from skills.sh and GitHub repositories 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-project-intro：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-mcp-tools：MCP工具详解。围绕“MCP工具详解”模拟一次用户任务，不展示安装或运行结果。\n3. page-core-modules：核心模块架构。围绕“核心模块架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-skill-resolver：技能解析器。围绕“技能解析器”模拟一次用户任务，不展示安装或运行结果。\n5. page-skill-fetcher：技能获取器。围绕“技能获取器”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-project-intro\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-mcp-tools\n输入：用户提供的“MCP工具详解”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-core-modules\n输入：用户提供的“核心模块架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-skill-resolver\n输入：用户提供的“技能解析器”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-skill-fetcher\n输入：用户提供的“技能获取器”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-project-intro：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-mcp-tools：Step 2 必须围绕“MCP工具详解”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-core-modules：Step 3 必须围绕“核心模块架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-skill-resolver：Step 4 必须围绕“技能解析器”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-skill-fetcher：Step 5 必须围绕“技能获取器”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/goldzulu/skill-loader-mcp-server\n- https://github.com/goldzulu/skill-loader-mcp-server#readme\n- README.md\n- package.json\n- src/index.ts\n- src/tools/list-skills.ts\n- src/tools/search-skills.ts\n- src/tools/get-leaderboard.ts\n- src/tools/fetch-skill.ts\n- src/tools/validate-skill.ts\n- src/tools/convert-to-steering.ts\n- src/tools/convert-to-power.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 skill-loader-mcp-server 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_release: v1.1.0 — skills.sh API migration & Power format update（https://github.com/goldzulu/skill-loader-mcp-server/releases/tag/v1.1.0）；github/github_release: v1.0.0 - Initial Release（https://github.com/goldzulu/skill-loader-mcp-server/releases/tag/v1.0.0）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_release",
"source": "github",
"title": "v1.1.0 — skills.sh API migration & Power format update",
"url": "https://github.com/goldzulu/skill-loader-mcp-server/releases/tag/v1.1.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.0.0 - Initial Release",
"url": "https://github.com/goldzulu/skill-loader-mcp-server/releases/tag/v1.0.0"
}
],
"status": "已收录 2 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "工具连接与集成",
"desc": "MCP server for discovering, fetching, validating, and converting Claude skills from skills.sh and GitHub repositories",
"effort": "安装已验证",
"forks": 0,
"icon": "link",
"name": "skill-loader-mcp-server 能力包",
"risk": "需复核",
"slug": "skill-loader-mcp-server",
"stars": 0,
"tags": [
"MCP 工具",
"知识库问答",
"结构化提取",
"节点式流程编排",
"评测体系"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/goldzulu/skill-loader-mcp-server 项目说明书\n\n生成时间：2026-05-13 18:01:33 UTC\n\n## 目录\n\n- [项目介绍](#page-project-intro)\n- [MCP工具详解](#page-mcp-tools)\n- [核心模块架构](#page-core-modules)\n- [类型定义系统](#page-type-system)\n- [技能解析器](#page-skill-resolver)\n- [技能获取器](#page-skill-fetcher)\n- [转换引擎](#page-conversion-engine)\n- [安全验证器](#page-security-validator)\n- [缓存机制](#page-caching)\n- [命令行工具](#page-cli-usage)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[MCP工具详解](#page-mcp-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n- [examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n- [src/core/conversion-engine.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)\n- [src/core/security-validator.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)\n- [src/core/errors.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts)\n- [CHANGELOG.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CHANGELOG.md)\n- [CONTRIBUTING.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CONTRIBUTING.md)\n \n\n# 项目介绍\n\n## 概述\n\nSkill Loader MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器项目，用于管理 Claude Skills 的导入、转换和验证工作流。该项目由 GoldZulu 开发维护，提供了与 skills.sh 市场平台集成的完整工具链，使用户能够安全地发现、获取和导入 Claude 技能。资料来源：[README.md:1]()\n\n## 核心功能\n\n### 技能发现与管理\n\n该项目支持从 skills.sh 平台发现和管理 Claude Skills，提供以下核心能力：\n\n- **技能搜索**：通过关键词搜索 skills.sh 目录，无需 API 密钥即可使用\n- **技能列表**：分页浏览所有可用技能，需要 API 密钥\n- **排行榜**：获取热门或安装量最高的技能，支持 24 小时和全部时间维度\n\n资料来源：[README.md:35-50]()\n\n### 安全验证\n\n内置多层安全验证机制，确保导入的技能不会危害系统安全：\n\n- **危险命令检测**：识别 `rm -rf`、`sudo`、`eval`、`exec` 等高风险命令\n- **可疑文件操作检测**：检测访问 `/etc/`、`/usr/`、`/bin/` 等系统目录的操作\n- **代码注入防护**：识别 `${...}` 和 `$(...)` 等代码注入模式\n- **来源验证**：仅允许来自 GitHub 的可信来源\n\n资料来源：[src/core/security-validator.ts:1-50]()\n\n### 格式转换\n\n支持将 Claude Skills 转换为 Kiro 平台支持的两种格式：\n\n| 格式类型 | 描述 | 输出文件 |\n|---------|------|---------|\n| Steering | Kiro 转向文件格式 | `.kiro/steering/{skill-name}.md` |\n| Power | Kiro Power 格式 | `POWER.md` + 可选的 `mcp.json` 和 `steering/` 目录 |\n\n当技能包含依赖或工具引用时，转换引擎会自动生成 `mcp.json` 配置文件。当技能包含 3 个以上复杂章节时，会生成 `steering/` 目录结构。资料来源：[README.md:60-75]()\n\n## 架构设计\n\n### 模块结构\n\n```\nskill-loader-mcp-server/\n├── src/\n│ ├── core/ # 核心功能模块\n│ │ ├── conversion-engine.ts # 技能格式转换引擎\n│ │ ├── security-validator.ts # 安全验证器\n│ │ └── errors.ts # 错误处理\n│ ├── tools/ # MCP 工具实现\n│ ├── utils/ # 工具函数\n│ ├── index.ts # 主入口点\n│ └── cli.ts # CLI 入口点\n├── examples/ # 使用示例\n├── dist/ # 编译输出\n└── tests/ # 测试文件\n```\n\n资料来源：[CONTRIBUTING.md:10-25]()\n\n### 核心组件\n\n#### 转换引擎 (Conversion Engine)\n\n转换引擎负责将 Claude Skills 解析并转换为目标格式，主要功能包括：\n\n- **解析技能**：提取 YAML frontmatter 和 Markdown 正文内容\n- **生成 Steering 文件**：转换为 Kiro 转向文件格式\n- **生成 Power 文件**：转换为 Kiro Power 格式，包含元数据和导入信息\n- **kebab-case 命名**：自动将技能名称转换为标准的 kebab-case 格式\n\n资料来源：[src/core/conversion-engine.ts:1-100]()\n\n#### 安全验证器 (Security Validator)\n\n安全验证器扫描技能内容中的潜在安全风险：\n\n- **问题类型分类**：区分 `dangerous_command`、`suspicious_pattern`、`untrusted_source`、`code_injection` 四类问题\n- **严重级别判定**：根据问题类型返回 `safe`、`warning`、`unsafe` 三级判定\n- **行号定位**：精确定位问题所在的代码行\n\n资料来源：[src/core/security-validator.ts:100-150]()\n\n#### 错误处理系统\n\n统一的错误处理系统包含多种专用错误类型：\n\n| 错误类型 | 用途 | Requirement ID |\n|---------|------|----------------|\n| `SkillLoaderError` | 基类错误 | 8.1 |\n| `NetworkError` | 网络请求失败 | 8.2 |\n| `ValidationError` | 技能验证失败 | 8.3 |\n| `FileSystemError` | 文件系统操作失败 | 8.4 |\n\n资料来源：[src/core/errors.ts:1-80]()\n\n## MCP 工具接口\n\n### 可用工具列表\n\n| 工具名称 | 功能描述 | 认证要求 |\n|---------|---------|---------|\n| `search_skills` | 按关键词搜索技能 | 无需认证 |\n| `list_skills` | 分页列出所有技能 | 需要 API Key |\n| `get_leaderboard` | 获取热门技能排行 | 需要 API Key |\n| `fetch_skill` | 从 GitHub 获取技能内容 | 无需认证 |\n| `validate_skill` | 验证技能安全性 | 无需认证 |\n| `convert_to_steering` | 转换为 Steering 格式 | 无需认证 |\n| `convert_to_power` | 转换为 Power 格式 | 无需认证 |\n| `import_skill` | 完整导入工作流 | 无需认证 |\n\n资料来源：[README.md:50-85]()\n\n### 完整导入工作流\n\n```mermaid\ngraph TD\n A[import_skill 调用] --> B[fetch_skill 获取技能]\n B --> C{跳过验证?}\n C -->|否| D[validate_skill 安全验证]\n C -->|是| E[convert_to_steering/power 格式转换]\n D --> F{验证通过?}\n F -->|否| G[返回错误,阻止导入]\n F -->|是| E\n E --> H[返回转换结果]\n```\n\n资料来源：[examples/usage-examples.md:1-50]()\n\n## 配置与部署\n\n### 环境变量\n\n| 变量名 | 必填 | 描述 |\n|-------|------|------|\n| `SKILLS_SH_API_KEY` | 仅 list_skills 和 get_leaderboard | skills.sh API 密钥 |\n\n资料来源：[README.md:25-30]()\n\n### 部署方式\n\n#### Kiro 平台\n\n```json\n{\n \"mcpServers\": {\n \"skill-loader\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@goldzulu/skill-loader-mcp-server\"],\n \"env\": {\n \"SKILLS_SH_API_KEY\": \"your-api-key-here\"\n }\n }\n }\n}\n```\n\n#### Claude Desktop\n\n```json\n{\n \"mcpServers\": {\n \"skill-loader\": {\n \"command\": \"skill-loader-mcp-server\",\n \"env\": {\n \"SKILLS_SH_API_KEY\": \"your-api-key-here\"\n }\n }\n }\n}\n```\n\n#### 独立运行\n\n```bash\nskill-loader-mcp-server\n```\n\n资料来源：[README.md:100-125]()\n\n## 技术特性\n\n### 缓存机制\n\n服务器内置内存缓存，用于存储 skills.sh 搜索结果：\n\n- **缓存时长**：1 小时 TTL\n- **自动刷新**：过期后自动重新获取\n- **适用场景**：仅 `list_skills` 和 `get_leaderboard` 调用\n\n资料来源：[README.md:130-135]()\n\n### 重试机制\n\n网络请求采用指数退避策略进行重试，提高系统可靠性：\n\n- **适用场景**：所有外部 API 调用\n- **策略**：指数增长的重试间隔\n\n资料来源：[CHANGELOG.md:20-25]()\n\n### 依赖更新\n\n项目已更新至 `@modelcontextprotocol/sdk` v1.29，确保与最新 MCP 协议兼容。资料来源：[README.md:1-5]()\n\n## 错误处理\n\n所有工具返回统一格式的错误信息：\n\n```json\n{\n \"error\": \"错误描述\",\n \"tool\": \"工具名称\",\n \"timestamp\": \"ISO 时间戳\"\n}\n```\n\n常见错误场景：\n\n| 错误类型 | 可能原因 | 解决方案 |\n|---------|---------|---------|\n| 网络错误 | 网络连接问题 | 检查互联网连接和 GitHub 可用性 |\n| 资源未找到 | 技能名称错误 | 验证技能名称和仓库地址 |\n| 验证错误 | 安全问题 | 导入前审查安全问题 |\n| 解析错误 | 格式问题 | 检查技能格式和 YAML 语法 |\n\n资料来源：[examples/usage-examples.md:100-120]()\n\n## 贡献指南\n\n项目欢迎各类贡献：\n\n- **Bug 修复**：修复现有代码问题\n- **新功能**：添加新的 MCP 工具\n- **文档**：改进 README 或代码注释\n- **测试**：提高测试覆盖率\n- **性能优化**：优化现有代码\n- **重构**：提升代码质量\n\n代码规范要求使用 TypeScript，遵循现有代码风格，避免使用 `any` 类型。资料来源：[CONTRIBUTING.md:30-55]()\n\n## 版本历史\n\n### v1.1.0 (当前版本)\n\n- Skills.sh 集成不再依赖脆弱的 HTML 解析\n- 新增 `SkillsShV1Response` 和 `SkillsShV1Entry` 类型\n- 支持 `id`、`skillId`、`source` 字段\n- 新增 `listSkills()` 方法支持认证分页列表\n- Power 转换支持 `mcp.json` 和 `steering/` 目录生成\n\n### v1.0.0 (初始版本)\n\n- 发布 9 个 MCP 工具\n- 实现安全验证功能\n- 内置内存缓存和重试逻辑\n- 支持 stdio 传输\n- 兼容 Kiro 和 Claude Desktop\n\n资料来源：[CHANGELOG.md:1-35]()\n\n---\n\n\n\n## MCP工具详解\n\n### 相关页面\n\n相关主题：[项目介绍](#page-project-intro), [技能获取器](#page-skill-fetcher), [转换引擎](#page-conversion-engine)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/list-skills.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/list-skills.ts)\n- [src/tools/search-skills.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/search-skills.ts)\n- [src/tools/get-leaderboard.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/get-leaderboard.ts)\n- [src/tools/fetch-skill.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/fetch-skill.ts)\n- [src/tools/validate-skill.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/validate-skill.ts)\n- [src/tools/convert-to-steering.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/convert-to-steering.ts)\n- [src/tools/convert-to-power.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/convert-to-power.ts)\n- [src/tools/import-skill.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/import-skill.ts)\n \n\n# MCP工具详解\n\n## 概述\n\nSkill Loader MCP Server 提供了一套完整的MCP（Model Context Protocol）工具集，用于管理Claude Skills的生命周期。该工具集涵盖从技能发现、获取、验证、格式转换到完整导入的完整工作流程。资料来源：[README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n\n系统共包含8个MCP工具，按功能可分为三大类别：\n\n| 类别 | 工具 | 核心功能 |\n|------|------|----------|\n| **发现工具** | `list_skills` | 分页列出技能市场所有技能 |\n| | `search_skills` | 关键词搜索技能 |\n| | `get_leaderboard` | 获取热门/趋势技能榜单 |\n| **获取与验证工具** | `fetch_skill` | 从GitHub获取原始技能内容 |\n| | `validate_skill` | 安全扫描与格式验证 |\n| **转换与导入工具** | `convert_to_steering` | 转换为Kiro Steering格式 |\n| | `convert_to_power` | 转换为Kiro Power格式 |\n| | `import_skill` | 端到端导入工作流 |\n\n资料来源：[README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n\n---\n\n## 架构概览\n\n### 工具调用流程\n\n```mermaid\ngraph TD\n A[用户请求] --> B{选择工具类型}\n \n B -->|发现类| C[list_skills
search_skills
get_leaderboard]\n B -->|获取类| D[fetch_skill]\n B -->|验证类| E[validate_skill]\n B -->|转换类| F[convert_to_steering
convert_to_power]\n B -->|导入类| G[import_skill]\n \n C --> H[skills.sh API]\n D --> I[GitHub Raw]\n E --> J[安全验证器]\n F --> K[转换引擎]\n G --> L[完整工作流]\n \n L --> D\n L --> E\n L --> F\n \n H --> M[返回结果]\n I --> M\n J --> M\n K --> M\n```\n\n### 核心模块依赖关系\n\n```mermaid\ngraph LR\n A[tools/*.ts] --> B[core/skill-resolver.ts]\n A --> C[core/conversion-engine.ts]\n A --> D[core/security-validator.ts]\n A --> E[core/errors.ts]\n \n B --> F[skills.sh API]\n C --> E\n D --> E\n```\n\n---\n\n## 发现类工具\n\n### 1. list_skills\n\n分页列出skills.sh技能市场中的所有可用技能。资料来源：[examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n\n**参数说明：**\n\n| 参数 | 类型 | 必需 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `page` | number | 否 | 1 | 页码，从1开始 |\n| `pageSize` | number | 否 | 50 | 每页数量，最大100 |\n\n**返回值结构：**\n\n```json\n{\n \"skills\": [\n {\n \"name\": \"pdf-extractor\",\n \"description\": \"Extract text from PDF files\",\n \"owner\": \"anthropics\",\n \"repo\": \"skills\",\n \"installs\": 30400\n }\n ],\n \"total\": 150,\n \"page\": 1,\n \"pageSize\": 10\n}\n```\n\n**环境要求：** 需要 `SKILLS_SH_API_KEY` 环境变量进行身份验证。资料来源：[README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n\n---\n\n### 2. search_skills\n\n通过关键词搜索skills.sh技能市场。该工具使用公开搜索API，无需API密钥。资料来源：[examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n\n**参数说明：**\n\n| 参数 | 类型 | 必需 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `query` | string | 是 | - | 搜索关键词 |\n| `limit` | number | 否 | 5 | 返回结果数量限制 |\n\n**返回值结构：**\n\n```json\n{\n \"skills\": [\n {\n \"name\": \"pdf-extractor\",\n \"description\": \"Extract text from PDF files\",\n \"owner\": \"anthropics\",\n \"repo\": \"skills\",\n \"installs\": 30400,\n \"relevance\": 5\n }\n ],\n \"query\": \"pdf\",\n \"count\": 5\n}\n```\n\n---\n\n### 3. get_leaderboard\n\n获取热门或趋势技能榜单，支持按时间范围筛选。资料来源：[examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n\n**参数说明：**\n\n| 参数 | 类型 | 必需 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `timeframe` | string | 否 | \"all\" | 时间范围：`\"all\"`或`\"24h\"` |\n| `limit` | number | 否 | 20 | 返回结果数量，最大50 |\n\n**返回值结构：**\n\n```json\n{\n \"skills\": [\n {\n \"name\": \"pdf-extractor\",\n \"description\": \"Extract text from PDF files\",\n \"owner\": \"anthropics\",\n \"repo\": \"skills\",\n \"installs\": 30400,\n \"rank\": 1,\n \"trending\": true\n }\n ],\n \"timeframe\": \"24h\",\n \"count\": 10\n}\n```\n\n**环境要求：** 需要 `SKILLS_SH_API_KEY` 环境变量。资料来源：[README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n\n---\n\n## 获取与验证工具\n\n### 4. fetch_skill\n\n从GitHub获取原始技能内容。支持多种标识符格式。资料来源：[examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n\n**参数说明：**\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `identifier` | string | 是 | 技能名称或`owner/repo`格式 |\n\n**支持的标识符格式：**\n\n| 格式 | 示例 | 说明 |\n|------|------|------|\n| 纯名称 | `pdf-extractor` | 从skills.sh目录解析 |\n| owner/repo | `anthropics/pdf-extractor` | 直接指定GitHub位置 |\n| 完整路径 | `owner/repo/skill-path` | 指定具体路径 |\n\n**返回值结构：**\n\n```json\n{\n \"content\": \"---\\nname: PDF Extractor\\ndescription: Extract text from PDF files\\n---\\n\\n# PDF Extractor\\n\\n...\",\n \"url\": \"https://raw.githubusercontent.com/anthropics/skills/main/skills/pdf-extractor/SKILL.md\",\n \"metadata\": {\n \"name\": \"pdf-extractor\",\n \"owner\": \"anthropics\",\n \"repo\": \"skills\",\n \"skillPath\": \"skills/pdf-extractor\",\n \"fetchedAt\": \"2024-01-15T10:30:00.000Z\"\n }\n}\n```\n\n---\n\n### 5. validate_skill\n\n对技能内容进行安全扫描和格式验证，检测潜在的安全风险。资料来源：[src/core/security-validator.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)\n\n**参数说明：**\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `content` | string | 是 | 待验证的技能内容 |\n| `url` | string | 否 | 来源URL用于额外验证 |\n\n**安全检测类型：**\n\n| 类型 | 标识符 | 严重程度 | 说明 |\n|------|--------|----------|------|\n| 危险命令 | `dangerous_command` | unsafe | `rm -rf`、`sudo`、`eval`、`exec`等 |\n| 可疑文件操作 | `suspicious_file_operation` | unsafe | 访问`/etc/`、`/usr/`、`/bin/`等系统目录 |\n| 代码注入 | `code_injection` | unsafe | `${...}`、`$(...)`等注入模式 |\n| 不信任源 | `untrusted_source` | unsafe | 非GitHub来源的URL |\n\n**返回值结构：**\n\n```json\n{\n \"isValid\": false,\n \"issues\": [\n {\n \"type\": \"dangerous_command\",\n \"description\": \"Dangerous recursive delete command (rm -rf)\",\n \"location\": \"Line 7: rm -rf /\"\n }\n ],\n \"severity\": \"unsafe\"\n}\n```\n\n**安全等级判定逻辑：**\n\n```mermaid\ngraph TD\n A[检测到问题?] --> B{问题类型}\n B -->|untrusted_source| C[unsafe]\n B -->|dangerous_command| C\n B -->|其他| D[warning]\n A -->|无问题| E[safe]\n```\n\n资料来源：[src/core/security-validator.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)\n\n---\n\n## 转换与导入工具\n\n### 6. convert_to_steering\n\n将Claude Skill转换为Kiro Steering文件格式。资料来源：[examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n\n**参数说明：**\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `content` | string | 是 | 技能原始内容 |\n| `sourceUrl` | string | 否 | 原始来源URL |\n\n**转换特性：**\n\n- 提取技能名称并转换为kebab-case格式作为文件名\n- 保留技能描述和正文内容\n- 添加依赖列表（如有）\n- 在文件末尾附加导入元数据\n- 包含原始技能名称和来源信息\n\n**输出格式：**\n\n```yaml\n---\noriginal_skill: PDF Extractor\nsource_url: https://raw.githubusercontent.com/...\nimported_at: '2024-01-15T10:30:00.000Z'\n---\n\n# PDF Extractor\n\nExtract text from PDF files\n\n# PDF Extractor\n\nExtract text content from PDF documents...\n\n---\n*Imported from Claude Skills via Skill Loader Power*\n```\n\n**返回值结构：**\n\n```json\n{\n \"steeringContent\": \"...\",\n \"filename\": \"pdf-extractor.md\",\n \"metadata\": {\n \"originalSkill\": \"PDF Extractor\",\n \"sourceUrl\": \"https://...\",\n \"importedAt\": \"2024-01-15T10:30:00.000Z\"\n }\n}\n```\n\n---\n\n### 7. convert_to_power\n\n将Claude Skill转换为Kiro Power格式。这是更高级的转换选项，会生成额外的配置文件。资料来源：[examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n\n**参数说明：**\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `content` | string | 是 | 技能原始内容 |\n| `sourceUrl` | string | 否 | 原始来源URL |\n\n**生成的文件：**\n\n| 条件 | 生成文件 | 说明 |\n|------|----------|------|\n| 始终 | `POWER.md` | 主技能内容文件 |\n| 有依赖或工具引用 | `mcp.json` | MCP服务器配置 |\n| 3+复杂章节 | `steering/`目录 | 多章节内容目录 |\n\n**mcp.json生成逻辑：**\n\n当技能包含依赖或MCP工具引用时，系统自动生成`mcp.json`配置文件，用于定义MCP服务器连接。资料来源：[CHANGELOG.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CHANGELOG.md)\n\n**steering目录生成逻辑：**\n\n当技能包含3个或以上复杂章节（级别≥2，内容>200字符）时，系统会将这些章节提取到独立的`steering/`目录中。资料来源：[CHANGELOG.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CHANGELOG.md)\n\n---\n\n### 8. import_skill\n\n完整的端到端导入工作流，集成了获取、验证和转换三个步骤。资料来源：[examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n\n**参数说明：**\n\n| 参数 | 类型 | 必需 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `identifier` | string | 是 | - | 技能标识符 |\n| `outputFormat` | string | 是 | - | 输出格式：`\"steering\"`或`\"power\"` |\n| `skipValidation` | boolean | 否 | false | 是否跳过安全验证 |\n\n**工作流程：**\n\n```mermaid\ngraph TD\n A[import_skill调用] --> B[fetch_skill获取内容]\n B --> C{skipValidation?}\n C -->|否| D[validate_skill安全验证]\n C -->|是| E[跳过验证]\n D --> F{验证通过?}\n F -->|是| G[转换格式]\n F -->|否| H[返回错误]\n E --> G\n G --> I{outputFormat?}\n I -->|steering| J[convert_to_steering]\n I -->|power| K[convert_to_power]\n J --> L[返回结果]\n K --> L\n```\n\n**返回值结构：**\n\n```json\n{\n \"success\": true,\n \"content\": \"...\",\n \"filename\": \"pdf-extractor.md\",\n \"targetPath\": \".kiro/steering/pdf-extractor.md\",\n \"metadata\": {\n \"skillName\": \"PDF Extractor\",\n \"sourceUrl\": \"https://...\",\n \"outputFormat\": \"steering\",\n \"validationResult\": {\n \"isValid\": true,\n \"issues\": [],\n \"severity\": \"safe\"\n }\n }\n}\n```\n\n**错误处理：**\n\n当安全验证失败时，返回详细的错误信息：\n\n```json\n{\n \"success\": false,\n \"content\": \"...\",\n \"metadata\": {\n \"validationResult\": {\n \"isValid\": false,\n \"issues\": [\n {\n \"type\": \"dangerous_command\",\n \"description\": \"Dangerous recursive delete command (rm -rf)\",\n \"location\": \"Line 10: rm -rf /\"\n }\n ],\n \"severity\": \"unsafe\"\n }\n },\n \"error\": \"Security validation failed: Dangerous recursive delete command (rm -rf)\"\n}\n```\n\n---\n\n## 常用工作流\n\n### 发现并导入技能\n\n```mermaid\ngraph LR\n A[search_skills] --> B[fetch_skill]\n B --> C[validate_skill]\n C --> D{安全?}\n D -->|是| E[import_skill]\n D -->|否| F[放弃]\n```\n\n**具体步骤：**\n\n1. **搜索技能**\n ```json\n { \"tool\": \"search_skills\", \"arguments\": { \"query\": \"pdf\", \"limit\": 5 } }\n ```\n\n2. **获取技能详情**\n ```json\n { \"tool\": \"fetch_skill\", \"arguments\": { \"identifier\": \"anthropics/pdf-extractor\" } }\n ```\n\n3. **导入技能**\n ```json\n { \"tool\": \"import_skill\", \"arguments\": { \"identifier\": \"anthropics/pdf-extractor\", \"outputFormat\": \"steering\" } }\n ```\n\n### 浏览趋势技能并导入\n\n1. **获取24小时热门榜单**\n ```json\n { \"tool\": \"get_leaderboard\", \"arguments\": { \"timeframe\": \"24h\", \"limit\": 20 } }\n ```\n\n2. **导入热门技能**\n ```json\n { \"tool\": \"import_skill\", \"arguments\": { \"identifier\": \"owner/skill-name\", \"outputFormat\": \"power\" } }\n ```\n\n### 先验证后导入\n\n```mermaid\ngraph TD\n A[fetch_skill] --> B[validate_skill]\n B --> C{isValid?}\n C -->|true| D[convert_to_steering]\n C -->|false| E[审查issues]\n E --> F{可接受?}\n F -->|是| D\n F -->|否| G[使用其他技能]\n```\n\n---\n\n## 错误处理\n\n所有工具返回的错误遵循统一格式：资料来源：[src/core/errors.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts)\n\n```json\n{\n \"error\": \"Error message describing what went wrong\",\n \"tool\": \"tool_name\",\n \"timestamp\": \"2024-01-15T10:30:00.000Z\"\n}\n```\n\n**常见错误类型：**\n\n| 错误类型 | 触发场景 | 解决方案 |\n|----------|----------|----------|\n| 网络错误 | GitHub访问失败 | 检查网络连接 |\n| 未找到错误 | 技能名称错误 | 验证技能名称和仓库 |\n| 验证错误 | 安全扫描失败 | 审查安全问题后再操作 |\n| 解析错误 | 格式问题 | 检查YAML语法 |\n\n---\n\n## 缓存机制\n\nskills.sh搜索结果在内存中缓存1小时，以减少API调用并提高性能。缓存过期后自动刷新。资料来源：[README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n\n---\n\n## 安全特性\n\n系统提供多层次的安全保护：\n\n| 层级 | 机制 | 说明 |\n|------|------|------|\n| 验证层 | 危险命令检测 | 阻止`rm -rf`、`sudo`、`eval`等 |\n| 验证层 | 文件操作限制 | 禁止访问系统目录 |\n| 验证层 | 注入模式识别 | 检测代码注入尝试 |\n| 验证层 | 来源验证 | 仅允许GitHub来源 |\n| 验证层 | 跳过选项 | 可选的`skipValidation`参数 |\n\n资料来源：[README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n\n---\n\n\n\n## 核心模块架构\n\n### 相关页面\n\n相关主题：[类型定义系统](#page-type-system), [缓存机制](#page-caching)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/index.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/index.ts)\n- [src/cli.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/cli.ts)\n- [src/core/types.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/types.ts)\n- [src/core/conversion-engine.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)\n- [src/core/security-validator.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)\n- [src/core/errors.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts)\n \n\n# 核心模块架构\n\n本文档详细介绍 Skill Loader MCP Server 的核心模块架构，包括各模块的职责、数据流转、以及模块间的协作关系。\n\n## 1. 架构概述\n\nSkill Loader MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器应用，用于管理 Claude Skills 的导入、转换和验证。其核心架构采用分层设计，将功能职责分离到不同的模块中。\n\n```mermaid\ngraph TD\n A[入口层
index.ts / cli.ts] --> B[工具层
MCP Tools]\n B --> C[核心服务层
Core Services]\n C --> D[安全验证模块
Security Validator]\n C --> E[转换引擎
Conversion Engine]\n C --> F[错误处理模块
Error System]\n C --> G[类型系统
Type Definitions]\n \n H[外部服务
skills.sh API
GitHub API] --> B\n```\n\n**架构分层说明**：\n\n| 层级 | 组件 | 职责 |\n|------|------|------|\n| 入口层 | `index.ts`, `cli.ts` | 服务器初始化、传输协议配置 |\n| 工具层 | MCP Tools | 暴露给客户端的 API 接口 |\n| 核心服务层 | 核心模块 | 业务逻辑处理 |\n| 类型系统 | `types.ts` | 统一数据类型定义 |\n\n资料来源：[src/index.ts:1-50](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/index.ts)\n\n## 2. 入口层架构\n\n### 2.1 主入口 (index.ts)\n\n`index.ts` 是 MCP 服务器的主入口点，负责初始化和配置服务器。\n\n**核心职责**：\n- 创建 MCP 服务器实例\n- 注册所有工具处理器\n- 配置 stdio 传输协议\n- 处理服务器生命周期\n\n**代码结构**：\n\n```typescript\n// 服务器初始化伪代码\nconst server = new Server(\n {\n name: 'skill-loader',\n version: '1.1.0',\n },\n {\n capabilities: {\n tools: {},\n },\n }\n);\n\n// 注册工具\nserver.setRequestHandler(ListToolsRequestSchema, async () => ({\n tools: [/* 工具列表 */]\n}));\n\nserver.setRequestHandler(CallToolRequestSchema, async (request) => {\n // 路由到对应工具处理器\n});\n```\n\n资料来源：[src/index.ts:1-100](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/index.ts)\n\n### 2.2 CLI 入口 (cli.ts)\n\n`cli.ts` 提供命令行接口，支持独立运行服务器。\n\n**功能特性**：\n- 支持配置文件加载\n- 环境变量配置\n- 独立的进程启动\n\n资料来源：[src/cli.ts:1-50](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/cli.ts)\n\n## 3. 类型系统\n\n### 3.1 类型定义概述\n\n`types.ts` 定义了项目中使用的所有核心数据类型，确保类型安全和一致性。\n\n**主要类型分类**：\n\n| 类型分类 | 说明 |\n|----------|------|\n| 技能相关类型 | Skill、SkillFrontmatter、SkillSection |\n| API 响应类型 | SkillsShResponse、SkillShEntry、LeaderboardResponse |\n| 验证相关类型 | ValidationResult、ValidationIssue |\n| 转换相关类型 | ConversionResult、PowerFiles |\n| 错误类型 | SkillLoaderError 子类 |\n\n资料来源：[src/core/types.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/types.ts)\n\n### 3.2 技能数据结构\n\n**SkillFrontmatter** 定义技能的元数据：\n\n```typescript\ninterface SkillFrontmatter {\n name: string; // 技能名称\n description?: string; // 技能描述\n dependencies?: string[];// 依赖列表\n // ...其他元数据字段\n}\n```\n\n**SkillSection** 定义技能内容的结构化分段：\n\n```typescript\ninterface SkillSection {\n level: number; // 标题层级 (1-6)\n heading: string; // 标题文本\n content: string; // 段落内容\n}\n```\n\n资料来源：[src/core/types.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/types.ts)\n\n### 3.3 验证结果类型\n\n**ValidationResult** 定义安全验证的结果：\n\n```typescript\ninterface ValidationResult {\n isValid: boolean; // 是否通过验证\n issues: ValidationIssue[];// 发现的问题列表\n severity: 'safe' | 'warning' | 'unsafe'; // 严重程度\n}\n\ninterface ValidationIssue {\n type: 'dangerous_command' | 'suspicious_pattern' | 'untrusted_source';\n description: string; // 问题描述\n location?: string; // 问题位置\n}\n```\n\n资料来源：[src/core/security-validator.ts:50-80](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)\n\n## 4. 安全验证模块\n\n### 4.1 模块概述\n\n`security-validator.ts` 是系统的安全防线，负责扫描和检测技能内容中的潜在安全风险。\n\n```mermaid\ngraph LR\n A[技能内容] --> B[危险命令检测]\n A --> C[可疑模式检测]\n A --> D[来源验证]\n B --> E[评估结果]\n C --> E\n D --> E\n```\n\n**安全检测范围**：\n\n| 检测类型 | 描述 | 严重级别 |\n|----------|------|----------|\n| 危险命令 | `rm -rf`, `sudo`, `eval`, `exec` | unsafe |\n| 可疑文件操作 | `/etc/`, `/usr/`, `/bin/` 路径访问 | warning |\n| 代码注入 | `${...}`, `$(...)` 模式 | warning |\n| 不信任来源 | 非 GitHub URL | unsafe |\n\n资料来源：[src/core/security-validator.ts:1-100](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)\n\n### 4.2 验证流程\n\n**严重级别判定逻辑**：\n\n```typescript\nprivate determineSeverity(issues: Issue[]): 'safe' | 'warning' | 'unsafe' {\n if (issues.length === 0) {\n return 'safe';\n }\n\n // 如果存在不信任来源或危险命令，标记为不安全\n const hasUntrustedSource = issues.some(issue => issue.type === 'untrusted_source');\n const hasDangerousCommand = issues.some(issue => issue.type === 'dangerous_command');\n\n if (hasUntrustedSource || hasDangerousCommand) {\n return 'unsafe';\n }\n\n // 否则，可疑模式为警告级别\n return 'warning';\n}\n```\n\n资料来源：[src/core/security-validator.ts:200-220](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)\n\n## 5. 转换引擎模块\n\n### 5.1 模块概述\n\n`conversion-engine.ts` 是核心的业务逻辑模块，负责将 Claude Skills 转换为 Kiro 格式（Steering 文件或 Power）。\n\n**转换引擎能力**：\n\n| 功能 | 说明 |\n|------|------|\n| 格式转换 | SKILL.md → Steering 文件 / Power |\n| 依赖处理 | 生成 `mcp.json` 配置文件 |\n| 复杂内容拆分 | 生成 `steering/` 目录结构 |\n| 元数据保留 | 保留原始技能信息和导入来源 |\n\n资料来源：[src/core/conversion-engine.ts:1-150](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)\n\n### 5.2 转换为 Steering 文件\n\n**转换流程**：\n\n```mermaid\ngraph TD\n A[解析 SKILL.md] --> B[提取 frontmatter]\n B --> C[处理 body 内容]\n C --> D{是否有复杂章节?}\n D -->|是| E[生成 steering/ 目录]\n D -->|否| F[直接生成 .md 文件]\n E --> G[添加导入元数据]\n F --> G\n G --> H[输出 Steering 文件]\n```\n\n**Steering 文件结构示例**：\n\n```markdown\n---\noriginal_skill: PDF Extractor\nsource_url: https://github.com/...\nimported_at: 2024-01-15T10:30:00.000Z\n---\n\n# PDF Extractor\n\n[技能内容...]\n\n---\n*Imported from Claude Skills via Skill Loader Power*\n```\n\n资料来源：[src/core/conversion-engine.ts:80-120](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)\n\n### 5.3 转换为 Power 格式\n\n**Power 格式特点**：\n- 使用 `POWER.md` 作为主文件\n- 可选生成 `mcp.json`（当技能有依赖或工具引用时）\n- 可选生成 `steering/` 目录（当技能有 3+ 复杂章节时）\n\n**生成条件判断**：\n\n```typescript\n// 是否应生成 mcp.json\nprivate shouldGenerateMcpJson(skill: Skill): boolean {\n return (\n (skill.frontmatter.dependencies && skill.frontmatter.dependencies.length > 0) ||\n this.hasToolReferences(skill)\n );\n}\n\n// 是否应生成 steering/ 目录\nprivate shouldGenerateSteeringDir(skill: Skill): boolean {\n const complexSections = skill.sections.filter(\n s => s.level >= 2 && s.content.length > 200\n );\n return complexSections.length >= 3;\n}\n```\n\n资料来源：[src/core/conversion-engine.ts:180-200](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)\n\n### 5.4 关键字提取\n\n转换引擎包含关键字提取功能，用于技能分类和搜索优化：\n\n```typescript\nprivate extractKeywords(description: string): string[] {\n const stopWords = new Set([\n 'the', 'and', 'for', 'with', 'this', 'that', 'from', 'into',\n 'when', 'what', 'where', 'how', 'why', 'can', 'will', 'should'\n // ...更多停用词\n ]);\n \n // 提取 3+ 字符的非停用词，最多返回 5 个\n const words = description\n .toLowerCase()\n .replace(/[^a-z0-9\\s]/g, ' ')\n .split(/\\s+/)\n .filter(word => word.length >= 3 && !stopWords.has(word))\n .slice(0, 5);\n \n return words;\n}\n```\n\n资料来源：[src/core/conversion-engine.ts:150-175](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)\n\n## 6. 错误处理系统\n\n### 6.1 错误类层次结构\n\n`errors.ts` 定义了完整的错误类型体系：\n\n```mermaid\ngraph TD\n A[SkillLoaderError
基类]\n A --> B[ValidationError
验证错误]\n A --> C[FileSystemError
文件系统错误]\n A --> D[NetworkError
网络错误]\n A --> E[ParseError
解析错误]\n```\n\n**基类特性**：\n\n```typescript\nexport class SkillLoaderError extends Error {\n public readonly code: string;\n public readonly timestamp: Date;\n public readonly context: Record;\n \n constructor(message: string, context?: Record) {\n super(message);\n this.code = this.getDefaultCode();\n this.timestamp = new Date();\n this.context = context || {};\n }\n}\n```\n\n资料来源：[src/core/errors.ts:1-100](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts)\n\n### 6.2 验证错误 (ValidationError)\n\n专门处理技能验证失败的错误类型：\n\n```typescript\nexport class ValidationError extends SkillLoaderError {\n public readonly validationType: 'security' | 'format' | 'content';\n \n getUserMessage(): string {\n // 返回用户友好的错误信息和恢复建议\n }\n}\n```\n\n**错误消息包含**：\n- 错误描述\n- 验证类型\n- 具体的恢复建议\n\n资料来源：[src/core/errors.ts:50-80](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts)\n\n### 6.3 文件系统错误 (FileSystemError)\n\n处理文件读写操作相关的错误：\n\n```typescript\nexport class FileSystemError extends SkillLoaderError {\n public readonly operation: 'read' | 'write' | 'delete' | 'access';\n public readonly filePath: string;\n public readonly systemError?: string;\n \n getUserMessage(): string {\n // 根据错误码提供具体的修复建议\n }\n}\n```\n\n**系统错误处理**：\n\n| 错误码 | 建议 |\n|--------|------|\n| EACCES/EPERM | 检查文件权限 |\n| ENOSPC | 释放磁盘空间 |\n| ENOENT | 验证目录存在 |\n| EEXIST | 使用 --overwrite 标志 |\n\n资料来源：[src/core/errors.ts:100-150](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts)\n\n## 7. MCP 工具层\n\n### 7.1 工具列表\n\n系统提供 8 个 MCP 工具：\n\n| 工具名称 | 功能 | 认证要求 |\n|----------|------|----------|\n| `search_skills` | 关键词搜索技能 | 不需要 |\n| `list_skills` | 分页列出所有技能 | 需要 API Key |\n| `get_leaderboard` | 获取排行榜 | 需要 API Key |\n| `fetch_skill` | 获取技能内容 | 不需要 |\n| `validate_skill` | 安全验证 | 不需要 |\n| `convert_to_steering` | 转为 Steering 格式 | 不需要 |\n| `convert_to_power` | 转为 Power 格式 | 不需要 |\n| `import_skill` | 完整导入流程 | 不需要 |\n\n资料来源：[README.md:50-150](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n\n### 7.2 工具调用流程\n\n**import_skill 完整工作流**：\n\n```mermaid\ngraph TD\n A[import_skill 调用] --> B[fetch_skill
获取技能内容]\n B --> C{skipValidation?}\n C -->|否| D[validate_skill
安全验证]\n C -->|是| E[跳过验证]\n D --> F{验证通过?}\n F -->|否| G[返回错误]\n F -->|是| H[convert_to_power
格式转换]\n E --> H\n H --> I[返回转换结果]\n```\n\n资料来源：[examples/usage-examples.md:1-100](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n\n## 8. 数据流与状态管理\n\n### 8.1 技能数据流转\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Server as MCP Server\n participant Fetcher as 技能获取器\n participant Validator as 安全验证器\n participant Converter as 转换引擎\n participant GitHub as GitHub API\n \n Client->>Server: import_skill(identifier)\n Server->>Fetcher: fetchSkill(identifier)\n Fetcher->>GitHub: GET raw skill content\n GitHub-->>Fetcher: SKILL.md content\n Fetcher-->>Server: skill content\n \n Server->>Validator: validateSkill(content)\n Validator-->>Server: ValidationResult\n \n Server->>Converter: convertToPower(content)\n Converter-->>Server: ConversionResult\n \n Server-->>Client: import result\n```\n\n### 8.2 缓存策略\n\n系统使用内存缓存来优化 skills.sh API 调用：\n\n| 缓存项 | TTL | 说明 |\n|--------|-----|------|\n| 搜索结果 | 1 小时 | 减少 API 调用 |\n| 目录列表 | 1 小时 | 提升分页性能 |\n\n资料来源：[README.md:180-200](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n\n## 9. 配置与环境\n\n### 9.1 环境变量\n\n| 变量名 | 必需 | 说明 |\n|--------|------|------|\n| `SKILLS_SH_API_KEY` | 仅 list_skills/get_leaderboard | skills.sh API 密钥 |\n\n### 9.2 MCP 服务器配置\n\n```json\n{\n \"mcpServers\": {\n \"skill-loader\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@goldzulu/skill-loader-mcp-server\"],\n \"env\": {\n \"SKILLS_SH_API_KEY\": \"your-api-key-here\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:30-60](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n\n## 10. 模块依赖关系\n\n```mermaid\ngraph TD\n index_ts[index.ts] --> cli_ts[cli.ts]\n index_ts --> types_ts[types.ts]\n \n tools[Tools Layer] --> conversion_engine[conversion-engine.ts]\n tools --> security_validator[security-validator.ts]\n tools --> errors_ts[errors.ts]\n \n conversion_engine --> types_ts\n security_validator --> types_ts\n errors_ts --> types_ts\n \n conversion_engine --> errors_ts\n security_validator --> errors_ts\n \n subgraph core[核心模块]\n conversion_engine\n security_validator\n errors_ts\n types_ts\n end\n```\n\n**依赖关系说明**：\n\n| 依赖方向 | 说明 |\n|----------|------|\n| tools → core | 工具层依赖核心服务处理业务逻辑 |\n| core 内部 | 核心模块相互依赖，types 作为共享基础 |\n| errors 被广泛依赖 | 所有模块在出错时使用错误系统 |\n\n## 11. 总结\n\nSkill Loader MCP Server 的核心模块架构采用清晰的分层设计：\n\n1. **入口层** 负责服务器初始化和协议配置\n2. **工具层** 暴露统一的 MCP 接口\n3. **核心服务层** 包含安全验证、格式转换、错误处理等关键功能\n4. **类型系统** 确保整个项目的类型安全\n\n该架构具有良好的可扩展性，便于添加新的工具、转换格式或验证规则。\n\n---\n\n\n\n## 类型定义系统\n\n### 相关页面\n\n相关主题：[核心模块架构](#page-core-modules), [技能获取器](#page-skill-fetcher)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/types.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/types.ts)\n- [src/core/errors.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts)\n- [src/core/conversion-engine.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)\n- [src/core/security-validator.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)\n- [examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n- [README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n \n\n# 类型定义系统\n\n## 概述\n\n类型定义系统是 Skill Loader MCP Server 的核心基础设施之一，为整个项目提供强类型的接口定义、数据模型和错误处理机制。该系统基于 TypeScript 编写，确保在 MCP 工具调用、数据流转和错误处理过程中具备类型安全性和编译时检查能力。\n\n类型定义系统的主要职责包括：\n\n- **数据结构定义**：为 skills.sh API 响应、技能元数据、导入结果等核心数据定义清晰的结构\n- **MCP 工具接口**：为 8 个 MCP 工具提供输入输出参数的类型规范\n- **错误类型体系**：建立分层分类的错误类型系统，支持精确的错误定位和恢复建议\n- **安全验证模型**：定义安全检查项和验证结果的数据结构\n\n资料来源：[README.md:1-20]()\n\n## 系统架构\n\n### 模块组成\n\n类型定义系统由以下几个核心模块组成：\n\n| 模块 | 文件路径 | 职责 |\n|------|----------|------|\n| 基础类型 | `src/core/types.ts` | 定义核心数据结构和接口 |\n| 错误类型 | `src/core/errors.ts` | 实现分层错误类体系 |\n| 转换引擎类型 | `src/core/conversion-engine.ts` | 技能转换相关类型 |\n| 安全验证类型 | `src/core/security-validator.ts` | 安全检查数据结构 |\n\n### 架构层次图\n\n```mermaid\ngraph TD\n A[类型定义系统] --> B[基础类型层]\n A --> C[错误类型层]\n A --> D[业务类型层]\n \n B --> B1[SkillShEntry]\n B --> B2[SkillContent]\n B --> B3[API响应类型]\n \n C --> C1[SkillLoaderError]\n C --> C2[NetworkError]\n C --> C3[ValidationError]\n C --> C4[FileSystemError]\n \n D --> D1[工具参数类型]\n D --> D2[转换结果类型]\n D --> D3[验证结果类型]\n```\n\n## 基础数据类型\n\n### 技能条目类型\n\n技能条目是 skills.sh 目录中的基本单位，包含以下关键字段：\n\n```typescript\ninterface SkillShEntry {\n name: string; // 技能名称（kebab-case格式）\n description: string; // 技能描述\n owner: string; // 仓库所有者\n repo: string; // 仓库名称\n installs: number; // 安装次数\n skillId?: string; // 技能唯一标识\n source?: string; // 来源信息\n relevance?: number; // 搜索相关性得分\n rank?: number; // 排行榜排名\n trending?: boolean; // 是否为热门技能\n}\n```\n\n资料来源：[examples/usage-examples.md:1-50]()\n\n### 技能内容类型\n\n技能内容用于存储解析后的完整技能信息：\n\n```typescript\ninterface SkillContent {\n frontmatter: {\n name: string;\n description?: string;\n dependencies?: string[];\n [key: string]: any;\n };\n body: string; // 技能正文内容\n sections: SkillSection[];\n}\n```\n\n资料来源：[src/core/conversion-engine.ts:1-30]()\n\n### 技能解析结果\n\n技能解析函数返回的结果包含元数据和解析状态：\n\n```typescript\ninterface ParsedSkill {\n frontmatter: Record;\n body: string;\n sections: Array<{\n heading: string;\n level: number;\n content: string;\n }>;\n}\n```\n\n## 错误类型体系\n\n### 基类设计\n\n错误系统采用继承层级结构，基类 `SkillLoaderError` 提供通用功能：\n\n```typescript\nexport class SkillLoaderError extends Error {\n public readonly timestamp: Date;\n public readonly context: Record;\n\n constructor(message: string, context: Record = {}) {\n super(message);\n this.name = this.constructor.name;\n this.timestamp = new Date();\n this.context = context;\n }\n}\n```\n\n资料来源：[src/core/errors.ts:1-30]()\n\n### 错误子类层级\n\n```mermaid\ngraph TD\n A[SkillLoaderError] --> B[NetworkError]\n A --> C[ValidationError]\n A --> D[FileSystemError]\n A --> E[ParsingError]\n \n B --> B1[HTTP状态码]\n B --> B2[重试次数]\n \n C --> C1[验证类型]\n C --> C2[问题详情]\n \n D --> D1[操作类型]\n D --> D2[文件路径]\n```\n\n### 网络错误 (NetworkError)\n\n用于处理网络相关故障：\n\n```typescript\nexport class NetworkError extends SkillLoaderError {\n public readonly url: string;\n public readonly statusCode?: number;\n public readonly retryCount: number;\n\n constructor(\n message: string,\n url: string,\n options: {\n statusCode?: number;\n retryCount?: number;\n context?: Record;\n } = {}\n );\n}\n```\n\n资料来源：[src/core/errors.ts:80-100]()\n\n**错误处理建议**：\n\n| 状态码 | 建议措施 |\n|--------|----------|\n| 404 | 验证技能名称是否正确，检查仓库是否存在 |\n| 403 | 可能是 GitHub 速率限制，等待后重试 |\n| >= 500 | 服务器端问题，稍后重试 |\n\n### 验证错误 (ValidationError)\n\n用于处理格式、安全和模式验证失败：\n\n```typescript\nexport class ValidationError extends SkillLoaderError {\n public readonly validationType: 'format' | 'security' | 'schema' | 'content';\n public readonly lineNumber?: number;\n public readonly details: string[];\n\n constructor(\n message: string,\n validationType: 'format' | 'security' | 'schema' | 'content',\n options: {\n lineNumber?: number;\n details?: string[];\n context?: Record;\n } = {}\n );\n}\n```\n\n资料来源：[src/core/errors.ts:180-200]()\n\n### 文件系统错误 (FileSystemError)\n\n用于处理文件系统操作错误：\n\n```typescript\nexport class FileSystemError extends SkillLoaderError {\n public readonly operation: 'read' | 'write' | 'delete' | 'access';\n public readonly filePath: string;\n public readonly systemError?: string;\n}\n```\n\n资料来源：[src/core/errors.ts:120-150]()\n\n**常见系统错误代码**：\n\n| 错误代码 | 含义 | 恢复建议 |\n|----------|------|----------|\n| EACCES/EPERM | 权限不足 | 检查文件权限，使用适当权限运行 |\n| ENOSPC | 磁盘空间不足 | 清理磁盘空间，选择其他输出位置 |\n| ENOENT | 路径不存在 | 验证目录存在，检查路径正确性 |\n| EEXIST | 文件已存在 | 使用 --overwrite 标志替换 |\n\n## MCP 工具类型定义\n\n### 工具参数类型\n\n系统为 8 个 MCP 工具定义了严格的输入参数类型：\n\n| 工具名称 | 必需参数 | 可选参数 |\n|----------|----------|----------|\n| `list_skills` | - | `page`, `pageSize` |\n| `search_skills` | `query` | `limit` |\n| `get_leaderboard` | - | `timeframe`, `limit` |\n| `fetch_skill` | `identifier` | - |\n| `validate_skill` | `content` | `url` |\n| `convert_to_steering` | `content` | `sourceUrl` |\n| `convert_to_power` | `content` | `sourceUrl` |\n| `import_skill` | `identifier`, `outputFormat` | `skipValidation` |\n\n资料来源：[README.md:1-80]()\n\n### 列表技能工具类型\n\n```typescript\ninterface ListSkillsParams {\n page?: number; // 页码，默认1\n pageSize?: number; // 每页数量，默认50，最大100\n}\n\ninterface ListSkillsResult {\n skills: SkillShEntry[];\n total: number;\n page: number;\n pageSize: number;\n}\n```\n\n### 搜索技能工具类型\n\n```typescript\ninterface SearchSkillsParams {\n query: string; // 搜索关键词\n limit?: number; // 最大返回数量，默认20\n}\n\ninterface SearchSkillsResult {\n skills: SkillShEntry[];\n query: string;\n count: number;\n}\n```\n\n### 获取排行榜工具类型\n\n```typescript\ninterface GetLeaderboardParams {\n timeframe?: 'all' | '24h'; // 时间范围，默认 'all'\n limit?: number; // 最大结果数，默认20，最大50\n}\n\ninterface GetLeaderboardResult {\n skills: Array;\n timeframe: string;\n count: number;\n}\n```\n\n### 验证技能工具类型\n\n```typescript\ninterface ValidateSkillParams {\n content: string; // 待验证的技能内容\n url?: string; // 源URL用于验证\n}\n\ninterface ValidationIssue {\n type: 'dangerous_command' | 'suspicious_pattern' | 'untrusted_source';\n description: string;\n location?: string;\n}\n\ninterface ValidateSkillResult {\n isValid: boolean;\n issues: ValidationIssue[];\n severity: 'safe' | 'warning' | 'unsafe';\n}\n```\n\n资料来源：[examples/usage-examples.md:80-120]()\n\n## 安全验证类型\n\n### 验证问题类型\n\n安全验证模块定义了多种检查类型：\n\n```typescript\ntype ValidationIssueType = \n | 'dangerous_command' // 危险命令\n | 'suspicious_pattern' // 可疑模式\n | 'untrusted_source'; // 不受信任的源\n```\n\n### 验证结果级别\n\n```typescript\ntype ValidationSeverity = 'safe' | 'warning' | 'unsafe';\n```\n\n安全级别判定逻辑：\n\n| 问题类型 | 严重级别 |\n|----------|----------|\n| `untrusted_source` | unsafe |\n| `dangerous_command` | unsafe |\n| `suspicious_pattern` | warning |\n| 无问题 | safe |\n\n资料来源：[src/core/security-validator.ts:1-50]()\n\n### 危险命令检测\n\n系统检测以下危险命令模式：\n\n- `rm -rf` 系列删除命令\n- `sudo` 特权命令\n- `eval` 和 `exec` 代码执行命令\n\n### 可疑模式检测\n\n检测以下可疑代码模式：\n\n- 模板注入：`${...}` 或 `$(...)`\n- 系统路径访问：`/etc/`、`/usr/`、`/bin/`\n- 敏感配置文件访问\n\n## 转换结果类型\n\n### 转换为转向文件结果\n\n```typescript\ninterface ConvertToSteeringResult {\n content: string; // 转换后的内容\n filename: string; // 生成的文件名\n metadata: {\n originalSkill: string;\n sourceUrl?: string;\n importedAt: string;\n };\n}\n```\n\n### 转换为 Power 结果\n\n```typescript\ninterface ConvertToPowerResult {\n files: Array<{\n path: string;\n content: string;\n }>;\n metadata: {\n skillName: string;\n sourceUrl?: string;\n filesGenerated: number;\n };\n}\n```\n\nPower 格式可能生成的文件：\n\n| 文件类型 | 条件 | 路径 |\n|----------|------|------|\n| POWER.md | 始终生成 | `~/.kiro/powers/{skill-name}/POWER.md` |\n| mcp.json | 技能有依赖或工具引用 | 同目录 |\n| steering/ | 技能有3+复杂章节 | 同目录 |\n\n资料来源：[src/core/conversion-engine.ts:50-100]()\n\n## API 响应类型\n\n### Skills.sh API v1 响应类型\n\n```typescript\ninterface SkillsShV1Response {\n skills: SkillsShV1Entry[];\n total: number;\n page: number;\n}\n\ninterface SkillsShV1Entry {\n id: string;\n skillId: string;\n name: string;\n description: string;\n owner: string;\n repo: string;\n installs: number;\n source: string;\n}\n```\n\n资料来源：[CHANGELOG.md:1-30]()\n\n## 类型使用最佳实践\n\n### 类型守卫\n\n系统支持 TypeScript 类型守卫以提供精确的类型缩小：\n\n```typescript\nfunction isNetworkError(error: unknown): error is NetworkError {\n return error instanceof NetworkError;\n}\n\nfunction isValidationError(error: unknown): error is ValidationError {\n return error instanceof ValidationError;\n}\n```\n\n### 错误恢复流程\n\n```mermaid\ngraph TD\n A[发生错误] --> B{错误类型?}\n B -->|NetworkError| C[检查状态码]\n B -->|ValidationError| D[检查验证类型]\n B -->|FileSystemError| E[检查系统错误]\n \n C --> C1{404?}\n C1 -->|是| C2[验证技能名称]\n C1 -->|否| C3{403?}\n C3 -->|是| C4[等待重试]\n C3 -->|否| C5[检查连接]\n \n D --> D1{security?}\n D1 -->|是| D2[拒绝导入]\n D1 -->|否| D3{format?}\n D3 -->|是| D4[检查YAML格式]\n \n E --> E1{EACCES?}\n E1 -->|是| E2[检查权限]\n E1 -->|否| E3{ENOSPC?}\n E3 -->|是| E4[清理磁盘]\n```\n\n## 总结\n\n类型定义系统为 Skill Loader MCP Server 提供了：\n\n1. **完整的类型安全**：从 API 响应到错误处理，全链路类型覆盖\n2. **清晰的错误分类**：四级错误类型体系，支持精确的问题定位\n3. **规范的工具接口**：8 个 MCP 工具的输入输出类型一致性保证\n4. **安全验证模型**：结构化的安全检查和问题报告机制\n\n该系统是项目架构的基础层，为上层的工具实现、CLI 入口和配置管理提供了坚实的类型支撑。\n\n---\n\n\n\n## 技能解析器\n\n### 相关页面\n\n相关主题：[技能获取器](#page-skill-fetcher), [MCP工具详解](#page-mcp-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/conversion-engine.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)\n- [src/core/security-validator.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)\n- [src/core/errors.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts)\n- [examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n- [README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n- [src/core/conversion-engine.test.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.test.ts)\n \n\n# 技能解析器\n\n技能解析器（Skill Resolver）是 Skill Loader MCP Server 的核心组件之一，负责从 GitHub 仓库解析、提取和处理 Claude Skills 内容。该模块在技能导入工作流中扮演着关键角色，与安全验证器、转换引擎协同工作，确保技能能够安全、高效地转换为 Kiro 格式。\n\n## 核心职责\n\n技能解析器的主要职责包括：\n\n| 职责类别 | 具体功能 |\n|---------|---------|\n| 内容获取 | 从 GitHub 远程仓库获取原始技能内容 |\n| 标识解析 | 支持 `owner/repo` 和纯技能名称两种格式的标识符解析 |\n| 元数据提取 | 解析 YAML frontmatter 中的名称、描述、依赖等信息 |\n| 内容验证 | 调用安全验证器检查潜在风险 |\n| 格式转换 | 将解析后的内容传递给转换引擎生成目标格式 |\n\n资料来源：[README.md:1-50]()\n\n## 解析流程\n\n技能解析器遵循标准化的解析流程，确保从远程获取的技能内容能够被准确处理和转换。\n\n```mermaid\ngraph TD\n A[输入: 技能标识符] --> B[标识符标准化]\n B --> C{格式判断}\n C -->|owner/repo 格式| D[构建 GitHub URL]\n C -->|纯名称格式| E[查询 skills.sh 目录]\n D --> F[获取原始内容]\n E --> F\n F --> G[解析 YAML Frontmatter]\n G --> H[提取 body 内容]\n H --> I[结构化输出]\n I --> J[传递给转换引擎]\n```\n\n资料来源：[examples/usage-examples.md:30-60]()\n\n## 标识符解析规则\n\n技能解析器支持两种标识符格式，具有不同的处理逻辑：\n\n### owner/repo 格式\n\n当提供完整的所有者/仓库格式时（如 `anthropics/pdf-extractor`），解析器直接构建 GitHub 原始内容 URL：\n\n```\nhttps://raw.githubusercontent.com/{owner}/{repo}/main/skills/{skill-name}/SKILL.md\n```\n\n### 纯名称格式\n\n当提供纯技能名称时（如 `pdf-extractor`），解析器会查询 skills.sh 目录获取完整的仓库信息，然后构建获取路径。 资料来源：[examples/usage-examples.md:45-55]()\n\n## YAML Frontmatter 解析\n\n技能解析器能够准确解析 Claude Skills 标准格式的 YAML frontmatter，提取以下元数据字段：\n\n| 字段 | 类型 | 说明 |\n|-----|------|-----|\n| `name` | string | 技能唯一标识名称 |\n| `description` | string | 技能功能描述 |\n| `dependencies` | string[] | 技能依赖列表 |\n| `version` | string | 技能版本号（可选） |\n\n解析后的结构化数据包含 `frontmatter` 和 `body` 两个主要部分：\n\n```typescript\ninterface ParsedSkill {\n frontmatter: {\n name: string;\n description?: string;\n dependencies?: string[];\n [key: string]: any;\n };\n body: string;\n}\n```\n\n资料来源：[src/core/conversion-engine.ts:1-30]()\n\n## 技能验证集成\n\n技能解析器与安全验证器紧密集成，在解析过程中自动进行安全检查：\n\n### 危险命令检测\n\n解析器会扫描技能内容中的危险命令模式：\n\n- `rm -rf` — 递归删除命令\n- `sudo` — 管理员权限执行\n- `eval` / `exec` — 代码执行函数\n\n### 可疑文件操作检测\n\n检测访问敏感系统路径的操作：\n\n- `/etc/` — 系统配置目录\n- `/usr/` — 用户程序目录\n- `/bin/` — 二进制程序目录\n\n### 代码注入检测\n\n识别潜在的代码注入攻击模式：\n\n- `${...}` — 模板字符串注入\n- `$(...)` — 命令替换注入\n\n资料来源：[src/core/security-validator.ts:1-40]()\n\n### 验证结果级别\n\n| 安全级别 | 条件 | 处理方式 |\n|---------|------|---------|\n| `safe` | 无安全问题 | 正常处理 |\n| `warning` | 存在可疑模式 | 警告但允许 |\n| `unsafe` | 包含危险命令或非信任来源 | 阻止导入 |\n\n资料来源：[src/core/security-validator.ts:35-50]()\n\n## 错误处理机制\n\n技能解析器实现了完善的错误处理机制，针对不同类型的故障提供精确的错误分类：\n\n### 错误类型分类\n\n| 错误类型 | 触发场景 | 恢复建议 |\n|---------|---------|---------|\n| `NetworkError` | 网络连接失败、GitHub 不可达 | 检查网络连接，等待后重试 |\n| `NotFoundError` | 技能或仓库不存在 (404) | 验证技能名称，检查仓库存在性 |\n| `RateLimitError` | GitHub API 频率限制 (403) | 等待几分钟后重试 |\n| `ValidationError` | 安全验证失败、格式错误 | 审查安全问题，使用信任来源 |\n| `FileSystemError` | 文件读写失败、权限问题 | 检查文件路径和权限设置 |\n\n资料来源：[src/core/errors.ts:1-80]()\n\n### HTTP 状态码处理\n\n解析器针对常见的 HTTP 错误状态码提供了用户友好的错误消息和建议：\n\n```typescript\nif (statusCode === 404) {\n // 验证技能名称是否正确\n // 检查仓库是否存在于 GitHub\n // 尝试使用 owner/repo 格式\n} else if (statusCode === 403) {\n // 可能触发了 GitHub 频率限制\n // 等待几分钟后重试\n} else if (statusCode >= 500) {\n // 服务器端问题\n // 稍后重试\n}\n```\n\n资料来源：[src/core/errors.ts:60-90]()\n\n## 转换引擎协作\n\n技能解析器与转换引擎协同工作，将解析后的技能内容转换为目标格式：\n\n### 支持的目标格式\n\n| 格式 | 输出文件 | 说明 |\n|-----|---------|------|\n| `steering` | `.md` 文件 | Kiro 方向盘文件格式 |\n| `power` | `POWER.md` + `mcp.json` | Kiro 能力格式 |\n\n### Power 格式生成规则\n\n转换引擎根据技能内容特征决定生成哪些文件：\n\n1. **基础文件**: 始终生成 `POWER.md`\n2. **MCP 配置**: 当技能包含依赖项或工具引用时生成 `mcp.json`\n3. **转向目录**: 当技能包含 3 个或以上复杂章节时生成 `steering/` 目录\n\n资料来源：[src/core/conversion-engine.ts:80-120]()\n\n### 转换测试验证\n\n```typescript\ndescribe('toPower', () => {\n it('converts parsed skill to power format', () => {\n const content = `---\nname: my-power\ndescription: A powerful skill\n---\n# Instructions\nDo power stuff.`;\n\n const parsed = engine.parseSkill(content);\n const power = engine.toPower(parsed, 'https://example.com');\n\n expect(power.powerName).toBe('my-power');\n expect(power.files.length).toBeGreaterThanOrEqual(1);\n expect(power.files[0].path).toBe('POWER.md');\n });\n\n it('generates mcp.json when skill has dependencies', () => {\n const content = `---\nname: dep-power\ndependencies:\n - express\n - cors\n---\n# Body`;\n\n const parsed = engine.parseSkill(content);\n const power = engine.toPower(parsed);\n\n const mcpFile = power.files.find(f => f.path === 'mcp.json');\n expect(mcpFile).toBeDefined();\n });\n});\n```\n\n资料来源：[src/core/conversion-engine.test.ts:60-100]()\n\n## 导入工作流\n\n完整的技能导入工作流将解析器、验证器和转换器整合为一个端到端的流程：\n\n```mermaid\ngraph LR\n A[用户请求导入] --> B[fetch_skill]\n B --> C{成功?}\n C -->|否| D[返回错误]\n C -->|是| E[validate_skill]\n E --> F{安全?}\n F -->|否| G[阻止或警告]\n F -->|是| H[convert_to_power/steering]\n H --> I[返回转换结果]\n```\n\n### 完整导入示例\n\n```json\n{\n \"tool\": \"import_skill\",\n \"arguments\": {\n \"identifier\": \"anthropics/pdf-extractor\",\n \"outputFormat\": \"power\",\n \"skipValidation\": false\n }\n}\n```\n\n响应包含转换后的文件和元数据：\n\n```json\n{\n \"success\": true,\n \"content\": \"---\\nname: pdf-extractor\\ndisplayName: PDF Extractor\\n...\",\n \"filename\": \"POWER.md\",\n \"targetPath\": \"~/.kiro/powers/pdf-extractor/POWER.md\",\n \"metadata\": {\n \"skillName\": \"pdf-extractor\",\n \"sourceUrl\": \"https://raw.githubusercontent.com/...\",\n \"outputFormat\": \"power\"\n }\n}\n```\n\n资料来源：[examples/usage-examples.md:80-120]()\n\n## 性能优化\n\n技能解析器实现了多项性能优化策略：\n\n### 缓存机制\n\nskills.sh 目录搜索结果在内存中缓存 1 小时，减少 API 调用并提升响应速度。缓存过期后自动刷新。\n\n### 重试机制\n\n网络请求采用指数退避重试策略，应对临时性网络故障：\n\n```typescript\n// 初始延迟: 1秒\n// 最大延迟: 30秒\n// 最大重试次数: 3次\n```\n\n### 并发控制\n\n解析请求支持并发处理，但限制最大并发数避免资源耗尽。\n\n资料来源：[README.md:100-120]()\n\n## 总结\n\n技能解析器是 Skill Loader MCP Server 的核心模块，承担着从远程 GitHub 仓库获取技能内容、解析 YAML 元数据、进行安全验证以及与转换引擎协作的重要职责。通过完善的错误处理机制、安全扫描集成和性能优化策略，确保技能导入过程的可靠性、安全性和高效性。开发者可以通过扩展解析规则和验证逻辑来支持更多技能格式和来源。\n\n---\n\n\n\n## 技能获取器\n\n### 相关页面\n\n相关主题：[技能解析器](#page-skill-resolver), [安全验证器](#page-security-validator)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/skill-fetcher.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/skill-fetcher.ts)\n- [src/tools/fetch-skill.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/fetch-skill.ts)\n- [src/core/skill-resolver.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/skill-resolver.ts)\n- [src/core/conversion-engine.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)\n- [examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n- [README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n \n\n# 技能获取器\n\n技能获取器（Skill Fetcher）是 Skill Loader MCP Server 的核心组件之一，负责从 GitHub 仓库获取 Claude Skills 的原始内容。该模块在技能导入工作流中扮演着数据源的角色，为后续的安全验证和格式转换提供原材料。\n\n## 核心定位\n\n在 Skill Loader MCP Server 的整体架构中，技能获取器处于工作流的最上游位置。用户的完整导入流程为：**获取技能 → 安全验证 → 格式转换 → 导入完成**。技能获取器仅负责完成第一步，即从 GitHub 获取技能的原始 Markdown 内容。\n\n技能获取器支持两种标识符格式：\n\n| 标识符格式 | 示例 | 说明 |\n|-----------|------|------|\n| `owner/repo` | `anthropics/pdf-extractor` | 标准格式，明确指定所有者仓库和技能名称 |\n| 纯技能名称 | `pdf-extractor` | 简写格式，自动使用 `anthropics/skills` 作为默认仓库 |\n\n资料来源：[examples/usage-examples.md:61-67]()\n\n## 架构设计\n\n### 模块分层\n\n技能获取器采用分层架构设计，主要分为两个层次：\n\n```\n┌─────────────────────────────────────┐\n│ MCP 工具层 (fetch-skill.ts) │ ← MCP 协议接口\n├─────────────────────────────────────┤\n│ 核心服务层 (skill-fetcher.ts) │ ← 业务逻辑\n├─────────────────────────────────────┤\n│ 解析层 (skill-resolver.ts) │ ← API 交互\n└─────────────────────────────────────┘\n```\n\n**工具层**负责处理 MCP 协议层面的参数解析和响应格式化；**核心服务层**实现技能获取的业务逻辑；**解析层**负责与外部 API（skills.sh 和 GitHub）进行实际的网络通信。\n\n资料来源：[src/tools/fetch-skill.ts]()\n\n### 获取流程\n\n```mermaid\ngraph TD\n A[接收 identifier] --> B{identifier 格式判断}\n B -->|包含 /| C[解析 owner/repo]\n B -->|纯名称| D[使用默认仓库 anthropics/skills]\n C --> E[构建 GitHub URL]\n D --> E\n E --> F[发起 HTTP 请求]\n F --> G{响应状态}\n G -->|200| H[返回技能内容]\n G -->|404| I[抛出 NotFoundError]\n G -->|网络错误| J[抛出 NetworkError]\n G -->|其他| K[抛出 FetchError]\n```\n\n资料来源：[src/core/conversion-engine.ts:75-89]()\n\n## 核心功能\n\n### fetch_skill 工具\n\n`fetch_skill` 是 MCP 服务器暴露给外部的唯一工具接口，用于获取存储在 GitHub 上的原始技能内容。\n\n**参数定义：**\n\n| 参数名 | 类型 | 必需 | 默认值 | 说明 |\n|-------|------|------|--------|------|\n| `identifier` | string | 是 | - | 技能标识符，格式为 `owner/repo` 或纯技能名称 |\n\n**请求示例：**\n\n```json\n{\n \"tool\": \"fetch_skill\",\n \"arguments\": {\n \"identifier\": \"anthropics/pdf-extractor\"\n }\n}\n```\n\n资料来源：[examples/usage-examples.md:53-67]()\n\n**响应结构：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `content` | string | 技能的原始 Markdown 内容 |\n| `url` | string | 实际获取内容的原始 URL |\n| `metadata` | object | 技能的元数据信息 |\n| `metadata.name` | string | 技能名称 |\n| `metadata.owner` | string | 仓库所有者 |\n| `metadata.repo` | string | 仓库名称 |\n| `metadata.skillPath` | string | 仓库中的技能路径 |\n| `metadata.fetchedAt` | string | ISO 格式的获取时间 |\n\n资料来源：[examples/usage-examples.md:68-79]()\n\n### 响应示例\n\n```json\n{\n \"content\": \"---\\nname: PDF Extractor\\ndescription: Extract text from PDF files\\n---\\n\\n# PDF Extractor\\n\\n...\",\n \"url\": \"https://raw.githubusercontent.com/anthropics/skills/main/skills/pdf-extractor/SKILL.md\",\n \"metadata\": {\n \"name\": \"pdf-extractor\",\n \"owner\": \"anthropics\",\n \"repo\": \"skills\",\n \"skillPath\": \"skills/pdf-extractor\",\n \"fetchedAt\": \"2024-01-15T10:30:00.000Z\"\n }\n}\n```\n\n资料来源：[examples/usage-examples.md:69-79]()\n\n## URL 构建规则\n\n技能获取器使用固定的 URL 模板从 GitHub 获取原始内容。URL 构建遵循以下规则：\n\n```\nhttps://raw.githubusercontent.com/{owner}/{repo}/main/skills/{skillName}/SKILL.md\n```\n\n**URL 组件解析：**\n\n| 组件 | 来源 | 说明 |\n|------|------|------|\n| `owner` | identifier 前半部分或 `anthropics` | 仓库所有者 |\n| `repo` | identifier 后半部分或 `skills` | 仓库名称 |\n| `skillName` | identifier 最后部分 | 技能名称（小写） |\n| 分支 | 固定为 `main` | GitHub 仓库分支 |\n| 文件路径 | 固定为 `skills/{skillName}/SKILL.md` | 标准技能文件结构 |\n\n资料来源：[src/core/conversion-engine.ts:75-89]()\n\n## 错误处理\n\n技能获取器定义了多种错误类型以应对不同的失败场景。\n\n### 错误类型\n\n| 错误类型 | 触发条件 | HTTP 状态码 |\n|----------|----------|-------------|\n| `NotFoundError` | 技能不存在或路径错误 | 404 |\n| `NetworkError` | 网络连接失败或超时 | - |\n| `FetchError` | HTTP 请求失败（非 200） | 4xx/5xx |\n\n资料来源：[src/core/errors.ts]()\n\n### 错误响应格式\n\n所有工具错误返回统一格式：\n\n```json\n{\n \"error\": \"Error message describing what went wrong\",\n \"tool\": \"tool_name\",\n \"timestamp\": \"2024-01-15T10:30:00.000Z\"\n}\n```\n\n资料来源：[examples/usage-examples.md:189-195]()\n\n### 常见错误场景\n\n| 错误场景 | 错误消息示例 | 解决方案 |\n|---------|-------------|---------|\n| 技能不存在 | `Skill not found: unknown/skill` | 检查 identifier 拼写 |\n| 网络连接失败 | `Failed to connect to GitHub` | 检查网络连接 |\n| 仓库不可访问 | `Repository not found` | 确认仓库公开状态 |\n\n资料来源：[README.md:77-85]()\n\n## 重试机制\n\n技能获取器内置重试逻辑以提高网络请求的可靠性。\n\n**重试策略：**\n\n| 参数 | 配置 |\n|------|------|\n| 最大重试次数 | 3 次 |\n| 重试间隔 | 指数退避 |\n| 初始延迟 | 1000ms |\n| 最大延迟 | 5000ms |\n\n指数退避公式：`delay = min(initialDelay * 2^attempt, maxDelay)`\n\n资料来源：[README.md:73]()\n\n## 与其他模块的集成\n\n### 在导入工作流中的角色\n\n技能获取器是 `import_skill` 工具的底层依赖。`import_skill` 工具的执行流程如下：\n\n```mermaid\ngraph LR\n A[fetch_skill] --> B[validate_skill]\n B --> C[convert_to_steering 或 convert_to_power]\n C --> D[返回导入结果]\n \n A -.->|数据源| B\n B -.->|验证通过| C\n```\n\n资料来源：[README.md:50-60]()\n\n### 配合安全验证\n\n获取到的原始内容会立即传递给安全验证模块进行检查。安全验证器会扫描以下危险模式：\n\n- **危险命令**：`rm -rf`、`sudo`、`eval`、`exec`\n- **可疑文件操作**：`/etc/`、`/usr/`、`/bin/`\n- **代码注入模式**：`${...}`、`$(...)`\n- **不可信来源**：非 GitHub URL\n\n资料来源：[README.md:71-73]()\n\n## 使用限制\n\n| 限制项 | 值 | 说明 |\n|--------|---|------|\n| 内容大小 | 无明确限制 | 受 GitHub 响应大小限制 |\n| 并发请求 | 无限制 | 但建议限制频率以避免触发限流 |\n| 缓存 | 1 小时 TTL | 仅对 skills.sh 搜索结果缓存，获取操作不缓存 |\n\n资料来源：[README.md:74-76]()\n\n## 总结\n\n技能获取器作为 Skill Loader MCP Server 的数据入口，提供了一个简洁可靠的接口从 GitHub 仓库获取 Claude Skills 的原始内容。它支持灵活的标识符格式，内置完善的错误处理和重试机制，并为后续的安全验证和格式转换模块提供稳定的数据源。该模块的稳定性直接影响整个导入工作流的可靠性。\n\n---\n\n\n\n## 转换引擎\n\n### 相关页面\n\n相关主题：[安全验证器](#page-security-validator), [MCP工具详解](#page-mcp-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/conversion-engine.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)\n- [src/core/conversion-engine.test.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.test.ts)\n- [src/tools/convert-to-steering.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/convert-to-steering.ts)\n- [src/tools/convert-to-power.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/convert-to-power.ts)\n \n\n# 转换引擎\n\n转换引擎（Conversion Engine）是 Skill Loader MCP Server 的核心模块，负责将 Claude Skills 格式的内容转换为 Kiro 平台所需的两种格式：**Steering 文件格式** 和 **Power 格式**。该引擎封装了所有与格式转换相关的逻辑，为 MCP 工具层提供统一的转换接口。\n\n## 核心职责\n\n转换引擎的主要职责包括：\n\n1. **解析 Skill 内容** — 解析 YAML frontmatter 和 Markdown 正文，提取元数据、标题层级和正文内容\n2. **格式转换** — 将解析后的技能数据转换为 steering 文件或 power 格式\n3. **文件名生成** — 将技能名称转换为 kebab-case 格式作为输出文件名\n4. **元数据注入** — 在转换后的文件中添加原始技能信息、来源 URL 和导入时间戳\n5. **条件生成** — 根据技能内容特征判断是否需要生成额外的 `mcp.json` 或 `steering/` 目录\n\n资料来源：[src/core/conversion-engine.ts:1-50]()\n\n## 架构概览\n\n```mermaid\ngraph TD\n A[原始 Skill 内容] --> B[ConversionEngine]\n B --> C{parseSkill}\n C --> D[ParsedSkill 数据结构]\n D --> E[toSteeringFile]\n D --> F[toPower]\n E --> G[Steering 文件]\n F --> H[POWER.md]\n F --> I{shouldGenerateMcpJson?}\n F --> J{shouldGenerateSteeringDir?}\n I -->|是| K[mcp.json]\n J -->|是| L[steering/ 目录]\n G --> M[转换结果]\n H --> N[files 数组]\n K --> N\n L --> N\n```\n\n## 核心类与接口\n\n### ConversionEngine 类\n\n`ConversionEngine` 是转换引擎的核心类，提供所有转换操作的入口方法。\n\n| 方法名 | 参数 | 返回值 | 功能说明 |\n|--------|------|--------|----------|\n| `parseSkill` | `content: string` | `ParsedSkill` | 解析 Skill 内容，返回结构化数据 |\n| `toSteeringFile` | `skill: ParsedSkill, sourceUrl?: string` | `SteeringResult` | 转换为 Steering 文件格式 |\n| `toPower` | `skill: ParsedSkill, sourceUrl?: string` | `PowerResult` | 转换为 Power 格式 |\n| `toKebabCase` | `str: string` | `string` | 字符串转 kebab-case |\n| `extractKeywords` | `description: string` | `string[]` | 从描述中提取关键词 |\n| `shouldGenerateMcpJson` | `skill: ParsedSkill` | `boolean` | 判断是否需要生成 mcp.json |\n| `generateMcpJson` | `skill: ParsedSkill` | `McpJsonConfig` | 生成 mcp.json 配置内容 |\n| `shouldGenerateSteeringDir` | `skill: ParsedSkill` | `boolean` | 判断是否需要生成 steering/ 目录 |\n| `generateSteeringContent` | `skill: ParsedSkill` | `string` | 生成 steering/ 目录内容 |\n\n资料来源：[src/core/conversion-engine.ts:1-100]()\n\n### ParsedSkill 数据结构\n\n解析后的技能数据结构包含以下字段：\n\n```typescript\ninterface ParsedSkill {\n frontmatter: {\n name: string; // 技能名称\n description: string; // 技能描述\n dependencies?: string[]; // 依赖列表（可选）\n [key: string]: any; // 其他 frontmatter 字段\n };\n body: string; // 原始正文内容\n sections: Array<{ // 解析后的章节列表\n heading: string; // 章节标题\n level: number; // 标题层级（1-6）\n content: string; // 章节内容\n }>;\n}\n```\n\n资料来源：[src/core/conversion-engine.ts:50-80]()\n\n## 解析流程\n\n`parseSkill` 方法负责将原始 Markdown 内容解析为结构化数据：\n\n```mermaid\ngraph TD\n A[原始内容] --> B{内容为空?}\n B -->|是| C[抛出 ValidationError]\n B -->|否| D[解析 YAML Frontmatter]\n D --> E{name 存在?}\n E -->|否| F[使用 'Untitled Skill']\n E -->|是| G[提取 name 字段]\n D --> H{description 存在?}\n H -->|否| I[抛出 ValidationError]\n H -->|是| J[提取 description 字段]\n G --> K[构建 frontmatter 对象]\n F --> K\n I --> K\n K --> L[解析 Markdown 章节]\n L --> M[构建 sections 数组]\n M --> N[返回 ParsedSkill]\n```\n\n### 解析规则\n\n- **空内容检测**：空字符串会抛出 `ValidationError`，错误消息包含 \"empty\" 关键词\n- **必填字段验证**：缺少 `name` 或 `description` 会抛出错误\n- **章节解析**：使用标题行（`#`、`##`、`###` 等）分割正文，构建层级化的 sections 数组\n- **容错处理**：缺少 frontmatter 时，使用默认值 `name: 'Untitled Skill'`\n\n资料来源：[src/core/conversion-engine.test.ts:20-80]()\n\n## Steering 文件转换\n\nSteering 文件是 Kiro 平台的轻量级格式，用于在 `.kiro/steering/` 目录下存储技能指南。\n\n### 输出格式\n\n```markdown\n---\noriginal_skill: {技能名称}\nsource_url: {来源URL}\nimported_at: {ISO时间戳}\n---\n\n# {技能名称}\n\n{正文内容}\n\n## Dependencies\n\n- {依赖1}\n- {依赖2}\n\n---\n*Imported from Claude Skills via Skill Loader Power*\n```\n\n### 转换结果结构\n\n```typescript\ninterface SteeringResult {\n steeringContent: string; // Steering 文件内容\n filename: string; // 文件名（kebab-case）\n targetPath: string; // 目标路径 .kiro/steering/{filename}\n metadata: {\n skillName: string;\n sourceUrl?: string;\n outputFormat: 'steering';\n validationResult: ValidationResult;\n };\n}\n```\n\n资料来源：[src/tools/convert-to-steering.ts]()\n\n## Power 格式转换\n\nPower 格式是 Kiro 平台的高级格式，支持更复杂的技能配置。当技能具有依赖或工具引用时，会自动生成额外的配置文件。\n\n### 输出结构\n\n```mermaid\ngraph TD\n A[PowerResult] --> B[files: Array]\n B --> C[POWER.md]\n B --> D[mcp.json?]\n B --> E[steering/?]\n C --> F[displayName, body, Dependencies, Import Metadata]\n D --> G[dependencies 数组]\n E --> H[详细章节内容]\n```\n\n### 生成条件\n\n| 条件 | 生成文件 | 说明 |\n|------|----------|------|\n| `dependencies` 存在且非空 | `mcp.json` | 包含依赖列表 |\n| 存在 MCP server 工具引用 | `mcp.json` | 包含 MCP 服务器配置 |\n| 3+ 个复杂章节（层级≥2，内容>200字符） | `steering/` 目录 | 存储详细指南内容 |\n\n### PowerResult 结构\n\n```typescript\ninterface PowerResult {\n powerName: string; // Power 名称（kebab-case）\n displayName: string; // 显示名称（原始格式）\n files: Array<{\n path: string; // 文件路径\n content: string; // 文件内容\n }>;\n}\n```\n\n资料来源：[src/core/conversion-engine.ts:100-200]()\n\n## kebab-case 转换\n\n转换引擎提供了 `toKebabCase` 方法，将任意字符串转换为标准的 kebab-case 格式（用于 Kiro powers 和 steering 文件的标准命名规范）。\n\n### 转换规则\n\n1. 转换为小写\n2. 空格和下划线替换为连字符\n3. 移除特殊字符（仅保留 a-z、0-9 和连字符）\n4. 折叠多个连续连字符为一个\n5. 移除首尾连字符\n\n### 转换示例\n\n| 输入 | 输出 |\n|------|------|\n| `PDF Extractor` | `pdf-extractor` |\n| `React_Best_Practices` | `react-best-practices` |\n| `My Skill!!` | `my-skill` |\n\n资料来源：[src/core/conversion-engine.ts:60-100]()\n\n## 关键词提取\n\n`extractKeywords` 方法从技能描述中提取最多 5 个有意义的关键词：\n\n### 过滤规则\n\n- 移除停用词集合中的常见词（`the`, `and`, `for`, `with`, `this`, `that`, `from`, `into` 等）\n- 仅保留长度 ≥ 3 的单词\n- 移除特殊字符后按空格分割\n\n```typescript\nprivate extractKeywords(description: string): string[] {\n const stopWords = new Set([\n 'the', 'and', 'for', 'with', 'this', 'that', 'from', 'into',\n 'when', 'what', 'where', 'how', 'why', 'can', 'will', 'should',\n 'would', 'could', 'has', 'have', 'had', 'are', 'was', 'were',\n 'been', 'being', 'you', 'your', 'use', 'used', 'using'\n ]);\n // ... 实现逻辑\n}\n```\n\n资料来源：[src/core/conversion-engine.ts:200-250]()\n\n## MCP 工具集成\n\n转换引擎通过两个 MCP 工具与外部交互：\n\n### convert_to_steering\n\n将原始 Skill 内容转换为 Steering 文件格式：\n\n```typescript\ninterface ConvertToSteeringInput {\n content: string; // 必填：Skill 内容\n sourceUrl?: string; // 可选：原始来源 URL\n}\n```\n\n资料来源：[src/tools/convert-to-steering.ts]()\n\n### convert_to_power\n\n将原始 Skill 内容转换为 Power 格式：\n\n```typescript\ninterface ConvertToPowerInput {\n content: string; // 必填：Skill 内容\n sourceUrl?: string; // 可选：原始来源 URL\n}\n```\n\n**自动生成逻辑**：当技能包含依赖或工具引用时，自动在 `files` 数组中添加 `mcp.json`；当技能有 3+ 个复杂章节时，添加 `steering/` 目录。\n\n资料来源：[src/tools/convert-to-power.ts]()\n\n## 完整导入流程\n\n转换引擎通常在 `import_skill` 工具中被调用，作为完整导入工作流的一部分：\n\n```mermaid\ngraph LR\n A[fetch_skill] --> B[validate_skill]\n B --> C{验证通过?}\n C -->|否| D[返回错误]\n C -->|是| E[ConversionEngine.parseSkill]\n E --> F{outputFormat}\n F -->|steering| G[ConversionEngine.toSteeringFile]\n F -->|power| H[ConversionEngine.toPower]\n G --> I[SteeringResult]\n H --> J[PowerResult]\n I --> K[输出到 .kiro/steering/]\n J --> L[输出到 ~/.kiro/powers/]\n```\n\n资料来源：[README.md]()，[src/core/conversion-engine.test.ts]()\n\n## 测试覆盖\n\n转换引擎拥有完整的单元测试覆盖，测试文件为 `src/core/conversion-engine.test.ts`。\n\n### 测试场景\n\n| 测试用例 | 验证内容 |\n|----------|----------|\n| `parses valid skill with frontmatter and body` | 正确解析包含 frontmatter 和正文的技能 |\n| `throws on empty content` | 空内容抛出 ValidationError |\n| `throws on missing name in frontmatter` | 缺少 name 字段时抛出错误 |\n| `throws on missing description in frontmatter` | 缺少 description 字段时抛出错误 |\n| `handles content without frontmatter` | 无 frontmatter 时使用默认值 |\n| `converts parsed skill to steering format` | Steering 文件格式转换正确 |\n| `includes dependencies in steering file` | 依赖项正确包含在 Steering 文件中 |\n| `converts parsed skill to power format` | Power 格式转换正确 |\n| `generates mcp.json when skill has dependencies` | 有依赖时正确生成 mcp.json |\n| `does not generate mcp.json when skill has no dependencies` | 无依赖时不生成 mcp.json |\n\n资料来源：[src/core/conversion-engine.test.ts:1-150]()\n\n## 依赖关系\n\n```mermaid\ngraph TD\n A[conversion-engine.ts] --> B[errors.ts]\n A --> C[ParsedSkill 类型定义]\n C --> D[frontmatter 类型]\n C --> E[section 类型]\n B --> F[SkillLoaderError]\n B --> G[ValidationError]\n B --> H[FileSystemError]\n I[convert-to-steering.ts] --> A\n J[convert-to-power.ts] --> A\n K[import_skill 工具] --> I\n K --> J\n```\n\n## 扩展点\n\n如需扩展转换引擎功能，可考虑以下方向：\n\n1. **新增输出格式**：添加新的转换方法（如 `toPrompt` 或 `toAgentConfig`）\n2. **自定义元数据**：扩展 frontmatter 的解析和注入逻辑\n3. **高级章节处理**：增强 `shouldGenerateSteeringDir` 的判断逻辑\n4. **模板支持**：引入模板引擎以支持自定义输出格式\n\n---\n\n\n\n## 安全验证器\n\n### 相关页面\n\n相关主题：[技能获取器](#page-skill-fetcher), [转换引擎](#page-conversion-engine)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/security-validator.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)\n- [src/core/security-validator.test.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.test.ts)\n- [src/core/conversion-engine.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)\n- [src/core/errors.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts)\n- [examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n \n\n# 安全验证器\n\n## 概述\n\n安全验证器（Security Validator）是 Skill Loader MCP Server 的核心安全组件，负责在导入外部技能（Skill）之前对其内容进行全面的安全扫描和风险评估。该组件能够检测危险命令、可疑文件操作、代码注入模式和不受信任的来源，从而保护用户系统免受潜在恶意代码的侵害。\n\n安全验证器的主要职责包括：\n\n- 扫描技能内容中的危险系统命令\n- 检测可疑的文件路径访问\n- 识别代码注入模式（如变量展开和命令替换）\n- 验证技能来源的可信度\n- 提供详细的验证结果和修复建议\n\n资料来源：[src/core/security-validator.ts:1-50]()\n\n## 架构设计\n\n### 模块位置\n\n安全验证器位于 `src/core/security-validator.ts`，是核心模块的重要组成部分。项目的目录结构如下：\n\n```\nskill-loader-mcp-server/\n├── src/\n│ ├── core/ # 核心功能模块\n│ │ ├── security-validator.ts # 安全验证器\n│ │ ├── conversion-engine.ts # 转换引擎\n│ │ └── errors.ts # 错误处理\n│ ├── tools/ # MCP 工具实现\n│ ├── utils/ # 工具函数\n│ └── index.ts # 主入口点\n├── tests/ # 测试文件\n└── examples/ # 使用示例\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CONTRIBUTING.md)\n\n### 验证流程\n\n安全验证器采用多阶段验证流程，对技能内容进行逐层安全检查：\n\n```mermaid\ngraph TD\n A[接收技能内容] --> B[扫描危险命令]\n B --> C{检测到危险命令?}\n C -->|是| D[标记为 unsafe]\n C -->|否| E[检查可疑文件路径]\n E --> F{检测到可疑路径?}\n F -->|是| G[标记为 unsafe]\n F -->|否| H[检测代码注入模式]\n H --> I{检测到注入模式?}\n I -->|是| J[标记为 warning]\n I -->|否| K[验证来源可信度]\n K --> L{来源可信?}\n L -->|是| M[标记为 safe]\n L -->|否| N[标记为 unsafe]\n D --> O[返回验证结果]\n G --> O\n J --> O\n M --> O\n N --> O\n```\n\n资料来源：[src/core/security-validator.ts:30-45]()\n\n## 验证规则\n\n### 危险命令检测\n\n安全验证器会扫描技能内容中的危险系统命令，这些命令可能对系统造成不可逆的损害。\n\n| 命令模式 | 描述 | 严重级别 |\n|---------|------|---------|\n| `rm -rf` | 递归强制删除命令 | unsafe |\n| `sudo` | 超级用户权限执行 | unsafe |\n| `eval` | 动态代码执行 | unsafe |\n| `exec` | 命令执行函数 | unsafe |\n\n```typescript\n// 危险命令检测逻辑示例\nconst dangerousCommands = ['rm -rf', 'sudo', 'eval', 'exec'];\ndangerousCommands.forEach(cmd => {\n if (content.includes(cmd)) {\n issues.push({\n type: 'dangerous_command',\n description: `危险命令: ${cmd}`,\n location: `Line ${getLineNumber(content, index)}`\n });\n }\n});\n```\n\n资料来源：[src/core/security-validator.ts:50-80]()\n\n### 可疑文件路径检测\n\n验证器会检查技能内容中是否包含对系统关键目录的访问企图。\n\n| 路径模式 | 描述 | 风险级别 |\n|---------|------|---------|\n| `/etc/` | 系统配置文件目录 | warning |\n| `/usr/` | 系统程序目录 | warning |\n| `/bin/` | 二进制可执行文件目录 | warning |\n\n这些路径的访问通常不是普通技能所需的，可能表明存在恶意意图。\n\n资料来源：[src/core/security-validator.ts:80-100]()\n\n### 代码注入模式检测\n\n安全验证器能够识别多种代码注入攻击模式。\n\n| 注入类型 | 模式示例 | 描述 |\n|---------|---------|------|\n| 变量展开 | `${VARIABLE}` | 模板变量展开可能执行任意代码 |\n| 命令替换 | `$(command)` | Shell 命令替换语法 |\n\n```typescript\n// 代码注入检测\nif (content.includes('${')) {\n issues.push({\n type: 'code_injection',\n description: '检测到变量展开模式'\n });\n}\n\nif (content.includes('$(')) {\n issues.push({\n type: 'command_substitution',\n description: '检测到命令替换模式'\n });\n}\n```\n\n资料来源：[src/core/security-validator.ts:100-130]()\n\n### 来源可信度验证\n\n安全验证器会验证技能来源的可靠性。只有来自受信任来源的技能才会被标记为安全。\n\n| 来源类型 | 可信状态 | 说明 |\n|---------|---------|------|\n| GitHub URL | 可信 | GitHub 是主要的技能托管平台 |\n| 其他 URL | 不可信 | 存在安全风险 |\n\n```typescript\nif (url && !url.includes('github.com')) {\n issues.push({\n type: 'untrusted_source',\n description: '技能来源不是受信任的 GitHub URL',\n location: 'Source URL'\n });\n}\n```\n\n资料来源：[src/core/security-validator.ts:130-150]()\n\n## API 接口\n\n### validate_skill 工具\n\n`validate_skill` 是 MCP 服务器提供的安全验证工具，用于验证技能内容的安全性。\n\n**参数定义：**\n\n| 参数名 | 类型 | 必需 | 描述 |\n|-------|------|------|------|\n| content | string | 是 | 要验证的技能内容 |\n| url | string | 否 | 来源 URL 用于验证 |\n\n**返回值结构：**\n\n```json\n{\n \"isValid\": true,\n \"issues\": [\n {\n \"type\": \"dangerous_command\",\n \"description\": \"危险递归删除命令 (rm -rf)\",\n \"location\": \"Line 7: rm -rf /\"\n }\n ],\n \"severity\": \"unsafe\"\n}\n```\n\n**使用示例：**\n\n```json\n{\n \"tool\": \"validate_skill\",\n \"arguments\": {\n \"content\": \"---\\nname: Test\\n---\\n\\n# Test\",\n \"url\": \"https://example.com/skill.md\"\n }\n}\n```\n\n资料来源：[examples/usage-examples.md:1-30]()\n\n### 验证结果对象\n\n验证完成后，系统返回一个结构化的验证结果对象。\n\n```typescript\ninterface ValidationResult {\n isValid: boolean; // 是否通过验证\n issues: ValidationIssue[]; // 发现的问题列表\n severity: 'safe' | 'warning' | 'unsafe'; // 整体严重级别\n}\n```\n\n**严重级别判定规则：**\n\n| 条件 | 判定结果 |\n|-----|---------|\n| 存在 `untrusted_source` 或 `dangerous_command` | unsafe |\n| 仅存在 `suspicious_pattern` | warning |\n| 无任何问题 | safe |\n\n资料来源：[src/core/security-validator.ts:200-220]()\n\n## 错误处理\n\n### ValidationError 类\n\n当验证过程发生错误时，系统会抛出 `ValidationError` 异常。\n\n```typescript\nexport class ValidationError extends SkillLoaderError {\n public readonly validationType: 'format' | 'security' | 'schema' | 'content';\n public readonly lineNumber?: number;\n public readonly details: string[];\n}\n```\n\n**错误类型：**\n\n| 类型 | 描述 | 恢复建议 |\n|-----|------|---------|\n| format | 格式错误 | 验证 YAML frontmatter 格式是否正确 |\n| security | 安全问题 | 手动检查技能内容，使用可信来源的技能 |\n| schema | 结构错误 | 验证技能是否符合 Agent Skills 标准 |\n| content | 内容错误 | 检查内容语法，向技能作者报告问题 |\n\n资料来源：[src/core/errors.ts:80-120]()\n\n### 错误消息格式\n\n```typescript\ngetUserMessage(): string {\n let msg = `Validation Error: ${this.message}\\n`;\n msg += `Type: ${this.validationType}\\n`;\n \n if (this.lineNumber) {\n msg += `Line: ${this.lineNumber}\\n`;\n }\n \n msg += '\\nDetails:\\n';\n for (const detail of this.details) {\n msg += `- ${detail}\\n`;\n }\n \n // 根据验证类型添加恢复建议\n if (this.validationType === 'security') {\n msg += '\\nSuggestions:\\n';\n msg += '- Review the skill content manually\\n';\n msg += '- Contact the skill author about security concerns\\n';\n msg += '- Use a different skill from a trusted source\\n';\n }\n \n return msg;\n}\n```\n\n资料来源：[src/core/errors.ts:120-150]()\n\n## 测试覆盖\n\n安全验证器拥有完整的单元测试覆盖，确保各项安全检测功能的准确性。\n\n### 测试用例列表\n\n| 测试用例 | 测试目标 | 预期结果 |\n|---------|---------|---------|\n| 检测危险删除命令 | `rm -rf /` | 发现问题 |\n| 检测提权命令 | `sudo rm` | 发现问题 |\n| 检测 eval 使用 | `eval $var` | 发现问题 |\n| 检测代码注入 | `${VARIABLE}` | 发现问题 |\n| 检测命令替换 | `$(whoami)` | 发现问题 |\n| 检测可疑模式 | `~/. hidden` | 警告级别 |\n\n资料来源：[src/core/security-validator.test.ts:1-50]()\n\n### 测试实现示例\n\n```typescript\nit('detects dangerous commands', () => {\n const content = makeContent('rm -rf /');\n const result = validator.validate(content);\n expect(result.issues.some(i => i.type === 'dangerous_command')).toBe(true);\n});\n\nit('detects code injection patterns', () => {\n const content = makeContent('Use ${VARIABLE} in template');\n const result = validator.validate(content);\n expect(result.issues.some(i => i.description.includes('Variable expansion'))).toBe(true);\n});\n\nit('returns warning for suspicious patterns only', () => {\n const content = makeContent('Access ~/. hidden files');\n const result = validator.validate(content);\n expect(result.isValid).toBe(true);\n expect(result.severity).toBe('warning');\n});\n```\n\n资料来源：[src/core/security-validator.test.ts:30-60]()\n\n## 与转换引擎的集成\n\n安全验证器是转换引擎（Conversion Engine）工作流程的重要组成部分。在将技能转换为 Kiro 格式之前，系统会自动进行安全验证。\n\n```mermaid\ngraph LR\n A[fetch_skill] --> B[validate_skill]\n B --> C{验证通过?}\n C -->|是| D[convert_to_steering]\n C -->|否| E[返回错误]\n D --> F[导入完成]\n E --> G[跳过或报告]\n```\n\n资料来源：[src/core/conversion-engine.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)\n\n### import_skill 工具\n\n`import_skill` 工具提供了完整的导入工作流程，包含自动安全验证：\n\n```json\n{\n \"tool\": \"import_skill\",\n \"arguments\": {\n \"identifier\": \"anthropics/pdf-extractor\",\n \"outputFormat\": \"power\",\n \"skipValidation\": false\n }\n}\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 必需 | 默认值 | 描述 |\n|-----|------|------|-------|------|\n| identifier | string | 是 | - | 技能标识符 |\n| outputFormat | string | 是 | - | 输出格式：`steering` 或 `power` |\n| skipValidation | boolean | 否 | false | 是否跳过安全验证 |\n\n**响应示例：**\n\n```json\n{\n \"success\": true,\n \"targetPath\": \"~/.kiro/powers/pdf-extractor/POWER.md\",\n \"metadata\": {\n \"validationResult\": {\n \"isValid\": true,\n \"issues\": [],\n \"severity\": \"safe\"\n }\n }\n}\n```\n\n资料来源：[examples/usage-examples.md:80-120]()\n\n## 配置与使用建议\n\n### 何时跳过验证\n\n在某些情况下，用户可能需要跳过安全验证：\n\n| 场景 | 建议 | 风险等级 |\n|-----|------|---------|\n| 内部可信技能 | 可跳过 | 低 |\n| 已人工审查的技能 | 可跳过 | 低 |\n| 来自不可信来源 | 建议保留验证 | 高 |\n| 包含系统命令的技能 | 必须保留验证 | 高 |\n\n### 验证流程建议\n\n建议的技能导入流程如下：\n\n1. **获取技能信息**：使用 `fetch_skill` 获取原始内容\n2. **验证安全性**：使用 `validate_skill` 检查安全问题\n3. **审查结果**：检查返回的 issues 列表\n4. **转换格式**：使用 `convert_to_steering` 或 `convert_to_power` 转换\n5. **导入技能**：根据验证结果决定是否继续\n\n资料来源：[examples/usage-examples.md:120-150]()\n\n## 安全特性总结\n\n安全验证器提供了多层次的安全保护机制：\n\n| 安全功能 | 实现状态 | 描述 |\n|---------|---------|------|\n| 危险命令检测 | ✅ 已实现 | 检测 rm -rf, sudo, eval, exec |\n| 可疑路径检测 | ✅ 已实现 | 检测 /etc/, /usr/, /bin/ |\n| 代码注入检测 | ✅ 已实现 | 检测 ${} 和 $() 模式 |\n| 来源验证 | ✅ 已实现 | 仅允许 GitHub 来源 |\n| 严重级别评估 | ✅ 已实现 | safe/warning/unsafe 三级 |\n| 详细错误信息 | ✅ 已实现 | 包含行号和修复建议 |\n\n资料来源：[src/core/security-validator.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)\n\n---\n\n\n\n## 缓存机制\n\n### 相关页面\n\n相关主题：[核心模块架构](#page-core-modules), [技能获取器](#page-skill-fetcher)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/utils/cache.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/utils/cache.ts)\n- [README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n- [CHANGELOG.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CHANGELOG.md)\n \n\n# 缓存机制\n\n## 概述\n\nSkill Loader MCP Server 实现了一套内存缓存系统，用于提升 API 调用效率并减少网络请求次数。缓存机制的核心设计目标是：\n\n- 减少对 skills.sh 目录 API 的重复调用\n- 提升搜索和列表查询的响应速度\n- 通过 TTL（Time-To-Live）机制确保数据的时效性\n\n缓存系统在项目架构中属于基础工具层，被核心业务模块调用。资料来源：[src/utils/cache.ts:1-20]()\n\n## 核心组件\n\n### CacheEntry 接口\n\n泛型缓存条目接口，存储数据及其时间戳：\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| `data` | `T` | 缓存的数据内容 |\n| `timestamp` | `number` | 缓存创建时间戳（毫秒） |\n\n资料来源：[src/utils/cache.ts:6-10]()\n\n### Cache 类\n\n通用内存缓存类，支持 TTL 过期机制：\n\n```typescript\nexport class Cache {\n private cache: Map> = new Map();\n private ttl: number;\n}\n```\n\n| 属性 | 类型 | 描述 |\n|------|------|------|\n| `cache` | `Map>` | 内部缓存存储结构 |\n| `ttl` | `number` | 缓存有效期（毫秒） |\n\n资料来源：[src/utils/cache.ts:14-17]()\n\n## API 参考\n\n### 构造函数\n\n```typescript\nconstructor(ttl: number)\n```\n\n| 参数 | 类型 | 描述 |\n|------|------|------|\n| `ttl` | `number` | 缓存存活时间（毫秒） |\n\n资料来源：[src/utils/cache.ts:19-24]()\n\n### get 方法\n\n从缓存中获取值，若不存在或已过期则返回 `undefined`：\n\n```typescript\nget(key: string): T | undefined\n```\n\n**执行流程：**\n\n```mermaid\ngraph TD\n A[调用 get 方法] --> B{查找 key 是否存在}\n B -->|不存在| C[返回 undefined]\n B -->|存在| D{检查是否过期}\n D -->|已过期| E[删除 key 并返回 undefined]\n D -->|未过期| F[返回缓存数据]\n```\n\n资料来源：[src/utils/cache.ts:31-50]()\n\n### set 方法\n\n将数据存入缓存，自动记录当前时间戳：\n\n```typescript\nset(key: string, data: T): void\n```\n\n| 参数 | 类型 | 描述 |\n|------|------|------|\n| `key` | `string` | 缓存键名 |\n| `data` | `T` | 要缓存的数据 |\n\n资料来源：[src/utils/cache.ts:57-66]()\n\n### has 方法\n\n检查指定键是否存在且未过期：\n\n```typescript\nhas(key: string): boolean\n```\n\n**返回值说明：**\n\n| 返回值 | 含义 |\n|--------|------|\n| `true` | 键存在且未过期 |\n| `false` | 键不存在或已过期 |\n\n资料来源：[src/utils/cache.ts:73-86]()\n\n## 过期检测机制\n\n缓存条目通过时间戳与当前时间的差值判断是否过期：\n\n```typescript\nif (Date.now() - entry.timestamp > this.ttl) {\n this.cache.delete(key);\n return undefined;\n}\n```\n\n- **当前时间**：`Date.now()` 返回自 1970-01-01 以来的毫秒数\n- **时间差**：当前时间减去缓存创建时间\n- **过期判定**：时间差大于 `ttl` 值时视为过期\n\n资料来源：[src/utils/cache.ts:44-47]()\n\n## 实际应用场景\n\n### skills.sh 目录缓存\n\n项目在生产环境中使用 1 小时 TTL 对 skills.sh 目录搜索结果进行缓存：\n\n> 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.\n\n资料来源：[README.md:95-97]()\n\n### 缓存优势\n\n| 优势 | 说明 |\n|------|------|\n| 减少 API 调用 | 避免重复请求 skills.sh 目录 |\n| 提升响应速度 | 命中缓存时直接返回，无需网络请求 |\n| 自动刷新 | TTL 过期后自动清除，确保数据时效性 |\n\n资料来源：[CHANGELOG.md:10-12]()\n\n## 架构位置\n\n缓存模块位于项目的工具层，被核心业务模块依赖：\n\n```\nskill-loader-mcp-server/\n├── src/\n│ ├── core/ # 核心业务逻辑\n│ ├── tools/ # MCP 工具实现\n│ ├── utils/ # 工具函数（包含 cache.ts）\n│ ├── index.ts # 主入口\n│ └── cli.ts # CLI 入口\n├── examples/ # 使用示例\n├── dist/ # 编译输出\n└── tests/ # 测试文件\n```\n\n资料来源：[CONTRIBUTING.md:10-18]()\n\n## 使用限制\n\n当前缓存实现为**进程级内存缓存**，存在以下限制：\n\n| 限制 | 说明 |\n|------|------|\n| 进程生命周期 | 服务重启后缓存丢失 |\n| 单实例 | 分布式环境下各实例独立缓存 |\n| 内存占用 | 大数据量缓存可能影响内存使用 |\n\n> **注意**：此缓存工具类为未来扩展性提供，项目当前主要依赖 SkillResolver 类的内置缓存功能。\n\n资料来源：[src/utils/cache.ts:3-6]()\n\n## 扩展建议\n\n如需更强的缓存能力，可考虑：\n\n1. **持久化缓存**：接入 Redis 或 Memcached\n2. **分布式缓存**：支持多实例共享\n3. **缓存预热**：服务启动时主动加载热门数据\n4. **缓存统计**：添加命中率和性能指标监控\n\n---\n\n\n\n## 命令行工具\n\n### 相关页面\n\n相关主题：[项目介绍](#page-project-intro)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/cli.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/cli.ts)\n- [test-server.js](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/test-server.js)\n- [examples/mcp-config.json](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/mcp-config.json)\n- [README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n- [CONTRIBUTING.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CONTRIBUTING.md)\n \n\n# 命令行工具\n\nSkill Loader MCP Server 提供了一套完整的命令行工具，用于管理 Claude Skills 的导入、转换和验证操作。本页面详细说明服务器的命令行使用方式、配置参数以及与 Claude Desktop 和 Kiro 的集成方法。\n\n## 概述\n\nSkill Loader MCP Server 的命令行工具是连接 Claude Desktop 与技能仓库的桥梁。通过 MCP（Model Context Protocol）协议，服务器提供了 9 个核心工具函数，涵盖技能发现、获取、验证、格式转换和导入等完整工作流程。资料来源：[README.md:1-50]()\n\n### 支持的运行环境\n\n| 运行方式 | 说明 | 环境变量要求 |\n|---------|------|-------------|\n| Claude Desktop | 通过配置文件集成 | 可选 |\n| Kiro | 通过 mcp.json 配置 | 可选 |\n| 独立运行 | 直接执行二进制 | 可选 |\n| npx | 在线执行 | 可选 |\n\n## 快速开始\n\n### 通过 npx 运行\n\n使用 npx 可以直接运行最新版本的服务器，无需本地安装：\n\n```bash\nnpx -y @goldzulu/skill-loader-mcp-server\n```\n\n资料来源：[README.md:60-65]()\n\n### 独立安装运行\n\n```bash\n# 全局安装\nnpm install -g skill-loader-mcp-server\n\n# 直接运行\nskill-loader-mcp-server\n```\n\n资料来源：[README.md:70-75]()\n\n## Claude Desktop 集成\n\n### 配置文件位置\n\n根据操作系统不同，配置文件位于：\n\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **Linux**: `~/.config/Claude/claude_desktop_config.json`\n\n### 配置示例\n\n在 Claude Desktop 配置文件中添加以下内容：\n\n```json\n{\n \"mcpServers\": {\n \"skill-loader\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@goldzulu/skill-loader-mcp-server\"],\n \"env\": {\n \"SKILLS_SH_API_KEY\": \"your-api-key-here\"\n },\n \"description\": \"Skill Loader MCP Server for managing Claude skills\"\n }\n }\n}\n```\n\n资料来源：[README.md:35-50]()\n\n### 使用可执行文件路径\n\n如果已全局安装，也可以直接指定可执行文件路径：\n\n```json\n{\n \"mcpServers\": {\n \"skill-loader\": {\n \"command\": \"skill-loader-mcp-server\",\n \"env\": {\n \"SKILLS_SH_API_KEY\": \"your-api-key-here\"\n }\n }\n }\n}\n```\n\n## 环境变量配置\n\n### SKILLS_SH_API_KEY\n\n此环境变量用于访问 skills.sh 的高级 API 功能，包括分页列出所有技能和获取排行榜数据。\n\n| 配置状态 | 影响的功能 |\n|---------|-----------|\n| 未设置 | 可使用 search_skills、fetch_skill、validate_skill、convert_*、import_skill |\n| 已设置 | 额外解锁 list_skills、get_leaderboard 功能 |\n\n资料来源：[README.md:90-95]()\n\n### 配置方式\n\n环境变量可以通过配置文件中的 `env` 块设置，也可以在 shell 中预先导出：\n\n```bash\nexport SKILLS_SH_API_KEY=\"your-api-key-here\"\n```\n\n## MCP 工具列表\n\n服务器提供了 9 个 MCP 工具，按功能可分为以下几类：\n\n### 技能发现类\n\n| 工具名称 | 功能 | 认证要求 |\n|---------|------|---------|\n| search_skills | 按关键词搜索技能 | 不需要 |\n| list_skills | 分页列出所有技能 | 需要 API Key |\n| get_leaderboard | 获取热门/趋势技能 | 需要 API Key |\n\n资料来源：[README.md:85-120]()\n\n### 技能获取类\n\n| 工具名称 | 功能 | 认证要求 |\n|---------|------|---------|\n| fetch_skill | 从 GitHub 获取技能原始内容 | 不需要 |\n\n### 技能验证类\n\n| 工具名称 | 功能 | 认证要求 |\n|---------|------|---------|\n| validate_skill | 验证技能内容安全性 | 不需要 |\n\n### 格式转换类\n\n| 工具名称 | 功能 | 认证要求 |\n|---------|------|---------|\n| convert_to_steering | 转换为 Kiro 转向文件格式 | 不需要 |\n| convert_to_power | 转换为 Kiro Power 格式 | 不需要 |\n\n### 导入操作类\n\n| 工具名称 | 功能 | 认证要求 |\n|---------|------|---------|\n| import_skill | 完整导入工作流（获取+验证+转换） | 不需要 |\n\n## 安全验证机制\n\n命令行工具内置了安全验证功能，会在导入前自动扫描技能内容：\n\n### 检测的威胁类型\n\n| 威胁类型 | 示例 | 严重级别 |\n|---------|------|---------|\n| 危险命令 | `rm -rf`、`sudo`、`eval`、`exec` | 不安全 |\n| 可疑文件操作 | `/etc/`、`/usr/`、`/bin/` | 警告 |\n| 代码注入模式 | `${...}`、`$(...)` | 警告 |\n| 不信任来源 | 非 GitHub URL | 不安全 |\n\n资料来源：[README.md:175-185]()\n\n### 验证响应示例\n\n```json\n{\n \"isValid\": false,\n \"issues\": [\n {\n \"type\": \"dangerous_command\",\n \"description\": \"Dangerous recursive delete command (rm -rf)\",\n \"location\": \"Line 7: rm -rf /\"\n }\n ],\n \"severity\": \"unsafe\"\n}\n```\n\n## 典型工作流程\n\n### 流程一：搜索并导入技能\n\n```mermaid\ngraph TD\n A[search_skills 查询关键词] --> B{找到目标技能?}\n B -->|是| C[fetch_skill 获取内容]\n B -->|否| D[调整搜索条件]\n D --> A\n C --> E[validate_skill 安全验证]\n E --> F{验证通过?}\n F -->|是| G[convert_to_steering 或 convert_to_power]\n F -->|否| H[输出安全警告]\n G --> I[技能已转换]\n H --> J[中止导入]\n```\n\n### 流程二：使用 list_skills（需 API Key）\n\n```mermaid\ngraph TD\n A[list_skills 分页获取] --> B{还有更多页面?}\n B -->|是| C[请求下一页]\n C --> A\n B -->|否| D[get_leaderboard 获取趋势]\n D --> E[fetch_skill 获取技能]\n E --> F[import_skill 完整导入]\n```\n\n## 完整导入示例\n\n### 导入为 Steering 文件\n\n```json\n{\n \"tool\": \"import_skill\",\n \"arguments\": {\n \"identifier\": \"anthropics/pdf-extractor\",\n \"outputFormat\": \"steering\",\n \"skipValidation\": false\n }\n}\n```\n\n响应示例：\n\n```json\n{\n \"success\": true,\n \"content\": \"---\\noriginal_skill: PDF Extractor\\n...\",\n \"filename\": \"pdf-extractor.md\",\n \"targetPath\": \".kiro/steering/pdf-extractor.md\",\n \"metadata\": {\n \"skillName\": \"PDF Extractor\",\n \"validationResult\": {\n \"isValid\": true,\n \"issues\": [],\n \"severity\": \"safe\"\n }\n }\n}\n```\n\n### 导入为 Power\n\n```json\n{\n \"tool\": \"import_skill\",\n \"arguments\": {\n \"identifier\": \"anthropics/pdf-extractor\",\n \"outputFormat\": \"power\",\n \"skipValidation\": false\n }\n}\n```\n\n## 缓存机制\n\n服务器内置了智能缓存功能：\n\n| 缓存对象 | TTL | 说明 |\n|---------|-----|------|\n| skills.sh 搜索结果 | 1 小时 | 自动刷新过期缓存 |\n\n资料来源：[README.md:195-200]()\n\n## 错误处理\n\n所有工具返回的错误遵循统一格式：\n\n```json\n{\n \"error\": \"Error message describing what went wrong\",\n \"tool\": \"tool_name\",\n \"timestamp\": \"2024-01-15T10:30:00.000Z\"\n}\n```\n\n### 常见错误场景\n\n| 错误类型 | 原因 | 解决方案 |\n|---------|------|---------|\n| 网络错误 | 互联网连接问题 | 检查网络和 GitHub 可用性 |\n| 未找到错误 | 技能名称或仓库错误 | 验证技能标识符 |\n| 验证错误 | 安全问题 | 导入前审查安全问题 |\n| 解析错误 | 格式问题 | 检查技能格式和 YAML 语法 |\n\n## 传输协议\n\n服务器支持 **stdio 传输协议**，这是 Claude Desktop 和 Kiro 集成的标准方式。stdio 传输通过标准输入输出流进行进程间通信，确保了与 Claude Desktop 的无缝集成。\n\n资料来源：[CONTRIBUTING.md:25-30]()\n\n## 开发调试\n\n### 本地运行测试服务器\n\n项目中提供了 `test-server.js` 用于本地调试和测试。开发者可以使用该脚本启动一个本地测试环境，验证工具行为是否符合预期。\n\n### 本地开发模式\n\n```bash\n# 安装依赖\nnpm install\n\n# 构建项目\nnpm run build\n\n# 运行测试\nnpm test\n\n# 启动服务器\nnpm start\n```\n\n资料来源：[CONTRIBUTING.md:10-15]()\n\n## 输出格式\n\n### Steering 格式输出\n\n当 `outputFormat` 为 `steering` 时，输出包含以下字段：\n\n| 字段 | 类型 | 说明 |\n|-----|------|------|\n| steeringContent | string | 转向文件完整内容 |\n| filename | string | 建议的文件名（kebab-case） |\n| metadata | object | 元数据对象 |\n| metadata.originalSkill | string | 原始技能名称 |\n| metadata.sourceUrl | string | 来源 URL |\n| metadata.importedAt | string | ISO 时间戳 |\n\n### Power 格式输出\n\n当 `outputFormat` 为 `power` 时，输出包含多个文件：\n\n| 文件路径 | 内容说明 |\n|---------|---------|\n| POWER.md | Power 主文件，包含导入元数据 |\n| mcp.json | 可选，技能有依赖或工具引用时生成 |\n| steering/ | 可选目录，技能有 3+ 复杂章节时生成 |\n\n## 相关文档\n\n- [使用示例](./examples/usage-examples.md) - 各工具的详细使用案例\n- [安全验证](./src/core/security-validator.ts) - 安全机制实现细节\n- [错误处理](./src/core/errors.ts) - 错误类定义和使用\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：goldzulu/skill-loader-mcp-server\n\n摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。\n\n## 1. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | host_targets=mcp_host, claude\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | no_demo; severity=medium\n\n## 6. 安全/权限坑 · 来源证据：v1.0.0 - Initial Release\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.0.0 - Initial Release\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fb2ea148b03e4fb5993d3b2db08b43f6 | https://github.com/goldzulu/skill-loader-mcp-server/releases/tag/v1.0.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 7. 安全/权限坑 · 来源证据：v1.1.0 — skills.sh API migration & Power format update\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.1.0 — skills.sh API migration & Power format update\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_78c48e3f6caa41a9bf94d3dba01baf0c | https://github.com/goldzulu/skill-loader-mcp-server/releases/tag/v1.1.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | issue_or_pr_quality=unknown\n\n## 9. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | release_recency=unknown\n\n\n",
"markdown_key": "skill-loader-mcp-server",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:1148400928",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/goldzulu/skill-loader-mcp-server"
},
{
"evidence_id": "art_84579c1aee8240cf8477e86f921f4b6d",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/goldzulu/skill-loader-mcp-server#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "skill-loader-mcp-server 说明书",
"toc": [
"https://github.com/goldzulu/skill-loader-mcp-server 项目说明书",
"目录",
"项目介绍",
"概述",
"核心功能",
"架构设计",
"MCP 工具接口",
"配置与部署",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "efded0721ae89378658494eaba3e2705bfd462e2",
"repo_inspection_error": null,
"repo_inspection_files": [
"package.json",
"README.md",
"examples/mcp-config.json",
"examples/usage-examples.md",
"src/index.ts",
"src/cli.ts",
"src/tools/convert-to-steering.ts",
"src/tools/search-skills.ts",
"src/tools/import-skill.ts",
"src/tools/get-leaderboard.ts",
"src/tools/list-skills.ts",
"src/tools/fetch-skill.ts",
"src/tools/convert-to-power.ts",
"src/tools/validate-skill.ts",
"src/utils/cache.test.ts",
"src/utils/cache.ts",
"src/core/conversion-engine.test.ts",
"src/core/skill-fetcher.ts",
"src/core/skill-resolver.ts",
"src/core/skill-resolver.test.ts",
"src/core/errors.ts",
"src/core/security-validator.test.ts",
"src/core/types.ts",
"src/core/security-validator.ts",
"src/core/conversion-engine.ts"
],
"repo_inspection_verified": true,
"review_reasons": [
"community_discussion_evidence_below_public_threshold"
],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# @goldzulu/skill-loader-mcp-server - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 @goldzulu/skill-loader-mcp-server 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `npm install -g @goldzulu/skill-loader-mcp-server` 证据：`README.md` Claim：`clm_0003` supported 0.86\n- `npm install @goldzulu/skill-loader-mcp-server` 证据：`README.md` Claim：`clm_0004` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、本地环境或项目文件、环境变量 / API Key\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`CHANGELOG.md`, `README.md`, `src/core/skill-resolver.test.ts`, `src/core/skill-resolver.ts` 等\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0005` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0006` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：40\n- 重要文件覆盖：21/40\n- 证据索引条目：21\n- 角色 / Skill 条目：10\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 @goldzulu/skill-loader-mcp-server 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 @goldzulu/skill-loader-mcp-server 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 @goldzulu/skill-loader-mcp-server 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 10 个角色 / Skill / 项目文档条目。\n\n- **Skill Loader MCP Server**（project_doc）：! npm version https://img.shields.io/npm/v/%40goldzulu/skill-loader-mcp-server https://www.npmjs.com/package/@goldzulu/skill-loader-mcp-server ! License: MIT https://img.shields.io/badge/License-MIT-yellow.svg https://opensource.org/licenses/MIT ! Node.js Version https://img.shields.io/node/v/@goldzulu/skill-loader-mcp-server.svg https://nodejs.org 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Contributing to Skill Loader MCP Server**（project_doc）：Contributing to Skill Loader MCP Server 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`\n- **Pull Request**（project_doc）：Please include a summary of the changes and which issue is fixed. Include relevant motivation and context. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/pull_request_template.md`\n- **Changelog**（project_doc）：All notable changes to the Skill Loader MCP Server will be documented in this file. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CHANGELOG.md`\n- **Contributor Covenant Code of Conduct**（project_doc）：Contributor Covenant Code of Conduct 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CODE_OF_CONDUCT.md`\n- **Release v1.0.0 - Initial Release**（project_doc）：This is the initial release of the Skill Loader MCP Server - an npm package that implements the Model Context Protocol MCP for discovering, fetching, validating, and converting Claude skills from skills.sh. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`RELEASE_NOTES_v1.0.0.md`\n- **Skill Loader MCP Server - Usage Examples**（project_doc）：Skill Loader MCP Server - Usage Examples 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/usage-examples.md`\n- **Bug Report**（project_doc）：A clear and concise description of what the bug is. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/ISSUE_TEMPLATE/bug_report.md`\n- **Feature Request**（project_doc）：A clear and concise description of the feature you'd like to see. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/ISSUE_TEMPLATE/feature_request.md`\n- **Question**（project_doc）：Ask your question here. Be as specific as possible. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/ISSUE_TEMPLATE/question.md`\n\n## 证据索引\n\n- 共索引 21 条证据。\n\n- **Skill Loader MCP Server**（documentation）：! npm version https://img.shields.io/npm/v/%40goldzulu/skill-loader-mcp-server https://www.npmjs.com/package/@goldzulu/skill-loader-mcp-server ! License: MIT https://img.shields.io/badge/License-MIT-yellow.svg https://opensource.org/licenses/MIT ! Node.js Version https://img.shields.io/node/v/@goldzulu/skill-loader-mcp-server.svg https://nodejs.org 证据：`README.md`\n- **Package**（package_manifest）：{ \"name\": \"@goldzulu/skill-loader-mcp-server\", \"version\": \"1.1.1\", \"description\": \"MCP server for discovering and converting Claude skills\", \"main\": \"dist/index.js\", \"types\": \"dist/index.d.ts\", \"type\": \"module\", \"bin\": { \"skill-loader-mcp-server\": \"dist/cli.js\" }, \"scripts\": { \"build\": \"tsc\", \"start\": \"node dist/cli.js\", \"test\": \"jest\", \"test:watch\": \"jest --watch\", \"prepublishOnly\": \"npm run build\" }, \"keywords\": \"mcp\", \"mcp-server\", \"claude\", \"skills\", \"agent-skills\", \"kiro\" , \"author\": \"goldzulu\", \"license\": \"MIT\", \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/goldzulu/skill-loader-mcp-server.git\" }, \"homepage\": \"https://github.com/goldzulu/skill-loader-mcp-server readme\", \"b… 证据：`package.json`\n- **Contributing to Skill Loader MCP Server**（documentation）：Contributing to Skill Loader MCP Server 证据：`CONTRIBUTING.md`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`LICENSE`\n- **Pull Request**（documentation）：Please include a summary of the changes and which issue is fixed. Include relevant motivation and context. 证据：`.github/pull_request_template.md`\n- **Changelog**（documentation）：All notable changes to the Skill Loader MCP Server will be documented in this file. 证据：`CHANGELOG.md`\n- **Contributor Covenant Code of Conduct**（documentation）：Contributor Covenant Code of Conduct 证据：`CODE_OF_CONDUCT.md`\n- **Release v1.0.0 - Initial Release**（documentation）：This is the initial release of the Skill Loader MCP Server - an npm package that implements the Model Context Protocol MCP for discovering, fetching, validating, and converting Claude skills from skills.sh. 证据：`RELEASE_NOTES_v1.0.0.md`\n- **Skill Loader MCP Server - Usage Examples**（documentation）：Skill Loader MCP Server - Usage Examples 证据：`examples/usage-examples.md`\n- **Bug Description**（documentation）：A clear and concise description of what the bug is. 证据：`.github/ISSUE_TEMPLATE/bug_report.md`\n- **Feature Description**（documentation）：A clear and concise description of the feature you'd like to see. 证据：`.github/ISSUE_TEMPLATE/feature_request.md`\n- **Question**（documentation）：Ask your question here. Be as specific as possible. 证据：`.github/ISSUE_TEMPLATE/question.md`\n- **Mcp Config**（structured_config）：{ \"mcpServers\": { \"skill-loader\": { \"command\": \"npx\", \"args\": \"-y\", \"@kiro/skill-loader-mcp-server\" , \"description\": \"Skill Loader MCP Server for managing Claude skills\" } } } 证据：`examples/mcp-config.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2022\", \"module\": \"ES2022\", \"lib\": \"ES2022\" , \"moduleResolution\": \"node\", \"outDir\": \"./dist\", \"rootDir\": \"./src\", \"declaration\": true, \"declarationMap\": true, \"sourceMap\": true, \"strict\": true, \"esModuleInterop\": true, \"skipLibCheck\": true, \"forceConsistentCasingInFileNames\": true, \"resolveJsonModule\": true, \"allowSyntheticDefaultImports\": true }, \"include\": \"src/ / \" , \"exclude\": \"node modules\", \"dist\", \" / .test.ts\" } 证据：`tsconfig.json`\n- **Dependencies**（source_file）：Dependencies node modules/ package-lock.json 证据：`.gitignore`\n- **.npmignore**（source_file）：src/ tests/ .test.ts .test.js tsconfig.json jest.config.js .git .gitignore node modules/ coverage/ .DS Store 证据：`.npmignore`\n- **Jest.Config**（source_file）：export default { preset: 'ts-jest/presets/default-esm', testEnvironment: 'node', extensionsToTreatAsEsm: '.ts' , moduleNameMapper: { '^ \\\\.{1,2}/. \\\\.js$': '$1', }, transform: { '^.+\\\\.tsx?$': 'ts-jest', { useESM: true, }, , }, collectCoverageFrom: 'src/ / .ts', '!src/ / .test.ts', '!src/ / .d.ts', , coverageThreshold: { global: { branches: 30, functions: 30, lines: 30, statements: 30, }, }, }; 证据：`jest.config.js`\n- **!/usr/bin/env node**（source_file）：!/usr/bin/env node / CLI Entry Point for Skill Loader MCP Server Starts the MCP server with stdio transport / 证据：`src/cli.ts`\n- **Index**（source_file）：/ Skill Loader MCP Server Main server class implementing the Model Context Protocol / 证据：`src/index.ts`\n- **!/usr/bin/env node**（source_file）：!/usr/bin/env node / Simple test script to verify the MCP server works This script tests the server by simulating MCP protocol messages / 证据：`test-server.js`\n- **!/bin/bash**（source_file）：!/bin/bash Final validation script for Skill Loader MCP Server 证据：`validate.sh`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `package.json`, `CONTRIBUTING.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `package.json`, `CONTRIBUTING.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目介绍**：importance `high`\n - source_paths: README.md, package.json, src/index.ts\n- **MCP工具详解**：importance `high`\n - source_paths: src/tools/list-skills.ts, src/tools/search-skills.ts, src/tools/get-leaderboard.ts, src/tools/fetch-skill.ts, src/tools/validate-skill.ts\n- **核心模块架构**：importance `high`\n - source_paths: src/index.ts, src/cli.ts, src/core/types.ts\n- **类型定义系统**：importance `medium`\n - source_paths: src/core/types.ts, src/core/errors.ts\n- **技能解析器**：importance `high`\n - source_paths: src/core/skill-resolver.ts, src/core/skill-resolver.test.ts\n- **技能获取器**：importance `high`\n - source_paths: src/core/skill-fetcher.ts, src/tools/fetch-skill.ts\n- **转换引擎**：importance `high`\n - source_paths: src/core/conversion-engine.ts, src/core/conversion-engine.test.ts, src/tools/convert-to-steering.ts, src/tools/convert-to-power.ts\n- **安全验证器**：importance `high`\n - source_paths: src/core/security-validator.ts, src/core/security-validator.test.ts, src/tools/validate-skill.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `efded0721ae89378658494eaba3e2705bfd462e2`\n- inspected_files: `package.json`, `README.md`, `examples/mcp-config.json`, `examples/usage-examples.md`, `src/index.ts`, `src/cli.ts`, `src/tools/convert-to-steering.ts`, `src/tools/search-skills.ts`, `src/tools/import-skill.ts`, `src/tools/get-leaderboard.ts`, `src/tools/list-skills.ts`, `src/tools/fetch-skill.ts`, `src/tools/convert-to-power.ts`, `src/tools/validate-skill.ts`, `src/utils/cache.test.ts`, `src/utils/cache.ts`, `src/core/conversion-engine.test.ts`, `src/core/skill-fetcher.ts`, `src/core/skill-resolver.ts`, `src/core/skill-resolver.test.ts`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 可能修改宿主 AI 配置\n\n- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Evidence: capability.host_targets | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | host_targets=mcp_host, claude\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：v1.0.0 - Initial Release\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.0.0 - Initial Release\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_fb2ea148b03e4fb5993d3b2db08b43f6 | https://github.com/goldzulu/skill-loader-mcp-server/releases/tag/v1.0.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：v1.1.0 — skills.sh API migration & Power format update\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.1.0 — skills.sh API migration & Power format update\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_78c48e3f6caa41a9bf94d3dba01baf0c | https://github.com/goldzulu/skill-loader-mcp-server/releases/tag/v1.1.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | release_recency=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：goldzulu/skill-loader-mcp-server\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host, claude\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- review_required: community_discussion_evidence_below_public_threshold\n\n## 项目专属踩坑\n\n- 可能修改宿主 AI 配置（medium）：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n- 存在评分风险（medium）：风险会影响是否适合普通用户安装。 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/goldzulu/skill-loader-mcp-server 项目说明书\n\n生成时间：2026-05-13 18:01:33 UTC\n\n## 目录\n\n- [项目介绍](#page-project-intro)\n- [MCP工具详解](#page-mcp-tools)\n- [核心模块架构](#page-core-modules)\n- [类型定义系统](#page-type-system)\n- [技能解析器](#page-skill-resolver)\n- [技能获取器](#page-skill-fetcher)\n- [转换引擎](#page-conversion-engine)\n- [安全验证器](#page-security-validator)\n- [缓存机制](#page-caching)\n- [命令行工具](#page-cli-usage)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[MCP工具详解](#page-mcp-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n- [examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n- [src/core/conversion-engine.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)\n- [src/core/security-validator.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)\n- [src/core/errors.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts)\n- [CHANGELOG.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CHANGELOG.md)\n- [CONTRIBUTING.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CONTRIBUTING.md)\n \n\n# 项目介绍\n\n## 概述\n\nSkill Loader MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器项目，用于管理 Claude Skills 的导入、转换和验证工作流。该项目由 GoldZulu 开发维护，提供了与 skills.sh 市场平台集成的完整工具链，使用户能够安全地发现、获取和导入 Claude 技能。资料来源：[README.md:1]()\n\n## 核心功能\n\n### 技能发现与管理\n\n该项目支持从 skills.sh 平台发现和管理 Claude Skills，提供以下核心能力：\n\n- **技能搜索**：通过关键词搜索 skills.sh 目录，无需 API 密钥即可使用\n- **技能列表**：分页浏览所有可用技能，需要 API 密钥\n- **排行榜**：获取热门或安装量最高的技能，支持 24 小时和全部时间维度\n\n资料来源：[README.md:35-50]()\n\n### 安全验证\n\n内置多层安全验证机制，确保导入的技能不会危害系统安全：\n\n- **危险命令检测**：识别 `rm -rf`、`sudo`、`eval`、`exec` 等高风险命令\n- **可疑文件操作检测**：检测访问 `/etc/`、`/usr/`、`/bin/` 等系统目录的操作\n- **代码注入防护**：识别 `${...}` 和 `$(...)` 等代码注入模式\n- **来源验证**：仅允许来自 GitHub 的可信来源\n\n资料来源：[src/core/security-validator.ts:1-50]()\n\n### 格式转换\n\n支持将 Claude Skills 转换为 Kiro 平台支持的两种格式：\n\n| 格式类型 | 描述 | 输出文件 |\n|---------|------|---------|\n| Steering | Kiro 转向文件格式 | `.kiro/steering/{skill-name}.md` |\n| Power | Kiro Power 格式 | `POWER.md` + 可选的 `mcp.json` 和 `steering/` 目录 |\n\n当技能包含依赖或工具引用时，转换引擎会自动生成 `mcp.json` 配置文件。当技能包含 3 个以上复杂章节时，会生成 `steering/` 目录结构。资料来源：[README.md:60-75]()\n\n## 架构设计\n\n### 模块结构\n\n```\nskill-loader-mcp-server/\n├── src/\n│ ├── core/ # 核心功能模块\n│ │ ├── conversion-engine.ts # 技能格式转换引擎\n│ │ ├── security-validator.ts # 安全验证器\n│ │ └── errors.ts # 错误处理\n│ ├── tools/ # MCP 工具实现\n│ ├── utils/ # 工具函数\n│ ├── index.ts # 主入口点\n│ └── cli.ts # CLI 入口点\n├── examples/ # 使用示例\n├── dist/ # 编译输出\n└── tests/ # 测试文件\n```\n\n资料来源：[CONTRIBUTING.md:10-25]()\n\n### 核心组件\n\n#### 转换引擎 (Conversion Engine)\n\n转换引擎负责将 Claude Skills 解析并转换为目标格式，主要功能包括：\n\n- **解析技能**：提取 YAML frontmatter 和 Markdown 正文内容\n- **生成 Steering 文件**：转换为 Kiro 转向文件格式\n- **生成 Power 文件**：转换为 Kiro Power 格式，包含元数据和导入信息\n- **kebab-case 命名**：自动将技能名称转换为标准的 kebab-case 格式\n\n资料来源：[src/core/conversion-engine.ts:1-100]()\n\n#### 安全验证器 (Security Validator)\n\n安全验证器扫描技能内容中的潜在安全风险：\n\n- **问题类型分类**：区分 `dangerous_command`、`suspicious_pattern`、`untrusted_source`、`code_injection` 四类问题\n- **严重级别判定**：根据问题类型返回 `safe`、`warning`、`unsafe` 三级判定\n- **行号定位**：精确定位问题所在的代码行\n\n资料来源：[src/core/security-validator.ts:100-150]()\n\n#### 错误处理系统\n\n统一的错误处理系统包含多种专用错误类型：\n\n| 错误类型 | 用途 | Requirement ID |\n|---------|------|----------------|\n| `SkillLoaderError` | 基类错误 | 8.1 |\n| `NetworkError` | 网络请求失败 | 8.2 |\n| `ValidationError` | 技能验证失败 | 8.3 |\n| `FileSystemError` | 文件系统操作失败 | 8.4 |\n\n资料来源：[src/core/errors.ts:1-80]()\n\n## MCP 工具接口\n\n### 可用工具列表\n\n| 工具名称 | 功能描述 | 认证要求 |\n|---------|---------|---------|\n| `search_skills` | 按关键词搜索技能 | 无需认证 |\n| `list_skills` | 分页列出所有技能 | 需要 API Key |\n| `get_leaderboard` | 获取热门技能排行 | 需要 API Key |\n| `fetch_skill` | 从 GitHub 获取技能内容 | 无需认证 |\n| `validate_skill` | 验证技能安全性 | 无需认证 |\n| `convert_to_steering` | 转换为 Steering 格式 | 无需认证 |\n| `convert_to_power` | 转换为 Power 格式 | 无需认证 |\n| `import_skill` | 完整导入工作流 | 无需认证 |\n\n资料来源：[README.md:50-85]()\n\n### 完整导入工作流\n\n```mermaid\ngraph TD\n A[import_skill 调用] --> B[fetch_skill 获取技能]\n B --> C{跳过验证?}\n C -->|否| D[validate_skill 安全验证]\n C -->|是| E[convert_to_steering/power 格式转换]\n D --> F{验证通过?}\n F -->|否| G[返回错误,阻止导入]\n F -->|是| E\n E --> H[返回转换结果]\n```\n\n资料来源：[examples/usage-examples.md:1-50]()\n\n## 配置与部署\n\n### 环境变量\n\n| 变量名 | 必填 | 描述 |\n|-------|------|------|\n| `SKILLS_SH_API_KEY` | 仅 list_skills 和 get_leaderboard | skills.sh API 密钥 |\n\n资料来源：[README.md:25-30]()\n\n### 部署方式\n\n#### Kiro 平台\n\n```json\n{\n \"mcpServers\": {\n \"skill-loader\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@goldzulu/skill-loader-mcp-server\"],\n \"env\": {\n \"SKILLS_SH_API_KEY\": \"your-api-key-here\"\n }\n }\n }\n}\n```\n\n#### Claude Desktop\n\n```json\n{\n \"mcpServers\": {\n \"skill-loader\": {\n \"command\": \"skill-loader-mcp-server\",\n \"env\": {\n \"SKILLS_SH_API_KEY\": \"your-api-key-here\"\n }\n }\n }\n}\n```\n\n#### 独立运行\n\n```bash\nskill-loader-mcp-server\n```\n\n资料来源：[README.md:100-125]()\n\n## 技术特性\n\n### 缓存机制\n\n服务器内置内存缓存，用于存储 skills.sh 搜索结果：\n\n- **缓存时长**：1 小时 TTL\n- **自动刷新**：过期后自动重新获取\n- **适用场景**：仅 `list_skills` 和 `get_leaderboard` 调用\n\n资料来源：[README.md:130-135]()\n\n### 重试机制\n\n网络请求采用指数退避策略进行重试，提高系统可靠性：\n\n- **适用场景**：所有外部 API 调用\n- **策略**：指数增长的重试间隔\n\n资料来源：[CHANGELOG.md:20-25]()\n\n### 依赖更新\n\n项目已更新至 `@modelcontextprotocol/sdk` v1.29，确保与最新 MCP 协议兼容。资料来源：[README.md:1-5]()\n\n## 错误处理\n\n所有工具返回统一格式的错误信息：\n\n```json\n{\n \"error\": \"错误描述\",\n \"tool\": \"工具名称\",\n \"timestamp\": \"ISO 时间戳\"\n}\n```\n\n常见错误场景：\n\n| 错误类型 | 可能原因 | 解决方案 |\n|---------|---------|---------|\n| 网络错误 | 网络连接问题 | 检查互联网连接和 GitHub 可用性 |\n| 资源未找到 | 技能名称错误 | 验证技能名称和仓库地址 |\n| 验证错误 | 安全问题 | 导入前审查安全问题 |\n| 解析错误 | 格式问题 | 检查技能格式和 YAML 语法 |\n\n资料来源：[examples/usage-examples.md:100-120]()\n\n## 贡献指南\n\n项目欢迎各类贡献：\n\n- **Bug 修复**：修复现有代码问题\n- **新功能**：添加新的 MCP 工具\n- **文档**：改进 README 或代码注释\n- **测试**：提高测试覆盖率\n- **性能优化**：优化现有代码\n- **重构**：提升代码质量\n\n代码规范要求使用 TypeScript，遵循现有代码风格，避免使用 `any` 类型。资料来源：[CONTRIBUTING.md:30-55]()\n\n## 版本历史\n\n### v1.1.0 (当前版本)\n\n- Skills.sh 集成不再依赖脆弱的 HTML 解析\n- 新增 `SkillsShV1Response` 和 `SkillsShV1Entry` 类型\n- 支持 `id`、`skillId`、`source` 字段\n- 新增 `listSkills()` 方法支持认证分页列表\n- Power 转换支持 `mcp.json` 和 `steering/` 目录生成\n\n### v1.0.0 (初始版本)\n\n- 发布 9 个 MCP 工具\n- 实现安全验证功能\n- 内置内存缓存和重试逻辑\n- 支持 stdio 传输\n- 兼容 Kiro 和 Claude Desktop\n\n资料来源：[CHANGELOG.md:1-35]()\n\n---\n\n\n\n## MCP工具详解\n\n### 相关页面\n\n相关主题：[项目介绍](#page-project-intro), [技能获取器](#page-skill-fetcher), [转换引擎](#page-conversion-engine)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/list-skills.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/list-skills.ts)\n- [src/tools/search-skills.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/search-skills.ts)\n- [src/tools/get-leaderboard.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/get-leaderboard.ts)\n- [src/tools/fetch-skill.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/fetch-skill.ts)\n- [src/tools/validate-skill.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/validate-skill.ts)\n- [src/tools/convert-to-steering.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/convert-to-steering.ts)\n- [src/tools/convert-to-power.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/convert-to-power.ts)\n- [src/tools/import-skill.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/import-skill.ts)\n \n\n# MCP工具详解\n\n## 概述\n\nSkill Loader MCP Server 提供了一套完整的MCP（Model Context Protocol）工具集，用于管理Claude Skills的生命周期。该工具集涵盖从技能发现、获取、验证、格式转换到完整导入的完整工作流程。资料来源：[README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n\n系统共包含8个MCP工具，按功能可分为三大类别：\n\n| 类别 | 工具 | 核心功能 |\n|------|------|----------|\n| **发现工具** | `list_skills` | 分页列出技能市场所有技能 |\n| | `search_skills` | 关键词搜索技能 |\n| | `get_leaderboard` | 获取热门/趋势技能榜单 |\n| **获取与验证工具** | `fetch_skill` | 从GitHub获取原始技能内容 |\n| | `validate_skill` | 安全扫描与格式验证 |\n| **转换与导入工具** | `convert_to_steering` | 转换为Kiro Steering格式 |\n| | `convert_to_power` | 转换为Kiro Power格式 |\n| | `import_skill` | 端到端导入工作流 |\n\n资料来源：[README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n\n---\n\n## 架构概览\n\n### 工具调用流程\n\n```mermaid\ngraph TD\n A[用户请求] --> B{选择工具类型}\n \n B -->|发现类| C[list_skills
search_skills
get_leaderboard]\n B -->|获取类| D[fetch_skill]\n B -->|验证类| E[validate_skill]\n B -->|转换类| F[convert_to_steering
convert_to_power]\n B -->|导入类| G[import_skill]\n \n C --> H[skills.sh API]\n D --> I[GitHub Raw]\n E --> J[安全验证器]\n F --> K[转换引擎]\n G --> L[完整工作流]\n \n L --> D\n L --> E\n L --> F\n \n H --> M[返回结果]\n I --> M\n J --> M\n K --> M\n```\n\n### 核心模块依赖关系\n\n```mermaid\ngraph LR\n A[tools/*.ts] --> B[core/skill-resolver.ts]\n A --> C[core/conversion-engine.ts]\n A --> D[core/security-validator.ts]\n A --> E[core/errors.ts]\n \n B --> F[skills.sh API]\n C --> E\n D --> E\n```\n\n---\n\n## 发现类工具\n\n### 1. list_skills\n\n分页列出skills.sh技能市场中的所有可用技能。资料来源：[examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n\n**参数说明：**\n\n| 参数 | 类型 | 必需 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `page` | number | 否 | 1 | 页码，从1开始 |\n| `pageSize` | number | 否 | 50 | 每页数量，最大100 |\n\n**返回值结构：**\n\n```json\n{\n \"skills\": [\n {\n \"name\": \"pdf-extractor\",\n \"description\": \"Extract text from PDF files\",\n \"owner\": \"anthropics\",\n \"repo\": \"skills\",\n \"installs\": 30400\n }\n ],\n \"total\": 150,\n \"page\": 1,\n \"pageSize\": 10\n}\n```\n\n**环境要求：** 需要 `SKILLS_SH_API_KEY` 环境变量进行身份验证。资料来源：[README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n\n---\n\n### 2. search_skills\n\n通过关键词搜索skills.sh技能市场。该工具使用公开搜索API，无需API密钥。资料来源：[examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n\n**参数说明：**\n\n| 参数 | 类型 | 必需 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `query` | string | 是 | - | 搜索关键词 |\n| `limit` | number | 否 | 5 | 返回结果数量限制 |\n\n**返回值结构：**\n\n```json\n{\n \"skills\": [\n {\n \"name\": \"pdf-extractor\",\n \"description\": \"Extract text from PDF files\",\n \"owner\": \"anthropics\",\n \"repo\": \"skills\",\n \"installs\": 30400,\n \"relevance\": 5\n }\n ],\n \"query\": \"pdf\",\n \"count\": 5\n}\n```\n\n---\n\n### 3. get_leaderboard\n\n获取热门或趋势技能榜单，支持按时间范围筛选。资料来源：[examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n\n**参数说明：**\n\n| 参数 | 类型 | 必需 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `timeframe` | string | 否 | \"all\" | 时间范围：`\"all\"`或`\"24h\"` |\n| `limit` | number | 否 | 20 | 返回结果数量，最大50 |\n\n**返回值结构：**\n\n```json\n{\n \"skills\": [\n {\n \"name\": \"pdf-extractor\",\n \"description\": \"Extract text from PDF files\",\n \"owner\": \"anthropics\",\n \"repo\": \"skills\",\n \"installs\": 30400,\n \"rank\": 1,\n \"trending\": true\n }\n ],\n \"timeframe\": \"24h\",\n \"count\": 10\n}\n```\n\n**环境要求：** 需要 `SKILLS_SH_API_KEY` 环境变量。资料来源：[README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n\n---\n\n## 获取与验证工具\n\n### 4. fetch_skill\n\n从GitHub获取原始技能内容。支持多种标识符格式。资料来源：[examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n\n**参数说明：**\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `identifier` | string | 是 | 技能名称或`owner/repo`格式 |\n\n**支持的标识符格式：**\n\n| 格式 | 示例 | 说明 |\n|------|------|------|\n| 纯名称 | `pdf-extractor` | 从skills.sh目录解析 |\n| owner/repo | `anthropics/pdf-extractor` | 直接指定GitHub位置 |\n| 完整路径 | `owner/repo/skill-path` | 指定具体路径 |\n\n**返回值结构：**\n\n```json\n{\n \"content\": \"---\\nname: PDF Extractor\\ndescription: Extract text from PDF files\\n---\\n\\n# PDF Extractor\\n\\n...\",\n \"url\": \"https://raw.githubusercontent.com/anthropics/skills/main/skills/pdf-extractor/SKILL.md\",\n \"metadata\": {\n \"name\": \"pdf-extractor\",\n \"owner\": \"anthropics\",\n \"repo\": \"skills\",\n \"skillPath\": \"skills/pdf-extractor\",\n \"fetchedAt\": \"2024-01-15T10:30:00.000Z\"\n }\n}\n```\n\n---\n\n### 5. validate_skill\n\n对技能内容进行安全扫描和格式验证，检测潜在的安全风险。资料来源：[src/core/security-validator.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)\n\n**参数说明：**\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `content` | string | 是 | 待验证的技能内容 |\n| `url` | string | 否 | 来源URL用于额外验证 |\n\n**安全检测类型：**\n\n| 类型 | 标识符 | 严重程度 | 说明 |\n|------|--------|----------|------|\n| 危险命令 | `dangerous_command` | unsafe | `rm -rf`、`sudo`、`eval`、`exec`等 |\n| 可疑文件操作 | `suspicious_file_operation` | unsafe | 访问`/etc/`、`/usr/`、`/bin/`等系统目录 |\n| 代码注入 | `code_injection` | unsafe | `${...}`、`$(...)`等注入模式 |\n| 不信任源 | `untrusted_source` | unsafe | 非GitHub来源的URL |\n\n**返回值结构：**\n\n```json\n{\n \"isValid\": false,\n \"issues\": [\n {\n \"type\": \"dangerous_command\",\n \"description\": \"Dangerous recursive delete command (rm -rf)\",\n \"location\": \"Line 7: rm -rf /\"\n }\n ],\n \"severity\": \"unsafe\"\n}\n```\n\n**安全等级判定逻辑：**\n\n```mermaid\ngraph TD\n A[检测到问题?] --> B{问题类型}\n B -->|untrusted_source| C[unsafe]\n B -->|dangerous_command| C\n B -->|其他| D[warning]\n A -->|无问题| E[safe]\n```\n\n资料来源：[src/core/security-validator.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)\n\n---\n\n## 转换与导入工具\n\n### 6. convert_to_steering\n\n将Claude Skill转换为Kiro Steering文件格式。资料来源：[examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n\n**参数说明：**\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `content` | string | 是 | 技能原始内容 |\n| `sourceUrl` | string | 否 | 原始来源URL |\n\n**转换特性：**\n\n- 提取技能名称并转换为kebab-case格式作为文件名\n- 保留技能描述和正文内容\n- 添加依赖列表（如有）\n- 在文件末尾附加导入元数据\n- 包含原始技能名称和来源信息\n\n**输出格式：**\n\n```yaml\n---\noriginal_skill: PDF Extractor\nsource_url: https://raw.githubusercontent.com/...\nimported_at: '2024-01-15T10:30:00.000Z'\n---\n\n# PDF Extractor\n\nExtract text from PDF files\n\n# PDF Extractor\n\nExtract text content from PDF documents...\n\n---\n*Imported from Claude Skills via Skill Loader Power*\n```\n\n**返回值结构：**\n\n```json\n{\n \"steeringContent\": \"...\",\n \"filename\": \"pdf-extractor.md\",\n \"metadata\": {\n \"originalSkill\": \"PDF Extractor\",\n \"sourceUrl\": \"https://...\",\n \"importedAt\": \"2024-01-15T10:30:00.000Z\"\n }\n}\n```\n\n---\n\n### 7. convert_to_power\n\n将Claude Skill转换为Kiro Power格式。这是更高级的转换选项，会生成额外的配置文件。资料来源：[examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n\n**参数说明：**\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `content` | string | 是 | 技能原始内容 |\n| `sourceUrl` | string | 否 | 原始来源URL |\n\n**生成的文件：**\n\n| 条件 | 生成文件 | 说明 |\n|------|----------|------|\n| 始终 | `POWER.md` | 主技能内容文件 |\n| 有依赖或工具引用 | `mcp.json` | MCP服务器配置 |\n| 3+复杂章节 | `steering/`目录 | 多章节内容目录 |\n\n**mcp.json生成逻辑：**\n\n当技能包含依赖或MCP工具引用时，系统自动生成`mcp.json`配置文件，用于定义MCP服务器连接。资料来源：[CHANGELOG.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CHANGELOG.md)\n\n**steering目录生成逻辑：**\n\n当技能包含3个或以上复杂章节（级别≥2，内容>200字符）时，系统会将这些章节提取到独立的`steering/`目录中。资料来源：[CHANGELOG.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CHANGELOG.md)\n\n---\n\n### 8. import_skill\n\n完整的端到端导入工作流，集成了获取、验证和转换三个步骤。资料来源：[examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n\n**参数说明：**\n\n| 参数 | 类型 | 必需 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `identifier` | string | 是 | - | 技能标识符 |\n| `outputFormat` | string | 是 | - | 输出格式：`\"steering\"`或`\"power\"` |\n| `skipValidation` | boolean | 否 | false | 是否跳过安全验证 |\n\n**工作流程：**\n\n```mermaid\ngraph TD\n A[import_skill调用] --> B[fetch_skill获取内容]\n B --> C{skipValidation?}\n C -->|否| D[validate_skill安全验证]\n C -->|是| E[跳过验证]\n D --> F{验证通过?}\n F -->|是| G[转换格式]\n F -->|否| H[返回错误]\n E --> G\n G --> I{outputFormat?}\n I -->|steering| J[convert_to_steering]\n I -->|power| K[convert_to_power]\n J --> L[返回结果]\n K --> L\n```\n\n**返回值结构：**\n\n```json\n{\n \"success\": true,\n \"content\": \"...\",\n \"filename\": \"pdf-extractor.md\",\n \"targetPath\": \".kiro/steering/pdf-extractor.md\",\n \"metadata\": {\n \"skillName\": \"PDF Extractor\",\n \"sourceUrl\": \"https://...\",\n \"outputFormat\": \"steering\",\n \"validationResult\": {\n \"isValid\": true,\n \"issues\": [],\n \"severity\": \"safe\"\n }\n }\n}\n```\n\n**错误处理：**\n\n当安全验证失败时，返回详细的错误信息：\n\n```json\n{\n \"success\": false,\n \"content\": \"...\",\n \"metadata\": {\n \"validationResult\": {\n \"isValid\": false,\n \"issues\": [\n {\n \"type\": \"dangerous_command\",\n \"description\": \"Dangerous recursive delete command (rm -rf)\",\n \"location\": \"Line 10: rm -rf /\"\n }\n ],\n \"severity\": \"unsafe\"\n }\n },\n \"error\": \"Security validation failed: Dangerous recursive delete command (rm -rf)\"\n}\n```\n\n---\n\n## 常用工作流\n\n### 发现并导入技能\n\n```mermaid\ngraph LR\n A[search_skills] --> B[fetch_skill]\n B --> C[validate_skill]\n C --> D{安全?}\n D -->|是| E[import_skill]\n D -->|否| F[放弃]\n```\n\n**具体步骤：**\n\n1. **搜索技能**\n ```json\n { \"tool\": \"search_skills\", \"arguments\": { \"query\": \"pdf\", \"limit\": 5 } }\n ```\n\n2. **获取技能详情**\n ```json\n { \"tool\": \"fetch_skill\", \"arguments\": { \"identifier\": \"anthropics/pdf-extractor\" } }\n ```\n\n3. **导入技能**\n ```json\n { \"tool\": \"import_skill\", \"arguments\": { \"identifier\": \"anthropics/pdf-extractor\", \"outputFormat\": \"steering\" } }\n ```\n\n### 浏览趋势技能并导入\n\n1. **获取24小时热门榜单**\n ```json\n { \"tool\": \"get_leaderboard\", \"arguments\": { \"timeframe\": \"24h\", \"limit\": 20 } }\n ```\n\n2. **导入热门技能**\n ```json\n { \"tool\": \"import_skill\", \"arguments\": { \"identifier\": \"owner/skill-name\", \"outputFormat\": \"power\" } }\n ```\n\n### 先验证后导入\n\n```mermaid\ngraph TD\n A[fetch_skill] --> B[validate_skill]\n B --> C{isValid?}\n C -->|true| D[convert_to_steering]\n C -->|false| E[审查issues]\n E --> F{可接受?}\n F -->|是| D\n F -->|否| G[使用其他技能]\n```\n\n---\n\n## 错误处理\n\n所有工具返回的错误遵循统一格式：资料来源：[src/core/errors.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts)\n\n```json\n{\n \"error\": \"Error message describing what went wrong\",\n \"tool\": \"tool_name\",\n \"timestamp\": \"2024-01-15T10:30:00.000Z\"\n}\n```\n\n**常见错误类型：**\n\n| 错误类型 | 触发场景 | 解决方案 |\n|----------|----------|----------|\n| 网络错误 | GitHub访问失败 | 检查网络连接 |\n| 未找到错误 | 技能名称错误 | 验证技能名称和仓库 |\n| 验证错误 | 安全扫描失败 | 审查安全问题后再操作 |\n| 解析错误 | 格式问题 | 检查YAML语法 |\n\n---\n\n## 缓存机制\n\nskills.sh搜索结果在内存中缓存1小时，以减少API调用并提高性能。缓存过期后自动刷新。资料来源：[README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n\n---\n\n## 安全特性\n\n系统提供多层次的安全保护：\n\n| 层级 | 机制 | 说明 |\n|------|------|------|\n| 验证层 | 危险命令检测 | 阻止`rm -rf`、`sudo`、`eval`等 |\n| 验证层 | 文件操作限制 | 禁止访问系统目录 |\n| 验证层 | 注入模式识别 | 检测代码注入尝试 |\n| 验证层 | 来源验证 | 仅允许GitHub来源 |\n| 验证层 | 跳过选项 | 可选的`skipValidation`参数 |\n\n资料来源：[README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n\n---\n\n\n\n## 核心模块架构\n\n### 相关页面\n\n相关主题：[类型定义系统](#page-type-system), [缓存机制](#page-caching)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/index.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/index.ts)\n- [src/cli.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/cli.ts)\n- [src/core/types.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/types.ts)\n- [src/core/conversion-engine.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)\n- [src/core/security-validator.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)\n- [src/core/errors.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts)\n \n\n# 核心模块架构\n\n本文档详细介绍 Skill Loader MCP Server 的核心模块架构，包括各模块的职责、数据流转、以及模块间的协作关系。\n\n## 1. 架构概述\n\nSkill Loader MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器应用，用于管理 Claude Skills 的导入、转换和验证。其核心架构采用分层设计，将功能职责分离到不同的模块中。\n\n```mermaid\ngraph TD\n A[入口层
index.ts / cli.ts] --> B[工具层
MCP Tools]\n B --> C[核心服务层
Core Services]\n C --> D[安全验证模块
Security Validator]\n C --> E[转换引擎
Conversion Engine]\n C --> F[错误处理模块
Error System]\n C --> G[类型系统
Type Definitions]\n \n H[外部服务
skills.sh API
GitHub API] --> B\n```\n\n**架构分层说明**：\n\n| 层级 | 组件 | 职责 |\n|------|------|------|\n| 入口层 | `index.ts`, `cli.ts` | 服务器初始化、传输协议配置 |\n| 工具层 | MCP Tools | 暴露给客户端的 API 接口 |\n| 核心服务层 | 核心模块 | 业务逻辑处理 |\n| 类型系统 | `types.ts` | 统一数据类型定义 |\n\n资料来源：[src/index.ts:1-50](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/index.ts)\n\n## 2. 入口层架构\n\n### 2.1 主入口 (index.ts)\n\n`index.ts` 是 MCP 服务器的主入口点，负责初始化和配置服务器。\n\n**核心职责**：\n- 创建 MCP 服务器实例\n- 注册所有工具处理器\n- 配置 stdio 传输协议\n- 处理服务器生命周期\n\n**代码结构**：\n\n```typescript\n// 服务器初始化伪代码\nconst server = new Server(\n {\n name: 'skill-loader',\n version: '1.1.0',\n },\n {\n capabilities: {\n tools: {},\n },\n }\n);\n\n// 注册工具\nserver.setRequestHandler(ListToolsRequestSchema, async () => ({\n tools: [/* 工具列表 */]\n}));\n\nserver.setRequestHandler(CallToolRequestSchema, async (request) => {\n // 路由到对应工具处理器\n});\n```\n\n资料来源：[src/index.ts:1-100](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/index.ts)\n\n### 2.2 CLI 入口 (cli.ts)\n\n`cli.ts` 提供命令行接口，支持独立运行服务器。\n\n**功能特性**：\n- 支持配置文件加载\n- 环境变量配置\n- 独立的进程启动\n\n资料来源：[src/cli.ts:1-50](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/cli.ts)\n\n## 3. 类型系统\n\n### 3.1 类型定义概述\n\n`types.ts` 定义了项目中使用的所有核心数据类型，确保类型安全和一致性。\n\n**主要类型分类**：\n\n| 类型分类 | 说明 |\n|----------|------|\n| 技能相关类型 | Skill、SkillFrontmatter、SkillSection |\n| API 响应类型 | SkillsShResponse、SkillShEntry、LeaderboardResponse |\n| 验证相关类型 | ValidationResult、ValidationIssue |\n| 转换相关类型 | ConversionResult、PowerFiles |\n| 错误类型 | SkillLoaderError 子类 |\n\n资料来源：[src/core/types.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/types.ts)\n\n### 3.2 技能数据结构\n\n**SkillFrontmatter** 定义技能的元数据：\n\n```typescript\ninterface SkillFrontmatter {\n name: string; // 技能名称\n description?: string; // 技能描述\n dependencies?: string[];// 依赖列表\n // ...其他元数据字段\n}\n```\n\n**SkillSection** 定义技能内容的结构化分段：\n\n```typescript\ninterface SkillSection {\n level: number; // 标题层级 (1-6)\n heading: string; // 标题文本\n content: string; // 段落内容\n}\n```\n\n资料来源：[src/core/types.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/types.ts)\n\n### 3.3 验证结果类型\n\n**ValidationResult** 定义安全验证的结果：\n\n```typescript\ninterface ValidationResult {\n isValid: boolean; // 是否通过验证\n issues: ValidationIssue[];// 发现的问题列表\n severity: 'safe' | 'warning' | 'unsafe'; // 严重程度\n}\n\ninterface ValidationIssue {\n type: 'dangerous_command' | 'suspicious_pattern' | 'untrusted_source';\n description: string; // 问题描述\n location?: string; // 问题位置\n}\n```\n\n资料来源：[src/core/security-validator.ts:50-80](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)\n\n## 4. 安全验证模块\n\n### 4.1 模块概述\n\n`security-validator.ts` 是系统的安全防线，负责扫描和检测技能内容中的潜在安全风险。\n\n```mermaid\ngraph LR\n A[技能内容] --> B[危险命令检测]\n A --> C[可疑模式检测]\n A --> D[来源验证]\n B --> E[评估结果]\n C --> E\n D --> E\n```\n\n**安全检测范围**：\n\n| 检测类型 | 描述 | 严重级别 |\n|----------|------|----------|\n| 危险命令 | `rm -rf`, `sudo`, `eval`, `exec` | unsafe |\n| 可疑文件操作 | `/etc/`, `/usr/`, `/bin/` 路径访问 | warning |\n| 代码注入 | `${...}`, `$(...)` 模式 | warning |\n| 不信任来源 | 非 GitHub URL | unsafe |\n\n资料来源：[src/core/security-validator.ts:1-100](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)\n\n### 4.2 验证流程\n\n**严重级别判定逻辑**：\n\n```typescript\nprivate determineSeverity(issues: Issue[]): 'safe' | 'warning' | 'unsafe' {\n if (issues.length === 0) {\n return 'safe';\n }\n\n // 如果存在不信任来源或危险命令，标记为不安全\n const hasUntrustedSource = issues.some(issue => issue.type === 'untrusted_source');\n const hasDangerousCommand = issues.some(issue => issue.type === 'dangerous_command');\n\n if (hasUntrustedSource || hasDangerousCommand) {\n return 'unsafe';\n }\n\n // 否则，可疑模式为警告级别\n return 'warning';\n}\n```\n\n资料来源：[src/core/security-validator.ts:200-220](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)\n\n## 5. 转换引擎模块\n\n### 5.1 模块概述\n\n`conversion-engine.ts` 是核心的业务逻辑模块，负责将 Claude Skills 转换为 Kiro 格式（Steering 文件或 Power）。\n\n**转换引擎能力**：\n\n| 功能 | 说明 |\n|------|------|\n| 格式转换 | SKILL.md → Steering 文件 / Power |\n| 依赖处理 | 生成 `mcp.json` 配置文件 |\n| 复杂内容拆分 | 生成 `steering/` 目录结构 |\n| 元数据保留 | 保留原始技能信息和导入来源 |\n\n资料来源：[src/core/conversion-engine.ts:1-150](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)\n\n### 5.2 转换为 Steering 文件\n\n**转换流程**：\n\n```mermaid\ngraph TD\n A[解析 SKILL.md] --> B[提取 frontmatter]\n B --> C[处理 body 内容]\n C --> D{是否有复杂章节?}\n D -->|是| E[生成 steering/ 目录]\n D -->|否| F[直接生成 .md 文件]\n E --> G[添加导入元数据]\n F --> G\n G --> H[输出 Steering 文件]\n```\n\n**Steering 文件结构示例**：\n\n```markdown\n---\noriginal_skill: PDF Extractor\nsource_url: https://github.com/...\nimported_at: 2024-01-15T10:30:00.000Z\n---\n\n# PDF Extractor\n\n[技能内容...]\n\n---\n*Imported from Claude Skills via Skill Loader Power*\n```\n\n资料来源：[src/core/conversion-engine.ts:80-120](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)\n\n### 5.3 转换为 Power 格式\n\n**Power 格式特点**：\n- 使用 `POWER.md` 作为主文件\n- 可选生成 `mcp.json`（当技能有依赖或工具引用时）\n- 可选生成 `steering/` 目录（当技能有 3+ 复杂章节时）\n\n**生成条件判断**：\n\n```typescript\n// 是否应生成 mcp.json\nprivate shouldGenerateMcpJson(skill: Skill): boolean {\n return (\n (skill.frontmatter.dependencies && skill.frontmatter.dependencies.length > 0) ||\n this.hasToolReferences(skill)\n );\n}\n\n// 是否应生成 steering/ 目录\nprivate shouldGenerateSteeringDir(skill: Skill): boolean {\n const complexSections = skill.sections.filter(\n s => s.level >= 2 && s.content.length > 200\n );\n return complexSections.length >= 3;\n}\n```\n\n资料来源：[src/core/conversion-engine.ts:180-200](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)\n\n### 5.4 关键字提取\n\n转换引擎包含关键字提取功能，用于技能分类和搜索优化：\n\n```typescript\nprivate extractKeywords(description: string): string[] {\n const stopWords = new Set([\n 'the', 'and', 'for', 'with', 'this', 'that', 'from', 'into',\n 'when', 'what', 'where', 'how', 'why', 'can', 'will', 'should'\n // ...更多停用词\n ]);\n \n // 提取 3+ 字符的非停用词，最多返回 5 个\n const words = description\n .toLowerCase()\n .replace(/[^a-z0-9\\s]/g, ' ')\n .split(/\\s+/)\n .filter(word => word.length >= 3 && !stopWords.has(word))\n .slice(0, 5);\n \n return words;\n}\n```\n\n资料来源：[src/core/conversion-engine.ts:150-175](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)\n\n## 6. 错误处理系统\n\n### 6.1 错误类层次结构\n\n`errors.ts` 定义了完整的错误类型体系：\n\n```mermaid\ngraph TD\n A[SkillLoaderError
基类]\n A --> B[ValidationError
验证错误]\n A --> C[FileSystemError
文件系统错误]\n A --> D[NetworkError
网络错误]\n A --> E[ParseError
解析错误]\n```\n\n**基类特性**：\n\n```typescript\nexport class SkillLoaderError extends Error {\n public readonly code: string;\n public readonly timestamp: Date;\n public readonly context: Record;\n \n constructor(message: string, context?: Record) {\n super(message);\n this.code = this.getDefaultCode();\n this.timestamp = new Date();\n this.context = context || {};\n }\n}\n```\n\n资料来源：[src/core/errors.ts:1-100](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts)\n\n### 6.2 验证错误 (ValidationError)\n\n专门处理技能验证失败的错误类型：\n\n```typescript\nexport class ValidationError extends SkillLoaderError {\n public readonly validationType: 'security' | 'format' | 'content';\n \n getUserMessage(): string {\n // 返回用户友好的错误信息和恢复建议\n }\n}\n```\n\n**错误消息包含**：\n- 错误描述\n- 验证类型\n- 具体的恢复建议\n\n资料来源：[src/core/errors.ts:50-80](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts)\n\n### 6.3 文件系统错误 (FileSystemError)\n\n处理文件读写操作相关的错误：\n\n```typescript\nexport class FileSystemError extends SkillLoaderError {\n public readonly operation: 'read' | 'write' | 'delete' | 'access';\n public readonly filePath: string;\n public readonly systemError?: string;\n \n getUserMessage(): string {\n // 根据错误码提供具体的修复建议\n }\n}\n```\n\n**系统错误处理**：\n\n| 错误码 | 建议 |\n|--------|------|\n| EACCES/EPERM | 检查文件权限 |\n| ENOSPC | 释放磁盘空间 |\n| ENOENT | 验证目录存在 |\n| EEXIST | 使用 --overwrite 标志 |\n\n资料来源：[src/core/errors.ts:100-150](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts)\n\n## 7. MCP 工具层\n\n### 7.1 工具列表\n\n系统提供 8 个 MCP 工具：\n\n| 工具名称 | 功能 | 认证要求 |\n|----------|------|----------|\n| `search_skills` | 关键词搜索技能 | 不需要 |\n| `list_skills` | 分页列出所有技能 | 需要 API Key |\n| `get_leaderboard` | 获取排行榜 | 需要 API Key |\n| `fetch_skill` | 获取技能内容 | 不需要 |\n| `validate_skill` | 安全验证 | 不需要 |\n| `convert_to_steering` | 转为 Steering 格式 | 不需要 |\n| `convert_to_power` | 转为 Power 格式 | 不需要 |\n| `import_skill` | 完整导入流程 | 不需要 |\n\n资料来源：[README.md:50-150](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n\n### 7.2 工具调用流程\n\n**import_skill 完整工作流**：\n\n```mermaid\ngraph TD\n A[import_skill 调用] --> B[fetch_skill
获取技能内容]\n B --> C{skipValidation?}\n C -->|否| D[validate_skill
安全验证]\n C -->|是| E[跳过验证]\n D --> F{验证通过?}\n F -->|否| G[返回错误]\n F -->|是| H[convert_to_power
格式转换]\n E --> H\n H --> I[返回转换结果]\n```\n\n资料来源：[examples/usage-examples.md:1-100](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n\n## 8. 数据流与状态管理\n\n### 8.1 技能数据流转\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Server as MCP Server\n participant Fetcher as 技能获取器\n participant Validator as 安全验证器\n participant Converter as 转换引擎\n participant GitHub as GitHub API\n \n Client->>Server: import_skill(identifier)\n Server->>Fetcher: fetchSkill(identifier)\n Fetcher->>GitHub: GET raw skill content\n GitHub-->>Fetcher: SKILL.md content\n Fetcher-->>Server: skill content\n \n Server->>Validator: validateSkill(content)\n Validator-->>Server: ValidationResult\n \n Server->>Converter: convertToPower(content)\n Converter-->>Server: ConversionResult\n \n Server-->>Client: import result\n```\n\n### 8.2 缓存策略\n\n系统使用内存缓存来优化 skills.sh API 调用：\n\n| 缓存项 | TTL | 说明 |\n|--------|-----|------|\n| 搜索结果 | 1 小时 | 减少 API 调用 |\n| 目录列表 | 1 小时 | 提升分页性能 |\n\n资料来源：[README.md:180-200](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n\n## 9. 配置与环境\n\n### 9.1 环境变量\n\n| 变量名 | 必需 | 说明 |\n|--------|------|------|\n| `SKILLS_SH_API_KEY` | 仅 list_skills/get_leaderboard | skills.sh API 密钥 |\n\n### 9.2 MCP 服务器配置\n\n```json\n{\n \"mcpServers\": {\n \"skill-loader\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@goldzulu/skill-loader-mcp-server\"],\n \"env\": {\n \"SKILLS_SH_API_KEY\": \"your-api-key-here\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:30-60](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n\n## 10. 模块依赖关系\n\n```mermaid\ngraph TD\n index_ts[index.ts] --> cli_ts[cli.ts]\n index_ts --> types_ts[types.ts]\n \n tools[Tools Layer] --> conversion_engine[conversion-engine.ts]\n tools --> security_validator[security-validator.ts]\n tools --> errors_ts[errors.ts]\n \n conversion_engine --> types_ts\n security_validator --> types_ts\n errors_ts --> types_ts\n \n conversion_engine --> errors_ts\n security_validator --> errors_ts\n \n subgraph core[核心模块]\n conversion_engine\n security_validator\n errors_ts\n types_ts\n end\n```\n\n**依赖关系说明**：\n\n| 依赖方向 | 说明 |\n|----------|------|\n| tools → core | 工具层依赖核心服务处理业务逻辑 |\n| core 内部 | 核心模块相互依赖，types 作为共享基础 |\n| errors 被广泛依赖 | 所有模块在出错时使用错误系统 |\n\n## 11. 总结\n\nSkill Loader MCP Server 的核心模块架构采用清晰的分层设计：\n\n1. **入口层** 负责服务器初始化和协议配置\n2. **工具层** 暴露统一的 MCP 接口\n3. **核心服务层** 包含安全验证、格式转换、错误处理等关键功能\n4. **类型系统** 确保整个项目的类型安全\n\n该架构具有良好的可扩展性，便于添加新的工具、转换格式或验证规则。\n\n---\n\n\n\n## 类型定义系统\n\n### 相关页面\n\n相关主题：[核心模块架构](#page-core-modules), [技能获取器](#page-skill-fetcher)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/types.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/types.ts)\n- [src/core/errors.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts)\n- [src/core/conversion-engine.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)\n- [src/core/security-validator.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)\n- [examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n- [README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n \n\n# 类型定义系统\n\n## 概述\n\n类型定义系统是 Skill Loader MCP Server 的核心基础设施之一，为整个项目提供强类型的接口定义、数据模型和错误处理机制。该系统基于 TypeScript 编写，确保在 MCP 工具调用、数据流转和错误处理过程中具备类型安全性和编译时检查能力。\n\n类型定义系统的主要职责包括：\n\n- **数据结构定义**：为 skills.sh API 响应、技能元数据、导入结果等核心数据定义清晰的结构\n- **MCP 工具接口**：为 8 个 MCP 工具提供输入输出参数的类型规范\n- **错误类型体系**：建立分层分类的错误类型系统，支持精确的错误定位和恢复建议\n- **安全验证模型**：定义安全检查项和验证结果的数据结构\n\n资料来源：[README.md:1-20]()\n\n## 系统架构\n\n### 模块组成\n\n类型定义系统由以下几个核心模块组成：\n\n| 模块 | 文件路径 | 职责 |\n|------|----------|------|\n| 基础类型 | `src/core/types.ts` | 定义核心数据结构和接口 |\n| 错误类型 | `src/core/errors.ts` | 实现分层错误类体系 |\n| 转换引擎类型 | `src/core/conversion-engine.ts` | 技能转换相关类型 |\n| 安全验证类型 | `src/core/security-validator.ts` | 安全检查数据结构 |\n\n### 架构层次图\n\n```mermaid\ngraph TD\n A[类型定义系统] --> B[基础类型层]\n A --> C[错误类型层]\n A --> D[业务类型层]\n \n B --> B1[SkillShEntry]\n B --> B2[SkillContent]\n B --> B3[API响应类型]\n \n C --> C1[SkillLoaderError]\n C --> C2[NetworkError]\n C --> C3[ValidationError]\n C --> C4[FileSystemError]\n \n D --> D1[工具参数类型]\n D --> D2[转换结果类型]\n D --> D3[验证结果类型]\n```\n\n## 基础数据类型\n\n### 技能条目类型\n\n技能条目是 skills.sh 目录中的基本单位，包含以下关键字段：\n\n```typescript\ninterface SkillShEntry {\n name: string; // 技能名称（kebab-case格式）\n description: string; // 技能描述\n owner: string; // 仓库所有者\n repo: string; // 仓库名称\n installs: number; // 安装次数\n skillId?: string; // 技能唯一标识\n source?: string; // 来源信息\n relevance?: number; // 搜索相关性得分\n rank?: number; // 排行榜排名\n trending?: boolean; // 是否为热门技能\n}\n```\n\n资料来源：[examples/usage-examples.md:1-50]()\n\n### 技能内容类型\n\n技能内容用于存储解析后的完整技能信息：\n\n```typescript\ninterface SkillContent {\n frontmatter: {\n name: string;\n description?: string;\n dependencies?: string[];\n [key: string]: any;\n };\n body: string; // 技能正文内容\n sections: SkillSection[];\n}\n```\n\n资料来源：[src/core/conversion-engine.ts:1-30]()\n\n### 技能解析结果\n\n技能解析函数返回的结果包含元数据和解析状态：\n\n```typescript\ninterface ParsedSkill {\n frontmatter: Record;\n body: string;\n sections: Array<{\n heading: string;\n level: number;\n content: string;\n }>;\n}\n```\n\n## 错误类型体系\n\n### 基类设计\n\n错误系统采用继承层级结构，基类 `SkillLoaderError` 提供通用功能：\n\n```typescript\nexport class SkillLoaderError extends Error {\n public readonly timestamp: Date;\n public readonly context: Record;\n\n constructor(message: string, context: Record = {}) {\n super(message);\n this.name = this.constructor.name;\n this.timestamp = new Date();\n this.context = context;\n }\n}\n```\n\n资料来源：[src/core/errors.ts:1-30]()\n\n### 错误子类层级\n\n```mermaid\ngraph TD\n A[SkillLoaderError] --> B[NetworkError]\n A --> C[ValidationError]\n A --> D[FileSystemError]\n A --> E[ParsingError]\n \n B --> B1[HTTP状态码]\n B --> B2[重试次数]\n \n C --> C1[验证类型]\n C --> C2[问题详情]\n \n D --> D1[操作类型]\n D --> D2[文件路径]\n```\n\n### 网络错误 (NetworkError)\n\n用于处理网络相关故障：\n\n```typescript\nexport class NetworkError extends SkillLoaderError {\n public readonly url: string;\n public readonly statusCode?: number;\n public readonly retryCount: number;\n\n constructor(\n message: string,\n url: string,\n options: {\n statusCode?: number;\n retryCount?: number;\n context?: Record;\n } = {}\n );\n}\n```\n\n资料来源：[src/core/errors.ts:80-100]()\n\n**错误处理建议**：\n\n| 状态码 | 建议措施 |\n|--------|----------|\n| 404 | 验证技能名称是否正确，检查仓库是否存在 |\n| 403 | 可能是 GitHub 速率限制，等待后重试 |\n| >= 500 | 服务器端问题，稍后重试 |\n\n### 验证错误 (ValidationError)\n\n用于处理格式、安全和模式验证失败：\n\n```typescript\nexport class ValidationError extends SkillLoaderError {\n public readonly validationType: 'format' | 'security' | 'schema' | 'content';\n public readonly lineNumber?: number;\n public readonly details: string[];\n\n constructor(\n message: string,\n validationType: 'format' | 'security' | 'schema' | 'content',\n options: {\n lineNumber?: number;\n details?: string[];\n context?: Record;\n } = {}\n );\n}\n```\n\n资料来源：[src/core/errors.ts:180-200]()\n\n### 文件系统错误 (FileSystemError)\n\n用于处理文件系统操作错误：\n\n```typescript\nexport class FileSystemError extends SkillLoaderError {\n public readonly operation: 'read' | 'write' | 'delete' | 'access';\n public readonly filePath: string;\n public readonly systemError?: string;\n}\n```\n\n资料来源：[src/core/errors.ts:120-150]()\n\n**常见系统错误代码**：\n\n| 错误代码 | 含义 | 恢复建议 |\n|----------|------|----------|\n| EACCES/EPERM | 权限不足 | 检查文件权限，使用适当权限运行 |\n| ENOSPC | 磁盘空间不足 | 清理磁盘空间，选择其他输出位置 |\n| ENOENT | 路径不存在 | 验证目录存在，检查路径正确性 |\n| EEXIST | 文件已存在 | 使用 --overwrite 标志替换 |\n\n## MCP 工具类型定义\n\n### 工具参数类型\n\n系统为 8 个 MCP 工具定义了严格的输入参数类型：\n\n| 工具名称 | 必需参数 | 可选参数 |\n|----------|----------|----------|\n| `list_skills` | - | `page`, `pageSize` |\n| `search_skills` | `query` | `limit` |\n| `get_leaderboard` | - | `timeframe`, `limit` |\n| `fetch_skill` | `identifier` | - |\n| `validate_skill` | `content` | `url` |\n| `convert_to_steering` | `content` | `sourceUrl` |\n| `convert_to_power` | `content` | `sourceUrl` |\n| `import_skill` | `identifier`, `outputFormat` | `skipValidation` |\n\n资料来源：[README.md:1-80]()\n\n### 列表技能工具类型\n\n```typescript\ninterface ListSkillsParams {\n page?: number; // 页码，默认1\n pageSize?: number; // 每页数量，默认50，最大100\n}\n\ninterface ListSkillsResult {\n skills: SkillShEntry[];\n total: number;\n page: number;\n pageSize: number;\n}\n```\n\n### 搜索技能工具类型\n\n```typescript\ninterface SearchSkillsParams {\n query: string; // 搜索关键词\n limit?: number; // 最大返回数量，默认20\n}\n\ninterface SearchSkillsResult {\n skills: SkillShEntry[];\n query: string;\n count: number;\n}\n```\n\n### 获取排行榜工具类型\n\n```typescript\ninterface GetLeaderboardParams {\n timeframe?: 'all' | '24h'; // 时间范围，默认 'all'\n limit?: number; // 最大结果数，默认20，最大50\n}\n\ninterface GetLeaderboardResult {\n skills: Array;\n timeframe: string;\n count: number;\n}\n```\n\n### 验证技能工具类型\n\n```typescript\ninterface ValidateSkillParams {\n content: string; // 待验证的技能内容\n url?: string; // 源URL用于验证\n}\n\ninterface ValidationIssue {\n type: 'dangerous_command' | 'suspicious_pattern' | 'untrusted_source';\n description: string;\n location?: string;\n}\n\ninterface ValidateSkillResult {\n isValid: boolean;\n issues: ValidationIssue[];\n severity: 'safe' | 'warning' | 'unsafe';\n}\n```\n\n资料来源：[examples/usage-examples.md:80-120]()\n\n## 安全验证类型\n\n### 验证问题类型\n\n安全验证模块定义了多种检查类型：\n\n```typescript\ntype ValidationIssueType = \n | 'dangerous_command' // 危险命令\n | 'suspicious_pattern' // 可疑模式\n | 'untrusted_source'; // 不受信任的源\n```\n\n### 验证结果级别\n\n```typescript\ntype ValidationSeverity = 'safe' | 'warning' | 'unsafe';\n```\n\n安全级别判定逻辑：\n\n| 问题类型 | 严重级别 |\n|----------|----------|\n| `untrusted_source` | unsafe |\n| `dangerous_command` | unsafe |\n| `suspicious_pattern` | warning |\n| 无问题 | safe |\n\n资料来源：[src/core/security-validator.ts:1-50]()\n\n### 危险命令检测\n\n系统检测以下危险命令模式：\n\n- `rm -rf` 系列删除命令\n- `sudo` 特权命令\n- `eval` 和 `exec` 代码执行命令\n\n### 可疑模式检测\n\n检测以下可疑代码模式：\n\n- 模板注入：`${...}` 或 `$(...)`\n- 系统路径访问：`/etc/`、`/usr/`、`/bin/`\n- 敏感配置文件访问\n\n## 转换结果类型\n\n### 转换为转向文件结果\n\n```typescript\ninterface ConvertToSteeringResult {\n content: string; // 转换后的内容\n filename: string; // 生成的文件名\n metadata: {\n originalSkill: string;\n sourceUrl?: string;\n importedAt: string;\n };\n}\n```\n\n### 转换为 Power 结果\n\n```typescript\ninterface ConvertToPowerResult {\n files: Array<{\n path: string;\n content: string;\n }>;\n metadata: {\n skillName: string;\n sourceUrl?: string;\n filesGenerated: number;\n };\n}\n```\n\nPower 格式可能生成的文件：\n\n| 文件类型 | 条件 | 路径 |\n|----------|------|------|\n| POWER.md | 始终生成 | `~/.kiro/powers/{skill-name}/POWER.md` |\n| mcp.json | 技能有依赖或工具引用 | 同目录 |\n| steering/ | 技能有3+复杂章节 | 同目录 |\n\n资料来源：[src/core/conversion-engine.ts:50-100]()\n\n## API 响应类型\n\n### Skills.sh API v1 响应类型\n\n```typescript\ninterface SkillsShV1Response {\n skills: SkillsShV1Entry[];\n total: number;\n page: number;\n}\n\ninterface SkillsShV1Entry {\n id: string;\n skillId: string;\n name: string;\n description: string;\n owner: string;\n repo: string;\n installs: number;\n source: string;\n}\n```\n\n资料来源：[CHANGELOG.md:1-30]()\n\n## 类型使用最佳实践\n\n### 类型守卫\n\n系统支持 TypeScript 类型守卫以提供精确的类型缩小：\n\n```typescript\nfunction isNetworkError(error: unknown): error is NetworkError {\n return error instanceof NetworkError;\n}\n\nfunction isValidationError(error: unknown): error is ValidationError {\n return error instanceof ValidationError;\n}\n```\n\n### 错误恢复流程\n\n```mermaid\ngraph TD\n A[发生错误] --> B{错误类型?}\n B -->|NetworkError| C[检查状态码]\n B -->|ValidationError| D[检查验证类型]\n B -->|FileSystemError| E[检查系统错误]\n \n C --> C1{404?}\n C1 -->|是| C2[验证技能名称]\n C1 -->|否| C3{403?}\n C3 -->|是| C4[等待重试]\n C3 -->|否| C5[检查连接]\n \n D --> D1{security?}\n D1 -->|是| D2[拒绝导入]\n D1 -->|否| D3{format?}\n D3 -->|是| D4[检查YAML格式]\n \n E --> E1{EACCES?}\n E1 -->|是| E2[检查权限]\n E1 -->|否| E3{ENOSPC?}\n E3 -->|是| E4[清理磁盘]\n```\n\n## 总结\n\n类型定义系统为 Skill Loader MCP Server 提供了：\n\n1. **完整的类型安全**：从 API 响应到错误处理，全链路类型覆盖\n2. **清晰的错误分类**：四级错误类型体系，支持精确的问题定位\n3. **规范的工具接口**：8 个 MCP 工具的输入输出类型一致性保证\n4. **安全验证模型**：结构化的安全检查和问题报告机制\n\n该系统是项目架构的基础层，为上层的工具实现、CLI 入口和配置管理提供了坚实的类型支撑。\n\n---\n\n\n\n## 技能解析器\n\n### 相关页面\n\n相关主题：[技能获取器](#page-skill-fetcher), [MCP工具详解](#page-mcp-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/conversion-engine.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)\n- [src/core/security-validator.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)\n- [src/core/errors.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts)\n- [examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n- [README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n- [src/core/conversion-engine.test.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.test.ts)\n \n\n# 技能解析器\n\n技能解析器（Skill Resolver）是 Skill Loader MCP Server 的核心组件之一，负责从 GitHub 仓库解析、提取和处理 Claude Skills 内容。该模块在技能导入工作流中扮演着关键角色，与安全验证器、转换引擎协同工作，确保技能能够安全、高效地转换为 Kiro 格式。\n\n## 核心职责\n\n技能解析器的主要职责包括：\n\n| 职责类别 | 具体功能 |\n|---------|---------|\n| 内容获取 | 从 GitHub 远程仓库获取原始技能内容 |\n| 标识解析 | 支持 `owner/repo` 和纯技能名称两种格式的标识符解析 |\n| 元数据提取 | 解析 YAML frontmatter 中的名称、描述、依赖等信息 |\n| 内容验证 | 调用安全验证器检查潜在风险 |\n| 格式转换 | 将解析后的内容传递给转换引擎生成目标格式 |\n\n资料来源：[README.md:1-50]()\n\n## 解析流程\n\n技能解析器遵循标准化的解析流程，确保从远程获取的技能内容能够被准确处理和转换。\n\n```mermaid\ngraph TD\n A[输入: 技能标识符] --> B[标识符标准化]\n B --> C{格式判断}\n C -->|owner/repo 格式| D[构建 GitHub URL]\n C -->|纯名称格式| E[查询 skills.sh 目录]\n D --> F[获取原始内容]\n E --> F\n F --> G[解析 YAML Frontmatter]\n G --> H[提取 body 内容]\n H --> I[结构化输出]\n I --> J[传递给转换引擎]\n```\n\n资料来源：[examples/usage-examples.md:30-60]()\n\n## 标识符解析规则\n\n技能解析器支持两种标识符格式，具有不同的处理逻辑：\n\n### owner/repo 格式\n\n当提供完整的所有者/仓库格式时（如 `anthropics/pdf-extractor`），解析器直接构建 GitHub 原始内容 URL：\n\n```\nhttps://raw.githubusercontent.com/{owner}/{repo}/main/skills/{skill-name}/SKILL.md\n```\n\n### 纯名称格式\n\n当提供纯技能名称时（如 `pdf-extractor`），解析器会查询 skills.sh 目录获取完整的仓库信息，然后构建获取路径。 资料来源：[examples/usage-examples.md:45-55]()\n\n## YAML Frontmatter 解析\n\n技能解析器能够准确解析 Claude Skills 标准格式的 YAML frontmatter，提取以下元数据字段：\n\n| 字段 | 类型 | 说明 |\n|-----|------|-----|\n| `name` | string | 技能唯一标识名称 |\n| `description` | string | 技能功能描述 |\n| `dependencies` | string[] | 技能依赖列表 |\n| `version` | string | 技能版本号（可选） |\n\n解析后的结构化数据包含 `frontmatter` 和 `body` 两个主要部分：\n\n```typescript\ninterface ParsedSkill {\n frontmatter: {\n name: string;\n description?: string;\n dependencies?: string[];\n [key: string]: any;\n };\n body: string;\n}\n```\n\n资料来源：[src/core/conversion-engine.ts:1-30]()\n\n## 技能验证集成\n\n技能解析器与安全验证器紧密集成，在解析过程中自动进行安全检查：\n\n### 危险命令检测\n\n解析器会扫描技能内容中的危险命令模式：\n\n- `rm -rf` — 递归删除命令\n- `sudo` — 管理员权限执行\n- `eval` / `exec` — 代码执行函数\n\n### 可疑文件操作检测\n\n检测访问敏感系统路径的操作：\n\n- `/etc/` — 系统配置目录\n- `/usr/` — 用户程序目录\n- `/bin/` — 二进制程序目录\n\n### 代码注入检测\n\n识别潜在的代码注入攻击模式：\n\n- `${...}` — 模板字符串注入\n- `$(...)` — 命令替换注入\n\n资料来源：[src/core/security-validator.ts:1-40]()\n\n### 验证结果级别\n\n| 安全级别 | 条件 | 处理方式 |\n|---------|------|---------|\n| `safe` | 无安全问题 | 正常处理 |\n| `warning` | 存在可疑模式 | 警告但允许 |\n| `unsafe` | 包含危险命令或非信任来源 | 阻止导入 |\n\n资料来源：[src/core/security-validator.ts:35-50]()\n\n## 错误处理机制\n\n技能解析器实现了完善的错误处理机制，针对不同类型的故障提供精确的错误分类：\n\n### 错误类型分类\n\n| 错误类型 | 触发场景 | 恢复建议 |\n|---------|---------|---------|\n| `NetworkError` | 网络连接失败、GitHub 不可达 | 检查网络连接，等待后重试 |\n| `NotFoundError` | 技能或仓库不存在 (404) | 验证技能名称，检查仓库存在性 |\n| `RateLimitError` | GitHub API 频率限制 (403) | 等待几分钟后重试 |\n| `ValidationError` | 安全验证失败、格式错误 | 审查安全问题，使用信任来源 |\n| `FileSystemError` | 文件读写失败、权限问题 | 检查文件路径和权限设置 |\n\n资料来源：[src/core/errors.ts:1-80]()\n\n### HTTP 状态码处理\n\n解析器针对常见的 HTTP 错误状态码提供了用户友好的错误消息和建议：\n\n```typescript\nif (statusCode === 404) {\n // 验证技能名称是否正确\n // 检查仓库是否存在于 GitHub\n // 尝试使用 owner/repo 格式\n} else if (statusCode === 403) {\n // 可能触发了 GitHub 频率限制\n // 等待几分钟后重试\n} else if (statusCode >= 500) {\n // 服务器端问题\n // 稍后重试\n}\n```\n\n资料来源：[src/core/errors.ts:60-90]()\n\n## 转换引擎协作\n\n技能解析器与转换引擎协同工作，将解析后的技能内容转换为目标格式：\n\n### 支持的目标格式\n\n| 格式 | 输出文件 | 说明 |\n|-----|---------|------|\n| `steering` | `.md` 文件 | Kiro 方向盘文件格式 |\n| `power` | `POWER.md` + `mcp.json` | Kiro 能力格式 |\n\n### Power 格式生成规则\n\n转换引擎根据技能内容特征决定生成哪些文件：\n\n1. **基础文件**: 始终生成 `POWER.md`\n2. **MCP 配置**: 当技能包含依赖项或工具引用时生成 `mcp.json`\n3. **转向目录**: 当技能包含 3 个或以上复杂章节时生成 `steering/` 目录\n\n资料来源：[src/core/conversion-engine.ts:80-120]()\n\n### 转换测试验证\n\n```typescript\ndescribe('toPower', () => {\n it('converts parsed skill to power format', () => {\n const content = `---\nname: my-power\ndescription: A powerful skill\n---\n# Instructions\nDo power stuff.`;\n\n const parsed = engine.parseSkill(content);\n const power = engine.toPower(parsed, 'https://example.com');\n\n expect(power.powerName).toBe('my-power');\n expect(power.files.length).toBeGreaterThanOrEqual(1);\n expect(power.files[0].path).toBe('POWER.md');\n });\n\n it('generates mcp.json when skill has dependencies', () => {\n const content = `---\nname: dep-power\ndependencies:\n - express\n - cors\n---\n# Body`;\n\n const parsed = engine.parseSkill(content);\n const power = engine.toPower(parsed);\n\n const mcpFile = power.files.find(f => f.path === 'mcp.json');\n expect(mcpFile).toBeDefined();\n });\n});\n```\n\n资料来源：[src/core/conversion-engine.test.ts:60-100]()\n\n## 导入工作流\n\n完整的技能导入工作流将解析器、验证器和转换器整合为一个端到端的流程：\n\n```mermaid\ngraph LR\n A[用户请求导入] --> B[fetch_skill]\n B --> C{成功?}\n C -->|否| D[返回错误]\n C -->|是| E[validate_skill]\n E --> F{安全?}\n F -->|否| G[阻止或警告]\n F -->|是| H[convert_to_power/steering]\n H --> I[返回转换结果]\n```\n\n### 完整导入示例\n\n```json\n{\n \"tool\": \"import_skill\",\n \"arguments\": {\n \"identifier\": \"anthropics/pdf-extractor\",\n \"outputFormat\": \"power\",\n \"skipValidation\": false\n }\n}\n```\n\n响应包含转换后的文件和元数据：\n\n```json\n{\n \"success\": true,\n \"content\": \"---\\nname: pdf-extractor\\ndisplayName: PDF Extractor\\n...\",\n \"filename\": \"POWER.md\",\n \"targetPath\": \"~/.kiro/powers/pdf-extractor/POWER.md\",\n \"metadata\": {\n \"skillName\": \"pdf-extractor\",\n \"sourceUrl\": \"https://raw.githubusercontent.com/...\",\n \"outputFormat\": \"power\"\n }\n}\n```\n\n资料来源：[examples/usage-examples.md:80-120]()\n\n## 性能优化\n\n技能解析器实现了多项性能优化策略：\n\n### 缓存机制\n\nskills.sh 目录搜索结果在内存中缓存 1 小时，减少 API 调用并提升响应速度。缓存过期后自动刷新。\n\n### 重试机制\n\n网络请求采用指数退避重试策略，应对临时性网络故障：\n\n```typescript\n// 初始延迟: 1秒\n// 最大延迟: 30秒\n// 最大重试次数: 3次\n```\n\n### 并发控制\n\n解析请求支持并发处理，但限制最大并发数避免资源耗尽。\n\n资料来源：[README.md:100-120]()\n\n## 总结\n\n技能解析器是 Skill Loader MCP Server 的核心模块，承担着从远程 GitHub 仓库获取技能内容、解析 YAML 元数据、进行安全验证以及与转换引擎协作的重要职责。通过完善的错误处理机制、安全扫描集成和性能优化策略，确保技能导入过程的可靠性、安全性和高效性。开发者可以通过扩展解析规则和验证逻辑来支持更多技能格式和来源。\n\n---\n\n\n\n## 技能获取器\n\n### 相关页面\n\n相关主题：[技能解析器](#page-skill-resolver), [安全验证器](#page-security-validator)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/skill-fetcher.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/skill-fetcher.ts)\n- [src/tools/fetch-skill.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/fetch-skill.ts)\n- [src/core/skill-resolver.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/skill-resolver.ts)\n- [src/core/conversion-engine.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)\n- [examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n- [README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n \n\n# 技能获取器\n\n技能获取器（Skill Fetcher）是 Skill Loader MCP Server 的核心组件之一，负责从 GitHub 仓库获取 Claude Skills 的原始内容。该模块在技能导入工作流中扮演着数据源的角色，为后续的安全验证和格式转换提供原材料。\n\n## 核心定位\n\n在 Skill Loader MCP Server 的整体架构中，技能获取器处于工作流的最上游位置。用户的完整导入流程为：**获取技能 → 安全验证 → 格式转换 → 导入完成**。技能获取器仅负责完成第一步，即从 GitHub 获取技能的原始 Markdown 内容。\n\n技能获取器支持两种标识符格式：\n\n| 标识符格式 | 示例 | 说明 |\n|-----------|------|------|\n| `owner/repo` | `anthropics/pdf-extractor` | 标准格式，明确指定所有者仓库和技能名称 |\n| 纯技能名称 | `pdf-extractor` | 简写格式，自动使用 `anthropics/skills` 作为默认仓库 |\n\n资料来源：[examples/usage-examples.md:61-67]()\n\n## 架构设计\n\n### 模块分层\n\n技能获取器采用分层架构设计，主要分为两个层次：\n\n```\n┌─────────────────────────────────────┐\n│ MCP 工具层 (fetch-skill.ts) │ ← MCP 协议接口\n├─────────────────────────────────────┤\n│ 核心服务层 (skill-fetcher.ts) │ ← 业务逻辑\n├─────────────────────────────────────┤\n│ 解析层 (skill-resolver.ts) │ ← API 交互\n└─────────────────────────────────────┘\n```\n\n**工具层**负责处理 MCP 协议层面的参数解析和响应格式化；**核心服务层**实现技能获取的业务逻辑；**解析层**负责与外部 API（skills.sh 和 GitHub）进行实际的网络通信。\n\n资料来源：[src/tools/fetch-skill.ts]()\n\n### 获取流程\n\n```mermaid\ngraph TD\n A[接收 identifier] --> B{identifier 格式判断}\n B -->|包含 /| C[解析 owner/repo]\n B -->|纯名称| D[使用默认仓库 anthropics/skills]\n C --> E[构建 GitHub URL]\n D --> E\n E --> F[发起 HTTP 请求]\n F --> G{响应状态}\n G -->|200| H[返回技能内容]\n G -->|404| I[抛出 NotFoundError]\n G -->|网络错误| J[抛出 NetworkError]\n G -->|其他| K[抛出 FetchError]\n```\n\n资料来源：[src/core/conversion-engine.ts:75-89]()\n\n## 核心功能\n\n### fetch_skill 工具\n\n`fetch_skill` 是 MCP 服务器暴露给外部的唯一工具接口，用于获取存储在 GitHub 上的原始技能内容。\n\n**参数定义：**\n\n| 参数名 | 类型 | 必需 | 默认值 | 说明 |\n|-------|------|------|--------|------|\n| `identifier` | string | 是 | - | 技能标识符，格式为 `owner/repo` 或纯技能名称 |\n\n**请求示例：**\n\n```json\n{\n \"tool\": \"fetch_skill\",\n \"arguments\": {\n \"identifier\": \"anthropics/pdf-extractor\"\n }\n}\n```\n\n资料来源：[examples/usage-examples.md:53-67]()\n\n**响应结构：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `content` | string | 技能的原始 Markdown 内容 |\n| `url` | string | 实际获取内容的原始 URL |\n| `metadata` | object | 技能的元数据信息 |\n| `metadata.name` | string | 技能名称 |\n| `metadata.owner` | string | 仓库所有者 |\n| `metadata.repo` | string | 仓库名称 |\n| `metadata.skillPath` | string | 仓库中的技能路径 |\n| `metadata.fetchedAt` | string | ISO 格式的获取时间 |\n\n资料来源：[examples/usage-examples.md:68-79]()\n\n### 响应示例\n\n```json\n{\n \"content\": \"---\\nname: PDF Extractor\\ndescription: Extract text from PDF files\\n---\\n\\n# PDF Extractor\\n\\n...\",\n \"url\": \"https://raw.githubusercontent.com/anthropics/skills/main/skills/pdf-extractor/SKILL.md\",\n \"metadata\": {\n \"name\": \"pdf-extractor\",\n \"owner\": \"anthropics\",\n \"repo\": \"skills\",\n \"skillPath\": \"skills/pdf-extractor\",\n \"fetchedAt\": \"2024-01-15T10:30:00.000Z\"\n }\n}\n```\n\n资料来源：[examples/usage-examples.md:69-79]()\n\n## URL 构建规则\n\n技能获取器使用固定的 URL 模板从 GitHub 获取原始内容。URL 构建遵循以下规则：\n\n```\nhttps://raw.githubusercontent.com/{owner}/{repo}/main/skills/{skillName}/SKILL.md\n```\n\n**URL 组件解析：**\n\n| 组件 | 来源 | 说明 |\n|------|------|------|\n| `owner` | identifier 前半部分或 `anthropics` | 仓库所有者 |\n| `repo` | identifier 后半部分或 `skills` | 仓库名称 |\n| `skillName` | identifier 最后部分 | 技能名称（小写） |\n| 分支 | 固定为 `main` | GitHub 仓库分支 |\n| 文件路径 | 固定为 `skills/{skillName}/SKILL.md` | 标准技能文件结构 |\n\n资料来源：[src/core/conversion-engine.ts:75-89]()\n\n## 错误处理\n\n技能获取器定义了多种错误类型以应对不同的失败场景。\n\n### 错误类型\n\n| 错误类型 | 触发条件 | HTTP 状态码 |\n|----------|----------|-------------|\n| `NotFoundError` | 技能不存在或路径错误 | 404 |\n| `NetworkError` | 网络连接失败或超时 | - |\n| `FetchError` | HTTP 请求失败（非 200） | 4xx/5xx |\n\n资料来源：[src/core/errors.ts]()\n\n### 错误响应格式\n\n所有工具错误返回统一格式：\n\n```json\n{\n \"error\": \"Error message describing what went wrong\",\n \"tool\": \"tool_name\",\n \"timestamp\": \"2024-01-15T10:30:00.000Z\"\n}\n```\n\n资料来源：[examples/usage-examples.md:189-195]()\n\n### 常见错误场景\n\n| 错误场景 | 错误消息示例 | 解决方案 |\n|---------|-------------|---------|\n| 技能不存在 | `Skill not found: unknown/skill` | 检查 identifier 拼写 |\n| 网络连接失败 | `Failed to connect to GitHub` | 检查网络连接 |\n| 仓库不可访问 | `Repository not found` | 确认仓库公开状态 |\n\n资料来源：[README.md:77-85]()\n\n## 重试机制\n\n技能获取器内置重试逻辑以提高网络请求的可靠性。\n\n**重试策略：**\n\n| 参数 | 配置 |\n|------|------|\n| 最大重试次数 | 3 次 |\n| 重试间隔 | 指数退避 |\n| 初始延迟 | 1000ms |\n| 最大延迟 | 5000ms |\n\n指数退避公式：`delay = min(initialDelay * 2^attempt, maxDelay)`\n\n资料来源：[README.md:73]()\n\n## 与其他模块的集成\n\n### 在导入工作流中的角色\n\n技能获取器是 `import_skill` 工具的底层依赖。`import_skill` 工具的执行流程如下：\n\n```mermaid\ngraph LR\n A[fetch_skill] --> B[validate_skill]\n B --> C[convert_to_steering 或 convert_to_power]\n C --> D[返回导入结果]\n \n A -.->|数据源| B\n B -.->|验证通过| C\n```\n\n资料来源：[README.md:50-60]()\n\n### 配合安全验证\n\n获取到的原始内容会立即传递给安全验证模块进行检查。安全验证器会扫描以下危险模式：\n\n- **危险命令**：`rm -rf`、`sudo`、`eval`、`exec`\n- **可疑文件操作**：`/etc/`、`/usr/`、`/bin/`\n- **代码注入模式**：`${...}`、`$(...)`\n- **不可信来源**：非 GitHub URL\n\n资料来源：[README.md:71-73]()\n\n## 使用限制\n\n| 限制项 | 值 | 说明 |\n|--------|---|------|\n| 内容大小 | 无明确限制 | 受 GitHub 响应大小限制 |\n| 并发请求 | 无限制 | 但建议限制频率以避免触发限流 |\n| 缓存 | 1 小时 TTL | 仅对 skills.sh 搜索结果缓存，获取操作不缓存 |\n\n资料来源：[README.md:74-76]()\n\n## 总结\n\n技能获取器作为 Skill Loader MCP Server 的数据入口，提供了一个简洁可靠的接口从 GitHub 仓库获取 Claude Skills 的原始内容。它支持灵活的标识符格式，内置完善的错误处理和重试机制，并为后续的安全验证和格式转换模块提供稳定的数据源。该模块的稳定性直接影响整个导入工作流的可靠性。\n\n---\n\n\n\n## 转换引擎\n\n### 相关页面\n\n相关主题：[安全验证器](#page-security-validator), [MCP工具详解](#page-mcp-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/conversion-engine.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)\n- [src/core/conversion-engine.test.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.test.ts)\n- [src/tools/convert-to-steering.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/convert-to-steering.ts)\n- [src/tools/convert-to-power.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/convert-to-power.ts)\n \n\n# 转换引擎\n\n转换引擎（Conversion Engine）是 Skill Loader MCP Server 的核心模块，负责将 Claude Skills 格式的内容转换为 Kiro 平台所需的两种格式：**Steering 文件格式** 和 **Power 格式**。该引擎封装了所有与格式转换相关的逻辑，为 MCP 工具层提供统一的转换接口。\n\n## 核心职责\n\n转换引擎的主要职责包括：\n\n1. **解析 Skill 内容** — 解析 YAML frontmatter 和 Markdown 正文，提取元数据、标题层级和正文内容\n2. **格式转换** — 将解析后的技能数据转换为 steering 文件或 power 格式\n3. **文件名生成** — 将技能名称转换为 kebab-case 格式作为输出文件名\n4. **元数据注入** — 在转换后的文件中添加原始技能信息、来源 URL 和导入时间戳\n5. **条件生成** — 根据技能内容特征判断是否需要生成额外的 `mcp.json` 或 `steering/` 目录\n\n资料来源：[src/core/conversion-engine.ts:1-50]()\n\n## 架构概览\n\n```mermaid\ngraph TD\n A[原始 Skill 内容] --> B[ConversionEngine]\n B --> C{parseSkill}\n C --> D[ParsedSkill 数据结构]\n D --> E[toSteeringFile]\n D --> F[toPower]\n E --> G[Steering 文件]\n F --> H[POWER.md]\n F --> I{shouldGenerateMcpJson?}\n F --> J{shouldGenerateSteeringDir?}\n I -->|是| K[mcp.json]\n J -->|是| L[steering/ 目录]\n G --> M[转换结果]\n H --> N[files 数组]\n K --> N\n L --> N\n```\n\n## 核心类与接口\n\n### ConversionEngine 类\n\n`ConversionEngine` 是转换引擎的核心类，提供所有转换操作的入口方法。\n\n| 方法名 | 参数 | 返回值 | 功能说明 |\n|--------|------|--------|----------|\n| `parseSkill` | `content: string` | `ParsedSkill` | 解析 Skill 内容，返回结构化数据 |\n| `toSteeringFile` | `skill: ParsedSkill, sourceUrl?: string` | `SteeringResult` | 转换为 Steering 文件格式 |\n| `toPower` | `skill: ParsedSkill, sourceUrl?: string` | `PowerResult` | 转换为 Power 格式 |\n| `toKebabCase` | `str: string` | `string` | 字符串转 kebab-case |\n| `extractKeywords` | `description: string` | `string[]` | 从描述中提取关键词 |\n| `shouldGenerateMcpJson` | `skill: ParsedSkill` | `boolean` | 判断是否需要生成 mcp.json |\n| `generateMcpJson` | `skill: ParsedSkill` | `McpJsonConfig` | 生成 mcp.json 配置内容 |\n| `shouldGenerateSteeringDir` | `skill: ParsedSkill` | `boolean` | 判断是否需要生成 steering/ 目录 |\n| `generateSteeringContent` | `skill: ParsedSkill` | `string` | 生成 steering/ 目录内容 |\n\n资料来源：[src/core/conversion-engine.ts:1-100]()\n\n### ParsedSkill 数据结构\n\n解析后的技能数据结构包含以下字段：\n\n```typescript\ninterface ParsedSkill {\n frontmatter: {\n name: string; // 技能名称\n description: string; // 技能描述\n dependencies?: string[]; // 依赖列表（可选）\n [key: string]: any; // 其他 frontmatter 字段\n };\n body: string; // 原始正文内容\n sections: Array<{ // 解析后的章节列表\n heading: string; // 章节标题\n level: number; // 标题层级（1-6）\n content: string; // 章节内容\n }>;\n}\n```\n\n资料来源：[src/core/conversion-engine.ts:50-80]()\n\n## 解析流程\n\n`parseSkill` 方法负责将原始 Markdown 内容解析为结构化数据：\n\n```mermaid\ngraph TD\n A[原始内容] --> B{内容为空?}\n B -->|是| C[抛出 ValidationError]\n B -->|否| D[解析 YAML Frontmatter]\n D --> E{name 存在?}\n E -->|否| F[使用 'Untitled Skill']\n E -->|是| G[提取 name 字段]\n D --> H{description 存在?}\n H -->|否| I[抛出 ValidationError]\n H -->|是| J[提取 description 字段]\n G --> K[构建 frontmatter 对象]\n F --> K\n I --> K\n K --> L[解析 Markdown 章节]\n L --> M[构建 sections 数组]\n M --> N[返回 ParsedSkill]\n```\n\n### 解析规则\n\n- **空内容检测**：空字符串会抛出 `ValidationError`，错误消息包含 \"empty\" 关键词\n- **必填字段验证**：缺少 `name` 或 `description` 会抛出错误\n- **章节解析**：使用标题行（`#`、`##`、`###` 等）分割正文，构建层级化的 sections 数组\n- **容错处理**：缺少 frontmatter 时，使用默认值 `name: 'Untitled Skill'`\n\n资料来源：[src/core/conversion-engine.test.ts:20-80]()\n\n## Steering 文件转换\n\nSteering 文件是 Kiro 平台的轻量级格式，用于在 `.kiro/steering/` 目录下存储技能指南。\n\n### 输出格式\n\n```markdown\n---\noriginal_skill: {技能名称}\nsource_url: {来源URL}\nimported_at: {ISO时间戳}\n---\n\n# {技能名称}\n\n{正文内容}\n\n## Dependencies\n\n- {依赖1}\n- {依赖2}\n\n---\n*Imported from Claude Skills via Skill Loader Power*\n```\n\n### 转换结果结构\n\n```typescript\ninterface SteeringResult {\n steeringContent: string; // Steering 文件内容\n filename: string; // 文件名（kebab-case）\n targetPath: string; // 目标路径 .kiro/steering/{filename}\n metadata: {\n skillName: string;\n sourceUrl?: string;\n outputFormat: 'steering';\n validationResult: ValidationResult;\n };\n}\n```\n\n资料来源：[src/tools/convert-to-steering.ts]()\n\n## Power 格式转换\n\nPower 格式是 Kiro 平台的高级格式，支持更复杂的技能配置。当技能具有依赖或工具引用时，会自动生成额外的配置文件。\n\n### 输出结构\n\n```mermaid\ngraph TD\n A[PowerResult] --> B[files: Array]\n B --> C[POWER.md]\n B --> D[mcp.json?]\n B --> E[steering/?]\n C --> F[displayName, body, Dependencies, Import Metadata]\n D --> G[dependencies 数组]\n E --> H[详细章节内容]\n```\n\n### 生成条件\n\n| 条件 | 生成文件 | 说明 |\n|------|----------|------|\n| `dependencies` 存在且非空 | `mcp.json` | 包含依赖列表 |\n| 存在 MCP server 工具引用 | `mcp.json` | 包含 MCP 服务器配置 |\n| 3+ 个复杂章节（层级≥2，内容>200字符） | `steering/` 目录 | 存储详细指南内容 |\n\n### PowerResult 结构\n\n```typescript\ninterface PowerResult {\n powerName: string; // Power 名称（kebab-case）\n displayName: string; // 显示名称（原始格式）\n files: Array<{\n path: string; // 文件路径\n content: string; // 文件内容\n }>;\n}\n```\n\n资料来源：[src/core/conversion-engine.ts:100-200]()\n\n## kebab-case 转换\n\n转换引擎提供了 `toKebabCase` 方法，将任意字符串转换为标准的 kebab-case 格式（用于 Kiro powers 和 steering 文件的标准命名规范）。\n\n### 转换规则\n\n1. 转换为小写\n2. 空格和下划线替换为连字符\n3. 移除特殊字符（仅保留 a-z、0-9 和连字符）\n4. 折叠多个连续连字符为一个\n5. 移除首尾连字符\n\n### 转换示例\n\n| 输入 | 输出 |\n|------|------|\n| `PDF Extractor` | `pdf-extractor` |\n| `React_Best_Practices` | `react-best-practices` |\n| `My Skill!!` | `my-skill` |\n\n资料来源：[src/core/conversion-engine.ts:60-100]()\n\n## 关键词提取\n\n`extractKeywords` 方法从技能描述中提取最多 5 个有意义的关键词：\n\n### 过滤规则\n\n- 移除停用词集合中的常见词（`the`, `and`, `for`, `with`, `this`, `that`, `from`, `into` 等）\n- 仅保留长度 ≥ 3 的单词\n- 移除特殊字符后按空格分割\n\n```typescript\nprivate extractKeywords(description: string): string[] {\n const stopWords = new Set([\n 'the', 'and', 'for', 'with', 'this', 'that', 'from', 'into',\n 'when', 'what', 'where', 'how', 'why', 'can', 'will', 'should',\n 'would', 'could', 'has', 'have', 'had', 'are', 'was', 'were',\n 'been', 'being', 'you', 'your', 'use', 'used', 'using'\n ]);\n // ... 实现逻辑\n}\n```\n\n资料来源：[src/core/conversion-engine.ts:200-250]()\n\n## MCP 工具集成\n\n转换引擎通过两个 MCP 工具与外部交互：\n\n### convert_to_steering\n\n将原始 Skill 内容转换为 Steering 文件格式：\n\n```typescript\ninterface ConvertToSteeringInput {\n content: string; // 必填：Skill 内容\n sourceUrl?: string; // 可选：原始来源 URL\n}\n```\n\n资料来源：[src/tools/convert-to-steering.ts]()\n\n### convert_to_power\n\n将原始 Skill 内容转换为 Power 格式：\n\n```typescript\ninterface ConvertToPowerInput {\n content: string; // 必填：Skill 内容\n sourceUrl?: string; // 可选：原始来源 URL\n}\n```\n\n**自动生成逻辑**：当技能包含依赖或工具引用时，自动在 `files` 数组中添加 `mcp.json`；当技能有 3+ 个复杂章节时，添加 `steering/` 目录。\n\n资料来源：[src/tools/convert-to-power.ts]()\n\n## 完整导入流程\n\n转换引擎通常在 `import_skill` 工具中被调用，作为完整导入工作流的一部分：\n\n```mermaid\ngraph LR\n A[fetch_skill] --> B[validate_skill]\n B --> C{验证通过?}\n C -->|否| D[返回错误]\n C -->|是| E[ConversionEngine.parseSkill]\n E --> F{outputFormat}\n F -->|steering| G[ConversionEngine.toSteeringFile]\n F -->|power| H[ConversionEngine.toPower]\n G --> I[SteeringResult]\n H --> J[PowerResult]\n I --> K[输出到 .kiro/steering/]\n J --> L[输出到 ~/.kiro/powers/]\n```\n\n资料来源：[README.md]()，[src/core/conversion-engine.test.ts]()\n\n## 测试覆盖\n\n转换引擎拥有完整的单元测试覆盖，测试文件为 `src/core/conversion-engine.test.ts`。\n\n### 测试场景\n\n| 测试用例 | 验证内容 |\n|----------|----------|\n| `parses valid skill with frontmatter and body` | 正确解析包含 frontmatter 和正文的技能 |\n| `throws on empty content` | 空内容抛出 ValidationError |\n| `throws on missing name in frontmatter` | 缺少 name 字段时抛出错误 |\n| `throws on missing description in frontmatter` | 缺少 description 字段时抛出错误 |\n| `handles content without frontmatter` | 无 frontmatter 时使用默认值 |\n| `converts parsed skill to steering format` | Steering 文件格式转换正确 |\n| `includes dependencies in steering file` | 依赖项正确包含在 Steering 文件中 |\n| `converts parsed skill to power format` | Power 格式转换正确 |\n| `generates mcp.json when skill has dependencies` | 有依赖时正确生成 mcp.json |\n| `does not generate mcp.json when skill has no dependencies` | 无依赖时不生成 mcp.json |\n\n资料来源：[src/core/conversion-engine.test.ts:1-150]()\n\n## 依赖关系\n\n```mermaid\ngraph TD\n A[conversion-engine.ts] --> B[errors.ts]\n A --> C[ParsedSkill 类型定义]\n C --> D[frontmatter 类型]\n C --> E[section 类型]\n B --> F[SkillLoaderError]\n B --> G[ValidationError]\n B --> H[FileSystemError]\n I[convert-to-steering.ts] --> A\n J[convert-to-power.ts] --> A\n K[import_skill 工具] --> I\n K --> J\n```\n\n## 扩展点\n\n如需扩展转换引擎功能，可考虑以下方向：\n\n1. **新增输出格式**：添加新的转换方法（如 `toPrompt` 或 `toAgentConfig`）\n2. **自定义元数据**：扩展 frontmatter 的解析和注入逻辑\n3. **高级章节处理**：增强 `shouldGenerateSteeringDir` 的判断逻辑\n4. **模板支持**：引入模板引擎以支持自定义输出格式\n\n---\n\n\n\n## 安全验证器\n\n### 相关页面\n\n相关主题：[技能获取器](#page-skill-fetcher), [转换引擎](#page-conversion-engine)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/security-validator.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)\n- [src/core/security-validator.test.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.test.ts)\n- [src/core/conversion-engine.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)\n- [src/core/errors.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts)\n- [examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n \n\n# 安全验证器\n\n## 概述\n\n安全验证器（Security Validator）是 Skill Loader MCP Server 的核心安全组件，负责在导入外部技能（Skill）之前对其内容进行全面的安全扫描和风险评估。该组件能够检测危险命令、可疑文件操作、代码注入模式和不受信任的来源，从而保护用户系统免受潜在恶意代码的侵害。\n\n安全验证器的主要职责包括：\n\n- 扫描技能内容中的危险系统命令\n- 检测可疑的文件路径访问\n- 识别代码注入模式（如变量展开和命令替换）\n- 验证技能来源的可信度\n- 提供详细的验证结果和修复建议\n\n资料来源：[src/core/security-validator.ts:1-50]()\n\n## 架构设计\n\n### 模块位置\n\n安全验证器位于 `src/core/security-validator.ts`，是核心模块的重要组成部分。项目的目录结构如下：\n\n```\nskill-loader-mcp-server/\n├── src/\n│ ├── core/ # 核心功能模块\n│ │ ├── security-validator.ts # 安全验证器\n│ │ ├── conversion-engine.ts # 转换引擎\n│ │ └── errors.ts # 错误处理\n│ ├── tools/ # MCP 工具实现\n│ ├── utils/ # 工具函数\n│ └── index.ts # 主入口点\n├── tests/ # 测试文件\n└── examples/ # 使用示例\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CONTRIBUTING.md)\n\n### 验证流程\n\n安全验证器采用多阶段验证流程，对技能内容进行逐层安全检查：\n\n```mermaid\ngraph TD\n A[接收技能内容] --> B[扫描危险命令]\n B --> C{检测到危险命令?}\n C -->|是| D[标记为 unsafe]\n C -->|否| E[检查可疑文件路径]\n E --> F{检测到可疑路径?}\n F -->|是| G[标记为 unsafe]\n F -->|否| H[检测代码注入模式]\n H --> I{检测到注入模式?}\n I -->|是| J[标记为 warning]\n I -->|否| K[验证来源可信度]\n K --> L{来源可信?}\n L -->|是| M[标记为 safe]\n L -->|否| N[标记为 unsafe]\n D --> O[返回验证结果]\n G --> O\n J --> O\n M --> O\n N --> O\n```\n\n资料来源：[src/core/security-validator.ts:30-45]()\n\n## 验证规则\n\n### 危险命令检测\n\n安全验证器会扫描技能内容中的危险系统命令，这些命令可能对系统造成不可逆的损害。\n\n| 命令模式 | 描述 | 严重级别 |\n|---------|------|---------|\n| `rm -rf` | 递归强制删除命令 | unsafe |\n| `sudo` | 超级用户权限执行 | unsafe |\n| `eval` | 动态代码执行 | unsafe |\n| `exec` | 命令执行函数 | unsafe |\n\n```typescript\n// 危险命令检测逻辑示例\nconst dangerousCommands = ['rm -rf', 'sudo', 'eval', 'exec'];\ndangerousCommands.forEach(cmd => {\n if (content.includes(cmd)) {\n issues.push({\n type: 'dangerous_command',\n description: `危险命令: ${cmd}`,\n location: `Line ${getLineNumber(content, index)}`\n });\n }\n});\n```\n\n资料来源：[src/core/security-validator.ts:50-80]()\n\n### 可疑文件路径检测\n\n验证器会检查技能内容中是否包含对系统关键目录的访问企图。\n\n| 路径模式 | 描述 | 风险级别 |\n|---------|------|---------|\n| `/etc/` | 系统配置文件目录 | warning |\n| `/usr/` | 系统程序目录 | warning |\n| `/bin/` | 二进制可执行文件目录 | warning |\n\n这些路径的访问通常不是普通技能所需的，可能表明存在恶意意图。\n\n资料来源：[src/core/security-validator.ts:80-100]()\n\n### 代码注入模式检测\n\n安全验证器能够识别多种代码注入攻击模式。\n\n| 注入类型 | 模式示例 | 描述 |\n|---------|---------|------|\n| 变量展开 | `${VARIABLE}` | 模板变量展开可能执行任意代码 |\n| 命令替换 | `$(command)` | Shell 命令替换语法 |\n\n```typescript\n// 代码注入检测\nif (content.includes('${')) {\n issues.push({\n type: 'code_injection',\n description: '检测到变量展开模式'\n });\n}\n\nif (content.includes('$(')) {\n issues.push({\n type: 'command_substitution',\n description: '检测到命令替换模式'\n });\n}\n```\n\n资料来源：[src/core/security-validator.ts:100-130]()\n\n### 来源可信度验证\n\n安全验证器会验证技能来源的可靠性。只有来自受信任来源的技能才会被标记为安全。\n\n| 来源类型 | 可信状态 | 说明 |\n|---------|---------|------|\n| GitHub URL | 可信 | GitHub 是主要的技能托管平台 |\n| 其他 URL | 不可信 | 存在安全风险 |\n\n```typescript\nif (url && !url.includes('github.com')) {\n issues.push({\n type: 'untrusted_source',\n description: '技能来源不是受信任的 GitHub URL',\n location: 'Source URL'\n });\n}\n```\n\n资料来源：[src/core/security-validator.ts:130-150]()\n\n## API 接口\n\n### validate_skill 工具\n\n`validate_skill` 是 MCP 服务器提供的安全验证工具，用于验证技能内容的安全性。\n\n**参数定义：**\n\n| 参数名 | 类型 | 必需 | 描述 |\n|-------|------|------|------|\n| content | string | 是 | 要验证的技能内容 |\n| url | string | 否 | 来源 URL 用于验证 |\n\n**返回值结构：**\n\n```json\n{\n \"isValid\": true,\n \"issues\": [\n {\n \"type\": \"dangerous_command\",\n \"description\": \"危险递归删除命令 (rm -rf)\",\n \"location\": \"Line 7: rm -rf /\"\n }\n ],\n \"severity\": \"unsafe\"\n}\n```\n\n**使用示例：**\n\n```json\n{\n \"tool\": \"validate_skill\",\n \"arguments\": {\n \"content\": \"---\\nname: Test\\n---\\n\\n# Test\",\n \"url\": \"https://example.com/skill.md\"\n }\n}\n```\n\n资料来源：[examples/usage-examples.md:1-30]()\n\n### 验证结果对象\n\n验证完成后，系统返回一个结构化的验证结果对象。\n\n```typescript\ninterface ValidationResult {\n isValid: boolean; // 是否通过验证\n issues: ValidationIssue[]; // 发现的问题列表\n severity: 'safe' | 'warning' | 'unsafe'; // 整体严重级别\n}\n```\n\n**严重级别判定规则：**\n\n| 条件 | 判定结果 |\n|-----|---------|\n| 存在 `untrusted_source` 或 `dangerous_command` | unsafe |\n| 仅存在 `suspicious_pattern` | warning |\n| 无任何问题 | safe |\n\n资料来源：[src/core/security-validator.ts:200-220]()\n\n## 错误处理\n\n### ValidationError 类\n\n当验证过程发生错误时，系统会抛出 `ValidationError` 异常。\n\n```typescript\nexport class ValidationError extends SkillLoaderError {\n public readonly validationType: 'format' | 'security' | 'schema' | 'content';\n public readonly lineNumber?: number;\n public readonly details: string[];\n}\n```\n\n**错误类型：**\n\n| 类型 | 描述 | 恢复建议 |\n|-----|------|---------|\n| format | 格式错误 | 验证 YAML frontmatter 格式是否正确 |\n| security | 安全问题 | 手动检查技能内容，使用可信来源的技能 |\n| schema | 结构错误 | 验证技能是否符合 Agent Skills 标准 |\n| content | 内容错误 | 检查内容语法，向技能作者报告问题 |\n\n资料来源：[src/core/errors.ts:80-120]()\n\n### 错误消息格式\n\n```typescript\ngetUserMessage(): string {\n let msg = `Validation Error: ${this.message}\\n`;\n msg += `Type: ${this.validationType}\\n`;\n \n if (this.lineNumber) {\n msg += `Line: ${this.lineNumber}\\n`;\n }\n \n msg += '\\nDetails:\\n';\n for (const detail of this.details) {\n msg += `- ${detail}\\n`;\n }\n \n // 根据验证类型添加恢复建议\n if (this.validationType === 'security') {\n msg += '\\nSuggestions:\\n';\n msg += '- Review the skill content manually\\n';\n msg += '- Contact the skill author about security concerns\\n';\n msg += '- Use a different skill from a trusted source\\n';\n }\n \n return msg;\n}\n```\n\n资料来源：[src/core/errors.ts:120-150]()\n\n## 测试覆盖\n\n安全验证器拥有完整的单元测试覆盖，确保各项安全检测功能的准确性。\n\n### 测试用例列表\n\n| 测试用例 | 测试目标 | 预期结果 |\n|---------|---------|---------|\n| 检测危险删除命令 | `rm -rf /` | 发现问题 |\n| 检测提权命令 | `sudo rm` | 发现问题 |\n| 检测 eval 使用 | `eval $var` | 发现问题 |\n| 检测代码注入 | `${VARIABLE}` | 发现问题 |\n| 检测命令替换 | `$(whoami)` | 发现问题 |\n| 检测可疑模式 | `~/. hidden` | 警告级别 |\n\n资料来源：[src/core/security-validator.test.ts:1-50]()\n\n### 测试实现示例\n\n```typescript\nit('detects dangerous commands', () => {\n const content = makeContent('rm -rf /');\n const result = validator.validate(content);\n expect(result.issues.some(i => i.type === 'dangerous_command')).toBe(true);\n});\n\nit('detects code injection patterns', () => {\n const content = makeContent('Use ${VARIABLE} in template');\n const result = validator.validate(content);\n expect(result.issues.some(i => i.description.includes('Variable expansion'))).toBe(true);\n});\n\nit('returns warning for suspicious patterns only', () => {\n const content = makeContent('Access ~/. hidden files');\n const result = validator.validate(content);\n expect(result.isValid).toBe(true);\n expect(result.severity).toBe('warning');\n});\n```\n\n资料来源：[src/core/security-validator.test.ts:30-60]()\n\n## 与转换引擎的集成\n\n安全验证器是转换引擎（Conversion Engine）工作流程的重要组成部分。在将技能转换为 Kiro 格式之前，系统会自动进行安全验证。\n\n```mermaid\ngraph LR\n A[fetch_skill] --> B[validate_skill]\n B --> C{验证通过?}\n C -->|是| D[convert_to_steering]\n C -->|否| E[返回错误]\n D --> F[导入完成]\n E --> G[跳过或报告]\n```\n\n资料来源：[src/core/conversion-engine.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)\n\n### import_skill 工具\n\n`import_skill` 工具提供了完整的导入工作流程，包含自动安全验证：\n\n```json\n{\n \"tool\": \"import_skill\",\n \"arguments\": {\n \"identifier\": \"anthropics/pdf-extractor\",\n \"outputFormat\": \"power\",\n \"skipValidation\": false\n }\n}\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 必需 | 默认值 | 描述 |\n|-----|------|------|-------|------|\n| identifier | string | 是 | - | 技能标识符 |\n| outputFormat | string | 是 | - | 输出格式：`steering` 或 `power` |\n| skipValidation | boolean | 否 | false | 是否跳过安全验证 |\n\n**响应示例：**\n\n```json\n{\n \"success\": true,\n \"targetPath\": \"~/.kiro/powers/pdf-extractor/POWER.md\",\n \"metadata\": {\n \"validationResult\": {\n \"isValid\": true,\n \"issues\": [],\n \"severity\": \"safe\"\n }\n }\n}\n```\n\n资料来源：[examples/usage-examples.md:80-120]()\n\n## 配置与使用建议\n\n### 何时跳过验证\n\n在某些情况下，用户可能需要跳过安全验证：\n\n| 场景 | 建议 | 风险等级 |\n|-----|------|---------|\n| 内部可信技能 | 可跳过 | 低 |\n| 已人工审查的技能 | 可跳过 | 低 |\n| 来自不可信来源 | 建议保留验证 | 高 |\n| 包含系统命令的技能 | 必须保留验证 | 高 |\n\n### 验证流程建议\n\n建议的技能导入流程如下：\n\n1. **获取技能信息**：使用 `fetch_skill` 获取原始内容\n2. **验证安全性**：使用 `validate_skill` 检查安全问题\n3. **审查结果**：检查返回的 issues 列表\n4. **转换格式**：使用 `convert_to_steering` 或 `convert_to_power` 转换\n5. **导入技能**：根据验证结果决定是否继续\n\n资料来源：[examples/usage-examples.md:120-150]()\n\n## 安全特性总结\n\n安全验证器提供了多层次的安全保护机制：\n\n| 安全功能 | 实现状态 | 描述 |\n|---------|---------|------|\n| 危险命令检测 | ✅ 已实现 | 检测 rm -rf, sudo, eval, exec |\n| 可疑路径检测 | ✅ 已实现 | 检测 /etc/, /usr/, /bin/ |\n| 代码注入检测 | ✅ 已实现 | 检测 ${} 和 $() 模式 |\n| 来源验证 | ✅ 已实现 | 仅允许 GitHub 来源 |\n| 严重级别评估 | ✅ 已实现 | safe/warning/unsafe 三级 |\n| 详细错误信息 | ✅ 已实现 | 包含行号和修复建议 |\n\n资料来源：[src/core/security-validator.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)\n\n---\n\n\n\n## 缓存机制\n\n### 相关页面\n\n相关主题：[核心模块架构](#page-core-modules), [技能获取器](#page-skill-fetcher)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/utils/cache.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/utils/cache.ts)\n- [README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n- [CHANGELOG.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CHANGELOG.md)\n \n\n# 缓存机制\n\n## 概述\n\nSkill Loader MCP Server 实现了一套内存缓存系统，用于提升 API 调用效率并减少网络请求次数。缓存机制的核心设计目标是：\n\n- 减少对 skills.sh 目录 API 的重复调用\n- 提升搜索和列表查询的响应速度\n- 通过 TTL（Time-To-Live）机制确保数据的时效性\n\n缓存系统在项目架构中属于基础工具层，被核心业务模块调用。资料来源：[src/utils/cache.ts:1-20]()\n\n## 核心组件\n\n### CacheEntry 接口\n\n泛型缓存条目接口，存储数据及其时间戳：\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| `data` | `T` | 缓存的数据内容 |\n| `timestamp` | `number` | 缓存创建时间戳（毫秒） |\n\n资料来源：[src/utils/cache.ts:6-10]()\n\n### Cache 类\n\n通用内存缓存类，支持 TTL 过期机制：\n\n```typescript\nexport class Cache {\n private cache: Map> = new Map();\n private ttl: number;\n}\n```\n\n| 属性 | 类型 | 描述 |\n|------|------|------|\n| `cache` | `Map>` | 内部缓存存储结构 |\n| `ttl` | `number` | 缓存有效期（毫秒） |\n\n资料来源：[src/utils/cache.ts:14-17]()\n\n## API 参考\n\n### 构造函数\n\n```typescript\nconstructor(ttl: number)\n```\n\n| 参数 | 类型 | 描述 |\n|------|------|------|\n| `ttl` | `number` | 缓存存活时间（毫秒） |\n\n资料来源：[src/utils/cache.ts:19-24]()\n\n### get 方法\n\n从缓存中获取值，若不存在或已过期则返回 `undefined`：\n\n```typescript\nget(key: string): T | undefined\n```\n\n**执行流程：**\n\n```mermaid\ngraph TD\n A[调用 get 方法] --> B{查找 key 是否存在}\n B -->|不存在| C[返回 undefined]\n B -->|存在| D{检查是否过期}\n D -->|已过期| E[删除 key 并返回 undefined]\n D -->|未过期| F[返回缓存数据]\n```\n\n资料来源：[src/utils/cache.ts:31-50]()\n\n### set 方法\n\n将数据存入缓存，自动记录当前时间戳：\n\n```typescript\nset(key: string, data: T): void\n```\n\n| 参数 | 类型 | 描述 |\n|------|------|------|\n| `key` | `string` | 缓存键名 |\n| `data` | `T` | 要缓存的数据 |\n\n资料来源：[src/utils/cache.ts:57-66]()\n\n### has 方法\n\n检查指定键是否存在且未过期：\n\n```typescript\nhas(key: string): boolean\n```\n\n**返回值说明：**\n\n| 返回值 | 含义 |\n|--------|------|\n| `true` | 键存在且未过期 |\n| `false` | 键不存在或已过期 |\n\n资料来源：[src/utils/cache.ts:73-86]()\n\n## 过期检测机制\n\n缓存条目通过时间戳与当前时间的差值判断是否过期：\n\n```typescript\nif (Date.now() - entry.timestamp > this.ttl) {\n this.cache.delete(key);\n return undefined;\n}\n```\n\n- **当前时间**：`Date.now()` 返回自 1970-01-01 以来的毫秒数\n- **时间差**：当前时间减去缓存创建时间\n- **过期判定**：时间差大于 `ttl` 值时视为过期\n\n资料来源：[src/utils/cache.ts:44-47]()\n\n## 实际应用场景\n\n### skills.sh 目录缓存\n\n项目在生产环境中使用 1 小时 TTL 对 skills.sh 目录搜索结果进行缓存：\n\n> 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.\n\n资料来源：[README.md:95-97]()\n\n### 缓存优势\n\n| 优势 | 说明 |\n|------|------|\n| 减少 API 调用 | 避免重复请求 skills.sh 目录 |\n| 提升响应速度 | 命中缓存时直接返回，无需网络请求 |\n| 自动刷新 | TTL 过期后自动清除，确保数据时效性 |\n\n资料来源：[CHANGELOG.md:10-12]()\n\n## 架构位置\n\n缓存模块位于项目的工具层，被核心业务模块依赖：\n\n```\nskill-loader-mcp-server/\n├── src/\n│ ├── core/ # 核心业务逻辑\n│ ├── tools/ # MCP 工具实现\n│ ├── utils/ # 工具函数（包含 cache.ts）\n│ ├── index.ts # 主入口\n│ └── cli.ts # CLI 入口\n├── examples/ # 使用示例\n├── dist/ # 编译输出\n└── tests/ # 测试文件\n```\n\n资料来源：[CONTRIBUTING.md:10-18]()\n\n## 使用限制\n\n当前缓存实现为**进程级内存缓存**，存在以下限制：\n\n| 限制 | 说明 |\n|------|------|\n| 进程生命周期 | 服务重启后缓存丢失 |\n| 单实例 | 分布式环境下各实例独立缓存 |\n| 内存占用 | 大数据量缓存可能影响内存使用 |\n\n> **注意**：此缓存工具类为未来扩展性提供，项目当前主要依赖 SkillResolver 类的内置缓存功能。\n\n资料来源：[src/utils/cache.ts:3-6]()\n\n## 扩展建议\n\n如需更强的缓存能力，可考虑：\n\n1. **持久化缓存**：接入 Redis 或 Memcached\n2. **分布式缓存**：支持多实例共享\n3. **缓存预热**：服务启动时主动加载热门数据\n4. **缓存统计**：添加命中率和性能指标监控\n\n---\n\n\n\n## 命令行工具\n\n### 相关页面\n\n相关主题：[项目介绍](#page-project-intro)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/cli.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/cli.ts)\n- [test-server.js](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/test-server.js)\n- [examples/mcp-config.json](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/mcp-config.json)\n- [README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n- [CONTRIBUTING.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CONTRIBUTING.md)\n \n\n# 命令行工具\n\nSkill Loader MCP Server 提供了一套完整的命令行工具，用于管理 Claude Skills 的导入、转换和验证操作。本页面详细说明服务器的命令行使用方式、配置参数以及与 Claude Desktop 和 Kiro 的集成方法。\n\n## 概述\n\nSkill Loader MCP Server 的命令行工具是连接 Claude Desktop 与技能仓库的桥梁。通过 MCP（Model Context Protocol）协议，服务器提供了 9 个核心工具函数，涵盖技能发现、获取、验证、格式转换和导入等完整工作流程。资料来源：[README.md:1-50]()\n\n### 支持的运行环境\n\n| 运行方式 | 说明 | 环境变量要求 |\n|---------|------|-------------|\n| Claude Desktop | 通过配置文件集成 | 可选 |\n| Kiro | 通过 mcp.json 配置 | 可选 |\n| 独立运行 | 直接执行二进制 | 可选 |\n| npx | 在线执行 | 可选 |\n\n## 快速开始\n\n### 通过 npx 运行\n\n使用 npx 可以直接运行最新版本的服务器，无需本地安装：\n\n```bash\nnpx -y @goldzulu/skill-loader-mcp-server\n```\n\n资料来源：[README.md:60-65]()\n\n### 独立安装运行\n\n```bash\n# 全局安装\nnpm install -g skill-loader-mcp-server\n\n# 直接运行\nskill-loader-mcp-server\n```\n\n资料来源：[README.md:70-75]()\n\n## Claude Desktop 集成\n\n### 配置文件位置\n\n根据操作系统不同，配置文件位于：\n\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **Linux**: `~/.config/Claude/claude_desktop_config.json`\n\n### 配置示例\n\n在 Claude Desktop 配置文件中添加以下内容：\n\n```json\n{\n \"mcpServers\": {\n \"skill-loader\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@goldzulu/skill-loader-mcp-server\"],\n \"env\": {\n \"SKILLS_SH_API_KEY\": \"your-api-key-here\"\n },\n \"description\": \"Skill Loader MCP Server for managing Claude skills\"\n }\n }\n}\n```\n\n资料来源：[README.md:35-50]()\n\n### 使用可执行文件路径\n\n如果已全局安装，也可以直接指定可执行文件路径：\n\n```json\n{\n \"mcpServers\": {\n \"skill-loader\": {\n \"command\": \"skill-loader-mcp-server\",\n \"env\": {\n \"SKILLS_SH_API_KEY\": \"your-api-key-here\"\n }\n }\n }\n}\n```\n\n## 环境变量配置\n\n### SKILLS_SH_API_KEY\n\n此环境变量用于访问 skills.sh 的高级 API 功能，包括分页列出所有技能和获取排行榜数据。\n\n| 配置状态 | 影响的功能 |\n|---------|-----------|\n| 未设置 | 可使用 search_skills、fetch_skill、validate_skill、convert_*、import_skill |\n| 已设置 | 额外解锁 list_skills、get_leaderboard 功能 |\n\n资料来源：[README.md:90-95]()\n\n### 配置方式\n\n环境变量可以通过配置文件中的 `env` 块设置，也可以在 shell 中预先导出：\n\n```bash\nexport SKILLS_SH_API_KEY=\"your-api-key-here\"\n```\n\n## MCP 工具列表\n\n服务器提供了 9 个 MCP 工具，按功能可分为以下几类：\n\n### 技能发现类\n\n| 工具名称 | 功能 | 认证要求 |\n|---------|------|---------|\n| search_skills | 按关键词搜索技能 | 不需要 |\n| list_skills | 分页列出所有技能 | 需要 API Key |\n| get_leaderboard | 获取热门/趋势技能 | 需要 API Key |\n\n资料来源：[README.md:85-120]()\n\n### 技能获取类\n\n| 工具名称 | 功能 | 认证要求 |\n|---------|------|---------|\n| fetch_skill | 从 GitHub 获取技能原始内容 | 不需要 |\n\n### 技能验证类\n\n| 工具名称 | 功能 | 认证要求 |\n|---------|------|---------|\n| validate_skill | 验证技能内容安全性 | 不需要 |\n\n### 格式转换类\n\n| 工具名称 | 功能 | 认证要求 |\n|---------|------|---------|\n| convert_to_steering | 转换为 Kiro 转向文件格式 | 不需要 |\n| convert_to_power | 转换为 Kiro Power 格式 | 不需要 |\n\n### 导入操作类\n\n| 工具名称 | 功能 | 认证要求 |\n|---------|------|---------|\n| import_skill | 完整导入工作流（获取+验证+转换） | 不需要 |\n\n## 安全验证机制\n\n命令行工具内置了安全验证功能，会在导入前自动扫描技能内容：\n\n### 检测的威胁类型\n\n| 威胁类型 | 示例 | 严重级别 |\n|---------|------|---------|\n| 危险命令 | `rm -rf`、`sudo`、`eval`、`exec` | 不安全 |\n| 可疑文件操作 | `/etc/`、`/usr/`、`/bin/` | 警告 |\n| 代码注入模式 | `${...}`、`$(...)` | 警告 |\n| 不信任来源 | 非 GitHub URL | 不安全 |\n\n资料来源：[README.md:175-185]()\n\n### 验证响应示例\n\n```json\n{\n \"isValid\": false,\n \"issues\": [\n {\n \"type\": \"dangerous_command\",\n \"description\": \"Dangerous recursive delete command (rm -rf)\",\n \"location\": \"Line 7: rm -rf /\"\n }\n ],\n \"severity\": \"unsafe\"\n}\n```\n\n## 典型工作流程\n\n### 流程一：搜索并导入技能\n\n```mermaid\ngraph TD\n A[search_skills 查询关键词] --> B{找到目标技能?}\n B -->|是| C[fetch_skill 获取内容]\n B -->|否| D[调整搜索条件]\n D --> A\n C --> E[validate_skill 安全验证]\n E --> F{验证通过?}\n F -->|是| G[convert_to_steering 或 convert_to_power]\n F -->|否| H[输出安全警告]\n G --> I[技能已转换]\n H --> J[中止导入]\n```\n\n### 流程二：使用 list_skills（需 API Key）\n\n```mermaid\ngraph TD\n A[list_skills 分页获取] --> B{还有更多页面?}\n B -->|是| C[请求下一页]\n C --> A\n B -->|否| D[get_leaderboard 获取趋势]\n D --> E[fetch_skill 获取技能]\n E --> F[import_skill 完整导入]\n```\n\n## 完整导入示例\n\n### 导入为 Steering 文件\n\n```json\n{\n \"tool\": \"import_skill\",\n \"arguments\": {\n \"identifier\": \"anthropics/pdf-extractor\",\n \"outputFormat\": \"steering\",\n \"skipValidation\": false\n }\n}\n```\n\n响应示例：\n\n```json\n{\n \"success\": true,\n \"content\": \"---\\noriginal_skill: PDF Extractor\\n...\",\n \"filename\": \"pdf-extractor.md\",\n \"targetPath\": \".kiro/steering/pdf-extractor.md\",\n \"metadata\": {\n \"skillName\": \"PDF Extractor\",\n \"validationResult\": {\n \"isValid\": true,\n \"issues\": [],\n \"severity\": \"safe\"\n }\n }\n}\n```\n\n### 导入为 Power\n\n```json\n{\n \"tool\": \"import_skill\",\n \"arguments\": {\n \"identifier\": \"anthropics/pdf-extractor\",\n \"outputFormat\": \"power\",\n \"skipValidation\": false\n }\n}\n```\n\n## 缓存机制\n\n服务器内置了智能缓存功能：\n\n| 缓存对象 | TTL | 说明 |\n|---------|-----|------|\n| skills.sh 搜索结果 | 1 小时 | 自动刷新过期缓存 |\n\n资料来源：[README.md:195-200]()\n\n## 错误处理\n\n所有工具返回的错误遵循统一格式：\n\n```json\n{\n \"error\": \"Error message describing what went wrong\",\n \"tool\": \"tool_name\",\n \"timestamp\": \"2024-01-15T10:30:00.000Z\"\n}\n```\n\n### 常见错误场景\n\n| 错误类型 | 原因 | 解决方案 |\n|---------|------|---------|\n| 网络错误 | 互联网连接问题 | 检查网络和 GitHub 可用性 |\n| 未找到错误 | 技能名称或仓库错误 | 验证技能标识符 |\n| 验证错误 | 安全问题 | 导入前审查安全问题 |\n| 解析错误 | 格式问题 | 检查技能格式和 YAML 语法 |\n\n## 传输协议\n\n服务器支持 **stdio 传输协议**，这是 Claude Desktop 和 Kiro 集成的标准方式。stdio 传输通过标准输入输出流进行进程间通信，确保了与 Claude Desktop 的无缝集成。\n\n资料来源：[CONTRIBUTING.md:25-30]()\n\n## 开发调试\n\n### 本地运行测试服务器\n\n项目中提供了 `test-server.js` 用于本地调试和测试。开发者可以使用该脚本启动一个本地测试环境，验证工具行为是否符合预期。\n\n### 本地开发模式\n\n```bash\n# 安装依赖\nnpm install\n\n# 构建项目\nnpm run build\n\n# 运行测试\nnpm test\n\n# 启动服务器\nnpm start\n```\n\n资料来源：[CONTRIBUTING.md:10-15]()\n\n## 输出格式\n\n### Steering 格式输出\n\n当 `outputFormat` 为 `steering` 时，输出包含以下字段：\n\n| 字段 | 类型 | 说明 |\n|-----|------|------|\n| steeringContent | string | 转向文件完整内容 |\n| filename | string | 建议的文件名（kebab-case） |\n| metadata | object | 元数据对象 |\n| metadata.originalSkill | string | 原始技能名称 |\n| metadata.sourceUrl | string | 来源 URL |\n| metadata.importedAt | string | ISO 时间戳 |\n\n### Power 格式输出\n\n当 `outputFormat` 为 `power` 时，输出包含多个文件：\n\n| 文件路径 | 内容说明 |\n|---------|---------|\n| POWER.md | Power 主文件，包含导入元数据 |\n| mcp.json | 可选，技能有依赖或工具引用时生成 |\n| steering/ | 可选目录，技能有 3+ 复杂章节时生成 |\n\n## 相关文档\n\n- [使用示例](./examples/usage-examples.md) - 各工具的详细使用案例\n- [安全验证](./src/core/security-validator.ts) - 安全机制实现细节\n- [错误处理](./src/core/errors.ts) - 错误类定义和使用\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：goldzulu/skill-loader-mcp-server\n\n摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。\n\n## 1. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | host_targets=mcp_host, claude\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | no_demo; severity=medium\n\n## 6. 安全/权限坑 · 来源证据：v1.0.0 - Initial Release\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.0.0 - Initial Release\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fb2ea148b03e4fb5993d3b2db08b43f6 | https://github.com/goldzulu/skill-loader-mcp-server/releases/tag/v1.0.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 7. 安全/权限坑 · 来源证据：v1.1.0 — skills.sh API migration & Power format update\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.1.0 — skills.sh API migration & Power format update\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_78c48e3f6caa41a9bf94d3dba01baf0c | https://github.com/goldzulu/skill-loader-mcp-server/releases/tag/v1.1.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | issue_or_pr_quality=unknown\n\n## 9. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：goldzulu/skill-loader-mcp-server\n\n摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。\n\n## 1. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | host_targets=mcp_host, claude\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | no_demo; severity=medium\n\n## 6. 安全/权限坑 · 来源证据：v1.0.0 - Initial Release\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.0.0 - Initial Release\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fb2ea148b03e4fb5993d3b2db08b43f6 | https://github.com/goldzulu/skill-loader-mcp-server/releases/tag/v1.0.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 7. 安全/权限坑 · 来源证据：v1.1.0 — skills.sh API migration & Power format update\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.1.0 — skills.sh API migration & Power format update\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_78c48e3f6caa41a9bf94d3dba01baf0c | https://github.com/goldzulu/skill-loader-mcp-server/releases/tag/v1.1.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | issue_or_pr_quality=unknown\n\n## 9. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# skill-loader-mcp-server - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 skill-loader-mcp-server 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client / claude\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: MCP server for discovering, fetching, validating, and converting Claude skills from skills.sh and GitHub repositories 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-project-intro：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-mcp-tools：MCP工具详解。围绕“MCP工具详解”模拟一次用户任务，不展示安装或运行结果。\n3. page-core-modules：核心模块架构。围绕“核心模块架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-skill-resolver：技能解析器。围绕“技能解析器”模拟一次用户任务，不展示安装或运行结果。\n5. page-skill-fetcher：技能获取器。围绕“技能获取器”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-project-intro\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-mcp-tools\n输入：用户提供的“MCP工具详解”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-core-modules\n输入：用户提供的“核心模块架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-skill-resolver\n输入：用户提供的“技能解析器”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-skill-fetcher\n输入：用户提供的“技能获取器”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-project-intro：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-mcp-tools：Step 2 必须围绕“MCP工具详解”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-core-modules：Step 3 必须围绕“核心模块架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-skill-resolver：Step 4 必须围绕“技能解析器”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-skill-fetcher：Step 5 必须围绕“技能获取器”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/goldzulu/skill-loader-mcp-server\n- https://github.com/goldzulu/skill-loader-mcp-server#readme\n- README.md\n- package.json\n- src/index.ts\n- src/tools/list-skills.ts\n- src/tools/search-skills.ts\n- src/tools/get-leaderboard.ts\n- src/tools/fetch-skill.ts\n- src/tools/validate-skill.ts\n- src/tools/convert-to-steering.ts\n- src/tools/convert-to-power.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 skill-loader-mcp-server 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：goldzulu/skill-loader-mcp-server\n\n## 官方安装入口\n\n### Node.js / npm · 官方安装入口\n\n```bash\nnpm install -g @goldzulu/skill-loader-mcp-server\n```\n\n来源：https://github.com/goldzulu/skill-loader-mcp-server#readme\n\n## 来源\n\n- repo: https://github.com/goldzulu/skill-loader-mcp-server\n- docs: https://github.com/goldzulu/skill-loader-mcp-server#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_8ce4d558491d446bb0dcf2ba3b02b025"
}