{
"canonical_name": "goldzulu/skill-loader-mcp-server",
"compilation_id": "pack_33d88641981644d1acdfa8fec52dd433",
"created_at": "2026-05-24T13:35:39.263158+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 Data Extraction",
"label_zh": "结构化数据提取",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-structured-data-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": "Open Source Tool",
"label_zh": "开源工具",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-open-source-tool",
"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> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for goldzulu/skill-loader-mcp-server.\n\nProject:\n- Name: skill-loader-mcp-server\n- Repository: https://github.com/goldzulu/skill-loader-mcp-server\n- Summary: MCP server for discovering, fetching, validating, and converting Claude skills from skills.sh and GitHub repositories\n- Host target: mcp_host, claude\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: MCP server for discovering, fetching, validating, and converting Claude skills from skills.sh and GitHub repositories\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: MCP server for discovering, fetching, validating, and converting Claude skills from skills.sh and GitHub repositories\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. getting-started: Getting Started. Produce one small intermediate artifact and wait for confirmation.\n2. project-structure: Project Structure. Produce one small intermediate artifact and wait for confirmation.\n3. mcp-server-architecture: MCP Server Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. core-modules: Core Modules. Produce one small intermediate artifact and wait for confirmation.\n5. mcp-tools-reference: MCP Tools Reference. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\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/cli.ts\n- tsconfig.json\n- src/core/conversion-engine.ts\n- src/core/security-validator.ts\n- src/core/skill-fetcher.ts\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\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-18 02:39:22 UTC\n\n## 目录\n\n- [Getting Started](#getting-started)\n- [Project Structure](#project-structure)\n- [MCP Server Architecture](#mcp-server-architecture)\n- [Core Modules](#core-modules)\n- [MCP Tools Reference](#mcp-tools-reference)\n- [Skill Discovery](#skill-discovery)\n- [Security Validation](#security-validation)\n- [Format Conversion](#format-conversion)\n- [Caching System](#caching-system)\n- [Type Definitions](#type-definitions)\n- [Deployment and Configuration](#deployment)\n- [Error Handling](#error-handling)\n\n\n\n## Getting Started\n\n### 相关页面\n\n相关主题：[Deployment and Configuration](#deployment), [MCP Server Architecture](#mcp-server-architecture)\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- [CONTRIBUTING.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CONTRIBUTING.md)\n- [CHANGELOG.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CHANGELOG.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 \n\n# Getting Started\n\nThe **Skill Loader MCP Server** is a Model Context Protocol (MCP) server that enables discovery, fetching, validation, and conversion of Claude Skills from the skills.sh marketplace into formats compatible with the Kiro platform. This guide provides everything you need to install, configure, and begin using the server effectively.\n\n## Overview\n\nThe Skill Loader MCP Server acts as a bridge between the skills.sh marketplace and local skill management systems. It provides a unified interface for:\n\n- Discovering available skills through search and browsing\n- Fetching skill content directly from GitHub repositories\n- Validating skill content for security issues before import\n- Converting skills to Kiro steering file format or power format\n- Performing complete end-to-end skill imports with a single command\n\n资料来源：[README.md:1-10]()\n\n### Architecture Overview\n\n```mermaid\ngraph TD\n A[Client] -->|MCP Protocol| B[Skill Loader MCP Server]\n B --> C[Skills.sh API]\n B --> D[GitHub Raw Content]\n \n C -->|Search Results| E[list_skills]\n C -->|Trending Data| F[get_leaderboard]\n D -->|Raw .md| G[fetch_skill]\n \n G --> H[validate_skill]\n H -->|Safe| I[convert_to_steering]\n H -->|Safe| J[convert_to_power]\n \n I --> K[Kiro Steering Files]\n J --> L[Kiro Power Format]\n \n G --> M[import_skill]\n M --> H\n M -->|Validated| I\n M -->|Validated| J\n```\n\n## Prerequisites\n\nBefore installing the Skill Loader MCP Server, ensure your environment meets the following requirements:\n\n| Requirement | Version/Details |\n|-------------|------------------|\n| Node.js | v18.0.0 or higher |\n| npm or yarn | Latest stable version |\n| Git | Installed and configured |\n| Skills.sh API Key | Optional (required only for `list_skills` and `get_leerboard`) |\n\n资料来源：[CONTRIBUTING.md:1-5]()\n\n## Installation\n\n### Global Installation\n\nFor system-wide access, install the package globally using npm:\n\n```bash\nnpm install -g @goldzulu/skill-loader-mcp-server\n```\n\n资料来源：[README.md:30-32]()\n\n### Local Installation\n\nFor project-specific usage, install locally:\n\n```bash\nnpm install @goldzulu/skill-loader-mcp-server\n```\n\n资料来源：[README.md:34-36]()\n\n## Configuration\n\n### Environment Variables\n\nThe server uses a single environment variable for authenticated API access:\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `SKILLS_SH_API_KEY` | No | API key for the skills.sh authenticated `/api/v1/skills` endpoint. Required only for `list_skills` and `get_leaderboard` tools. Not required for `search_skills`. |\n\n资料来源：[README.md:43-47]()\n\n### Configuration with Kiro\n\nAdd the server to your Kiro configuration file (`mcp.json`):\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:53-64]()\n\n### Configuration with Claude Desktop\n\nFor Claude Desktop integration, add to your configuration:\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资料来源：[README.md:70-80]()\n\n## Available Tools\n\nThe server provides eight MCP tools for skill management. Each tool accepts JSON-formatted arguments and returns structured responses.\n\n资料来源：[README.md:82-100]()\n\n### Tool Overview\n\n| Tool | Authentication | Purpose |\n|------|----------------|---------|\n| `search_skills` | Not required | Search skills by keyword |\n| `list_skills` | Required | List all available skills with pagination |\n| `get_leaderboard` | Required | Get trending or top-installed skills |\n| `fetch_skill` | Not required | Fetch raw skill content from GitHub |\n| `validate_skill` | Not required | Validate skill content for security issues |\n| `convert_to_steering` | Not required | Convert skill to Kiro steering file format |\n| `convert_to_power` | Not required | Convert skill to Kiro power format |\n| `import_skill` | Not required | Complete import workflow (fetch + validate + convert) |\n\n资料来源：[README.md:82-100]()\n\n### 1. search_skills\n\nSearch for skills by keyword using the skills.sh public search API. No authentication required.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `query` | string | Yes | - | Search query |\n| `limit` | number | No | 20 | Maximum results (max: 50) |\n\n**Example Request:**\n```json\n{\n \"tool\": \"search_skills\",\n \"arguments\": {\n \"query\": \"pdf\",\n \"limit\": 5\n }\n}\n```\n\n**Example Response:**\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资料来源：[examples/usage-examples.md:1-50]()\n\n### 2. list_skills\n\nList all available skills from skills.sh with pagination. Requires `SKILLS_SH_API_KEY`.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `page` | number | No | 1 | Page number |\n| `pageSize` | number | No | 50 | Results per page (max: 100) |\n\n**Example Request:**\n```json\n{\n \"tool\": \"list_skills\",\n \"arguments\": {\n \"page\": 1,\n \"pageSize\": 10\n }\n}\n```\n\n资料来源：[README.md:102-115]()\n\n### 3. get_leaderboard\n\nGet trending or top-installed skills. Requires `SKILLS_SH_API_KEY`.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `timeframe` | string | No | `'all'` | `'all'` or `'24h'` |\n| `limit` | number | No | 20 | Maximum results (max: 50) |\n\n**Example Request:**\n```json\n{\n \"tool\": \"get_leaderboard\",\n \"arguments\": {\n \"timeframe\": \"24h\",\n \"limit\": 10\n }\n}\n```\n\n**Example Response:**\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资料来源：[examples/usage-examples.md:90-120]()\n\n### 4. fetch_skill\n\nFetch raw skill content directly from GitHub. Supports both simple skill names and `owner/repo` format.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `identifier` | string | Yes | Skill name or `owner/repo` format |\n\n**Example Request:**\n```json\n{\n \"tool\": \"fetch_skill\",\n \"arguments\": {\n \"identifier\": \"anthropics/pdf-extractor\"\n }\n}\n```\n\n**Example Response:**\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:130-165]()\n\n### 5. validate_skill\n\nValidate skill content for security issues before importing. This tool scans for dangerous commands, suspicious patterns, and untrusted sources.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `content` | string | Yes | Skill content to validate |\n| `url` | string | No | Source URL for verification |\n\n**Example Request:**\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**Security Checks Performed:**\n\n| Check Type | Description |\n|------------|-------------|\n| `dangerous_command` | Commands like `rm -rf`, `sudo`, `eval`, `exec` |\n| `suspicious_file_operation` | Access to system directories (`/etc/`, `/usr/`, `/bin/`) |\n| `code_injection` | Patterns like `${...}`, `$(...)` |\n| `untrusted_source` | Non-GitHub source URLs |\n\n资料来源：[README.md:155-175]()\n\n**Severity Levels:**\n\n| Severity | Conditions |\n|----------|------------|\n| `safe` | No issues found |\n| `warning` | Suspicious patterns detected |\n| `unsafe` | Dangerous commands or untrusted sources |\n\n资料来源：[src/core/security-validator.ts:1-30]()\n\n### 6. convert_to_steering\n\nConvert skill content to Kiro steering file format. This format adds metadata headers and preserves the original skill structure.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `content` | string | Yes | Skill content |\n| `sourceUrl` | string | No | Original source URL |\n\n**Example Request:**\n```json\n{\n \"tool\": \"convert_to_steering\",\n \"arguments\": {\n \"content\": \"---\\nname: PDF Extractor\\ndescription: Extract text from PDF files\\n---\\n\\n# PDF Extractor\\n\\nExtract text content from PDF documents.\",\n \"sourceUrl\": \"https://raw.githubusercontent.com/anthropics/skills/main/skills/pdf-extractor/SKILL.md\"\n }\n}\n```\n\n资料来源：[examples/usage-examples.md:195-220]()\n\n### 7. convert_to_power\n\nConvert skill to Kiro power format. This generates additional configuration files based on skill complexity:\n\n- **mcp.json**: Generated when the skill has dependencies or MCP server references\n- **steering/ directory**: Generated when the skill has 3+ complex sections\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `content` | string | Yes | Skill content |\n| `sourceUrl` | string | No | Original source URL |\n\n**Example Request:**\n```json\n{\n \"tool\": \"convert_to_power\",\n \"arguments\": {\n \"content\": \"---\\nname: Test\\ndescription: A test skill\\n---\\n\\n# Test\",\n \"sourceUrl\": \"https://example.com/skill.md\"\n }\n}\n```\n\n资料来源：[README.md:190-205]()\n\n### 8. import_skill\n\nComplete import workflow combining fetch, validate, and convert operations in a single command.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `identifier` | string | Yes | Skill identifier (`owner/skill-name` format) |\n| `outputFormat` | string | Yes | `'steering'` or `'power'` |\n| `skipValidation` | boolean | No | Skip security validation (default: false) |\n\n**Example Request (Steering Format):**\n```json\n{\n \"tool\": \"import_skill\",\n \"arguments\": {\n \"identifier\": \"anthropics/pdf-extractor\",\n \"outputFormat\": \"steering\"\n }\n}\n```\n\n**Example Response:**\n```json\n{\n \"success\": true,\n \"content\": \"---\\noriginal_skill: PDF Extractor\\nsource_url: https://raw.githubusercontent.com/anthropics/skills/main/skills/pdf-extractor/SKILL.md\\nimported_at: '2024-01-15T10:30:00.000Z'\\n---\\n\\n...\",\n \"filename\": \"pdf-extractor.md\",\n \"targetPath\": \".kiro/steering/pdf-extractor.md\",\n \"metadata\": {\n \"skillName\": \"PDF Extractor\",\n \"sourceUrl\": \"https://raw.githubusercontent.com/anthropics/skills/main/skills/pdf-extractor/SKILL.md\",\n \"outputFormat\": \"steering\",\n \"validationResult\": {\n \"isValid\": true,\n \"issues\": [],\n \"severity\": \"safe\"\n }\n }\n}\n```\n\n资料来源：[examples/usage-examples.md:250-280]()\n\n## Common Workflows\n\n### Discovery and Import Workflow\n\n```mermaid\ngraph LR\n A[Search Skills] --> B[Find Interesting Skill]\n B --> C[Fetch Skill]\n C --> D{Validate}\n D -->|Issues Found| E[Review Security Issues]\n D -->|Safe| F[Choose Format]\n E -->|Override| F\n F --> G[Import as Steering]\n F --> H[Import as Power]\n```\n\n### Quick Start: Discover and Import\n\n1. Search for skills by keyword:\n```json\n{ \"tool\": \"search_skills\", \"arguments\": { \"query\": \"pdf\", \"limit\": 20 } }\n```\n\n2. Import a trending skill:\n```json\n{ \"tool\": \"import_skill\", \"arguments\": { \"identifier\": \"owner/skill-name\", \"outputFormat\": \"power\" } }\n```\n\n### Validate Before Importing\n\n1. Fetch the skill:\n```json\n{ \"tool\": \"fetch_skill\", \"arguments\": { \"identifier\": \"unknown/skill\" } }\n```\n\n2. Validate the content:\n```json\n{ \"tool\": \"validate_skill\", \"arguments\": { \"content\": \"...\", \"url\": \"...\" } }\n```\n\n3. If safe, convert and use:\n```json\n{ \"tool\": \"convert_to_steering\", \"arguments\": { \"content\": \"...\", \"sourceUrl\": \"...\" } }\n```\n\n资料来源：[examples/usage-examples.md:330-360]()\n\n## Caching\n\nThe server implements in-memory caching for skills.sh search results to reduce API calls and improve performance.\n\n| Cache Property | Value |\n|----------------|-------|\n| Storage | In-memory |\n| TTL | 1 hour |\n| Refresh | Automatic on expiration |\n\n资料来源：[README.md:180-182]()\n\n## Error Handling\n\nAll tools return errors in a consistent format:\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### Common Error Scenarios\n\n| Error Type | Resolution |\n|------------|------------|\n| Network errors | Check internet connection, GitHub availability |\n| Not found errors | Verify skill name and repository |\n| Validation errors | Review security issues before proceeding |\n| Parsing errors | Check skill format and YAML syntax |\n\n资料来源：[examples/usage-examples.md:365-375]()\n\n## Development Setup\n\nFor local development and contribution:\n\n```bash\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n\n# Run tests\nnpm test\n```\n\n资料来源：[CONTRIBUTING.md:8-14]()\n\n### Project Structure\n\n```\nskill-loader-mcp-server/\n├── src/\n│ ├── core/ # Core functionality\n│ │ ├── conversion-engine.ts\n│ │ ├── security-validator.ts\n│ │ └── errors.ts\n│ ├── tools/ # MCP tool implementations\n│ ├── utils/ # Utility functions\n│ ├── index.ts # Main entry point\n│ └── cli.ts # CLI entry point\n├── examples/ # Usage examples\n├── dist/ # Compiled output\n└── tests/ # Test files\n```\n\n资料来源：[CONTRIBUTING.md:16-28]()\n\n## Supported Versions\n\n| Version | Status | Notes |\n|---------|--------|-------|\n| 1.1.0 | Latest | Updated to `@modelcontextprotocol/sdk` v1.29 |\n| 1.0.0 | Previous | Initial release |\n\n资料来源：[CHANGELOG.md:1-10]()\n\n## Next Steps\n\n- Review the [Usage Examples](examples/usage-examples.md) for detailed tool demonstrations\n- Check the [CONTRIBUTING.md](CONTRIBUTING.md) if you wish to contribute to the project\n- Explore the [CHANGELOG.md](CHANGELOG.md) for version history and recent changes\n\n---\n\n\n\n## Project Structure\n\n### 相关页面\n\n相关主题：[Getting Started](#getting-started), [Core Modules](#core-modules)\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/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- [CONTRIBUTING.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CONTRIBUTING.md)\n \n\n# Project Structure\n\nThe skill-loader-mcp-server is a Model Context Protocol (MCP) server that enables discovery, fetching, validation, and conversion of Claude skills from the skills.sh marketplace. The project follows a modular architecture with clear separation between core functionality, MCP tool implementations, and utility modules.\n\n## Architecture Overview\n\nThe server is built on the `@modelcontextprotocol/sdk` framework and exposes 9 MCP tools for skill management operations. The architecture follows a layered pattern where the core layer handles business logic, the tools layer exposes MCP-compatible interfaces, and the utils layer provides shared functionality.\n\n```mermaid\ngraph TD\n A[Client] --> B[MCP Server Entry]\n B --> C[Tool Handlers]\n C --> D[Core Services]\n C --> E[SkillResolver]\n C --> F[ConversionEngine]\n C --> G[SecurityValidator]\n D --> H[skills.sh API]\n D --> I[GitHub API]\n G --> J[Error System]\n```\n\n## Directory Structure\n\n```\nskill-loader-mcp-server/\n├── src/\n│ ├── core/ # Core business logic\n│ ├── tools/ # MCP tool implementations\n│ ├── utils/ # Utility functions\n│ ├── index.ts # Main entry point\n│ └── cli.ts # CLI entry point\n├── examples/ # Usage examples\n├── dist/ # Compiled output\n├── tests/ # Test files\n├── package.json\n└── tsconfig.json\n```\n\n### Source Directory Organization\n\nThe `src/` directory contains the primary application code organized into functional layers:\n\n| Directory | Purpose | Key Files |\n|-----------|---------|-----------|\n| `core/` | Business logic and domain operations | `conversion-engine.ts`, `security-validator.ts`, `errors.ts` |\n| `tools/` | MCP tool handler implementations | Tool definitions and handlers |\n| `utils/` | Shared utility functions | Parsers, helpers, constants |\n\n## Entry Points\n\nThe project provides two entry points for different execution contexts.\n\n### Main Entry Point (index.ts)\n\nThe primary entry point initializes the MCP server with stdio transport and registers all available tools. This is the standard entry used when the server runs as an MCP server integration.\n\n```typescript\n// Conceptual structure from src/index.ts\nimport { Server } from '@modelcontextprotocol/sdk/server/index.js';\nimport { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';\n\nconst server = new Server(\n { name: 'skill-loader', version: '1.1.0' },\n { capabilities: { tools: {} } }\n);\n\n// Register tools and start transport\nconst transport = new StdioServerTransport();\nawait server.connect(transport);\n```\n\n资料来源：[CONTRIBUTING.md:23-24]()\n\n### CLI Entry Point (cli.ts)\n\nThe CLI entry point provides standalone execution capability, allowing the server to run as a command-line utility. This is useful for direct invocation and debugging scenarios.\n\n资料来源：[CONTRIBUTING.md:19]()\n\n## Core Layer Modules\n\n### Conversion Engine\n\nThe conversion engine (`src/core/conversion-engine.ts`) handles transformation of skills between different formats. It supports conversion to steering files and power formats with additional generation capabilities.\n\n**Key Responsibilities:**\n\n- Parse YAML frontmatter and markdown body from skill content\n- Convert to Kiro steering file format with metadata preservation\n- Generate POWER.md content with dependencies section\n- Create `mcp.json` for skills with dependencies or tool references\n- Generate `steering/` directory for skills with multiple complex sections\n- Extract keywords from descriptions for metadata\n\n**Conversion Output Formats:**\n\n| Format | Output File | Generation Triggers |\n|--------|-------------|---------------------|\n| Steering | `filename.md` | Standard conversion |\n| Power | `POWER.md` | Power format conversion |\n| MCP Config | `mcp.json` | Skills with dependencies or MCP server references |\n| Steering Directory | `steering/*.md` | Skills with 3+ complex sections |\n\n资料来源：[src/core/conversion-engine.ts:1-200]()\n\n### Security Validator\n\nThe security validator (`src/core/security-validator.ts`) scans skill content for potential security threats before import. It provides a consistent validation interface across all import operations.\n\n**Security Checks Performed:**\n\n| Check Type | Description | Severity |\n|------------|-------------|----------|\n| `dangerous_command` | Commands like `rm -rf`, `sudo`, `eval`, `exec` | unsafe |\n| `suspicious_path` | Access to system paths (`/etc/`, `/usr/`, `/bin/`) | unsafe |\n| `code_injection` | Injection patterns (`${...}`, `$(...)`) | warning |\n| `untrusted_source` | Non-GitHub URLs | unsafe |\n\n**Severity Levels:**\n\n- **safe**: No issues detected\n- **warning**: Suspicious patterns found, import allowed\n- **unsafe**: Dangerous patterns detected, import blocked\n\n资料来源：[src/core/security-validator.ts:1-100]()\n\n### Error Handling System\n\nThe error system (`src/core/errors.ts`) provides structured error types with recovery suggestions. All errors extend a base `SkillLoaderError` class with context tracking.\n\n**Error Hierarchy:**\n\n| Error Class | Use Case | Context Fields |\n|-------------|----------|----------------|\n| `NetworkError` | GitHub/API connectivity failures | `statusCode`, `url` |\n| `ValidationError` | Format, security, schema issues | `validationType`, `details` |\n| `FileSystemError` | Permission, disk, path issues | `operation`, `filePath` |\n| `SkillLoaderError` | Base class for all errors | `operation`, `timestamp` |\n\n资料来源：[src/core/errors.ts:1-150]()\n\n## Tool Layer\n\nThe tools layer implements MCP-compatible handlers that expose core functionality to MCP clients. Each tool follows a consistent pattern of parameter validation, execution, and response formatting.\n\n### Available MCP Tools\n\n| Tool | Purpose | Authentication Required |\n|------|---------|------------------------|\n| `search_skills` | Search skills.sh by keyword | No |\n| `list_skills` | Paginated listing of all skills | Yes (API key) |\n| `get_leaderboard` | Trending/top-installed skills | Yes (API key) |\n| `fetch_skill` | Download skill content from GitHub | No |\n| `validate_skill` | Security scan for dangerous patterns | No |\n| `convert_to_steering` | Convert to Kiro steering format | No |\n| `convert_to_power` | Convert to Kiro power format | No |\n| `import_skill` | Complete workflow (fetch + validate + convert) | No |\n\n资料来源：[README.md:40-120]()\n\n## Data Flow\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Server\n participant Resolver\n participant Validator\n participant Converter\n participant External\n\n Client->>Server: import_skill(identifier, format)\n Server->>Resolver: fetchSkill(identifier)\n Resolver->>External: GET GitHub raw content\n External-->>Resolver: SKILL.md content\n Resolver-->>Server: rawContent\n Server->>Validator: validate(content, url)\n Validator-->>Server: ValidationResult\n Server->>Converter: convert(content, format, url)\n Converter-->>Server: ConvertResult\n Server-->>Client: ImportResult\n\n alt skipValidation = true\n Server->>Converter: Skip validation\n end\n```\n\n## Module Dependencies\n\n```mermaid\ngraph TD\n A[index.ts] --> B[tools/*]\n B --> C[core/ConversionEngine]\n B --> D[core/SkillResolver]\n B --> E[core/SecurityValidator]\n C --> F[core/errors.ts]\n D --> F\n E --> F\n C --> G[utils/*]\n D --> G\n```\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `SKILLS_SH_API_KEY` | For `list_skills` and `get_leaderboard` only | API key for authenticated skills.sh API endpoint |\n\n资料来源：[README.md:28-35]()\n\n### TypeScript Configuration\n\nThe project uses TypeScript with strict mode enabled. Key configuration in `tsconfig.json`:\n\n- ES2022 target for modern JavaScript features\n- ES modules (`module: nodenext`)\n- Strict type checking enabled\n- Path aliases for clean imports\n\n资料来源：[tsconfig.json](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/tsconfig.json)\n\n## Build and Deployment\n\n### Build Process\n\n```bash\n# Install dependencies\nnpm install\n\n# Build TypeScript\nnpm run build\n\n# Output to dist/ directory\n```\n\n### Deployment Targets\n\n| Target | Entry Point | Transport |\n|--------|-------------|-----------|\n| Kiro MCP | `index.ts` | stdio |\n| Claude Desktop | `index.ts` | stdio |\n| Standalone CLI | `cli.ts` | stdio/terminal |\n\n资料来源：[README.md:20-55]()\n\n## Testing Structure\n\nThe `tests/` directory follows the project structure with test files mirroring source file organization. Tests use descriptive naming and follow the pattern:\n\n```\ntests/\n├── core/\n│ ├── conversion-engine.test.ts\n│ ├── security-validator.test.ts\n│ └── errors.test.ts\n└── tools/\n └── *.test.ts\n```\n\n资料来源：[CONTRIBUTING.md:80-100]()\n\n## Summary\n\nThe project architecture emphasizes separation of concerns with a clear hierarchy from entry points through tool handlers to core services. The core layer is framework-agnostic and handles all business logic including skill fetching, validation, and conversion. The tools layer provides MCP-compatible interfaces while delegating to core services. This design allows for easy testing, maintainability, and extension of new features.\n\n---\n\n\n\n## MCP Server Architecture\n\n### 相关页面\n\n相关主题：[MCP Tools Reference](#mcp-tools-reference), [Getting Started](#getting-started)\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- [package.json](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/package.json)\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- [src/core/security-validator.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.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# MCP Server Architecture\n\nThe Skill Loader MCP Server is a Model Context Protocol (MCP) server implementation that enables AI assistants to discover, fetch, validate, and import Claude skills from the skills.sh marketplace. Built on the `@modelcontextprotocol/sdk`, it provides a comprehensive toolset for skill management with enterprise-grade security validation.\n\n## Architecture Overview\n\nThe server follows a layered architecture pattern with clear separation between the transport layer, tool handlers, core services, and utilities.\n\n```mermaid\ngraph TD\n subgraph Transport Layer\n STDIO[Stdio Transport]\n HTTP[HTTP/SSE Transport]\n end\n\n subgraph MCP SDK\n Server[MCP Server Instance]\n Handlers[Request Handlers]\n end\n\n subgraph Core Services\n SR[SkillResolver]\n SV[SecurityValidator]\n CE[ConversionEngine]\n Cache[In-Memory Cache]\n end\n\n subgraph External Services\n SkillsAPI[skills.sh API]\n GitHub[GitHub API]\n end\n\n STDIO --> Server\n HTTP --> Server\n Server --> Handlers\n Handlers --> SR\n Handlers --> SV\n Handlers --> CE\n SR --> Cache\n SR --> SkillsAPI\n SR --> GitHub\n CE --> SV\n```\n\n### Core Components\n\n| Component | Responsibility | Key Files |\n|-----------|---------------|-----------|\n| **MCP Server** | Protocol handling, request routing | `src/index.ts` |\n| **CLI Entry** | Application bootstrap | `src/cli.ts` |\n| **SkillResolver** | Fetches skills from GitHub and skills.sh API | Core service |\n| **SecurityValidator** | Scans for dangerous patterns | `src/core/security-validator.ts` |\n| **ConversionEngine** | Transforms skill formats | `src/core/conversion-engine.ts` |\n| **Error System** | Unified error handling | `src/core/errors.ts` |\n\n## Server Initialization\n\nThe server is initialized with the `@modelcontextprotocol/sdk` version 1.29 and configured with stdio transport for maximum compatibility.\n\n```typescript\n// Simplified initialization pattern\nimport { Server } from \"@modelcontextprotocol/sdk/server/index.js\";\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\n\nconst server = new Server(\n { name: \"skill-loader\", version: \"1.x.x\" },\n { capabilities: { tools: {} } }\n);\n\nconst transport = new StdioServerTransport();\nawait server.connect(transport);\n```\n\n资料来源：[README.md:1-50]()\n\nThe server supports both stdio transport (for CLI and desktop integrations) and can be configured for HTTP/SSE transport when deployed as a network service.\n\n## Tool System\n\nThe server exposes 8 MCP tools that provide complete skill management capabilities:\n\n### Tool Overview\n\n| Tool | Purpose | Authentication Required |\n|------|---------|------------------------|\n| `search_skills` | Search marketplace by keyword | No |\n| `list_skills` | Paginated skill directory | Yes (API Key) |\n| `get_leaderboard` | Trending/popular skills | Yes (API Key) |\n| `fetch_skill` | Download skill content from GitHub | No |\n| `validate_skill` | Security scan skill content | No |\n| `convert_to_steering` | Transform to Kiro steering format | No |\n| `convert_to_power` | Transform to Kiro power format | No |\n| `import_skill` | Complete workflow (fetch + validate + convert) | No |\n\n资料来源：[README.md:50-120]()\n\n### Tool Request Flow\n\n```mermaid\nsequence diagram\n participant Client\n participant Server\n participant Resolver\n participant Validator\n participant Converter\n\n Client->>Server: tool_request\n Server->>Resolver: fetch/resolve skill\n Resolver-->>Server: raw content\n Server->>Validator: scan content\n alt Validation Failed\n Server-->>Client: error with issues\n else Validation Passed\n Server->>Converter: transform content\n Converter-->>Server: formatted output\n end\n Server-->>Client: tool_response\n```\n\n## Core Services\n\n### SkillResolver\n\nThe `SkillResolver` service handles all interactions with external skill sources. It provides:\n\n- **GitHub Resolution**: Parse `owner/repo` identifiers to fetch raw skill content\n- **skills.sh API Integration**: Query marketplace for search, listing, and leaderboard\n- **Content Fetching**: Retrieve raw SKILL.md files from GitHub repositories\n\n```typescript\ninterface ISkillResolver {\n resolveGitHub(identifier: string): Promise;\n searchSkills(query: string, limit: number): Promise;\n listSkills(page: number, pageSize: number): Promise;\n getLeaderboard(timeframe: string, limit: number): Promise;\n}\n```\n\n资料来源：[src/core/conversion-engine.ts:1-50]()\n\nThe resolver supports the skills.sh API v1 responses with types including `SkillsShV1Response`, `SkillsShV1Entry`, and extends `SkillShEntry` with additional fields like `id`, `skillId`, and `source`.\n\n### SecurityValidator\n\nThe `SecurityValidator` service performs comprehensive security scanning on skill content before import.\n\n```typescript\ninterface ValidationIssue {\n type: 'dangerous_command' | 'suspicious_pattern' | 'untrusted_source';\n description: string;\n severity: 'critical' | 'warning' | 'info';\n lineNumber?: number;\n location?: string;\n}\n```\n\n资料来源：[src/core/security-validator.ts:1-80]()\n\n#### Security Checks Performed\n\n| Check Type | Patterns Detected | Severity |\n|------------|-------------------|----------|\n| **Dangerous Commands** | `rm -rf`, `sudo`, `eval`, `exec` | Critical |\n| **Suspicious File Operations** | `/etc/`, `/usr/`, `/bin/` paths | Warning |\n| **Code Injection** | `${...}`, `$(...)` patterns | Critical |\n| **Untrusted Sources** | Non-GitHub URLs | Critical |\n\n#### Severity Determination\n\nThe validator calculates overall severity based on detected issues:\n\n- **Safe**: No issues found\n- **Warning**: Only suspicious patterns detected\n- **Unsafe**: Dangerous commands or untrusted sources present\n\n资料来源：[src/core/security-validator.ts:80-100]()\n\n### ConversionEngine\n\nThe `ConversionEngine` transforms Claude skills into Kiro-compatible formats. It supports two output formats:\n\n#### Steering Format\n\nConverts skills to Kiro steering file format:\n- Preserves skill body content\n- Adds YAML frontmatter with original skill metadata\n- Includes dependencies section if present\n- Adds import attribution footer\n\n```typescript\ninterface SteeringOutput {\n filename: string; // kebab-case derived from skill name\n content: string; // Full steering file content\n metadata: {\n originalSkill: string;\n sourceUrl?: string;\n importedAt: string; // ISO timestamp\n };\n}\n```\n\n资料来源：[src/core/conversion-engine.ts:50-150]()\n\n#### Power Format\n\nConverts skills to Kiro power format with enhanced capabilities:\n\n- **POWER.md**: Primary power definition file\n- **mcp.json** (optional): Generated when skill has dependencies or MCP server references\n- **steering/ directory** (optional): Generated for skills with 3+ complex sections\n\n```typescript\ninterface PowerOutput {\n filename: string; // \"POWER.md\"\n content: string; // Power content with metadata\n files?: Array<{\n path: string;\n content: string;\n }>;\n}\n```\n\n资料来源：[src/core/conversion-engine.ts:150-250]()\n\n#### Format Selection Logic\n\n| Condition | Output Format |\n|-----------|--------------|\n| Skill has no dependencies | Single `STEERING.md` file |\n| Skill has dependencies/tools | `STEERING.md` + `mcp.json` |\n| 3+ complex sections (>200 chars) | Steering directory structure |\n| Full power workflow | `POWER.md` + optional `mcp.json` + optional `steering/` |\n\n资料来源：[src/core/conversion-engine.ts:250-300]()\n\n## Error Handling System\n\nThe server implements a hierarchical error system with specialized error classes for different failure modes.\n\n```mermaid\ngraph TD\n SkillLoaderError[SkillLoaderError]\n NetworkError[NetworkError]\n ValidationError[ValidationError]\n FileSystemError[FileSystemError]\n SkillLoaderError --> NetworkError\n SkillLoaderError --> ValidationError\n SkillLoaderError --> FileSystemError\n```\n\n### Error Class Hierarchy\n\n| Error Class | HTTP Code Support | Use Case |\n|-------------|------------------|----------|\n| `SkillLoaderError` | Base class | All errors |\n| `NetworkError` | 404, 403, 5xx | GitHub/API failures |\n| `ValidationError` | N/A | Format, schema, security issues |\n| `FileSystemError` | N/A | Permission, disk, path issues |\n\n资料来源：[src/core/errors.ts:1-100]()\n\n### Error Response Format\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\nAll errors include recovery suggestions based on error type and context.\n\n## Caching Mechanism\n\nThe server implements in-memory caching for the skills.sh directory to reduce API calls and improve performance.\n\n| Cache Property | Value |\n|---------------|-------|\n| **Storage** | In-memory Map |\n| **TTL** | 1 hour |\n| **Scope** | Search results |\n| **Refresh** | Automatic on expiration |\n\n资料来源：[README.md:180-200]()\n\nCache invalidation is automatic when the TTL expires. No manual cache clearing is required.\n\n## Configuration and Deployment\n\n### Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `SKILLS_SH_API_KEY` | For list/leaderboard only | Authentication for authenticated API endpoints |\n\n### Deployment Targets\n\n```mermaid\ngraph LR\n subgraph Deployment Options\n Kiro[Kiro MCP Config]\n Claude[Claude Desktop]\n CLI[Standalone CLI]\n end\n\n Kiro --> STDIO\n Claude --> STDIO\n CLI --> STDIO\n```\n\n#### Kiro Configuration\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 Configuration\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资料来源：[README.md:30-80]()\n\n## Project Structure\n\n```\nskill-loader-mcp-server/\n├── src/\n│ ├── core/ # Core business logic\n│ │ ├── conversion-engine.ts\n│ │ ├── errors.ts\n│ │ └── security-validator.ts\n│ ├── tools/ # MCP tool implementations\n│ ├── utils/ # Utility functions\n│ ├── index.ts # Server entry point\n│ └── cli.ts # CLI entry point\n├── examples/ # Usage examples\n├── tests/ # Test suite\n├── dist/ # Compiled output\n├── package.json\n└── tsconfig.json\n```\n\n资料来源：[CONTRIBUTING.md:1-30]()\n\n## Dependencies\n\nThe server relies on the following key dependencies:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `@modelcontextprotocol/sdk` | ^1.29 | MCP protocol implementation |\n| `yaml` | Latest | YAML frontmatter parsing |\n| `typescript` | Latest | Type safety |\n\n资料来源：[package.json](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/package.json)\n\n## Complete Import Workflow\n\n```mermaid\ngraph TD\n A[Start: identifier] --> B[Fetch Skill from GitHub]\n B --> C{skipValidation?}\n C -->|No| D[Security Validation]\n C -->|Yes| E[Skip Validation]\n D --> F{isValid?}\n F -->|No| G[Return Error with Issues]\n F -->|Yes| E\n E --> H{outputFormat?}\n H -->|steering| I[Convert to Steering]\n H -->|power| J[Convert to Power]\n I --> K[Add Steering Metadata]\n J --> L[Generate Power Files]\n L --> M{mcp.json needed?}\n L --> N{steering/ needed?}\n M -->|Yes| O[Generate mcp.json]\n M -->|No| P[Skip mcp.json]\n N -->|Yes| Q[Generate steering/]\n N -->|No| R[Skip steering/]\n O --> S[Return Result]\n P --> S\n Q --> S\n R --> S\n```\n\nThe complete workflow is exposed through the `import_skill` tool, which orchestrates fetch, validation, and conversion in a single operation.\n\n资料来源：[examples/usage-examples.md:100-150]()\n\n## Version History\n\n| Version | Date | Key Changes |\n|---------|------|-------------|\n| 1.1.0 | 2026-02-XX | Added mcp.json and steering/ generation |\n| 1.0.0 | 2026-02-03 | Initial release with 8 core tools |\n\n资料来源：[CHANGELOG.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CHANGELOG.md)\n\n---\n\n\n\n## Core Modules\n\n### 相关页面\n\n相关主题：[Format Conversion](#format-conversion), [Security Validation](#security-validation)\n\n\nRelevant Source Files
\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- [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# Core Modules\n\nThe Core Modules of the skill-loader-mcp-server form the foundational layer responsible for skill fetching, parsing, security validation, and format conversion. These modules work together to provide a secure pipeline for importing Claude skills into the Kiro ecosystem.\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[Skill Input] --> B[Skill Fetcher]\n B --> C[Skill Resolver]\n C --> D[Conversion Engine]\n D --> E[Steering Format]\n D --> F[Power Format]\n G[Security Validator] --> D\n G --> C\n H[Error Handler] --> B\n H --> C\n H --> D\n H --> G\n```\n\n## Module Components\n\n### 1. Conversion Engine (`conversion-engine.ts`)\n\nThe Conversion Engine is responsible for transforming parsed skill content into different output formats suitable for various use cases.\n\n#### Key Methods\n\n| Method | Purpose | Output |\n|--------|---------|--------|\n| `parseSkill(content)` | Parses YAML frontmatter and markdown body | `ParsedSkill` object |\n| `toSteeringFile(skill, sourceUrl?)` | Converts to Kiro steering format | Steering file with metadata |\n| `toPower(skill, sourceUrl?)` | Converts to Kiro power format | Power files including `POWER.md` |\n| `extractKeywords(description)` | Extracts 3+ char meaningful words | Array of keywords |\n| `shouldGenerateMcpJson(skill)` | Determines if MCP config needed | Boolean |\n| `shouldGenerateSteeringDir(skill)` | Checks for complex sections | Boolean |\n\n#### Steering File Conversion\n\nThe steering file format preserves the original skill structure with kebab-case naming:\n\n```typescript\n// Transformation rules:\n// 1. Convert to lowercase\n// 2. Replace spaces and underscores with hyphens\n// 3. Remove special characters (keep only a-z, 0-9, and hyphens)\n// 4. Collapse multiple consecutive hyphens into one\n// 5. Remove leading and trailing hyphens\n\n\"PDF Extractor\" → \"pdf-extractor\"\n\"React_Best_Practices\" → \"react-best-practices\"\n```\n\n资料来源：[src/core/conversion-engine.ts:1-50]()\n\n#### Power Format Generation\n\nThe power format generates a more structured output:\n\n```typescript\n// Power structure includes:\n// 1. POWER.md - Main content with displayName frontmatter\n// 2. mcp.json - (optional) MCP server configuration\n// 3. steering/ - (optional) Directory with complex sections\n```\n\n资料来源：[src/core/conversion-engine.ts:150-200]()\n\n#### Steering Directory Generation Logic\n\nThe engine generates a `steering/` directory when the skill has 3+ complex sections (level ≥ 2 with content > 200 characters):\n\n```typescript\nif (this.shouldGenerateSteeringDir(skill)) {\n const steeringContent = this.generateSteeringContent(skill);\n // Creates individual files for each complex section\n}\n```\n\n资料来源：[src/core/conversion-engine.test.ts:1-50]()\n\n---\n\n### 2. Security Validator (`security-validator.ts`)\n\nThe Security Validator provides comprehensive threat detection for skill content before processing.\n\n#### Validation Rules\n\n| Check Type | Patterns Detected | Severity |\n|------------|-------------------|----------|\n| Dangerous Commands | `rm -rf`, `sudo`, `eval`, `exec` | `unsafe` |\n| Suspicious File Operations | `/etc/`, `/usr/`, `/bin/` | `warning` |\n| Code Injection | `${...}`, `$(...)` | `warning` |\n| Untrusted Sources | Non-GitHub URLs | `unsafe` |\n\n#### Severity Levels\n\n```typescript\n'safe' // No issues found\n'warning' // Suspicious patterns detected\n'unsafe' // Dangerous commands or untrusted sources\n```\n\n资料来源：[src/core/security-validator.ts:1-50]()\n\n#### Validation Flow\n\n```mermaid\ngraph LR\n A[Skill Content] --> B{Untrusted Source?}\n B -->|Yes| C[Mark unsafe]\n B -->|No| D{Dangerous Command?}\n D -->|Yes| C\n D -->|No| E{Suspicious Patterns?}\n E -->|Yes| F[Mark warning]\n E -->|No| G[Mark safe]\n```\n\n资料来源：[src/core/security-validator.ts:50-100]()\n\n#### Line Number Detection\n\nThe validator can pinpoint exact locations of issues:\n\n```typescript\nprivate getLineNumber(content: string, index: number): number {\n const lines = content.substring(0, index).split('\\n');\n return lines.length;\n}\n```\n\n---\n\n### 3. Error Handling System (`errors.ts`)\n\nThe error system provides structured error handling across all core modules.\n\n#### Error Class Hierarchy\n\n```mermaid\nclassDiagram\n class SkillLoaderError {\n +string tool\n +string timestamp\n +Record context\n +getUserMessage() string\n }\n class ValidationError {\n +ValidationType validationType\n +ValidationResult result\n }\n class FileSystemError {\n +Operation operation\n +string filePath\n +string systemError?\n }\n class ParsingError {\n +ParsingType parsingType\n +string rawContent\n }\n \n SkillLoaderError <|-- ValidationError\n SkillLoaderError <|-- FileSystemError\n SkillLoaderError <|-- ParsingError\n```\n\n#### ValidationError\n\nHandles security and format validation failures:\n\n```typescript\nexport class ValidationError extends SkillLoaderError {\n public readonly validationType: 'security' | 'format';\n public readonly result: ValidationResult;\n}\n```\n\n**Recovery suggestions:**\n- Security: Review content manually, contact author, use trusted sources\n- Format: Verify YAML syntax, check Agent Skills standard compliance\n\n#### FileSystemError\n\nHandles file system operations:\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**Error codes handled:**\n\n| Code | Cause | Resolution |\n|------|-------|------------|\n| `EACCES`/`EPERM` | Permission denied | Check file permissions |\n| `ENOSPC` | Disk full | Free up space |\n| `ENOENT` | Path not found | Verify directory exists |\n| `EEXIST` | File exists | Use overwrite flag |\n\n资料来源：[src/core/errors.ts:1-100]()\n\n#### ParsingError\n\nHandles YAML and markdown parsing issues:\n\n```typescript\nexport class ParsingError extends SkillLoaderError {\n public readonly parsingType: 'yaml' | 'markdown' | 'frontmatter' | 'metadata';\n}\n```\n\n---\n\n### 4. Skill Fetcher (`skill-fetcher.ts`)\n\nThe Skill Fetcher retrieves raw skill content from GitHub repositories.\n\n#### Fetch Resolution Logic\n\nSkills can be referenced by:\n- **Simple name**: `pdf-extractor` (resolves to `anthropics/skills`)\n- **Full path**: `owner/repo/skill-name`\n\nThe resolver determines the correct GitHub URL and path structure.\n\n资料来源：[README.md:1-50]()\n\n---\n\n### 5. Skill Resolver (`skill-resolver.ts`)\n\nThe Skill Resolver handles skill identification and API interactions with skills.sh.\n\n#### API Methods\n\n| Method | Description | Auth Required |\n|--------|-------------|---------------|\n| `listSkills()` | Paginated skill listing | Yes |\n| `searchSkills()` | Public keyword search | No |\n| `getLeaderboard()` | Trending skills | Yes |\n\n资料来源：[README.md:50-100]()\n\n#### Type Definitions\n\n```typescript\ninterface SkillsShV1Response {\n skills: SkillsShV1Entry[];\n total: number;\n}\n\ninterface SkillsShV1Entry {\n id: string;\n skillId: string;\n source: string;\n // ... additional fields\n}\n```\n\n---\n\n## Data Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant Fetcher\n participant Resolver\n participant Validator\n participant Converter\n participant Output\n\n User->>Resolver: search_skills(query)\n Resolver-->>User: skill list\n\n User->>Fetcher: fetch_skill(identifier)\n Fetcher->>Resolver: resolve owner/repo\n Resolver-->>Fetcher: resolved URL\n Fetcher-->>User: raw content\n\n User->>Validator: validate_skill(content)\n Validator->>Validator: scan patterns\n Validator-->>User: ValidationResult\n\n User->>Converter: convert_to_power(content)\n Converter->>Validator: re-validate\n Validator-->>Converter: isValid\n alt is valid\n Converter->>Converter: generate POWER.md\n alt has dependencies\n Converter->>Converter: generate mcp.json\n end\n alt has complex sections\n Converter->>Converter: generate steering/\n end\n Converter-->>Output: files array\n else is invalid\n Converter-->>User: ValidationError\n end\n```\n\n---\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Required | Module | Description |\n|----------|----------|--------|-------------|\n| `SKILLS_SH_API_KEY` | For list/leaderboard | SkillResolver | API key for authenticated endpoints |\n\n### Caching\n\nThe resolver caches skills.sh search results:\n- **TTL**: 1 hour\n- **Scope**: In-memory\n- **Purpose**: Reduce API calls, improve performance\n\n---\n\n## Testing\n\nThe core modules include comprehensive test coverage:\n\n```typescript\ndescribe('ConversionEngine', () => {\n describe('toPower', () => {\n it('converts parsed skill to power format', () => { /* ... */ });\n it('generates mcp.json when skill has dependencies', () => { /* ... */ });\n it('does not generate mcp.json when skill has no dependencies', () => { /* ... */ });\n });\n});\n```\n\n资料来源：[src/core/conversion-engine.test.ts:1-100]()\n\n---\n\n## Integration Points\n\nThe Core Modules expose functionality through MCP tools:\n\n| Tool | Primary Module | Purpose |\n|------|---------------|---------|\n| `search_skills` | SkillResolver | Discover skills |\n| `list_skills` | SkillResolver | Browse marketplace |\n| `get_leaderboard` | SkillResolver | Trending skills |\n| `fetch_skill` | SkillFetcher | Download content |\n| `validate_skill` | SecurityValidator | Security scan |\n| `convert_to_steering` | ConversionEngine | Steering format |\n| `convert_to_power` | ConversionEngine | Power format |\n| `import_skill` | All modules | Complete workflow |\n\n---\n\n\n\n## MCP Tools Reference\n\n### 相关页面\n\n相关主题：[MCP Server Architecture](#mcp-server-architecture), [Skill Discovery](#skill-discovery)\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 Tools Reference\n\nThe Skill Loader MCP Server provides a comprehensive suite of 8 Model Context Protocol (MCP) tools for discovering, fetching, validating, and converting Claude skills from the skills.sh marketplace. These tools enable seamless integration between the skills.sh ecosystem and the Kiro AI platform's steering file and power formats.\n\n## Overview\n\nThe MCP Tools form the core interface of the Skill Loader MCP Server, providing programmatic access to the skills.sh API and GitHub-hosted skill repositories. Each tool serves a specific purpose in the skill management lifecycle, from discovery to import.\n\n```mermaid\ngraph TD\n A[Skills Discovery] --> B[search_skills]\n A --> C[list_skills]\n A --> D[get_leaderboard]\n E[Skill Retrieval] --> F[fetch_skill]\n G[Security] --> H[validate_skill]\n I[Conversion] --> J[convert_to_steering]\n I --> K[convert_to_power]\n L[Workflow] --> M[import_skill]\n \n F --> H\n H --> J\n H --> K\n M --> F\n M --> H\n M --> J\n M --> K\n```\n\n### Tool Categories\n\n| Category | Tools | Purpose |\n|----------|-------|---------|\n| Discovery | `search_skills`, `list_skills`, `get_leaderboard` | Find and browse available skills |\n| Retrieval | `fetch_skill` | Download skill content from GitHub |\n| Security | `validate_skill` | Scan for dangerous commands and patterns |\n| Conversion | `convert_to_steering`, `convert_to_power` | Transform skills to Kiro formats |\n| Workflow | `import_skill` | Execute complete import workflow |\n\n资料来源：[README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n\n## Discovery Tools\n\n### search_skills\n\nSearch for skills by keyword using the skills.sh search API. This tool requires no authentication and provides immediate access to the skill marketplace.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `query` | string | Yes | - | Search query string |\n| `limit` | number | No | 20 | Maximum results (max: 50) |\n\n**Response Schema:**\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**Example Request:**\n\n```json\n{\n \"tool\": \"search_skills\",\n \"arguments\": {\n \"query\": \"pdf\",\n \"limit\": 5\n }\n}\n```\n\n资料来源：[examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n\n### list_skills\n\nList all available skills from skills.sh with pagination support. This tool requires the `SKILLS_SH_API_KEY` environment variable for authenticated access to the paginated directory endpoint.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `page` | number | No | 1 | Page number for pagination |\n| `pageSize` | number | No | 50 | Results per page (max: 100) |\n\n**Response Schema:**\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**Authentication Requirement:**\n\nThis tool requires `SKILLS_SH_API_KEY` to access the authenticated `/api/v1/skills` endpoint. Request the API key from Vercel if needed.\n\n资料来源：[README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n\n### get_leaderboard\n\nGet trending or top-installed skills to identify the most popular skills in the marketplace.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `timeframe` | string | No | \"all\" | Time window: `\"all\"` or `\"24h\"` |\n| `limit` | number | No | 20 | Maximum results (max: 50) |\n\n**Response Schema:**\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**Authentication Requirement:**\n\nSimilar to `list_skills`, this tool requires `SKILLS_SH_API_KEY` for authenticated access.\n\n资料来源：[examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n\n## Retrieval Tools\n\n### fetch_skill\n\nFetch raw skill content directly from GitHub. This tool supports both short identifiers (skill name) and fully-qualified identifiers (`owner/repo` format).\n\n```mermaid\ngraph TD\n A[fetch_skill Request] --> B{Identifier Format?}\n B -->|Short name| C[Query skills.sh directory]\n B -->|owner/repo| D[Direct GitHub URL construction]\n C --> E[Resolve to owner/repo]\n E --> F[Construct GitHub URL]\n D --> F\n F --> G[Fetch from GitHub Raw]\n G --> H[Return Skill Content]\n \n H --> I[Extract YAML frontmatter]\n H --> J[Parse markdown body]\n H --> K[Extract sections]\n```\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `identifier` | string | Yes | Skill name or `owner/repo` format |\n\n**Supported Identifier Formats:**\n\n| Format | Example | Resolution |\n|--------|---------|------------|\n| Short name | `pdf-extractor` | Resolved via skills.sh directory |\n| Fully qualified | `anthropics/pdf-extractor` | Direct GitHub URL |\n\n**Response Schema:**\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**URL Resolution Pattern:**\n\nThe `SkillResolver` class constructs URLs using the pattern:\n```\nhttps://raw.githubusercontent.com/{owner}/{repo}/main/skills/{name}/SKILL.md\n```\n\n资料来源：[src/core/skill-resolver.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/skill-resolver.ts)\n\n## Security Tools\n\n### validate_skill\n\nValidate skill content for security issues before importing. This is a critical security measure that scans for dangerous commands, suspicious patterns, and code injection vulnerabilities.\n\n```mermaid\ngraph TD\n A[Skill Content] --> B[SecurityValidator]\n B --> C{Dangerous Commands?}\n B --> D{Suspicious Patterns?}\n B --> E{Untrusted Sources?}\n \n C -->|rm -rf, sudo, eval| F[dangerous_command]\n D -->|Code injection, special chars| G[suspicious_pattern]\n E -->|Non-GitHub URLs| H[untrusted_source]\n \n F --> I{Severity Assessment}\n G --> I\n H --> I\n I --> J[Validation Result]\n \n J --> K{Result}\n K -->|No issues| L[\"severity: safe\"]\n K -->|Untrusted/Dangerous| M[\"severity: unsafe\"]\n K -->|Suspicious only| N[\"severity: warning\"]\n```\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `content` | string | Yes | Skill content to validate |\n| `url` | string | No | Source URL for verification |\n\n**Detected Security Issues:**\n\n| Issue Type | Description | Severity |\n|------------|-------------|----------|\n| `dangerous_command` | Commands like `rm -rf`, `sudo`, `eval`, `exec` | unsafe |\n| `suspicious_pattern` | Code injection patterns `${...}`, `$(...)` | warning |\n| `untrusted_source` | Non-GitHub URLs in skill content | unsafe |\n\n**Dangerous Patterns Scanned:**\n\n- Recursive delete commands (`rm -rf`)\n- Privilege escalation (`sudo`)\n- Dynamic code execution (`eval`, `exec`)\n- Path traversal attempts (`/etc/`, `/usr/`, `/bin/`)\n- Shell interpolation patterns (`${`, `$(`)\n\n**Response Schema:**\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**Severity Determination Logic:**\n\n| Condition | Result |\n|-----------|--------|\n| No issues found | `safe` |\n| `untrusted_source` or `dangerous_command` present | `unsafe` |\n| Only `suspicious_pattern` issues | `warning` |\n\n资料来源：[src/core/security-validator.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)\n\n## Conversion Tools\n\n### convert_to_steering\n\nConvert skill content to Kiro steering file format. This format is designed for guiding AI behavior through structured markdown with YAML frontmatter.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `content` | string | Yes | Skill content to convert |\n| `sourceUrl` | string | No | Original source URL for metadata |\n\n**Output Format Structure:**\n\n```yaml\n---\noriginal_skill: PDF Extractor\nsource_url: https://raw.githubusercontent.com/anthropics/skills/main/skills/pdf-extractor/SKILL.md\nimported_at: '2024-01-15T10:30:00.000Z'\n---\n\n# PDF Extractor\n\nExtract text from PDF files\n\n[Skill body content...]\n\n---\n\n*Imported from Claude Skills via Skill Loader Power*\n```\n\n**Conversion Process:**\n\n1. Parse YAML frontmatter from skill content\n2. Build new frontmatter with original skill metadata\n3. Add skill name as H1 heading\n4. Include description if present\n5. Preserve skill body content\n6. Add dependencies section if applicable\n7. Append import attribution footer\n\n**Naming Convention:**\n\nThe filename is generated using `toKebabCase()` transformation:\n- `\"PDF Extractor\"` → `\"pdf-extractor\"`\n- `\"React Best Practices\"` → `\"react-best-practices\"`\n\n资料来源：[src/core/conversion-engine.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)\n\n### convert_to_power\n\nConvert skill content to Kiro power format. This is a more comprehensive format that may generate additional files beyond the main `POWER.md`.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `content` | string | Yes | Skill content to convert |\n| `sourceUrl` | string | No | Original source URL for metadata |\n\n**Generated Files:**\n\n| Condition | File | Purpose |\n|-----------|------|---------|\n| Always | `POWER.md` | Main power definition |\n| Skill has dependencies or tool references | `mcp.json` | MCP server configuration |\n| Skill has 3+ complex sections | `steering/` directory | Structured guidance files |\n\n**mcp.json Generation:**\n\nWhen a skill contains dependencies or MCP server references, the conversion engine generates an `mcp.json` configuration file:\n\n```json\n{\n \"mcpServers\": {\n \"skill-name\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@some/package\"],\n \"env\": {}\n }\n }\n}\n```\n\n**steering/ Directory:**\n\nFor skills with multiple complex sections (3+ sections with content > 200 characters at level 2+), a structured steering directory is generated to provide granular guidance.\n\n**Response Schema:**\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/anthropics/skills/main/skills/pdf-extractor/SKILL.md\",\n \"outputFormat\": \"power\",\n \"validationResult\": {\n \"isValid\": true,\n \"issues\": [],\n \"severity\": \"safe\"\n }\n }\n}\n```\n\n**Dependencies Section:**\n\nWhen present in the original skill, dependencies are converted to a markdown list:\n\n```markdown\n## Dependencies\n\n- dependency-1\n- dependency-2\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## Workflow Tools\n\n### import_skill\n\nComplete end-to-end import workflow that combines fetch, validate, and convert operations into a single atomic action.\n\n```mermaid\ngraph TD\n A[import_skill Request] --> B[Fetch Skill from GitHub]\n B --> C{skipValidation?}\n C -->|No| D[Validate Security]\n C -->|Yes| E[Skip Validation]\n D --> F{isValid?}\n F -->|Yes| G[Convert to Target Format]\n F -->|No| H[Block Import]\n E --> G\n G --> I[Return Converted Content]\n H --> J[Return Validation Error]\n \n I --> K[Optional: Write to Target Path]\n```\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `identifier` | string | Yes | - | Skill name or `owner/repo` format |\n| `outputFormat` | string | Yes | - | Target format: `\"steering\"` or `\"power\"` |\n| `skipValidation` | boolean | No | false | Bypass security validation |\n\n**Workflow Steps:**\n\n1. **Fetch**: Retrieve skill content from GitHub using `fetch_skill`\n2. **Validate**: Run security checks via `validate_skill` (unless skipped)\n3. **Convert**: Transform to requested format (`convert_to_steering` or `convert_to_power`)\n\n**Recommended Workflow Pattern:**\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**Security Considerations:**\n\n- Always validate skills from untrusted sources\n- Use `skipValidation: true` only for locally-verified content\n- Review validation issues before proceeding with imports\n\n**Response Schema:**\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/anthropics/skills/main/skills/pdf-extractor/SKILL.md\",\n \"outputFormat\": \"power\",\n \"validationResult\": {\n \"isValid\": true,\n \"issues\": [],\n \"severity\": \"safe\"\n }\n }\n}\n```\n\n**Error Response:**\n\n```json\n{\n \"error\": \"Error message describing what went wrong\",\n \"tool\": \"import_skill\",\n \"timestamp\": \"2024-01-15T10:30:00.000Z\"\n}\n```\n\n资料来源：[examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n\n## Error Handling\n\nAll MCP tools return errors in a consistent format to enable reliable error handling in clients:\n\n**Error Response Schema:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `error` | string | Human-readable error message |\n| `tool` | string | Name of the tool that failed |\n| `timestamp` | string | ISO 8601 timestamp of the error |\n\n**Common Error Scenarios:**\n\n| Scenario | Cause | Resolution |\n|----------|-------|------------|\n| Network errors | Internet connectivity, GitHub availability | Check connection, retry later |\n| Not found | Invalid skill name or repository | Verify identifier format |\n| Validation errors | Security issues detected | Review and address issues |\n| Parsing errors | Invalid YAML or markdown format | Check skill syntax |\n\n**Error Types:**\n\n| Error Class | Trigger | Context |\n|-------------|---------|---------|\n| `NetworkError` | HTTP request failures | Retry with backoff |\n| `SkillResolutionError` | Skill not found or ambiguous | Provide alternatives |\n| `ValidationError` | Security validation failures | Review skill content |\n| `FileSystemError` | File operations | Check permissions |\n\n资料来源：[src/core/errors.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts)\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Required | Tools | Description |\n|----------|----------|-------|-------------|\n| `SKILLS_SH_API_KEY` | Conditional | `list_skills`, `get_leaderboard` | API key for authenticated endpoints |\n\n**Note:** `search_skills` and `fetch_skill` do not require authentication as they use public APIs.\n\n### Caching Behavior\n\nThe server implements in-memory caching for skills.sh search results:\n\n| Cache | TTL | Scope |\n|-------|-----|-------|\n| Skills.sh directory | 1 hour | All authenticated list operations |\n\nCaching reduces API calls and improves response times for repeated queries.\n\n## Quick Reference\n\n### Tool Summary Table\n\n| Tool | Auth Required | Input | Output |\n|------|---------------|-------|--------|\n| `search_skills` | No | `query`, `limit` | Array of matching skills |\n| `list_skills` | Yes (API Key) | `page`, `pageSize` | Paginated skill directory |\n| `get_leaderboard` | Yes (API Key) | `timeframe`, `limit` | Trending/top skills |\n| `fetch_skill` | No | `identifier` | Raw skill content |\n| `validate_skill` | No | `content`, `url` | Validation result |\n| `convert_to_steering` | No | `content`, `sourceUrl` | Steering file |\n| `convert_to_power` | No | `content`, `sourceUrl` | Power format + extras |\n| `import_skill` | No* | `identifier`, `outputFormat` | Complete import result |\n\n*Security validation can be optionally skipped\n\n### Recommended Workflows\n\n**Discover and Import Trending Skill:**\n\n```json\n[\n { \"tool\": \"get_leaderboard\", \"arguments\": { \"timeframe\": \"24h\", \"limit\": 10 } },\n { \"tool\": \"fetch_skill\", \"arguments\": { \"identifier\": \"owner/skill-name\" } },\n { \"tool\": \"validate_skill\", \"arguments\": { \"content\": \"...\" } },\n { \"tool\": \"convert_to_steering\", \"arguments\": { \"content\": \"...\", \"sourceUrl\": \"...\" } }\n]\n```\n\n**Single-Command Import:**\n\n```json\n{ \"tool\": \"import_skill\", \"arguments\": { \"identifier\": \"owner/skill-name\", \"outputFormat\": \"power\" } }\n\n---\n\n\n\n## Skill Discovery\n\n### 相关页面\n\n相关主题：[MCP Tools Reference](#mcp-tools-reference), [Caching System](#caching-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/skill-resolver.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/skill-resolver.ts)\n- [src/tools/search-skills.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/list-skills.ts)\n- [src/tools/list-skills.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/list-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/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 \n\n# Skill Discovery\n\nSkill Discovery is a core subsystem of the Skill Loader MCP Server that enables users to find, browse, and explore available Claude skills from the skills.sh ecosystem. It provides multiple discovery mechanisms including keyword search, paginated listing, and trending leaderboards.\n\n## Overview\n\nThe Skill Discovery system acts as the front-end interface for exploring the skills.sh marketplace. It abstracts away the complexity of fetching and filtering skills from external APIs, providing a unified interface for skill exploration.\n\n### Key Capabilities\n\n- **Keyword Search**: Find skills by name or description keywords\n- **Paginated Listing**: Browse all available skills with pagination support\n- **Trending Leaderboard**: Discover popular or recently trending skills\n- **Source Resolution**: Resolve skill identifiers to GitHub URLs\n- **Install Statistics**: View install counts for skill popularity metrics\n\n### Architecture Overview\n\n```mermaid\ngraph TD\n A[User Request] --> B[MCP Tools Layer]\n B --> C[search_skills]\n B --> D[list_skills]\n B --> E[get_leaderboard]\n C --> F[SkillResolver]\n D --> F\n E --> F\n F --> G[Skills.sh API]\n F --> H[GitHub Raw Content]\n G --> I[SkillShEntry Parser]\n I --> J[ResolvedSkill Output]\n H --> J\n```\n\n## Core Components\n\n### SkillResolver\n\nThe `SkillResolver` class is the central orchestrator for skill discovery operations. Located at `src/core/skill-resolver.ts`, it handles all interactions with the skills.sh API and provides unified resolution of skill identifiers.\n\n**Primary Methods:**\n\n| Method | Purpose |\n|--------|---------|\n| `resolveSkill()` | Resolve a skill identifier to a full URL |\n| `searchSkills()` | Search skills by keyword |\n| `listSkills()` | List skills with pagination (authenticated) |\n| `getLeaderboard()` | Get trending or top-installed skills |\n\n资料来源：[src/core/skill-resolver.ts:1-50]()\n\n### Data Models\n\n#### SkillShEntry\n\nRepresents a skill entry from the skills.sh API:\n\n```typescript\ninterface SkillShEntry {\n name: string;\n owner: string;\n repo: string;\n installs: number;\n description: string;\n id?: string;\n skillId?: string;\n source?: string;\n metadata?: {\n trending: boolean;\n };\n}\n```\n\n#### ResolvedSkill\n\nInternal representation after resolution:\n\n```typescript\ninterface ResolvedSkill {\n name: string;\n description: string;\n owner: string;\n repo: string;\n skillPath: string;\n url: string;\n installs: number;\n}\n```\n\n资料来源：[src/core/skill-resolver.ts:60-100]()\n\n## Discovery Tools\n\n### 1. search_skills\n\nPerforms keyword-based search across skill names and descriptions. This tool uses the public search API endpoint and does not require authentication.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `query` | string | Yes | - | Search query string |\n| `limit` | number | No | 5 | Maximum results (max: 50) |\n\n**Workflow:**\n\n```mermaid\ngraph LR\n A[query: string] --> B[Call skills.sh Search API]\n B --> C[Parse Response]\n C --> D[Filter by Relevance]\n D --> E[Return Top N Results]\n E --> F[Skills with relevance scores]\n```\n\n**Response Structure:**\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资料来源：[examples/usage-examples.md:30-60]()\n\n### 2. list_skills\n\nRetrieves a paginated list of all available skills from the skills.sh directory. Requires `SKILLS_SH_API_KEY` for authenticated access to the v1 API endpoint.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `page` | number | No | 1 | Page number |\n| `pageSize` | number | No | 50 | Results per page (max: 100) |\n\n**API Integration:**\n\n```typescript\nconst url = `https://skills.sh/api/v1/skills?page=${page}&pageSize=${pageSize}`;\nconst headers = {\n 'Authorization': `Bearer ${apiKey}`,\n 'Content-Type': 'application/json'\n};\n```\n\n**Response Structure:**\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资料来源：[examples/usage-examples.md:20-40]()\n\n### 3. get_leaderboard\n\nRetrieves trending or top-installed skills ranked by popularity metrics.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `timeframe` | string | No | \"all\" | Time period: `'all'` or `'24h'` |\n| `limit` | number | No | 20 | Maximum results (max: 50) |\n\n**Timeframe Behavior:**\n\n| Timeframe | Source | Use Case |\n|-----------|--------|----------|\n| `all` | Historical install counts | All-time popular skills |\n| `24h` | Recent activity metrics | Currently trending skills |\n\n**Response Structure:**\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资料来源：[examples/usage-examples.md:55-80]()\n\n## Skill Resolution Flow\n\nThe resolution process transforms various identifier formats into canonical GitHub URLs:\n\n```mermaid\ngraph TD\n A[Identifier Input] --> B{Normalize Identifier}\n B --> C[\"owner/repo format?\"]\n C -->|Yes| D[Build URL: owner/repo]\n C -->|No| E[Search skills.sh Directory]\n E --> F{Match Found?}\n F -->|Single| G[Use Match]\n F -->|Multiple| H[Raise Error: Multiple Matches]\n F -->|None| I[Raise Error: Not Found]\n D --> J[Build Full GitHub URL]\n G --> J\n J --> K[Return ResolvedSkill]\n```\n\n### Resolution Rules\n\n1. **Explicit Format** (`owner/repo`): Directly constructs GitHub URL\n2. **Name Only**: Searches skills.sh directory for matching name\n3. **Fuzzy Match**: Case-insensitive partial matching on skill names\n4. **Multiple Matches**: Throws `SkillResolutionError` with list of matches\n\n资料来源：[src/core/skill-resolver.ts:100-150]()\n\n## API Integration\n\n### Skills.sh API Endpoints\n\n| Endpoint | Auth Required | Purpose |\n|----------|---------------|---------|\n| `GET /api/v1/skills` | Yes (API Key) | Paginated skill listing |\n| `GET /search?q={query}` | No | Public keyword search |\n\n### Authentication\n\n```typescript\nconst response = await fetch(url, {\n headers: {\n 'Authorization': `Bearer ${process.env.SKILLS_SH_API_KEY}`,\n 'Content-Type': 'application/json'\n }\n});\n```\n\n### Error Handling\n\n| Error Type | HTTP Code | Handling |\n|------------|-----------|----------|\n| `NetworkError` | 4xx/5xx | Retry with exponential backoff |\n| `SkillResolutionError` | N/A | Return helpful suggestions |\n\n资料来源：[src/core/skill-resolver.ts:150-200]()\n\n## Caching Strategy\n\nThe Skill Discovery system implements in-memory caching for the skills.sh directory to reduce API calls and improve performance.\n\n```mermaid\ngraph LR\n A[Request] --> B{Cache Valid?}\n B -->|Yes| C[Return Cached Data]\n B -->|No| D[Fetch from API]\n D --> E[Update Cache]\n E --> F[Return Fresh Data]\n C --> G[Response]\n F --> G\n```\n\n**Cache Configuration:**\n\n| Setting | Value | Description |\n|---------|-------|-------------|\n| TTL | 1 hour | Time-to-live for cached entries |\n| Scope | In-memory | Process-level caching |\n| Invalidation | TTL-based | Automatic refresh on expiry |\n\n资料来源：[examples/usage-examples.md:150-160]()\n\n## Usage Examples\n\n### Discover Skills by Keyword\n\n```json\n{\n \"tool\": \"search_skills\",\n \"arguments\": {\n \"query\": \"pdf\",\n \"limit\": 5\n }\n}\n```\n\n### Browse Available Skills\n\n```json\n{\n \"tool\": \"list_skills\",\n \"arguments\": {\n \"page\": 1,\n \"pageSize\": 10\n }\n}\n```\n\n### Find Trending Skills\n\n```json\n{\n \"tool\": \"get_leaderboard\",\n \"arguments\": {\n \"timeframe\": \"24h\",\n \"limit\": 20\n }\n}\n```\n\n### Complete Discovery Workflow\n\n```mermaid\ngraph TD\n A[Search for Skills] --> B[Found Interesting Skill?]\n B -->|Yes| C[Fetch Skill Details]\n B -->|No| A\n C --> D[Validate Skill Content]\n D --> E{Valid?}\n E -->|Yes| F[Convert to Target Format]\n E -->|No| G[Review Security Issues]\n G --> H[Skip or Find Alternative]\n F --> I[Import Skill]\n I --> J[Complete]\n```\n\n资料来源：[examples/usage-examples.md:170-210]()\n\n## Related Systems\n\n### Conversion Engine Integration\n\nAfter discovery, skills can be converted to target formats:\n\n| Format | Output | Use Case |\n|--------|--------|----------|\n| Steering | `.kiro/steering/` | Kiro steering files |\n| Power | `~/.kiro/powers/` | Kiro power modules |\n\n### Security Validation\n\nAll discovered skills should be validated before import using the `validate_skill` tool to scan for:\n\n- Dangerous commands (`rm -rf`, `sudo`, `eval`)\n- Suspicious file operations (`/etc/`, `/usr/`)\n- Code injection patterns (`${...}`, `$(...)`)\n\n资料来源：[src/core/security-validator.ts:1-50]()\n\n## Summary\n\nSkill Discovery provides the foundational capability to explore and find Claude skills from the skills.sh ecosystem. Through a combination of search, listing, and trending endpoints, users can efficiently discover relevant skills for their needs. The system emphasizes:\n\n- **Performance**: In-memory caching with 1-hour TTL\n- **Reliability**: Retry logic with exponential backoff\n- **Security**: Integration with validation pipeline\n- **Developer Experience**: Clear error messages with actionable suggestions\n\nFor implementation details, refer to the source files listed at the beginning of this page.\n\n---\n\n\n\n## Security Validation\n\n### 相关页面\n\n相关主题：[Error Handling](#error-handling), [Format Conversion](#format-conversion)\n\n\nRelated Source Files
\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/errors.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts)\n- [src/tools/validate-skill.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/validate-skill.ts)\n- [examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n \n\n# Security Validation\n\nThe Security Validation system is a critical component of the Skill Loader MCP Server that protects users from potentially malicious or unsafe skill content. It performs comprehensive static analysis on skill markdown files before they are imported, converted, or executed.\n\n## Overview\n\nThe security validation module (`SecurityValidator`) scans skill content for multiple categories of security threats, including dangerous system commands, file system access patterns, code injection vulnerabilities, and untrusted content sources. Skills that fail security validation are blocked from import unless validation is explicitly skipped.\n\n**Purpose:**\n- Prevent execution of harmful system commands\n- Block imports from non-verified sources\n- Detect potential code injection patterns\n- Protect the host system from malicious skills\n\n**Scope:** All skill content passing through the server's import, validation, and conversion workflows.\n\n资料来源：[src/core/security-validator.ts:1-50]()\n\n## Architecture\n\n```mermaid\ngraph TD\n A[Skill Content Input] --> B[SecurityValidator.validate]\n B --> C{Dangerous Commands?}\n C -->|Yes| D[Issue: dangerous_command]\n B --> E{Suspicious File Ops?}\n E -->|Yes| F[Issue: suspicious_file_operation]\n B --> G{Code Injection?}\n G -->|Yes| H[Issue: code_injection]\n B --> I{Untrusted Source?}\n I -->|Yes| J[Issue: untrusted_source]\n B --> K{Suspicious Patterns?}\n K -->|Yes| L[Issue: suspicious_pattern]\n \n D --> M[ValidationResult.issues]\n F --> M\n H --> M\n J --> M\n L --> M\n \n M --> N[getSeverity]\n N --> O{hasDangerousCommand
or untrustedSource?}\n O -->|Yes| P[Severity: unsafe]\n N --> Q{hasIssues?}\n Q -->|Yes| R[Severity: warning]\n N --> S{noIssues?}\n S -->|Yes| T[Severity: safe]\n```\n\n## Validation Checks\n\nThe security validator performs five distinct categories of checks:\n\n### 1. Dangerous Commands\n\nDetects execution of potentially harmful shell commands that could damage the system.\n\n| Pattern | Description | Severity |\n|---------|-------------|----------|\n| `rm -rf` | Recursive force delete | unsafe |\n| `sudo` | Privilege escalation | unsafe |\n| `eval` | Dynamic code execution | unsafe |\n| `exec` | Command execution | unsafe |\n\n资料来源：[src/core/security-validator.ts:60-80]()\n\n**Example detected content:**\n```bash\nrm -rf /\nsudo rm -rf /usr\neval $user_input\nexec sh\n```\n\n### 2. Suspicious File Operations\n\nIdentifies attempts to access or modify sensitive system directories.\n\n| Pattern | Target Directory | Severity |\n|---------|------------------|----------|\n| `/etc/` | System configuration | unsafe |\n| `/usr/` | System binaries | unsafe |\n| `/bin/` | Essential binaries | unsafe |\n| `~/.` | Hidden files | warning |\n\n资料来源：[src/core/security-validator.ts:81-100]()\n\n### 3. Code Injection Patterns\n\nDetects template injection and command substitution vulnerabilities.\n\n| Pattern | Type | Severity |\n|---------|------|----------|\n| `${...}` | Variable expansion | unsafe |\n| `$(...)` | Command substitution | unsafe |\n\n资料来源：[src/core/security-validator.ts:101-120]()\n\n**Example detected content:**\n```bash\necho ${MALICIOUS_VAR}\nResult: $(whoami)\n```\n\n### 4. Untrusted Sources\n\nBlocks content from non-GitHub sources that cannot be verified.\n\n| Source Type | Status | Severity |\n|-------------|--------|----------|\n| GitHub URLs | Trusted | safe |\n| Other URLs | Blocked | unsafe |\n\n资料来源：[src/core/security-validator.ts:121-140]()\n\n### 5. Suspicious Patterns\n\nFlags potentially concerning patterns that warrant review.\n\n| Pattern | Description | Severity |\n|---------|-------------|----------|\n| Hidden file access (`~/.`) | File hiding | warning |\n| Base64 encoded content | Obfuscation | warning |\n\n资料来源：[src/core/security-validator.ts:141-160]()\n\n## Data Models\n\n### ValidationIssue\n\n```typescript\ninterface ValidationIssue {\n type: 'dangerous_command' | 'suspicious_file_operation' | \n 'code_injection' | 'untrusted_source' | 'suspicious_pattern';\n description: string;\n line: number;\n content: string;\n}\n```\n\n资料来源：[src/core/security-validator.ts:20-30]()\n\n### ValidationResult\n\n```typescript\ninterface ValidationResult {\n isValid: boolean;\n issues: ValidationIssue[];\n severity: 'safe' | 'warning' | 'unsafe';\n}\n```\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `isValid` | boolean | True if no blocking issues (dangerous commands or untrusted sources) |\n| `issues` | ValidationIssue[] | Array of detected issues |\n| `severity` | 'safe' \\| 'warning' \\| 'unsafe' | Overall risk assessment |\n\n资料来源：[src/core/security-validator.ts:31-45]()\n\n## Severity Calculation\n\nThe severity determination follows a hierarchical logic:\n\n```mermaid\ngraph LR\n A[Issues Array] --> B{Contains
dangerous_command
or untrusted_source?}\n B -->|Yes| C[unsafe]\n B -->|No| D{Has any
issues?}\n D -->|Yes| E[warning]\n D -->|No| F[safe]\n```\n\n| Condition | Severity |\n|-----------|----------|\n| Contains `dangerous_command` OR `untrusted_source` | `unsafe` |\n| Contains any other issue type | `warning` |\n| No issues detected | `safe` |\n\n资料来源：[src/core/security-validator.ts:170-190]()\n\n## Integration Points\n\nThe security validator is integrated into the skill import workflow at multiple stages:\n\n```mermaid\ngraph TD\n A[import_skill Tool] --> B[fetch_skill]\n B --> C{validate_skill}\n C --> D{skipValidation?}\n D -->|No| E[SecurityValidator.validate]\n D -->|Yes| F[Skip validation]\n E --> G{unsafe?}\n G -->|Yes| H[Block import
Return error]\n G -->|No| I[Proceed]\n F --> I\n I --> J[convert_to_steering
or convert_to_power]\n J --> K[Import complete]\n```\n\n### validate_skill Tool\n\nThe `validate_skill` MCP tool provides standalone security validation:\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `content` | string | Yes | Skill content to validate |\n| `url` | string | No | Source URL for verification |\n\n**Example Request:**\n```json\n{\n \"tool\": \"validate_skill\",\n \"arguments\": {\n \"content\": \"---\\nname: Test\\n---\\n\\n# Test\",\n \"url\": \"https://github.com/example/repo/main/skill.md\"\n }\n}\n```\n\n**Example Response:**\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资料来源：[src/tools/validate-skill.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/validate-skill.ts)\n\n## Error Handling\n\nValidation errors are wrapped in the `ValidationError` class for consistent error handling:\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| Field | Type | Description |\n|-------|------|-------------|\n| `validationType` | 'format' \\| 'security' \\| 'schema' \\| 'content' | Category of validation failure |\n| `lineNumber` | number (optional) | Line where validation failed |\n| `details` | string[] | List of specific validation issues |\n\n资料来源：[src/core/errors.ts:100-130]()\n\n## Testing\n\nThe security validator includes comprehensive test coverage:\n\n| Test Case | Expected Behavior |\n|-----------|-------------------|\n| Content with `rm -rf` | Detects as `dangerous_command`, severity: unsafe |\n| Content with `${VAR}` | Detects as `code_injection`, severity: unsafe |\n| Content with `$(cmd)` | Detects as `code_injection`, severity: unsafe |\n| Content with `~/.` only | Detects as `suspicious_pattern`, severity: warning |\n| Clean content | Severity: safe |\n\n资料来源：[src/core/security-validator.test.ts:1-50]()\n\n**Test Implementation:**\n```typescript\nit('detects dangerous commands', () => {\n const content = makeContent('Run rm -rf /');\n const result = validator.validate(content);\n expect(result.issues.some(i => i.type === 'dangerous_command')).toBe(true);\n expect(result.severity).toBe('unsafe');\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```\n\n## Configuration\n\nSecurity validation behavior can be configured through the import workflow:\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `skipValidation` | boolean | false | Skip security checks entirely |\n\n**Warning:** Setting `skipValidation: true` bypasses all security checks and should only be used for trusted, locally-verified content.\n\n资料来源：[examples/usage-examples.md:80-100]()\n\n## Line Number Tracking\n\nThe validator tracks the line number for each detected issue:\n\n```typescript\nprivate getLineNumber(content: string, index: number): number {\n const lines = content.substring(0, index).split('\\n');\n return lines.length;\n}\n```\n\nThis enables precise error reporting showing exactly where issues were found in the skill content.\n\n资料来源：[src/core/security-validator.ts:200-210]()\n\n## Security Recommendations\n\nWhen working with skills from external sources:\n\n1. **Always validate first** - Use `validate_skill` before importing unknown skills\n2. **Review issue descriptions** - Understand what triggered each warning\n3. **Prefer GitHub sources** - Skills from GitHub are automatically verified\n4. **Use warning-level skills with caution** - Review content before proceeding\n5. **Never skip validation for untrusted sources** - The unsafe designation exists for protection\n\n---\n\n\n\n## Format Conversion\n\n### 相关页面\n\n相关主题：[Core Modules](#core-modules)\n\n\nRelated Source Files
\n\nThe following source files were used to generate this documentation page:\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/core/types.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/types.ts) (referenced)\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 \n\n# Format Conversion\n\nThe Format Conversion system is a core component of the Skill Loader MCP Server that transforms Claude Skills (represented in markdown with YAML frontmatter) into Kiro-compatible formats for use in AI agent contexts. This system provides bidirectional conversion capabilities through the `ConversionEngine` class and exposes conversion functionality via MCP tools.\n\n## Overview\n\nThe conversion system serves as a bridge between two ecosystems:\n\n| Source Format | Target Formats |\n|--------------|----------------|\n| Claude Skills (markdown + YAML) | Kiro Steering Files |\n| | Kiro Powers |\n\nClaude Skills follow a specific structure with YAML frontmatter containing metadata (name, description, dependencies) and a markdown body with instructions and sections. Kiro, by contrast, supports two distinct consumption patterns: lightweight steering files for simple guidance and comprehensive power packages for complex, multi-file skills.\n\n## Architecture\n\n### Core Components\n\n```mermaid\ngraph TD\n A[Claude Skill Markdown] --> B[ConversionEngine]\n B --> C[parseSkill]\n C --> D[ParsedSkill]\n D --> E{Output Format}\n E --> F[toSteeringFile]\n E --> G[toPower]\n F --> H[SteeringFile]\n G --> I[PowerStructure]\n \n H --> J[.kiro/steering/*.md]\n G --> K[POWER.md]\n G --> L[mcp.json]\n G --> M[steering/ directory]\n```\n\nThe `ConversionEngine` class located in `src/core/conversion-engine.ts` is the central orchestrator for all conversion operations. It provides three primary public methods:\n\n| Method | Purpose | Returns |\n|--------|---------|---------|\n| `parseSkill(content)` | Parse raw markdown into structured data | `ParsedSkill` |\n| `toSteeringFile(skill, sourceUrl?)` | Convert to Kiro steering format | `SteeringFile` |\n| `toPower(skill, sourceUrl?)` | Convert to Kiro power format | `PowerStructure` |\n\n资料来源：[src/core/conversion-engine.ts:38-200]()\n\n### Data Models\n\nThe conversion engine works with several interconnected TypeScript interfaces:\n\n```typescript\ninterface SkillFrontmatter {\n name: string;\n description: string;\n dependencies?: string[];\n // ... additional fields\n}\n\ninterface SkillSection {\n heading: string;\n level: number;\n content: string;\n}\n\ninterface ParsedSkill {\n frontmatter: SkillFrontmatter;\n body: string;\n sections: SkillSection[];\n}\n\ninterface SteeringFile {\n filename: string;\n content: string;\n metadata: {\n originalSkill: string;\n sourceUrl?: string;\n importedAt: string;\n };\n}\n\ninterface PowerStructure {\n powerName: string;\n files: Array<{ path: string; content: string }>;\n}\n```\n\n资料来源：[src/core/conversion-engine.ts:1-50]()\n\n## Skill Parsing\n\n### Frontmatter Extraction\n\nThe `parseSkill` method extracts YAML frontmatter using a regex pattern:\n\n```typescript\nconst frontmatterRegex = /^---\\n([\\s\\S]*?)\\n---/;\n```\n\nThis pattern matches content between `---` delimiters at the document start. The extracted YAML is then parsed using the `js-yaml` library into a JavaScript object.\n\n资料来源：[src/core/conversion-engine.ts:55-90]()\n\n### Validation Rules\n\nThe parser enforces the following validation rules:\n\n| Field | Requirement | Error Type |\n|-------|-------------|------------|\n| `name` | Required, non-empty string | `ValidationError` |\n| `description` | Required, non-empty string | `ValidationError` |\n| Content | Must not be empty after trimming | `ValidationError` |\n\n```typescript\nif (!content || content.trim().length === 0) {\n const error = new ValidationError(\n 'Skill content is empty',\n 'content',\n { details: ['The skill file contains no content'] }\n );\n ErrorLogger.log(error);\n throw error;\n}\n```\n\n资料来源：[src/core/conversion-engine.ts:55-65]()\n\n### Section Extraction\n\nThe parser splits the markdown body into hierarchical sections based on heading levels (H1-H6). Each section captures:\n\n- `heading`: The text following the `#` symbols\n- `level`: The heading depth (1-6)\n- `content`: The markdown content following the heading\n\n```typescript\nconst sectionRegex = /^(#{1,6})\\s+(.+)\\n([\\s\\S]*?)(?=\\n#{1,6}\\s|\\n*$)/gm;\n```\n\nThis regex preserves code blocks with language annotations, allowing syntax-highlighted examples to pass through unchanged.\n\n资料来源：[src/core/conversion-engine.ts:70-150]()\n\n### Keyword Extraction\n\nThe private `extractKeywords` method generates up to 5 relevant keywords from the skill description:\n\n1. Converts text to lowercase\n2. Removes special characters\n3. Filters out common stop words\n4. Keeps words with 3+ characters\n5. Returns the first 5 matches\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 // ... additional stop words\n ]);\n \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:180-220]()\n\n## Steering File Conversion\n\n### Output Format\n\nSteering files are designed for simple, single-file skill guidance. They are saved with a kebab-case filename derived from the skill name and placed in `.kiro/steering/` directories.\n\n### Conversion Process\n\n```mermaid\ngraph LR\n A[ParsedSkill] --> B[Generate Filename]\n B --> C[kebab-case + .md]\n A --> D[Build Content]\n D --> E[Title from name]\n D --> F[Description section]\n D --> G[Complex sections]\n D --> H[Dependencies list]\n A --> I[Create Metadata]\n I --> J[originalSkill]\n I --> K[sourceUrl]\n I --> L[importedAt]\n E --> M[SteeringFile]\n F --> M\n G --> M\n H --> M\n I --> M\n```\n\n### Content Structure\n\nA steering file contains these sections in order:\n\n1. **Title**: `# {skill.name} Guidelines`\n2. **Description**: From frontmatter if present\n3. **Complex Sections**: Sections with level ≥ 2 and content length > 200 characters\n4. **Dependencies**: Bulleted list if dependencies exist\n5. **Footer**: Attribution message\n\n### Filename Generation\n\nThe `toSteeringFile` method uses `toKebabCase` to transform skill names:\n\n```typescript\nprivate toKebabCase(str: string): string {\n return str\n .toLowerCase()\n .replace(/[\\s_]+/g, '-')\n .replace(/[^a-z0-9-]/g, '')\n .replace(/-+/g, '-')\n .replace(/^-|-$/g, '');\n}\n```\n\nTransformation examples:\n\n| Input | Output |\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:120-160]()\n\n### Steering File Output\n\n```typescript\nreturn {\n filename,\n content,\n metadata: {\n originalSkill: skill.frontmatter.name,\n sourceUrl,\n importedAt: now\n }\n};\n```\n\n资料来源：[src/core/conversion-engine.ts:190-200]()\n\n## Power Conversion\n\n### Output Format\n\nPower format is more comprehensive, supporting multi-file outputs for complex skills. The `toPower` method can generate up to three files:\n\n| File | Condition | Purpose |\n|------|-----------|---------|\n| `POWER.md` | Always | Main power manifest and content |\n| `mcp.json` | Has dependencies or MCP tool references | MCP server configuration |\n| `steering/` directory | Has 3+ complex sections | Additional guidance files |\n\n资料来源：[src/core/conversion-engine.ts:200-280]()\n\n### Power Manifest Structure\n\nThe `POWER.md` file follows Kiro's power specification:\n\n```markdown\n---\nname: {kebab-case-name}\ndisplayName: {original-name}\ndescription: {description}\nkeywords: [{extracted-keywords}]\n---\n\n# {skill.frontmatter.name}\n\n{skill.body}\n\n## Dependencies\n{dependency-list}\n\n## Import Metadata\n- **Original Skill**: {name}\n- **Source URL**: {url}\n- **Imported At**: {ISO-timestamp}\n- **Imported Via**: Skill Loader Power\n```\n\n资料来源：[src/core/conversion-engine.ts:220-260]()\n\n### MCP.json Generation\n\nThe method `shouldGenerateMcpJson` determines when to create the MCP configuration:\n\n```typescript\nprivate shouldGenerateMcpJson(skill: ParsedSkill): boolean {\n const hasDependencies = skill.frontmatter.dependencies?.length > 0;\n const hasTools = skill.sections.some(s => s.content.includes('mcp__'));\n return hasDependencies || hasTools;\n}\n```\n\n资料来源：[src/core/conversion-engine.ts:280-300]()\n\n### Steering Directory Generation\n\nComplex skills with multiple substantial sections generate additional files in a `steering/` subdirectory:\n\n```typescript\nprivate shouldGenerateSteeringDir(skill: ParsedSkill): 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:300-320]()\n\n### Power Output Structure\n\n```typescript\nconst files: Array<{ path: string; content: string }> = [\n { path: 'POWER.md', content: powerContent }\n];\n\nif (this.shouldGenerateMcpJson(skill)) {\n const mcpJson = this.generateMcpJson(skill);\n files.push({\n path: 'mcp.json',\n content: JSON.stringify(mcpJson, null, 2)\n });\n}\n\nif (this.shouldGenerateSteeringDir(skill)) {\n const steeringContent = this.generateSteeringContent(skill);\n // Add steering files...\n}\n```\n\n资料来源：[src/core/conversion-engine.ts:260-290]()\n\n## MCP Tools Integration\n\n### Available Tools\n\nThe conversion functionality is exposed through two MCP tools:\n\n#### convert_to_steering\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `content` | string | Yes | Raw skill markdown content |\n| `sourceUrl` | string | No | Original source URL for metadata |\n\n```json\n{\n \"tool\": \"convert_to_steering\",\n \"arguments\": {\n \"content\": \"---\\nname: PDF Extractor\\ndescription: Extract text from PDF files\\n---\\n\\n# PDF Extractor\",\n \"sourceUrl\": \"https://example.com/skill.md\"\n }\n}\n```\n\n资料来源：[README.md:80-100]()\n\n#### convert_to_power\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `content` | string | Yes | Raw skill markdown content |\n| `sourceUrl` | string | No | Original source URL for metadata |\n\n```json\n{\n \"tool\": \"convert_to_power\",\n \"arguments\": {\n \"content\": \"---\\nname: PDF Extractor\\ndescription: Extract text from PDF files\\n---\\n\\n# PDF Extractor\",\n \"sourceUrl\": \"https://example.com/skill.md\"\n }\n}\n```\n\n资料来源：[README.md:105-125]()\n\n### Complete Import Workflow\n\nThe `import_skill` tool provides a unified workflow combining fetch, validation, and conversion:\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\nThis workflow:\n1. Fetches skill content from GitHub\n2. Validates for security issues (unless skipped)\n3. Converts to the specified format\n4. Returns the converted content with metadata\n\n资料来源：[README.md:130-150]()\n\n## Error Handling\n\n### Error Types\n\nThe conversion engine uses specialized error classes for different failure scenarios:\n\n| Error Class | Usage | Context Fields |\n|-------------|-------|----------------|\n| `ParsingError` | YAML/frontmatter parsing failures | `field`, `value` |\n| `ValidationError` | Content validation failures | `field`, `details` |\n\n```typescript\nif (!parsed || typeof parsed !== 'object') {\n const error = new ParsingError(\n 'YAML frontmatter is not a valid object',\n 'frontmatter',\n { yamlContent: yamlContent.substring(0, 100) }\n );\n ErrorLogger.log(error);\n throw error;\n}\n```\n\n资料来源：[src/core/conversion-engine.ts:70-85]()\n\n### Error Logging\n\nAll errors are logged through `ErrorLogger` before being thrown, enabling debugging and audit trails:\n\n```typescript\nErrorLogger.log(error);\nthrow error;\n```\n\n资料来源：[src/core/errors.ts:50-100]()\n\n## Testing\n\nThe conversion engine has comprehensive test coverage in `src/core/conversion-engine.test.ts`:\n\n### parseSkill Tests\n\n| Test Case | Input | Expected |\n|-----------|-------|----------|\n| Valid skill with frontmatter | Complete YAML + body | Parsed frontmatter and sections |\n| Empty content | `\"\"` | Throws ValidationError |\n| Missing name | YAML without `name` | Throws ValidationError |\n| Missing description | YAML without `description` | Throws ValidationError |\n| No frontmatter | Plain markdown | Uses \"Untitled Skill\" |\n| Code block preservation | Markdown with code fences | Code blocks intact |\n\n资料来源：[src/core/conversion-engine.test.ts:1-80]()\n\n### Steering Conversion Tests\n\n| Test Case | Description |\n|-----------|-------------|\n| Basic conversion | Validates output structure |\n| Empty dependencies | No dependencies section generated |\n| With dependencies | Dependencies section populated |\n\n### Power Conversion Tests\n\n| Test Case | Expected Behavior |\n|-----------|-------------------|\n| Basic conversion | POWER.md generated with manifest |\n| With dependencies | `mcp.json` added to files array |\n| Without dependencies | No `mcp.json` generated |\n| Complex sections (3+) | `steering/` directory created |\n\n资料来源：[src/core/conversion-engine.test.ts:80-150]()\n\n## Usage Examples\n\n### Convert to Steering File\n\n```typescript\nconst content = `---\nname: PDF Extractor\ndescription: Extract text from PDF files\n---\n\n# PDF Extractor\n\nExtract text content from PDF documents.`;\n\nconst result = engine.toSteeringFile(\n engine.parseSkill(content),\n 'https://example.com/skill.md'\n);\n\n// Result structure:\n// {\n// filename: \"pdf-extractor.md\",\n// content: \"# PDF Extractor Guidelines\\n\\n...\",\n// metadata: { originalSkill: \"PDF Extractor\", ... }\n// }\n```\n\n### Convert to Power\n\n```typescript\nconst content = `---\nname: React Best Practices\ndescription: Guide for React development\ndependencies:\n - react\n - react-dom\n---\n\n# React Best Practices\n\nContent with multiple sections...`;\n\nconst result = engine.toPower(\n engine.parseSkill(content),\n 'https://example.com/skill.md'\n);\n\n// Result structure:\n// {\n// powerName: \"react-best-practices\",\n// files: [\n// { path: \"POWER.md\", content: \"...\" },\n// { path: \"mcp.json\", content: \"...\" }\n// ]\n// }\n```\n\n资料来源：[examples/usage-examples.md:50-120]()\n\n## Summary\n\nThe Format Conversion system provides a robust bridge between Claude Skills and Kiro formats:\n\n- **Single Entry Point**: `ConversionEngine` class handles all conversions\n- **Two Output Formats**: Steering files (simple) and Powers (complex)\n- **Automatic Structure Detection**: Determines output complexity based on content\n- **Security Integration**: Works with the validation system for safe imports\n- **Comprehensive Error Handling**: Typed errors with context for debugging\n- **Full Test Coverage**: Unit tests for all major code paths\n\n---\n\n\n\n## Caching System\n\n### 相关页面\n\n相关主题：[Skill Discovery](#skill-discovery), [Type Definitions](#type-definitions)\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- [src/utils/cache.test.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/utils/cache.test.ts)\n- [README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n \n\n# Caching System\n\n## Overview\n\nThe Caching System in the Skill Loader MCP Server provides an in-memory caching layer with TTL (Time To Live) support. It is designed to reduce redundant API calls to external services like skills.sh, improving response times and reducing network overhead.\n\nThe cache implementation is generic and reusable, supporting any data type through TypeScript generics. It automatically expires entries after a configurable TTL and provides basic cache management operations.\n\n**Key Characteristics:**\n- In-memory storage using `Map` data structure\n- Configurable TTL per cache instance\n- Automatic expiration checking on access\n- Zero external dependencies\n\n资料来源：[src/utils/cache.ts:1-60]()\n\n---\n\n## Architecture\n\n### Component Diagram\n\n```mermaid\ngraph TB\n subgraph \"Caching System Components\"\n Cache[\"Cache Class\"]\n CacheEntry[\"CacheEntry Interface\"]\n end\n \n subgraph \"Data Structure\"\n Map[\"Map>\"]\n Data[\"data: T\"]\n Timestamp[\"timestamp: number\"]\n end\n \n subgraph \"Operations\"\n Get[\"get(key)\"]\n Set[\"set(key, data)\"]\n Has[\"has(key)\"]\n Delete[\"delete(key)\"]\n Clear[\"clear()\"]\n end\n \n Cache --> CacheEntry\n CacheEntry --> Data\n CacheEntry --> Timestamp\n Cache --> Map\n Cache -.-> Get\n Cache -.-> Set\n Cache -.-> Has\n Cache -.-> Delete\n Cache -.-> Clear\n```\n\n### Data Model\n\n```typescript\ninterface CacheEntry {\n data: T; // The cached value\n timestamp: number; // Unix timestamp when entry was created\n}\n```\n\n资料来源：[src/utils/cache.ts:9-13]()\n\n---\n\n## API Reference\n\n### Cache Class\n\n```typescript\nclass Cache {\n constructor(ttl: number)\n get(key: string): T | undefined\n set(key: string, data: T): void\n has(key: string): boolean\n delete(key: string): void\n clear(): void\n}\n```\n\n### Constructor\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `ttl` | `number` | Time to live in milliseconds |\n\n```typescript\nconstructor(ttl: number) {\n this.ttl = ttl;\n}\n```\n\n资料来源：[src/utils/cache.ts:22-28]()\n\n### get()\n\nRetrieves a cached value by key. Returns `undefined` if the key does not exist or the entry has expired.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `key` | `string` | Cache key |\n\n| Return Type | Description |\n|-------------|-------------|\n| `T \\| undefined` | Cached value or undefined if not found/expired |\n\n```typescript\nget(key: string): T | undefined {\n const entry = this.cache.get(key);\n \n if (!entry) {\n return undefined;\n }\n \n // Check if entry has expired\n if (Date.now() - entry.timestamp > this.ttl) {\n this.cache.delete(key);\n return undefined;\n }\n \n return entry.data;\n}\n```\n\n资料来源：[src/utils/cache.ts:37-53]()\n\n### set()\n\nStores a value in the cache with the current timestamp.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `key` | `string` | Cache key |\n| `data` | `T` | Data to cache |\n\n```typescript\nset(key: string, data: T): void {\n this.cache.set(key, {\n data,\n timestamp: Date.now(),\n });\n}\n```\n\n资料来源：[src/utils/cache.ts:60-67]()\n\n### has()\n\nChecks if a key exists in the cache and has not expired.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `key` | `string` | Cache key |\n\n| Return Type | Description |\n|-------------|-------------|\n| `boolean` | True if key exists and is not expired |\n\n```typescript\nhas(key: string): boolean {\n return this.get(key) !== undefined;\n}\n```\n\n资料来源：[src/utils/cache.ts:69-72]()\n\n### delete()\n\nRemoves a specific entry from the cache.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `key` | `string` | Cache key to delete |\n\n```typescript\ndelete(key: string): void {\n this.cache.delete(key);\n}\n```\n\n资料来源：[src/utils/cache.ts:74-76]()\n\n### clear()\n\nRemoves all entries from the cache.\n\n```typescript\nclear(): void {\n this.cache.clear();\n}\n```\n\n资料来源：[src/utils/cache.ts:78-80]()\n\n---\n\n## Cache Lifecycle\n\n### Entry Lifecycle Diagram\n\n```mermaid\ngraph LR\n A[\"set(key, data)\"] --> B[\"Entry Created
timestamp = Date.now()\"]\n B --> C{\"get(key) called?\"}\n C -->|Yes| D{\"Date.now() - timestamp
> TTL?\"}\n D -->|No| E[\"Return cached data\"]\n D -->|Yes| F[\"Delete expired entry\"]\n F --> G[\"Return undefined\"]\n C -->|No| H[\"Entry remains in cache\"]\n E --> H\n G --> I[\"Next get() call\"]\n I --> C\n```\n\n### Expiration Check Flow\n\n```mermaid\nflowchart TD\n A[\"get(key)\"] --> B{\"Entry exists?\"}\n B -->|No| C[\"Return undefined\"]\n B -->|Yes| D{\"Date.now() - timestamp
> TTL?\"}\n D -->|Yes| E[\"Delete entry
from cache\"]\n E --> F[\"Return undefined\"]\n D -->|No| G[\"Return cached data\"]\n```\n\n资料来源：[src/utils/cache.ts:37-53]()\n\n---\n\n## Configuration\n\n### TTL Configuration\n\nThe TTL (Time to Live) determines how long cached entries remain valid.\n\n| TTL Value | Duration | Use Case |\n|-----------|----------|----------|\n| 60,000 ms | 1 minute | Short-lived data, frequent updates |\n| 3,600,000 ms | 1 hour | Skills.sh directory listings |\n| 86,400,000 ms | 24 hours | Stable, rarely changing data |\n\n**Implementation Note:** The skills.sh integration uses a 1-hour TTL to cache search results and directory listings, reducing API calls while ensuring relatively fresh data.\n\n资料来源：[README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n\n---\n\n## Usage Examples\n\n### Basic Cache Usage\n\n```typescript\nimport { Cache } from './utils/cache.js';\n\n// Create a cache with 60 second TTL\nconst cache = new Cache(60_000);\n\n// Set a value\ncache.set('user:123', JSON.stringify({ name: 'Alice', role: 'admin' }));\n\n// Get the value\nconst userData = cache.get('user:123');\nif (userData) {\n console.log(JSON.parse(userData));\n}\n\n// Check existence\nif (cache.has('user:123')) {\n console.log('User exists in cache');\n}\n\n// Delete specific entry\ncache.delete('user:123');\n\n// Clear all entries\ncache.clear();\n```\n\n资料来源：[src/utils/cache.test.ts:1-22]()\n\n### Type-Safe Caching\n\n```typescript\n// Generic cache works with any type\ninterface Skill {\n name: string;\n description: string;\n owner: string;\n}\n\nconst skillCache = new Cache(3_600_000); // 1 hour TTL\n\nskillCache.set('pdf-extractor', {\n name: 'pdf-extractor',\n description: 'Extract text from PDF files',\n owner: 'anthropics'\n});\n\nconst skill = skillCache.get('pdf-extractor');\n// skill is typed as Skill | undefined\n```\n\n---\n\n## Test Coverage\n\nThe cache implementation includes comprehensive unit tests covering:\n\n| Test Case | Description |\n|-----------|-------------|\n| Stores and retrieves values | Basic set/get operations |\n| Returns undefined for missing keys | Cache miss behavior |\n| Expires entries after TTL | Automatic expiration |\n| `has()` returns true for valid keys | Existence check |\n| `delete()` removes entries | Manual removal |\n| `clear()` removes all entries | Bulk removal |\n\n资料来源：[src/utils/cache.test.ts:1-32]()\n\n### Test Implementation\n\n```typescript\nit('expires entries after TTL', () => {\n const cache = new Cache(1); // 1ms TTL\n cache.set('key1', 'value1');\n // Force expiry by waiting\n const start = Date.now();\n while (Date.now() - start < 5) { /* busy wait */ }\n expect(cache.get('key1')).toBeUndefined();\n});\n```\n\n资料来源：[src/utils/cache.test.ts:16-24]()\n\n---\n\n## Design Decisions\n\n### Why In-Memory Cache?\n\n1. **Simplicity**: No external dependencies required\n2. **Performance**: Direct memory access is extremely fast\n3. **Suitable for Server Use Case**: The MCP server runs as a single process where in-memory caching is appropriate\n\n### Why TTL-Based Expiration?\n\n- Ensures data freshness without manual invalidation\n- Automatic cleanup prevents memory leaks\n- Simple and predictable behavior\n\n### Why Check Expiration on Get?\n\n- Lazy expiration keeps the cache simple\n- No background timer overhead\n- Expired entries are cleaned on next access\n\n---\n\n## Limitations\n\n| Limitation | Impact |\n|------------|--------|\n| Single-process only | Cache not shared between server instances |\n| No persistence | Cache lost on server restart |\n| Memory bound | Large caches consume RAM |\n| No distributed invalidation | Cannot invalidate across processes |\n\n资料来源：[src/utils/cache.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/utils/cache.ts)\n\n---\n\n## Related Components\n\n```mermaid\ngraph LR\n Cache[\"Caching System\"] --> SkillResolver[\"SkillResolver\"]\n SkillResolver[\"SkillResolver\"] -->|Caches directory listings| Cache\n \n Cache --> Usage[\"MCP Tools
list_skills
search_skills\"]\n \n subgraph \"Storage\"\n Cache\n end\n \n subgraph \"Consumers\"\n SkillResolver\n Usage\n end\n```\n\nThe caching system is utilized by the `SkillResolver` for caching skills.sh directory listings to improve performance of listing and searching operations.\n\n---\n\n## Summary\n\nThe Caching System provides a lightweight, generic in-memory cache with TTL support. It serves as the foundational caching layer for the Skill Loader MCP Server, enabling efficient storage of frequently accessed data like skills.sh API responses. The system prioritizes simplicity and reliability over feature complexity, making it suitable for server-side caching in a single-process environment.\n\n---\n\n\n\n## Type Definitions\n\n### 相关页面\n\n相关主题：[Core Modules](#core-modules), [Caching System](#caching-system)\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- [CHANGELOG.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CHANGELOG.md) - 变更日志\n \n\n# Type Definitions\n\nThis page documents the type system for the Skill Loader MCP Server, covering core data models, error classes, and validation types used throughout the application.\n\n## Overview\n\nThe Skill Loader MCP Server uses TypeScript for type-safe development. The type system is organized around several key domains:\n\n- **Skill Data Models**: Structures for representing Claude Skills and their components\n- **Error Handling**: Hierarchical error classes with context and recovery suggestions\n- **Security Validation**: Types for security issue detection and severity levels\n- **API Responses**: Standardized response formats for MCP tools\n\n资料来源：[src/core/types.ts]()，[src/core/errors.ts]()\n\n## Core Data Models\n\n### Skill Structure\n\nThe skill data model represents Claude Skills with their metadata and content sections.\n\n```mermaid\nclassDiagram\n class SkillFrontmatter {\n +string name\n +string description\n +string[] dependencies\n }\n class SkillSection {\n +number level\n +string heading\n +string content\n }\n class ParsedSkill {\n +SkillFrontmatter frontmatter\n +string body\n +SkillSection[] sections\n }\n class ConversionResult {\n +string filename\n +string content\n +Record metadata\n }\n \n ParsedSkill *-- SkillFrontmatter\n ParsedSkill *-- SkillSection\n ConversionResult ..> ParsedSkill\n```\n\n### SkillFrontmatter\n\nThe frontmatter contains skill metadata defined in YAML format at the top of skill files.\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `name` | `string` | The skill name |\n| `description` | `string` | Brief description of the skill |\n| `dependencies` | `string[]` | Optional list of required dependencies |\n\n资料来源：[src/core/conversion-engine.ts]() (示例展示结构)\n\n### ParsedSkill\n\nA fully parsed skill document containing all extracted components.\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `frontmatter` | `SkillFrontmatter` | YAML metadata block |\n| `body` | `string` | Raw skill content body |\n| `sections` | `SkillSection[]` | Extracted markdown sections |\n\n资料来源：[src/core/conversion-engine.ts]()\n\n### SkillSection\n\nRepresents a heading section within a skill document.\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `level` | `number` | Heading level (1-6) |\n| `heading` | `string` | Section title text |\n| `content` | `string` | Section body content |\n\n## Error Class Hierarchy\n\nThe error system uses a hierarchical class structure for granular error handling.\n\n```mermaid\nclassDiagram\n class Error {\n +string message\n +string name\n +Date timestamp\n +string stack\n }\n \n class SkillLoaderError {\n +Date timestamp\n +Record context\n +getDetailedMessage()\n }\n \n class NetworkError {\n +string url\n +number? statusCode\n +number retryCount\n +getUserMessage()\n }\n \n class ValidationError {\n +string validationType\n +number? lineNumber\n +string[] details\n }\n \n class FileSystemError {\n +string operation\n +string filePath\n +string? systemError\n }\n \n class ParsingError {\n +string parseType\n +string? invalidContent\n +getUserMessage()\n }\n \n Error <|-- SkillLoaderError\n SkillLoaderError <|-- NetworkError\n SkillLoaderError <|-- ValidationError\n SkillLoaderError <|-- FileSystemError\n SkillLoaderError <|-- ParsingError\n```\n\n### Base Class: SkillLoaderError\n\nAll application errors extend the base `SkillLoaderError` class.\n\n```typescript\nclass SkillLoaderError extends Error {\n public readonly timestamp: Date;\n public readonly context: Record;\n}\n```\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `timestamp` | `Date` | When the error occurred |\n| `context` | `Record` | Additional error context data |\n\n资料来源：[src/core/errors.ts]()\n\n### NetworkError\n\nHandles network-related failures including connection issues, timeouts, and HTTP errors.\n\n```typescript\nclass NetworkError extends SkillLoaderError {\n public readonly url: string;\n public readonly statusCode?: number;\n public readonly retryCount: number;\n}\n```\n\n资料来源：[src/core/errors.ts]()\n\n**Recovery suggestions by status code:**\n\n| Status Code | Suggestion |\n|-------------|------------|\n| `404` | Verify skill name is correct; check repository exists |\n| `403` | Rate limit hit; wait a few minutes |\n| `>= 500` | Server issues; try again later |\n\n### ValidationError\n\nRepresents validation failures for format, security, schema, or content issues.\n\n```typescript\nclass 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| Property | Type | Description |\n|----------|------|-------------|\n| `validationType` | `ValidationType` | Category of validation failure |\n| `lineNumber` | `number?` | Line where error occurred (if applicable) |\n| `details` | `string[]` | List of specific validation issues |\n\n资料来源：[src/core/errors.ts]()\n\n### FileSystemError\n\nHandles file system operations including read, write, delete, and access errors.\n\n```typescript\nclass 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| Property | Type | Description |\n|----------|------|-------------|\n| `operation` | `FileOperation` | Type of file operation that failed |\n| `filePath` | `string` | Path involved in the error |\n| `systemError` | `string?` | Raw system error message |\n\n**System error code mappings:**\n\n| Error Code | Issue | Recovery |\n|------------|-------|----------|\n| `EACCES` / `EPERM` | Permission denied | Check file permissions |\n| `ENOSPC` | Disk full | Free up disk space |\n| `ENOENT` | Path not found | Verify directory exists |\n| `EEXIST` | File exists | Use --overwrite flag |\n\n资料来源：[src/core/errors.ts]()\n\n## Security Validation Types\n\n### ValidationIssue\n\nRepresents a detected security or content issue.\n\n```typescript\ninterface ValidationIssue {\n type: 'dangerous_command' | 'suspicious_pattern' | 'untrusted_source' | 'suspicious_file_op';\n description: string;\n location: string;\n}\n```\n\n| Type | Severity | Description |\n|------|----------|-------------|\n| `dangerous_command` | unsafe | Commands like `rm -rf`, `sudo`, `eval`, `exec` |\n| `suspicious_pattern` | warning | Code injection patterns like `${...}`, `$(...)` |\n| `untrusted_source` | unsafe | Non-GitHub source URLs |\n| `suspicious_file_op` | warning | Access to system directories (`/etc/`, `/usr/`, `/bin/`) |\n\n资料来源：[src/core/security-validator.ts]()\n\n### ValidationResult\n\nComplete validation outcome with severity classification.\n\n```typescript\ninterface ValidationResult {\n isValid: boolean;\n issues: ValidationIssue[];\n severity: 'safe' | 'warning' | 'unsafe';\n}\n```\n\n**Severity determination rules:**\n\n```mermaid\ngraph TD\n A[ValidationResult] --> B{issues.length === 0?}\n B -->|Yes| C[Return safe]\n B -->|No| D{Has untrusted_source?}\n D -->|Yes| E[Return unsafe]\n D -->|No| F{Has dangerous_command?}\n F -->|Yes| E\n F -->|No| G[Return warning]\n```\n\n资料来源：[src/core/security-validator.ts]()\n\n## API Response Types\n\n### SkillsShEntry\n\nRepresents a skill entry from skills.sh directory.\n\n```typescript\ninterface SkillsShEntry {\n name: string;\n description: string;\n owner: string;\n repo: string;\n installs: number;\n relevance?: number;\n rank?: number;\n trending?: boolean;\n}\n```\n\n### SkillsShV1Response\n\nAPI response wrapper for skills.sh v1 endpoints.\n\n```typescript\ninterface SkillsShV1Response {\n skills: SkillsShEntry[];\n total?: number;\n page?: number;\n pageSize?: number;\n}\n```\n\n### ConversionResponse\n\nResponse format for skill conversion operations.\n\n```typescript\ninterface ConversionResponse {\n success: boolean;\n content: string;\n filename: string;\n targetPath: string;\n metadata: {\n skillName: string;\n sourceUrl?: string;\n outputFormat: 'steering' | 'power';\n validationResult: ValidationResult;\n };\n}\n```\n\n资料来源：[examples/usage-examples.md]()\n\n## MCP Tool Parameters\n\n### Tool Input Schemas\n\n| Tool | Required Parameters | Optional Parameters |\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## Configuration Types\n\n### Server Configuration\n\n```typescript\ninterface ServerConfig {\n SKILLS_SH_API_KEY?: string;\n cache?: {\n skillsTTL: number; // Default: 3600000 (1 hour)\n };\n retry?: {\n maxRetries: number;\n baseDelay: number;\n };\n}\n```\n\n## Type Naming Conventions\n\nPer project coding standards:\n\n| Category | Convention | Example |\n|----------|------------|---------|\n| Files | kebab-case | `skill-fetcher.ts` |\n| Classes | PascalCase | `SkillFetcher` |\n| Functions | camelCase | `fetchSkill` |\n| Constants | UPPER_SNAKE_CASE | `MAX_RETRIES` |\n| Interfaces | PascalCase | `ISkillData` |\n\n资料来源：[CONTRIBUTING.md]()\n\n## Summary\n\nThe type system provides:\n\n1. **Type-safe data models** for skills, sections, and metadata\n2. **Hierarchical error handling** with context and recovery suggestions\n3. **Security validation** with issue categorization and severity levels\n4. **Standardized API responses** for all MCP tools\n\nAll types are defined in TypeScript with proper JSDoc documentation for IDE support and generated documentation.\n\n资料来源：[CHANGELOG.md]()\n\n---\n\n\n\n## Deployment and Configuration\n\n### 相关页面\n\n相关主题：[Getting Started](#getting-started), [Error Handling](#error-handling)\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- [CONTRIBUTING.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CONTRIBUTING.md)\n- [CHANGELOG.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CHANGELOG.md)\n- [src/core/errors.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts)\n \n\n# Deployment and Configuration\n\n## Overview\n\nThe Skill Loader MCP Server provides a comprehensive deployment model for integrating Claude skill management capabilities into various AI development environments. The deployment architecture supports multiple integration patterns, including integration with Kiro, Claude Desktop, and standalone operation modes. Configuration is primarily driven through environment variables and MCP server configuration files, enabling flexible deployment scenarios ranging from simple local installations to enterprise-scale distributed setups.\n\nThe server operates as a Model Context Protocol (MCP) server that exposes eight distinct tools for skill management operations. These tools interact with external services including the skills.sh marketplace API and GitHub repositories containing skill definitions. The deployment model emphasizes security through content validation, caching strategies for performance optimization, and comprehensive error handling mechanisms that provide actionable feedback for administrators and users alike.\n\n## Installation Methods\n\n### Global Installation\n\nGlobal installation provides system-wide access to the Skill Loader MCP Server, making it immediately available to all projects and users on a given system. This approach is recommended for scenarios where multiple projects require access to skill management capabilities without individual per-project configuration.\n\nThe global installation is performed using npm with the `-g` flag, which installs the package in the global npm registry location. For systems with multiple Node.js versions or requiring specific version management, npx can be used to execute the package directly without permanent installation.\n\n```bash\nnpm install -g @goldzulu/skill-loader-mcp-server\n```\n\n资料来源：[README.md:49](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md#L49)\n\n### Local Installation\n\nLocal installation is appropriate for project-specific deployments where the skill loader should be tracked as a project dependency. This approach ensures version consistency across team members and facilitates reproducible builds through package.json dependency management.\n\n```bash\nnpm install @goldzulu/skill-loader-mcp-server\n```\n\n资料来源：[README.md:53](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md#L53)\n\n### Development Installation\n\nFor contributors setting up the development environment, the installation process includes additional steps for building the TypeScript source and running tests. The development setup requires Node.js, npm or yarn, and Git for version control.\n\n```bash\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n\n# Run tests\nnpm test\n```\n\n资料来源：[CONTRIBUTING.md:14-19](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CONTRIBUTING.md#L14-L19)\n\n## Environment Variables\n\nThe Skill Loader MCP Server uses environment variables to configure runtime behavior and authentication. Understanding the distinction between required and optional environment variables is critical for successful deployment.\n\n### SKILLS_SH_API_KEY\n\nThe `SKILLS_SH_API_KEY` environment variable provides authentication for the skills.sh marketplace API. This key is required only for tools that access authenticated endpoints of the skills.sh service.\n\n| Tool | SKILLS_SH_API_KEY Required |\n|------|---------------------------|\n| `search_skills` | No (uses public API) |\n| `list_skills` | Yes |\n| `get_leaderboard` | Yes |\n| `fetch_skill` | No |\n| `validate_skill` | No |\n| `convert_to_steering` | No |\n| `convert_to_power` | No |\n| `import_skill` | No |\n\n资料来源：[README.md:57-58](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md#L57-L58)\n\nThe API key must be requested from Vercel, the platform hosting the skills.sh service. Organizations planning to use the authenticated listing and leaderboard features should coordinate with the skills.sh team to obtain appropriate credentials.\n\n## MCP Server Configuration\n\nThe Skill Loader MCP Server implements the Model Context Protocol specification version 1.29, utilizing the official `@modelcontextprotocol/sdk` for protocol compliance. Configuration varies depending on the target platform and deployment scenario.\n\n### Kiro Configuration\n\nIntegration with Kiro requires modification of the `mcp.json` configuration file. The server can be launched using npx for immediate execution or configured as a persistent server service.\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:65-76](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md#L65-L76)\n\nThe configuration specifies the npx command with the `-y` flag to automatically confirm package installation. The `args` array passes the package name as an argument to npx. The `env` block configures the skills.sh API key, which is optional and only required when accessing authenticated endpoints.\n\n### Claude Desktop Configuration\n\nClaude Desktop users can integrate the Skill Loader MCP Server by adding the server configuration to their Claude Desktop configuration file. The configuration structure differs slightly from Kiro, using the `skill-loader-mcp-server` command directly rather than npx invocation.\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资料来源：[README.md:87-97](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md#L87-L97)\n\nThe Claude Desktop configuration omits the `description` field and uses the globally installed command directly. This approach assumes the package has been installed globally via npm.\n\n### Standalone Operation\n\nFor scenarios requiring direct execution without MCP integration, the server can be launched in standalone mode. This mode is useful for testing, debugging, or batch processing operations where the full MCP protocol overhead is unnecessary.\n\n```bash\nskill-loader-mcp-server\n```\n\n资料来源：[README.md:99-101](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md#L99-L101)\n\n## Deployment Architecture\n\nThe deployment architecture follows a layered design that separates concerns between protocol handling, core business logic, and external service integration.\n\n```mermaid\ngraph TD\n A[Client Application] -->|MCP Protocol| B[MCP Server Layer]\n B -->|Request Dispatch| C[Tool Handlers]\n C --> D1[list_skills]\n C --> D2[search_skills]\n C --> D3[get_leaderboard]\n C --> D4[fetch_skill]\n C --> D5[validate_skill]\n C --> D6[convert_to_steering]\n C --> D7[convert_to_power]\n C --> D8[import_skill]\n D1 --> E[Skills.sh API Client]\n D2 --> E\n D3 --> E\n D4 --> F[GitHub Fetcher]\n E --> G[(Skills.sh API)]\n F --> H[(GitHub)]\n D5 --> I[Security Validator]\n D6 --> J[Conversion Engine]\n D7 --> J\n D8 --> K[Complete Workflow]\n K --> D4\n K --> D5\n K --> D7\n J --> L[(Output Files)]\n I --> M[Error Handler]\n M --> N[User Feedback]\n```\n\n## Tool Configuration Parameters\n\nEach MCP tool exposed by the server accepts specific parameters that control its behavior. Understanding these parameters is essential for effective configuration and usage.\n\n### search_skills\n\nThe `search_skills` tool searches the skills.sh marketplace using the public search API. No authentication is required for this endpoint.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `query` | string | Yes | - | Search query string |\n| `limit` | number | No | 20 | Maximum results (max: 50) |\n\n资料来源：[README.md:109-118](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md#L109-L118)\n\n### list_skills\n\nThe `list_skills` tool retrieves paginated results from the authenticated skills.sh directory endpoint. This tool requires the `SKILLS_SH_API_KEY` environment variable.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `page` | number | No | 1 | Page number for pagination |\n| `pageSize` | number | No | 50 | Results per page (max: 100) |\n\n资料来源：[README.md:122-131](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md#L122-L131)\n\n### get_leaderboard\n\nThe `get_leaderboard` tool retrieves trending or top-installed skills, sorted by installation count or trending score.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `timeframe` | string | No | 'all' | Time window: 'all' or '24h' |\n| `limit` | number | No | 20 | Maximum results (max: 50) |\n\n资料来源：[README.md:135-144](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md#L135-L144)\n\n### fetch_skill\n\nThe `fetch_skill` tool retrieves raw skill content directly from GitHub repositories. The tool supports both shorthand skill names and fully-qualified owner/repo identifiers.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `identifier` | string | Yes | Skill name or 'owner/repo' format |\n\n资料来源：[README.md:148-156](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md#L148-L156)\n\n### validate_skill\n\nThe `validate_skill` tool performs security analysis on skill content, scanning for dangerous patterns and potential security risks.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `content` | string | Yes | Skill content to validate |\n| `url` | string | No | Source URL for verification |\n\n资料来源：[README.md:160-168](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md#L160-L168)\n\n### convert_to_steering\n\nThe `convert_to_steering` tool transforms skill content into the Kiro steering file format, which is used for providing behavioral guidelines to AI models.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `content` | string | Yes | Skill content to convert |\n| `sourceUrl` | string | No | Original source URL for metadata |\n\n资料来源：[README.md:173-181](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md#L173-L181)\n\n### convert_to_power\n\nThe `convert_to_power` tool generates the Kiro power format, which includes additional components for complex skills. When a skill has dependencies or MCP server references, the tool automatically generates an `mcp.json` configuration file. For skills containing three or more complex sections, the tool creates a `steering/` subdirectory with structured content.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `content` | string | Yes | Skill content to convert |\n| `sourceUrl` | string | No | Original source URL for metadata |\n\n资料来源：[README.md:185-193](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md#L185-L193)\n\n### import_skill\n\nThe `import_skill` tool orchestrates the complete import workflow, combining fetch, validation, and conversion operations in a single atomic transaction.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `identifier` | string | Yes | - | Skill name or 'owner/repo' format |\n| `outputFormat` | string | Yes | - | 'steering' or 'power' |\n| `skipValidation` | boolean | No | false | Bypass security validation |\n\n资料来源：[README.md:198-207](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md#L198-L207)\n\n## Security Configuration\n\nThe security validation system is a critical component of the deployment configuration, providing defense-in-depth against potentially malicious skill content.\n\n### Validation Checks\n\nThe security validator scans skill content for multiple categories of risk:\n\n| Category | Patterns Detected |\n|----------|------------------|\n| Dangerous Commands | `rm -rf`, `sudo`, `eval`, `exec` |\n| Suspicious Paths | `/etc/`, `/usr/`, `/bin/` |\n| Code Injection | `${...}`, `$(...)` |\n| Untrusted Sources | Non-GitHub URLs |\n\n资料来源：[README.md:212-220](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md#L212-L220)\n\n### Validation Bypass\n\nThe `skipValidation` parameter on the `import_skill` tool allows administrators to bypass security checks when importing trusted skills. This parameter should be used cautiously and only for skills from verified sources.\n\n```json\n{\n \"tool\": \"import_skill\",\n \"arguments\": {\n \"identifier\": \"trusted/author/skill-name\",\n \"outputFormat\": \"power\",\n \"skipValidation\": false\n }\n}\n```\n\n资料来源：[examples/usage-examples.md:175-183](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md#L175-L183)\n\n## Error Handling Configuration\n\nThe error handling system provides structured error responses that enable programmatic error recovery and user-friendly error messages.\n\n### Error Response Format\n\nAll tools return errors in a consistent JSON format that includes the error message, affected tool name, and timestamp:\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:220-226](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md#L220-L226)\n\n### Error Categories\n\nThe error handling system classifies errors into distinct categories, each with specific recovery suggestions:\n\n| Error Type | Description | Recovery Actions |\n|------------|-------------|------------------|\n| Network Errors | Connection failures, timeouts | Check internet connection, verify GitHub availability |\n| Not Found Errors | Invalid skill identifiers | Verify skill name and repository |\n| Validation Errors | Security issues detected | Review security issues before proceeding |\n| Parsing Errors | Invalid YAML or markdown syntax | Check skill format and YAML syntax |\n\n资料来源：[examples/usage-examples.md:228-236](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md#L228-L236)\n\n### Custom Error Classes\n\nThe error handling infrastructure includes specialized error classes that provide contextual information for different failure scenarios. The `FileSystemError` class captures operation type, file path, and system-level error details for file-related failures.\n\n资料来源：[src/core/errors.ts:1-50](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts#L1-L50)\n\nThe `ParsingError` class tracks parser type, line numbers, column positions, and code snippets for format-related failures, enabling precise identification of parsing issues in skill content.\n\n## Caching Configuration\n\nThe server implements in-memory caching for skills.sh directory results to optimize performance and reduce API load.\n\n### Cache Behavior\n\n| Setting | Value | Description |\n|---------|-------|-------------|\n| Cache Type | In-memory | Stored in process memory |\n| TTL | 1 hour | Time before automatic refresh |\n| Cache Target | search_skills results | Cached API responses |\n| Refresh | Automatic on expiry | Proactive cache refresh |\n\n资料来源：[README.md:224-228](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md#L224-L228)\n\nThe caching strategy balances performance optimization with data freshness, automatically refreshing cached data when the TTL expires. This approach reduces API calls for frequently accessed data while ensuring users receive current information.\n\n## Typical Workflow Configuration\n\nThe repository documentation provides recommended workflow patterns for common deployment scenarios.\n\n### Discovery and Import Workflow\n\n```mermaid\ngraph LR\n A[Search Skills] --> B[Evaluate Results]\n B --> C{Find Skill?}\n C -->|Yes| D[List with Pagination]\n C -->|No| E[Refine Search]\n D --> F[Fetch Skill]\n F --> G[Validate Content]\n G --> H{Valid?}\n H -->|Yes| I[Convert Format]\n H -->|No| J[Report Issues]\n I --> K[Import Complete]\n```\n\nFor discovering skills, users should first search using the `search_skills` tool to find relevant skills by keyword. When multiple results exist, the `list_skills` tool provides paginated browsing of the full directory.\n\n资料来源：[examples/usage-examples.md:200-212](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md#L200-L212)\n\n### Validation Workflow\n\nWhen importing skills from unknown sources, a two-step validation approach is recommended:\n\n1. **Fetch the skill**: Retrieve the raw content using `fetch_skill`\n2. **Validate the content**: Use `validate_skill` to scan for security issues\n3. **Convert if safe**: Apply `convert_to_steering` or `convert_to_power` if validation passes\n\n```json\n{ \"tool\": \"fetch_skill\", \"arguments\": { \"identifier\": \"unknown/skill\" } }\n```\n\n```json\n{ \"tool\": \"validate_skill\", \"arguments\": { \"content\": \"...\", \"url\": \"...\" } }\n```\n\n资料来源：[examples/usage-examples.md:215-228](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md#L215-L228)\n\n### Complete Import Workflow\n\nFor streamlined operations, the `import_skill` tool combines all steps into a single atomic operation:\n\n1. **Search for trending skills**:\n ```json\n { \"tool\": \"get_leaderboard\", \"arguments\": { \"timeframe\": \"24h\", \"limit\": 20 } }\n ```\n\n2. **Import a trending skill**:\n ```json\n { \"tool\": \"import_skill\", \"arguments\": { \"identifier\": \"owner/skill-name\", \"outputFormat\": \"power\" } }\n ```\n\n资料来源：[examples/usage-examples.md:195-200](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md#L195-L200)\n\n## Project Structure Reference\n\nThe deployment configuration is organized within a structured project layout that separates core functionality, tool implementations, and utilities:\n\n```\nskill-loader-mcp-server/\n├── src/\n│ ├── core/ # Core functionality\n│ │ ├── conversion-engine.ts\n│ │ └── errors.ts\n│ ├── tools/ # MCP tool implementations\n│ ├── utils/ # Utility functions\n│ ├── index.ts # Main entry point\n│ └── cli.ts # CLI entry point\n├── examples/ # Usage examples\n├── dist/ # Compiled output\n└── tests/ # Test files\n```\n\n资料来源：[CONTRIBUTING.md:26-35](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CONTRIBUTING.md#L26-L35)\n\nThe `dist/` directory contains the compiled JavaScript output from the TypeScript source, which is the code actually executed during deployment. The `examples/` directory provides configuration examples and usage documentation that inform deployment procedures.\n\n## Version History\n\nThe deployment and configuration capabilities have evolved through the following version milestones:\n\n| Version | Date | Key Configuration Changes |\n|---------|------|---------------------------|\n| 1.1.0 | 2026-02-03 | Updated to `@modelcontextprotocol/sdk` v1.29, improved skills.sh API integration |\n| 1.0.0 | 2026-02-03 | Initial release with 9 MCP tools and comprehensive error handling |\n\n资料来源：[CHANGELOG.md:1-40](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CHANGELOG.md#L1-L40)\n\n---\n\n\n\n## Error Handling\n\n### 相关页面\n\n相关主题：[Security Validation](#security-validation), [Deployment and Configuration](#deployment)\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- [src/core/security-validator.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)\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 \n\n# Error Handling\n\nThe Skill Loader MCP Server implements a comprehensive error handling system designed to provide consistent, informative, and actionable error feedback across all MCP tools. The system follows a hierarchical class structure that categorizes errors by their domain (validation, file system, network) and provides context-rich error messages with recovery suggestions.\n\n## Architecture Overview\n\nThe error handling system is built on a base `SkillLoaderError` class that extends the native `Error` class, adding structured metadata and context tracking. This design enables consistent error formatting across all tools while maintaining type safety and enabling programmatic error handling.\n\n```mermaid\ngraph TD\n A[Error Occurs] --> B{SkillLoaderError}\n B --> C[ValidationError]\n B --> D[FileSystemError]\n B --> E[NetworkError]\n C --> C1[security validation]\n C --> C2[format validation]\n D --> D1[read/write/delete/access]\n E --> E1[connection timeout]\n E --> E2[rate limiting]\n \n style A fill:#ff6b6b\n style B fill:#4ecdc4\n style C fill:#45b7d1\n style D fill:#96ceb4\n style E fill:#ffeaa7\n```\n\n## Error Class Hierarchy\n\n### Base Class: SkillLoaderError\n\nThe base error class provides common functionality for all error types:\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `message` | `string` | Human-readable error message |\n| `code` | `string` | Machine-readable error code |\n| `timestamp` | `Date` | When the error occurred |\n| `context` | `Record` | Additional error context |\n\n资料来源：[src/core/errors.ts:1-50]()\n\n### ValidationError\n\nThrown when skill content fails security or format validation checks:\n\n```typescript\nexport class ValidationError extends SkillLoaderError {\n public readonly validationType: 'security' | 'format';\n public readonly details?: string[];\n}\n```\n\n**Validation Types:**\n\n1. **Security Validation** - Triggered when dangerous patterns are detected:\n - Dangerous commands (`rm -rf`, `sudo`, `eval`, `exec`)\n - Suspicious file operations (`/etc/`, `/usr/`, `/bin/`)\n - Code injection patterns (`${...}`, `$(...)`)\n - Untrusted sources (non-GitHub URLs)\n\n2. **Format Validation** - Triggered when skill structure is invalid:\n - Malformed YAML frontmatter\n - Missing required fields\n - Invalid markdown structure\n\n资料来源：[src/core/errors.ts:60-120]()\n\n### FileSystemError\n\nHandles errors during file operations:\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `operation` | `'read' \\| 'write' \\| 'delete' \\| 'access'` | Type of file operation |\n| `filePath` | `string` | Target file path |\n| `systemError` | `string \\| undefined` | Raw system error message |\n\n**System Error Codes:**\n\n| Code | Meaning | Recovery Action |\n|------|---------|-----------------|\n| `EACCES` / `EPERM` | Permission denied | Check file permissions |\n| `ENOSPC` | Disk full | Free up disk space |\n| `ENOENT` | Path not found | Verify directory exists |\n| `EEXIST` | File exists | Use `--overwrite` flag |\n\n资料来源：[src/core/errors.ts:130-200]()\n\n### NetworkError\n\nHandles connectivity and API-related failures:\n\n```typescript\nexport class NetworkError extends SkillLoaderError {\n public readonly url: string;\n public readonly statusCode?: number;\n public readonly retryable: boolean;\n}\n```\n\n**Retry Behavior:**\n\n- `retryable: true` - Transient errors (timeout, 503, rate limit)\n- `retryable: false` - Permanent failures (404, 401, 403)\n\n资料来源：[src/core/errors.ts:200-280]()\n\n## Security Validation\n\nThe security validator analyzes skill content before import to prevent malicious code execution.\n\n### Security Issue Types\n\n```mermaid\ngraph LR\n A[Skill Content] --> B{Security Validator}\n B --> C[Dangerous Commands]\n B --> D[Suspicious Patterns]\n B --> E[Untrusted Sources]\n \n C --> C1[rm -rf, sudo, eval]\n D --> D1[Code injection, path traversal]\n E --> E1[Non-GitHub URLs]\n```\n\n### Severity Levels\n\n| Severity | Condition | Import Behavior |\n|----------|-----------|------------------|\n| `safe` | No issues found | Allowed |\n| `warning` | Suspicious patterns only | Allowed with notice |\n| `unsafe` | Dangerous commands OR untrusted sources | Blocked by default |\n\n资料来源：[src/core/security-validator.ts:1-50]()\n\n### Validation Response Format\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资料来源：[examples/usage-examples.md:30-40]()\n\n## Error Response Format\n\nAll MCP tools return errors in a standardized JSON format:\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### Common Error Scenarios\n\n| Scenario | Tool | Error Message Pattern |\n|----------|------|----------------------|\n| Network failure | `fetch_skill`, `list_skills` | \"Failed to connect to GitHub/skills.sh\" |\n| Not found | `fetch_skill` | \"Skill not found: {identifier}\" |\n| Validation failure | `validate_skill`, `import_skill` | \"Security validation failed\" |\n| Parsing error | `convert_to_*` | \"Failed to parse skill content\" |\n\n资料来源：[README.md:150-170]()\n\n## Error Recovery Suggestions\n\nThe error system provides actionable recovery guidance based on error type.\n\n### Validation Errors\n\n```\nSuggestions:\n- Review the skill content manually\n- Contact the skill author about security concerns\n- Use a different skill from a trusted source\n```\n\n### File System Errors\n\n```\nSuggestions:\n- Check file permissions (EACCES/EPERM)\n- Free up disk space (ENOSPC)\n- Verify the directory exists (ENOENT)\n- Use the --overwrite flag to replace existing files (EEXIST)\n```\n\n### Network Errors\n\n```\nSuggestions:\n- Check internet connection\n- Verify GitHub availability\n- Retry the request after a short delay\n- Use cached results if available\n```\n\n资料来源：[src/core/errors.ts:180-220]()\n\n## Error Flow Diagram\n\n```mermaid\nsequenceDiagram\n participant Tool as MCP Tool\n participant Engine as Conversion Engine\n participant Validator as Security Validator\n participant FS as File System\n \n Tool->>Engine: process(content)\n Engine->>Validator: validate(content)\n \n alt Validation Failed\n Validator-->>Tool: ValidationError\n Tool->>Tool: Return error with suggestions\n end\n \n Engine->>FS: write(output)\n \n alt File System Error\n FS-->>Tool: FileSystemError\n Tool->>Tool: Return error with path info\n end\n \n alt Success\n Validator-->>Engine: isValid: true\n Engine-->>Tool: Success result\n end\n```\n\n## Best Practices\n\n1. **Always validate before import** - Use `validate_skill` to check content safety\n2. **Handle errors gracefully** - Check for error responses before processing results\n3. **Use try-catch blocks** - Wrap tool calls to handle unexpected errors\n4. **Check severity levels** - Distinguish between warnings and blocking errors\n5. **Preserve error context** - Log error timestamps and tool names for debugging\n\n资料来源：[examples/usage-examples.md:180-200]()\n\n## Configuration\n\nError handling behavior can be influenced through these configuration options:\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `skipValidation` | Bypass security checks during import | `false` |\n| `timeout` | Request timeout in milliseconds | Platform-specific |\n| `maxRetries` | Maximum retry attempts for network errors | Configurable |\n\n资料来源：[README.md:140-150]()\n\n---\n\n---\n\n## Doramagic Pitfall Log\n\nProject: goldzulu/skill-loader-mcp-server\n\nSummary: Found 9 potential pitfall items; 0 are high/blocking. Highest priority: configuration - 可能修改宿主 AI 配置.\n\n## 1. configuration · 可能修改宿主 AI 配置\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- User impact: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Suggested check: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Guardrail action: 涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- Evidence: capability.host_targets | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | host_targets=mcp_host, claude\n\n## 2. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\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\n## 3. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | last_activity_observed missing\n\n## 4. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | no_demo; severity=medium\n\n## 5. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | no_demo; severity=medium\n\n## 6. security_permissions · 来源证据：v1.0.0 - Initial Release\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.0.0 - Initial Release\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_fb2ea148b03e4fb5993d3b2db08b43f6 | https://github.com/goldzulu/skill-loader-mcp-server/releases/tag/v1.0.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 7. security_permissions · 来源证据：v1.1.0 — skills.sh API migration & Power format update\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.1.0 — skills.sh API migration & Power format update\n- User impact: 可能影响升级、迁移或版本选择。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_78c48e3f6caa41a9bf94d3dba01baf0c | https://github.com/goldzulu/skill-loader-mcp-server/releases/tag/v1.1.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | issue_or_pr_quality=unknown\n\n## 9. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: 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 output with a Doramagic pitfall appendix.",
"title": "skill-loader-mcp-server 说明书",
"toc": [
"https://github.com/goldzulu/skill-loader-mcp-server 项目说明书",
"目录",
"Getting Started",
"Overview",
"Prerequisites",
"Installation",
"Configuration",
"Available Tools",
"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\nThe following material strengthens the Repomix/AI Context Pack body. Human Manual is only a reading skeleton; pitfall logs become hard operating constraints for the host AI.\n\n## Human Manual Skeleton\n\nUsage rule: this is only a reading path and salience signal, not factual authority. Concrete facts must still come from repo evidence / Claim Graph.\n\nHard rules for the host AI:\n- Do not treat page titles, order, summaries, or importance as project facts.\n- When explaining the Human Manual skeleton, state that it is only a reading path / salience signal.\n- Capability, installation, compatibility, runtime status, and risk judgments must cite repo evidence, source paths, or Claim Graph.\n\n- **Getting Started**：importance `high`\n - source_paths: README.md, package.json\n- **Project Structure**：importance `high`\n - source_paths: src/index.ts, src/cli.ts, tsconfig.json\n- **MCP Server Architecture**：importance `high`\n - source_paths: src/index.ts, src/cli.ts, package.json\n- **Core Modules**：importance `high`\n - source_paths: src/core/conversion-engine.ts, src/core/security-validator.ts, src/core/skill-fetcher.ts, src/core/skill-resolver.ts\n- **MCP Tools Reference**：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- **Skill Discovery**：importance `high`\n - source_paths: src/core/skill-resolver.ts, src/tools/search-skills.ts, src/tools/list-skills.ts, src/tools/get-leaderboard.ts\n- **Security Validation**：importance `high`\n - source_paths: src/core/security-validator.ts, src/core/security-validator.test.ts, src/tools/validate-skill.ts\n- **Format Conversion**：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\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\nHard rules for the host AI:\n- Without repo_clone_verified=true, do not claim the source code has been read.\n- Without repo_inspection_verified=true, do not turn README/docs/package observations into facts.\n- Without quick_start_verified=true, do not claim the Quick Start has been successfully run.\n\n## Doramagic Pitfall Constraints\n\nThese rules come from Doramagic discovery, validation, or compilation pitfalls. The host AI must treat them as operating constraints, not general background notes.\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: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\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: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\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: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\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: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\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: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\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: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\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: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\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: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\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: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n",
"summary": "Context and operating boundaries for host AI agents.",
"title": "AI Context Pack"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card\n\nProject: goldzulu/skill-loader-mcp-server\n\n## Doramagic Trial Decision\n\nCurrent decision: it can enter pre-publication recommendation checks. First use should still start with least privilege, a temporary directory, and reversible configuration.\n\n## What The User Can Do Now\n\n- Read the Human Manual first to understand the project purpose and main workflows.\n- Use Prompt Preview for pre-install exploration; it validates interaction shape, not real execution.\n- Run official Quick Start commands only inside an isolated environment, not a primary setup.\n\n## Do Not Do Yet\n\n- Do not treat Prompt Preview as a real project execution result.\n- Do not treat metadata-only validation as sandbox installation validation.\n- Do not describe unverified capabilities as supported, working, or safe to install.\n- Do not provide production data, private files, real secrets, or primary host configuration on first trial.\n\n## Pre-Install Checklist\n\n- Host AI match: mcp_host, claude\n- Official installation entry status: official entry point found\n- Isolated temporary directory, temporary host, or container validation: required\n- Configuration rollback path: required\n- API keys, network access, file access, or host configuration changes: treat as high risk until confirmed\n- Installation command, actual output, and failure logs: must be recorded\n\n## Current Blockers\n\n- review_required: community_discussion_evidence_below_public_threshold\n\n## Project-Specific Pitfalls\n\n- 可能修改宿主 AI 配置 (medium): 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 Suggested check: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- 能力判断依赖假设 (medium): 假设不成立时，用户拿不到承诺的能力。 Suggested check: 将假设转成下游验证清单。\n- 维护活跃度未知 (medium): 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项 (medium): 下游已经要求复核，不能在页面中弱化。 Suggested check: 进入安全/权限治理复核队列。\n- 存在评分风险 (medium): 风险会影响是否适合普通用户安装。 Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n\n## Risk And Permission Notes\n\n- no_demo: medium\n\n## Evidence Gaps\n\n- No structured evidence gaps are currently visible.\n",
"summary": "Installation, permission, validation, and pre-recommendation risks.",
"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-18 02:39:22 UTC\n\n## 目录\n\n- [Getting Started](#getting-started)\n- [Project Structure](#project-structure)\n- [MCP Server Architecture](#mcp-server-architecture)\n- [Core Modules](#core-modules)\n- [MCP Tools Reference](#mcp-tools-reference)\n- [Skill Discovery](#skill-discovery)\n- [Security Validation](#security-validation)\n- [Format Conversion](#format-conversion)\n- [Caching System](#caching-system)\n- [Type Definitions](#type-definitions)\n- [Deployment and Configuration](#deployment)\n- [Error Handling](#error-handling)\n\n\n\n## Getting Started\n\n### 相关页面\n\n相关主题：[Deployment and Configuration](#deployment), [MCP Server Architecture](#mcp-server-architecture)\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- [CONTRIBUTING.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CONTRIBUTING.md)\n- [CHANGELOG.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CHANGELOG.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 \n\n# Getting Started\n\nThe **Skill Loader MCP Server** is a Model Context Protocol (MCP) server that enables discovery, fetching, validation, and conversion of Claude Skills from the skills.sh marketplace into formats compatible with the Kiro platform. This guide provides everything you need to install, configure, and begin using the server effectively.\n\n## Overview\n\nThe Skill Loader MCP Server acts as a bridge between the skills.sh marketplace and local skill management systems. It provides a unified interface for:\n\n- Discovering available skills through search and browsing\n- Fetching skill content directly from GitHub repositories\n- Validating skill content for security issues before import\n- Converting skills to Kiro steering file format or power format\n- Performing complete end-to-end skill imports with a single command\n\n资料来源：[README.md:1-10]()\n\n### Architecture Overview\n\n```mermaid\ngraph TD\n A[Client] -->|MCP Protocol| B[Skill Loader MCP Server]\n B --> C[Skills.sh API]\n B --> D[GitHub Raw Content]\n \n C -->|Search Results| E[list_skills]\n C -->|Trending Data| F[get_leaderboard]\n D -->|Raw .md| G[fetch_skill]\n \n G --> H[validate_skill]\n H -->|Safe| I[convert_to_steering]\n H -->|Safe| J[convert_to_power]\n \n I --> K[Kiro Steering Files]\n J --> L[Kiro Power Format]\n \n G --> M[import_skill]\n M --> H\n M -->|Validated| I\n M -->|Validated| J\n```\n\n## Prerequisites\n\nBefore installing the Skill Loader MCP Server, ensure your environment meets the following requirements:\n\n| Requirement | Version/Details |\n|-------------|------------------|\n| Node.js | v18.0.0 or higher |\n| npm or yarn | Latest stable version |\n| Git | Installed and configured |\n| Skills.sh API Key | Optional (required only for `list_skills` and `get_leerboard`) |\n\n资料来源：[CONTRIBUTING.md:1-5]()\n\n## Installation\n\n### Global Installation\n\nFor system-wide access, install the package globally using npm:\n\n```bash\nnpm install -g @goldzulu/skill-loader-mcp-server\n```\n\n资料来源：[README.md:30-32]()\n\n### Local Installation\n\nFor project-specific usage, install locally:\n\n```bash\nnpm install @goldzulu/skill-loader-mcp-server\n```\n\n资料来源：[README.md:34-36]()\n\n## Configuration\n\n### Environment Variables\n\nThe server uses a single environment variable for authenticated API access:\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `SKILLS_SH_API_KEY` | No | API key for the skills.sh authenticated `/api/v1/skills` endpoint. Required only for `list_skills` and `get_leaderboard` tools. Not required for `search_skills`. |\n\n资料来源：[README.md:43-47]()\n\n### Configuration with Kiro\n\nAdd the server to your Kiro configuration file (`mcp.json`):\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:53-64]()\n\n### Configuration with Claude Desktop\n\nFor Claude Desktop integration, add to your configuration:\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资料来源：[README.md:70-80]()\n\n## Available Tools\n\nThe server provides eight MCP tools for skill management. Each tool accepts JSON-formatted arguments and returns structured responses.\n\n资料来源：[README.md:82-100]()\n\n### Tool Overview\n\n| Tool | Authentication | Purpose |\n|------|----------------|---------|\n| `search_skills` | Not required | Search skills by keyword |\n| `list_skills` | Required | List all available skills with pagination |\n| `get_leaderboard` | Required | Get trending or top-installed skills |\n| `fetch_skill` | Not required | Fetch raw skill content from GitHub |\n| `validate_skill` | Not required | Validate skill content for security issues |\n| `convert_to_steering` | Not required | Convert skill to Kiro steering file format |\n| `convert_to_power` | Not required | Convert skill to Kiro power format |\n| `import_skill` | Not required | Complete import workflow (fetch + validate + convert) |\n\n资料来源：[README.md:82-100]()\n\n### 1. search_skills\n\nSearch for skills by keyword using the skills.sh public search API. No authentication required.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `query` | string | Yes | - | Search query |\n| `limit` | number | No | 20 | Maximum results (max: 50) |\n\n**Example Request:**\n```json\n{\n \"tool\": \"search_skills\",\n \"arguments\": {\n \"query\": \"pdf\",\n \"limit\": 5\n }\n}\n```\n\n**Example Response:**\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资料来源：[examples/usage-examples.md:1-50]()\n\n### 2. list_skills\n\nList all available skills from skills.sh with pagination. Requires `SKILLS_SH_API_KEY`.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `page` | number | No | 1 | Page number |\n| `pageSize` | number | No | 50 | Results per page (max: 100) |\n\n**Example Request:**\n```json\n{\n \"tool\": \"list_skills\",\n \"arguments\": {\n \"page\": 1,\n \"pageSize\": 10\n }\n}\n```\n\n资料来源：[README.md:102-115]()\n\n### 3. get_leaderboard\n\nGet trending or top-installed skills. Requires `SKILLS_SH_API_KEY`.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `timeframe` | string | No | `'all'` | `'all'` or `'24h'` |\n| `limit` | number | No | 20 | Maximum results (max: 50) |\n\n**Example Request:**\n```json\n{\n \"tool\": \"get_leaderboard\",\n \"arguments\": {\n \"timeframe\": \"24h\",\n \"limit\": 10\n }\n}\n```\n\n**Example Response:**\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资料来源：[examples/usage-examples.md:90-120]()\n\n### 4. fetch_skill\n\nFetch raw skill content directly from GitHub. Supports both simple skill names and `owner/repo` format.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `identifier` | string | Yes | Skill name or `owner/repo` format |\n\n**Example Request:**\n```json\n{\n \"tool\": \"fetch_skill\",\n \"arguments\": {\n \"identifier\": \"anthropics/pdf-extractor\"\n }\n}\n```\n\n**Example Response:**\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:130-165]()\n\n### 5. validate_skill\n\nValidate skill content for security issues before importing. This tool scans for dangerous commands, suspicious patterns, and untrusted sources.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `content` | string | Yes | Skill content to validate |\n| `url` | string | No | Source URL for verification |\n\n**Example Request:**\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**Security Checks Performed:**\n\n| Check Type | Description |\n|------------|-------------|\n| `dangerous_command` | Commands like `rm -rf`, `sudo`, `eval`, `exec` |\n| `suspicious_file_operation` | Access to system directories (`/etc/`, `/usr/`, `/bin/`) |\n| `code_injection` | Patterns like `${...}`, `$(...)` |\n| `untrusted_source` | Non-GitHub source URLs |\n\n资料来源：[README.md:155-175]()\n\n**Severity Levels:**\n\n| Severity | Conditions |\n|----------|------------|\n| `safe` | No issues found |\n| `warning` | Suspicious patterns detected |\n| `unsafe` | Dangerous commands or untrusted sources |\n\n资料来源：[src/core/security-validator.ts:1-30]()\n\n### 6. convert_to_steering\n\nConvert skill content to Kiro steering file format. This format adds metadata headers and preserves the original skill structure.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `content` | string | Yes | Skill content |\n| `sourceUrl` | string | No | Original source URL |\n\n**Example Request:**\n```json\n{\n \"tool\": \"convert_to_steering\",\n \"arguments\": {\n \"content\": \"---\\nname: PDF Extractor\\ndescription: Extract text from PDF files\\n---\\n\\n# PDF Extractor\\n\\nExtract text content from PDF documents.\",\n \"sourceUrl\": \"https://raw.githubusercontent.com/anthropics/skills/main/skills/pdf-extractor/SKILL.md\"\n }\n}\n```\n\n资料来源：[examples/usage-examples.md:195-220]()\n\n### 7. convert_to_power\n\nConvert skill to Kiro power format. This generates additional configuration files based on skill complexity:\n\n- **mcp.json**: Generated when the skill has dependencies or MCP server references\n- **steering/ directory**: Generated when the skill has 3+ complex sections\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `content` | string | Yes | Skill content |\n| `sourceUrl` | string | No | Original source URL |\n\n**Example Request:**\n```json\n{\n \"tool\": \"convert_to_power\",\n \"arguments\": {\n \"content\": \"---\\nname: Test\\ndescription: A test skill\\n---\\n\\n# Test\",\n \"sourceUrl\": \"https://example.com/skill.md\"\n }\n}\n```\n\n资料来源：[README.md:190-205]()\n\n### 8. import_skill\n\nComplete import workflow combining fetch, validate, and convert operations in a single command.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `identifier` | string | Yes | Skill identifier (`owner/skill-name` format) |\n| `outputFormat` | string | Yes | `'steering'` or `'power'` |\n| `skipValidation` | boolean | No | Skip security validation (default: false) |\n\n**Example Request (Steering Format):**\n```json\n{\n \"tool\": \"import_skill\",\n \"arguments\": {\n \"identifier\": \"anthropics/pdf-extractor\",\n \"outputFormat\": \"steering\"\n }\n}\n```\n\n**Example Response:**\n```json\n{\n \"success\": true,\n \"content\": \"---\\noriginal_skill: PDF Extractor\\nsource_url: https://raw.githubusercontent.com/anthropics/skills/main/skills/pdf-extractor/SKILL.md\\nimported_at: '2024-01-15T10:30:00.000Z'\\n---\\n\\n...\",\n \"filename\": \"pdf-extractor.md\",\n \"targetPath\": \".kiro/steering/pdf-extractor.md\",\n \"metadata\": {\n \"skillName\": \"PDF Extractor\",\n \"sourceUrl\": \"https://raw.githubusercontent.com/anthropics/skills/main/skills/pdf-extractor/SKILL.md\",\n \"outputFormat\": \"steering\",\n \"validationResult\": {\n \"isValid\": true,\n \"issues\": [],\n \"severity\": \"safe\"\n }\n }\n}\n```\n\n资料来源：[examples/usage-examples.md:250-280]()\n\n## Common Workflows\n\n### Discovery and Import Workflow\n\n```mermaid\ngraph LR\n A[Search Skills] --> B[Find Interesting Skill]\n B --> C[Fetch Skill]\n C --> D{Validate}\n D -->|Issues Found| E[Review Security Issues]\n D -->|Safe| F[Choose Format]\n E -->|Override| F\n F --> G[Import as Steering]\n F --> H[Import as Power]\n```\n\n### Quick Start: Discover and Import\n\n1. Search for skills by keyword:\n```json\n{ \"tool\": \"search_skills\", \"arguments\": { \"query\": \"pdf\", \"limit\": 20 } }\n```\n\n2. Import a trending skill:\n```json\n{ \"tool\": \"import_skill\", \"arguments\": { \"identifier\": \"owner/skill-name\", \"outputFormat\": \"power\" } }\n```\n\n### Validate Before Importing\n\n1. Fetch the skill:\n```json\n{ \"tool\": \"fetch_skill\", \"arguments\": { \"identifier\": \"unknown/skill\" } }\n```\n\n2. Validate the content:\n```json\n{ \"tool\": \"validate_skill\", \"arguments\": { \"content\": \"...\", \"url\": \"...\" } }\n```\n\n3. If safe, convert and use:\n```json\n{ \"tool\": \"convert_to_steering\", \"arguments\": { \"content\": \"...\", \"sourceUrl\": \"...\" } }\n```\n\n资料来源：[examples/usage-examples.md:330-360]()\n\n## Caching\n\nThe server implements in-memory caching for skills.sh search results to reduce API calls and improve performance.\n\n| Cache Property | Value |\n|----------------|-------|\n| Storage | In-memory |\n| TTL | 1 hour |\n| Refresh | Automatic on expiration |\n\n资料来源：[README.md:180-182]()\n\n## Error Handling\n\nAll tools return errors in a consistent format:\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### Common Error Scenarios\n\n| Error Type | Resolution |\n|------------|------------|\n| Network errors | Check internet connection, GitHub availability |\n| Not found errors | Verify skill name and repository |\n| Validation errors | Review security issues before proceeding |\n| Parsing errors | Check skill format and YAML syntax |\n\n资料来源：[examples/usage-examples.md:365-375]()\n\n## Development Setup\n\nFor local development and contribution:\n\n```bash\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n\n# Run tests\nnpm test\n```\n\n资料来源：[CONTRIBUTING.md:8-14]()\n\n### Project Structure\n\n```\nskill-loader-mcp-server/\n├── src/\n│ ├── core/ # Core functionality\n│ │ ├── conversion-engine.ts\n│ │ ├── security-validator.ts\n│ │ └── errors.ts\n│ ├── tools/ # MCP tool implementations\n│ ├── utils/ # Utility functions\n│ ├── index.ts # Main entry point\n│ └── cli.ts # CLI entry point\n├── examples/ # Usage examples\n├── dist/ # Compiled output\n└── tests/ # Test files\n```\n\n资料来源：[CONTRIBUTING.md:16-28]()\n\n## Supported Versions\n\n| Version | Status | Notes |\n|---------|--------|-------|\n| 1.1.0 | Latest | Updated to `@modelcontextprotocol/sdk` v1.29 |\n| 1.0.0 | Previous | Initial release |\n\n资料来源：[CHANGELOG.md:1-10]()\n\n## Next Steps\n\n- Review the [Usage Examples](examples/usage-examples.md) for detailed tool demonstrations\n- Check the [CONTRIBUTING.md](CONTRIBUTING.md) if you wish to contribute to the project\n- Explore the [CHANGELOG.md](CHANGELOG.md) for version history and recent changes\n\n---\n\n\n\n## Project Structure\n\n### 相关页面\n\n相关主题：[Getting Started](#getting-started), [Core Modules](#core-modules)\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/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- [CONTRIBUTING.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CONTRIBUTING.md)\n \n\n# Project Structure\n\nThe skill-loader-mcp-server is a Model Context Protocol (MCP) server that enables discovery, fetching, validation, and conversion of Claude skills from the skills.sh marketplace. The project follows a modular architecture with clear separation between core functionality, MCP tool implementations, and utility modules.\n\n## Architecture Overview\n\nThe server is built on the `@modelcontextprotocol/sdk` framework and exposes 9 MCP tools for skill management operations. The architecture follows a layered pattern where the core layer handles business logic, the tools layer exposes MCP-compatible interfaces, and the utils layer provides shared functionality.\n\n```mermaid\ngraph TD\n A[Client] --> B[MCP Server Entry]\n B --> C[Tool Handlers]\n C --> D[Core Services]\n C --> E[SkillResolver]\n C --> F[ConversionEngine]\n C --> G[SecurityValidator]\n D --> H[skills.sh API]\n D --> I[GitHub API]\n G --> J[Error System]\n```\n\n## Directory Structure\n\n```\nskill-loader-mcp-server/\n├── src/\n│ ├── core/ # Core business logic\n│ ├── tools/ # MCP tool implementations\n│ ├── utils/ # Utility functions\n│ ├── index.ts # Main entry point\n│ └── cli.ts # CLI entry point\n├── examples/ # Usage examples\n├── dist/ # Compiled output\n├── tests/ # Test files\n├── package.json\n└── tsconfig.json\n```\n\n### Source Directory Organization\n\nThe `src/` directory contains the primary application code organized into functional layers:\n\n| Directory | Purpose | Key Files |\n|-----------|---------|-----------|\n| `core/` | Business logic and domain operations | `conversion-engine.ts`, `security-validator.ts`, `errors.ts` |\n| `tools/` | MCP tool handler implementations | Tool definitions and handlers |\n| `utils/` | Shared utility functions | Parsers, helpers, constants |\n\n## Entry Points\n\nThe project provides two entry points for different execution contexts.\n\n### Main Entry Point (index.ts)\n\nThe primary entry point initializes the MCP server with stdio transport and registers all available tools. This is the standard entry used when the server runs as an MCP server integration.\n\n```typescript\n// Conceptual structure from src/index.ts\nimport { Server } from '@modelcontextprotocol/sdk/server/index.js';\nimport { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';\n\nconst server = new Server(\n { name: 'skill-loader', version: '1.1.0' },\n { capabilities: { tools: {} } }\n);\n\n// Register tools and start transport\nconst transport = new StdioServerTransport();\nawait server.connect(transport);\n```\n\n资料来源：[CONTRIBUTING.md:23-24]()\n\n### CLI Entry Point (cli.ts)\n\nThe CLI entry point provides standalone execution capability, allowing the server to run as a command-line utility. This is useful for direct invocation and debugging scenarios.\n\n资料来源：[CONTRIBUTING.md:19]()\n\n## Core Layer Modules\n\n### Conversion Engine\n\nThe conversion engine (`src/core/conversion-engine.ts`) handles transformation of skills between different formats. It supports conversion to steering files and power formats with additional generation capabilities.\n\n**Key Responsibilities:**\n\n- Parse YAML frontmatter and markdown body from skill content\n- Convert to Kiro steering file format with metadata preservation\n- Generate POWER.md content with dependencies section\n- Create `mcp.json` for skills with dependencies or tool references\n- Generate `steering/` directory for skills with multiple complex sections\n- Extract keywords from descriptions for metadata\n\n**Conversion Output Formats:**\n\n| Format | Output File | Generation Triggers |\n|--------|-------------|---------------------|\n| Steering | `filename.md` | Standard conversion |\n| Power | `POWER.md` | Power format conversion |\n| MCP Config | `mcp.json` | Skills with dependencies or MCP server references |\n| Steering Directory | `steering/*.md` | Skills with 3+ complex sections |\n\n资料来源：[src/core/conversion-engine.ts:1-200]()\n\n### Security Validator\n\nThe security validator (`src/core/security-validator.ts`) scans skill content for potential security threats before import. It provides a consistent validation interface across all import operations.\n\n**Security Checks Performed:**\n\n| Check Type | Description | Severity |\n|------------|-------------|----------|\n| `dangerous_command` | Commands like `rm -rf`, `sudo`, `eval`, `exec` | unsafe |\n| `suspicious_path` | Access to system paths (`/etc/`, `/usr/`, `/bin/`) | unsafe |\n| `code_injection` | Injection patterns (`${...}`, `$(...)`) | warning |\n| `untrusted_source` | Non-GitHub URLs | unsafe |\n\n**Severity Levels:**\n\n- **safe**: No issues detected\n- **warning**: Suspicious patterns found, import allowed\n- **unsafe**: Dangerous patterns detected, import blocked\n\n资料来源：[src/core/security-validator.ts:1-100]()\n\n### Error Handling System\n\nThe error system (`src/core/errors.ts`) provides structured error types with recovery suggestions. All errors extend a base `SkillLoaderError` class with context tracking.\n\n**Error Hierarchy:**\n\n| Error Class | Use Case | Context Fields |\n|-------------|----------|----------------|\n| `NetworkError` | GitHub/API connectivity failures | `statusCode`, `url` |\n| `ValidationError` | Format, security, schema issues | `validationType`, `details` |\n| `FileSystemError` | Permission, disk, path issues | `operation`, `filePath` |\n| `SkillLoaderError` | Base class for all errors | `operation`, `timestamp` |\n\n资料来源：[src/core/errors.ts:1-150]()\n\n## Tool Layer\n\nThe tools layer implements MCP-compatible handlers that expose core functionality to MCP clients. Each tool follows a consistent pattern of parameter validation, execution, and response formatting.\n\n### Available MCP Tools\n\n| Tool | Purpose | Authentication Required |\n|------|---------|------------------------|\n| `search_skills` | Search skills.sh by keyword | No |\n| `list_skills` | Paginated listing of all skills | Yes (API key) |\n| `get_leaderboard` | Trending/top-installed skills | Yes (API key) |\n| `fetch_skill` | Download skill content from GitHub | No |\n| `validate_skill` | Security scan for dangerous patterns | No |\n| `convert_to_steering` | Convert to Kiro steering format | No |\n| `convert_to_power` | Convert to Kiro power format | No |\n| `import_skill` | Complete workflow (fetch + validate + convert) | No |\n\n资料来源：[README.md:40-120]()\n\n## Data Flow\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Server\n participant Resolver\n participant Validator\n participant Converter\n participant External\n\n Client->>Server: import_skill(identifier, format)\n Server->>Resolver: fetchSkill(identifier)\n Resolver->>External: GET GitHub raw content\n External-->>Resolver: SKILL.md content\n Resolver-->>Server: rawContent\n Server->>Validator: validate(content, url)\n Validator-->>Server: ValidationResult\n Server->>Converter: convert(content, format, url)\n Converter-->>Server: ConvertResult\n Server-->>Client: ImportResult\n\n alt skipValidation = true\n Server->>Converter: Skip validation\n end\n```\n\n## Module Dependencies\n\n```mermaid\ngraph TD\n A[index.ts] --> B[tools/*]\n B --> C[core/ConversionEngine]\n B --> D[core/SkillResolver]\n B --> E[core/SecurityValidator]\n C --> F[core/errors.ts]\n D --> F\n E --> F\n C --> G[utils/*]\n D --> G\n```\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `SKILLS_SH_API_KEY` | For `list_skills` and `get_leaderboard` only | API key for authenticated skills.sh API endpoint |\n\n资料来源：[README.md:28-35]()\n\n### TypeScript Configuration\n\nThe project uses TypeScript with strict mode enabled. Key configuration in `tsconfig.json`:\n\n- ES2022 target for modern JavaScript features\n- ES modules (`module: nodenext`)\n- Strict type checking enabled\n- Path aliases for clean imports\n\n资料来源：[tsconfig.json](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/tsconfig.json)\n\n## Build and Deployment\n\n### Build Process\n\n```bash\n# Install dependencies\nnpm install\n\n# Build TypeScript\nnpm run build\n\n# Output to dist/ directory\n```\n\n### Deployment Targets\n\n| Target | Entry Point | Transport |\n|--------|-------------|-----------|\n| Kiro MCP | `index.ts` | stdio |\n| Claude Desktop | `index.ts` | stdio |\n| Standalone CLI | `cli.ts` | stdio/terminal |\n\n资料来源：[README.md:20-55]()\n\n## Testing Structure\n\nThe `tests/` directory follows the project structure with test files mirroring source file organization. Tests use descriptive naming and follow the pattern:\n\n```\ntests/\n├── core/\n│ ├── conversion-engine.test.ts\n│ ├── security-validator.test.ts\n│ └── errors.test.ts\n└── tools/\n └── *.test.ts\n```\n\n资料来源：[CONTRIBUTING.md:80-100]()\n\n## Summary\n\nThe project architecture emphasizes separation of concerns with a clear hierarchy from entry points through tool handlers to core services. The core layer is framework-agnostic and handles all business logic including skill fetching, validation, and conversion. The tools layer provides MCP-compatible interfaces while delegating to core services. This design allows for easy testing, maintainability, and extension of new features.\n\n---\n\n\n\n## MCP Server Architecture\n\n### 相关页面\n\n相关主题：[MCP Tools Reference](#mcp-tools-reference), [Getting Started](#getting-started)\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- [package.json](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/package.json)\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- [src/core/security-validator.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.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# MCP Server Architecture\n\nThe Skill Loader MCP Server is a Model Context Protocol (MCP) server implementation that enables AI assistants to discover, fetch, validate, and import Claude skills from the skills.sh marketplace. Built on the `@modelcontextprotocol/sdk`, it provides a comprehensive toolset for skill management with enterprise-grade security validation.\n\n## Architecture Overview\n\nThe server follows a layered architecture pattern with clear separation between the transport layer, tool handlers, core services, and utilities.\n\n```mermaid\ngraph TD\n subgraph Transport Layer\n STDIO[Stdio Transport]\n HTTP[HTTP/SSE Transport]\n end\n\n subgraph MCP SDK\n Server[MCP Server Instance]\n Handlers[Request Handlers]\n end\n\n subgraph Core Services\n SR[SkillResolver]\n SV[SecurityValidator]\n CE[ConversionEngine]\n Cache[In-Memory Cache]\n end\n\n subgraph External Services\n SkillsAPI[skills.sh API]\n GitHub[GitHub API]\n end\n\n STDIO --> Server\n HTTP --> Server\n Server --> Handlers\n Handlers --> SR\n Handlers --> SV\n Handlers --> CE\n SR --> Cache\n SR --> SkillsAPI\n SR --> GitHub\n CE --> SV\n```\n\n### Core Components\n\n| Component | Responsibility | Key Files |\n|-----------|---------------|-----------|\n| **MCP Server** | Protocol handling, request routing | `src/index.ts` |\n| **CLI Entry** | Application bootstrap | `src/cli.ts` |\n| **SkillResolver** | Fetches skills from GitHub and skills.sh API | Core service |\n| **SecurityValidator** | Scans for dangerous patterns | `src/core/security-validator.ts` |\n| **ConversionEngine** | Transforms skill formats | `src/core/conversion-engine.ts` |\n| **Error System** | Unified error handling | `src/core/errors.ts` |\n\n## Server Initialization\n\nThe server is initialized with the `@modelcontextprotocol/sdk` version 1.29 and configured with stdio transport for maximum compatibility.\n\n```typescript\n// Simplified initialization pattern\nimport { Server } from \"@modelcontextprotocol/sdk/server/index.js\";\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\n\nconst server = new Server(\n { name: \"skill-loader\", version: \"1.x.x\" },\n { capabilities: { tools: {} } }\n);\n\nconst transport = new StdioServerTransport();\nawait server.connect(transport);\n```\n\n资料来源：[README.md:1-50]()\n\nThe server supports both stdio transport (for CLI and desktop integrations) and can be configured for HTTP/SSE transport when deployed as a network service.\n\n## Tool System\n\nThe server exposes 8 MCP tools that provide complete skill management capabilities:\n\n### Tool Overview\n\n| Tool | Purpose | Authentication Required |\n|------|---------|------------------------|\n| `search_skills` | Search marketplace by keyword | No |\n| `list_skills` | Paginated skill directory | Yes (API Key) |\n| `get_leaderboard` | Trending/popular skills | Yes (API Key) |\n| `fetch_skill` | Download skill content from GitHub | No |\n| `validate_skill` | Security scan skill content | No |\n| `convert_to_steering` | Transform to Kiro steering format | No |\n| `convert_to_power` | Transform to Kiro power format | No |\n| `import_skill` | Complete workflow (fetch + validate + convert) | No |\n\n资料来源：[README.md:50-120]()\n\n### Tool Request Flow\n\n```mermaid\nsequence diagram\n participant Client\n participant Server\n participant Resolver\n participant Validator\n participant Converter\n\n Client->>Server: tool_request\n Server->>Resolver: fetch/resolve skill\n Resolver-->>Server: raw content\n Server->>Validator: scan content\n alt Validation Failed\n Server-->>Client: error with issues\n else Validation Passed\n Server->>Converter: transform content\n Converter-->>Server: formatted output\n end\n Server-->>Client: tool_response\n```\n\n## Core Services\n\n### SkillResolver\n\nThe `SkillResolver` service handles all interactions with external skill sources. It provides:\n\n- **GitHub Resolution**: Parse `owner/repo` identifiers to fetch raw skill content\n- **skills.sh API Integration**: Query marketplace for search, listing, and leaderboard\n- **Content Fetching**: Retrieve raw SKILL.md files from GitHub repositories\n\n```typescript\ninterface ISkillResolver {\n resolveGitHub(identifier: string): Promise;\n searchSkills(query: string, limit: number): Promise;\n listSkills(page: number, pageSize: number): Promise;\n getLeaderboard(timeframe: string, limit: number): Promise;\n}\n```\n\n资料来源：[src/core/conversion-engine.ts:1-50]()\n\nThe resolver supports the skills.sh API v1 responses with types including `SkillsShV1Response`, `SkillsShV1Entry`, and extends `SkillShEntry` with additional fields like `id`, `skillId`, and `source`.\n\n### SecurityValidator\n\nThe `SecurityValidator` service performs comprehensive security scanning on skill content before import.\n\n```typescript\ninterface ValidationIssue {\n type: 'dangerous_command' | 'suspicious_pattern' | 'untrusted_source';\n description: string;\n severity: 'critical' | 'warning' | 'info';\n lineNumber?: number;\n location?: string;\n}\n```\n\n资料来源：[src/core/security-validator.ts:1-80]()\n\n#### Security Checks Performed\n\n| Check Type | Patterns Detected | Severity |\n|------------|-------------------|----------|\n| **Dangerous Commands** | `rm -rf`, `sudo`, `eval`, `exec` | Critical |\n| **Suspicious File Operations** | `/etc/`, `/usr/`, `/bin/` paths | Warning |\n| **Code Injection** | `${...}`, `$(...)` patterns | Critical |\n| **Untrusted Sources** | Non-GitHub URLs | Critical |\n\n#### Severity Determination\n\nThe validator calculates overall severity based on detected issues:\n\n- **Safe**: No issues found\n- **Warning**: Only suspicious patterns detected\n- **Unsafe**: Dangerous commands or untrusted sources present\n\n资料来源：[src/core/security-validator.ts:80-100]()\n\n### ConversionEngine\n\nThe `ConversionEngine` transforms Claude skills into Kiro-compatible formats. It supports two output formats:\n\n#### Steering Format\n\nConverts skills to Kiro steering file format:\n- Preserves skill body content\n- Adds YAML frontmatter with original skill metadata\n- Includes dependencies section if present\n- Adds import attribution footer\n\n```typescript\ninterface SteeringOutput {\n filename: string; // kebab-case derived from skill name\n content: string; // Full steering file content\n metadata: {\n originalSkill: string;\n sourceUrl?: string;\n importedAt: string; // ISO timestamp\n };\n}\n```\n\n资料来源：[src/core/conversion-engine.ts:50-150]()\n\n#### Power Format\n\nConverts skills to Kiro power format with enhanced capabilities:\n\n- **POWER.md**: Primary power definition file\n- **mcp.json** (optional): Generated when skill has dependencies or MCP server references\n- **steering/ directory** (optional): Generated for skills with 3+ complex sections\n\n```typescript\ninterface PowerOutput {\n filename: string; // \"POWER.md\"\n content: string; // Power content with metadata\n files?: Array<{\n path: string;\n content: string;\n }>;\n}\n```\n\n资料来源：[src/core/conversion-engine.ts:150-250]()\n\n#### Format Selection Logic\n\n| Condition | Output Format |\n|-----------|--------------|\n| Skill has no dependencies | Single `STEERING.md` file |\n| Skill has dependencies/tools | `STEERING.md` + `mcp.json` |\n| 3+ complex sections (>200 chars) | Steering directory structure |\n| Full power workflow | `POWER.md` + optional `mcp.json` + optional `steering/` |\n\n资料来源：[src/core/conversion-engine.ts:250-300]()\n\n## Error Handling System\n\nThe server implements a hierarchical error system with specialized error classes for different failure modes.\n\n```mermaid\ngraph TD\n SkillLoaderError[SkillLoaderError]\n NetworkError[NetworkError]\n ValidationError[ValidationError]\n FileSystemError[FileSystemError]\n SkillLoaderError --> NetworkError\n SkillLoaderError --> ValidationError\n SkillLoaderError --> FileSystemError\n```\n\n### Error Class Hierarchy\n\n| Error Class | HTTP Code Support | Use Case |\n|-------------|------------------|----------|\n| `SkillLoaderError` | Base class | All errors |\n| `NetworkError` | 404, 403, 5xx | GitHub/API failures |\n| `ValidationError` | N/A | Format, schema, security issues |\n| `FileSystemError` | N/A | Permission, disk, path issues |\n\n资料来源：[src/core/errors.ts:1-100]()\n\n### Error Response Format\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\nAll errors include recovery suggestions based on error type and context.\n\n## Caching Mechanism\n\nThe server implements in-memory caching for the skills.sh directory to reduce API calls and improve performance.\n\n| Cache Property | Value |\n|---------------|-------|\n| **Storage** | In-memory Map |\n| **TTL** | 1 hour |\n| **Scope** | Search results |\n| **Refresh** | Automatic on expiration |\n\n资料来源：[README.md:180-200]()\n\nCache invalidation is automatic when the TTL expires. No manual cache clearing is required.\n\n## Configuration and Deployment\n\n### Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `SKILLS_SH_API_KEY` | For list/leaderboard only | Authentication for authenticated API endpoints |\n\n### Deployment Targets\n\n```mermaid\ngraph LR\n subgraph Deployment Options\n Kiro[Kiro MCP Config]\n Claude[Claude Desktop]\n CLI[Standalone CLI]\n end\n\n Kiro --> STDIO\n Claude --> STDIO\n CLI --> STDIO\n```\n\n#### Kiro Configuration\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 Configuration\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资料来源：[README.md:30-80]()\n\n## Project Structure\n\n```\nskill-loader-mcp-server/\n├── src/\n│ ├── core/ # Core business logic\n│ │ ├── conversion-engine.ts\n│ │ ├── errors.ts\n│ │ └── security-validator.ts\n│ ├── tools/ # MCP tool implementations\n│ ├── utils/ # Utility functions\n│ ├── index.ts # Server entry point\n│ └── cli.ts # CLI entry point\n├── examples/ # Usage examples\n├── tests/ # Test suite\n├── dist/ # Compiled output\n├── package.json\n└── tsconfig.json\n```\n\n资料来源：[CONTRIBUTING.md:1-30]()\n\n## Dependencies\n\nThe server relies on the following key dependencies:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `@modelcontextprotocol/sdk` | ^1.29 | MCP protocol implementation |\n| `yaml` | Latest | YAML frontmatter parsing |\n| `typescript` | Latest | Type safety |\n\n资料来源：[package.json](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/package.json)\n\n## Complete Import Workflow\n\n```mermaid\ngraph TD\n A[Start: identifier] --> B[Fetch Skill from GitHub]\n B --> C{skipValidation?}\n C -->|No| D[Security Validation]\n C -->|Yes| E[Skip Validation]\n D --> F{isValid?}\n F -->|No| G[Return Error with Issues]\n F -->|Yes| E\n E --> H{outputFormat?}\n H -->|steering| I[Convert to Steering]\n H -->|power| J[Convert to Power]\n I --> K[Add Steering Metadata]\n J --> L[Generate Power Files]\n L --> M{mcp.json needed?}\n L --> N{steering/ needed?}\n M -->|Yes| O[Generate mcp.json]\n M -->|No| P[Skip mcp.json]\n N -->|Yes| Q[Generate steering/]\n N -->|No| R[Skip steering/]\n O --> S[Return Result]\n P --> S\n Q --> S\n R --> S\n```\n\nThe complete workflow is exposed through the `import_skill` tool, which orchestrates fetch, validation, and conversion in a single operation.\n\n资料来源：[examples/usage-examples.md:100-150]()\n\n## Version History\n\n| Version | Date | Key Changes |\n|---------|------|-------------|\n| 1.1.0 | 2026-02-XX | Added mcp.json and steering/ generation |\n| 1.0.0 | 2026-02-03 | Initial release with 8 core tools |\n\n资料来源：[CHANGELOG.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CHANGELOG.md)\n\n---\n\n\n\n## Core Modules\n\n### 相关页面\n\n相关主题：[Format Conversion](#format-conversion), [Security Validation](#security-validation)\n\n\nRelevant Source Files
\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- [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# Core Modules\n\nThe Core Modules of the skill-loader-mcp-server form the foundational layer responsible for skill fetching, parsing, security validation, and format conversion. These modules work together to provide a secure pipeline for importing Claude skills into the Kiro ecosystem.\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[Skill Input] --> B[Skill Fetcher]\n B --> C[Skill Resolver]\n C --> D[Conversion Engine]\n D --> E[Steering Format]\n D --> F[Power Format]\n G[Security Validator] --> D\n G --> C\n H[Error Handler] --> B\n H --> C\n H --> D\n H --> G\n```\n\n## Module Components\n\n### 1. Conversion Engine (`conversion-engine.ts`)\n\nThe Conversion Engine is responsible for transforming parsed skill content into different output formats suitable for various use cases.\n\n#### Key Methods\n\n| Method | Purpose | Output |\n|--------|---------|--------|\n| `parseSkill(content)` | Parses YAML frontmatter and markdown body | `ParsedSkill` object |\n| `toSteeringFile(skill, sourceUrl?)` | Converts to Kiro steering format | Steering file with metadata |\n| `toPower(skill, sourceUrl?)` | Converts to Kiro power format | Power files including `POWER.md` |\n| `extractKeywords(description)` | Extracts 3+ char meaningful words | Array of keywords |\n| `shouldGenerateMcpJson(skill)` | Determines if MCP config needed | Boolean |\n| `shouldGenerateSteeringDir(skill)` | Checks for complex sections | Boolean |\n\n#### Steering File Conversion\n\nThe steering file format preserves the original skill structure with kebab-case naming:\n\n```typescript\n// Transformation rules:\n// 1. Convert to lowercase\n// 2. Replace spaces and underscores with hyphens\n// 3. Remove special characters (keep only a-z, 0-9, and hyphens)\n// 4. Collapse multiple consecutive hyphens into one\n// 5. Remove leading and trailing hyphens\n\n\"PDF Extractor\" → \"pdf-extractor\"\n\"React_Best_Practices\" → \"react-best-practices\"\n```\n\n资料来源：[src/core/conversion-engine.ts:1-50]()\n\n#### Power Format Generation\n\nThe power format generates a more structured output:\n\n```typescript\n// Power structure includes:\n// 1. POWER.md - Main content with displayName frontmatter\n// 2. mcp.json - (optional) MCP server configuration\n// 3. steering/ - (optional) Directory with complex sections\n```\n\n资料来源：[src/core/conversion-engine.ts:150-200]()\n\n#### Steering Directory Generation Logic\n\nThe engine generates a `steering/` directory when the skill has 3+ complex sections (level ≥ 2 with content > 200 characters):\n\n```typescript\nif (this.shouldGenerateSteeringDir(skill)) {\n const steeringContent = this.generateSteeringContent(skill);\n // Creates individual files for each complex section\n}\n```\n\n资料来源：[src/core/conversion-engine.test.ts:1-50]()\n\n---\n\n### 2. Security Validator (`security-validator.ts`)\n\nThe Security Validator provides comprehensive threat detection for skill content before processing.\n\n#### Validation Rules\n\n| Check Type | Patterns Detected | Severity |\n|------------|-------------------|----------|\n| Dangerous Commands | `rm -rf`, `sudo`, `eval`, `exec` | `unsafe` |\n| Suspicious File Operations | `/etc/`, `/usr/`, `/bin/` | `warning` |\n| Code Injection | `${...}`, `$(...)` | `warning` |\n| Untrusted Sources | Non-GitHub URLs | `unsafe` |\n\n#### Severity Levels\n\n```typescript\n'safe' // No issues found\n'warning' // Suspicious patterns detected\n'unsafe' // Dangerous commands or untrusted sources\n```\n\n资料来源：[src/core/security-validator.ts:1-50]()\n\n#### Validation Flow\n\n```mermaid\ngraph LR\n A[Skill Content] --> B{Untrusted Source?}\n B -->|Yes| C[Mark unsafe]\n B -->|No| D{Dangerous Command?}\n D -->|Yes| C\n D -->|No| E{Suspicious Patterns?}\n E -->|Yes| F[Mark warning]\n E -->|No| G[Mark safe]\n```\n\n资料来源：[src/core/security-validator.ts:50-100]()\n\n#### Line Number Detection\n\nThe validator can pinpoint exact locations of issues:\n\n```typescript\nprivate getLineNumber(content: string, index: number): number {\n const lines = content.substring(0, index).split('\\n');\n return lines.length;\n}\n```\n\n---\n\n### 3. Error Handling System (`errors.ts`)\n\nThe error system provides structured error handling across all core modules.\n\n#### Error Class Hierarchy\n\n```mermaid\nclassDiagram\n class SkillLoaderError {\n +string tool\n +string timestamp\n +Record context\n +getUserMessage() string\n }\n class ValidationError {\n +ValidationType validationType\n +ValidationResult result\n }\n class FileSystemError {\n +Operation operation\n +string filePath\n +string systemError?\n }\n class ParsingError {\n +ParsingType parsingType\n +string rawContent\n }\n \n SkillLoaderError <|-- ValidationError\n SkillLoaderError <|-- FileSystemError\n SkillLoaderError <|-- ParsingError\n```\n\n#### ValidationError\n\nHandles security and format validation failures:\n\n```typescript\nexport class ValidationError extends SkillLoaderError {\n public readonly validationType: 'security' | 'format';\n public readonly result: ValidationResult;\n}\n```\n\n**Recovery suggestions:**\n- Security: Review content manually, contact author, use trusted sources\n- Format: Verify YAML syntax, check Agent Skills standard compliance\n\n#### FileSystemError\n\nHandles file system operations:\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**Error codes handled:**\n\n| Code | Cause | Resolution |\n|------|-------|------------|\n| `EACCES`/`EPERM` | Permission denied | Check file permissions |\n| `ENOSPC` | Disk full | Free up space |\n| `ENOENT` | Path not found | Verify directory exists |\n| `EEXIST` | File exists | Use overwrite flag |\n\n资料来源：[src/core/errors.ts:1-100]()\n\n#### ParsingError\n\nHandles YAML and markdown parsing issues:\n\n```typescript\nexport class ParsingError extends SkillLoaderError {\n public readonly parsingType: 'yaml' | 'markdown' | 'frontmatter' | 'metadata';\n}\n```\n\n---\n\n### 4. Skill Fetcher (`skill-fetcher.ts`)\n\nThe Skill Fetcher retrieves raw skill content from GitHub repositories.\n\n#### Fetch Resolution Logic\n\nSkills can be referenced by:\n- **Simple name**: `pdf-extractor` (resolves to `anthropics/skills`)\n- **Full path**: `owner/repo/skill-name`\n\nThe resolver determines the correct GitHub URL and path structure.\n\n资料来源：[README.md:1-50]()\n\n---\n\n### 5. Skill Resolver (`skill-resolver.ts`)\n\nThe Skill Resolver handles skill identification and API interactions with skills.sh.\n\n#### API Methods\n\n| Method | Description | Auth Required |\n|--------|-------------|---------------|\n| `listSkills()` | Paginated skill listing | Yes |\n| `searchSkills()` | Public keyword search | No |\n| `getLeaderboard()` | Trending skills | Yes |\n\n资料来源：[README.md:50-100]()\n\n#### Type Definitions\n\n```typescript\ninterface SkillsShV1Response {\n skills: SkillsShV1Entry[];\n total: number;\n}\n\ninterface SkillsShV1Entry {\n id: string;\n skillId: string;\n source: string;\n // ... additional fields\n}\n```\n\n---\n\n## Data Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant Fetcher\n participant Resolver\n participant Validator\n participant Converter\n participant Output\n\n User->>Resolver: search_skills(query)\n Resolver-->>User: skill list\n\n User->>Fetcher: fetch_skill(identifier)\n Fetcher->>Resolver: resolve owner/repo\n Resolver-->>Fetcher: resolved URL\n Fetcher-->>User: raw content\n\n User->>Validator: validate_skill(content)\n Validator->>Validator: scan patterns\n Validator-->>User: ValidationResult\n\n User->>Converter: convert_to_power(content)\n Converter->>Validator: re-validate\n Validator-->>Converter: isValid\n alt is valid\n Converter->>Converter: generate POWER.md\n alt has dependencies\n Converter->>Converter: generate mcp.json\n end\n alt has complex sections\n Converter->>Converter: generate steering/\n end\n Converter-->>Output: files array\n else is invalid\n Converter-->>User: ValidationError\n end\n```\n\n---\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Required | Module | Description |\n|----------|----------|--------|-------------|\n| `SKILLS_SH_API_KEY` | For list/leaderboard | SkillResolver | API key for authenticated endpoints |\n\n### Caching\n\nThe resolver caches skills.sh search results:\n- **TTL**: 1 hour\n- **Scope**: In-memory\n- **Purpose**: Reduce API calls, improve performance\n\n---\n\n## Testing\n\nThe core modules include comprehensive test coverage:\n\n```typescript\ndescribe('ConversionEngine', () => {\n describe('toPower', () => {\n it('converts parsed skill to power format', () => { /* ... */ });\n it('generates mcp.json when skill has dependencies', () => { /* ... */ });\n it('does not generate mcp.json when skill has no dependencies', () => { /* ... */ });\n });\n});\n```\n\n资料来源：[src/core/conversion-engine.test.ts:1-100]()\n\n---\n\n## Integration Points\n\nThe Core Modules expose functionality through MCP tools:\n\n| Tool | Primary Module | Purpose |\n|------|---------------|---------|\n| `search_skills` | SkillResolver | Discover skills |\n| `list_skills` | SkillResolver | Browse marketplace |\n| `get_leaderboard` | SkillResolver | Trending skills |\n| `fetch_skill` | SkillFetcher | Download content |\n| `validate_skill` | SecurityValidator | Security scan |\n| `convert_to_steering` | ConversionEngine | Steering format |\n| `convert_to_power` | ConversionEngine | Power format |\n| `import_skill` | All modules | Complete workflow |\n\n---\n\n\n\n## MCP Tools Reference\n\n### 相关页面\n\n相关主题：[MCP Server Architecture](#mcp-server-architecture), [Skill Discovery](#skill-discovery)\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 Tools Reference\n\nThe Skill Loader MCP Server provides a comprehensive suite of 8 Model Context Protocol (MCP) tools for discovering, fetching, validating, and converting Claude skills from the skills.sh marketplace. These tools enable seamless integration between the skills.sh ecosystem and the Kiro AI platform's steering file and power formats.\n\n## Overview\n\nThe MCP Tools form the core interface of the Skill Loader MCP Server, providing programmatic access to the skills.sh API and GitHub-hosted skill repositories. Each tool serves a specific purpose in the skill management lifecycle, from discovery to import.\n\n```mermaid\ngraph TD\n A[Skills Discovery] --> B[search_skills]\n A --> C[list_skills]\n A --> D[get_leaderboard]\n E[Skill Retrieval] --> F[fetch_skill]\n G[Security] --> H[validate_skill]\n I[Conversion] --> J[convert_to_steering]\n I --> K[convert_to_power]\n L[Workflow] --> M[import_skill]\n \n F --> H\n H --> J\n H --> K\n M --> F\n M --> H\n M --> J\n M --> K\n```\n\n### Tool Categories\n\n| Category | Tools | Purpose |\n|----------|-------|---------|\n| Discovery | `search_skills`, `list_skills`, `get_leaderboard` | Find and browse available skills |\n| Retrieval | `fetch_skill` | Download skill content from GitHub |\n| Security | `validate_skill` | Scan for dangerous commands and patterns |\n| Conversion | `convert_to_steering`, `convert_to_power` | Transform skills to Kiro formats |\n| Workflow | `import_skill` | Execute complete import workflow |\n\n资料来源：[README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n\n## Discovery Tools\n\n### search_skills\n\nSearch for skills by keyword using the skills.sh search API. This tool requires no authentication and provides immediate access to the skill marketplace.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `query` | string | Yes | - | Search query string |\n| `limit` | number | No | 20 | Maximum results (max: 50) |\n\n**Response Schema:**\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**Example Request:**\n\n```json\n{\n \"tool\": \"search_skills\",\n \"arguments\": {\n \"query\": \"pdf\",\n \"limit\": 5\n }\n}\n```\n\n资料来源：[examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n\n### list_skills\n\nList all available skills from skills.sh with pagination support. This tool requires the `SKILLS_SH_API_KEY` environment variable for authenticated access to the paginated directory endpoint.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `page` | number | No | 1 | Page number for pagination |\n| `pageSize` | number | No | 50 | Results per page (max: 100) |\n\n**Response Schema:**\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**Authentication Requirement:**\n\nThis tool requires `SKILLS_SH_API_KEY` to access the authenticated `/api/v1/skills` endpoint. Request the API key from Vercel if needed.\n\n资料来源：[README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n\n### get_leaderboard\n\nGet trending or top-installed skills to identify the most popular skills in the marketplace.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `timeframe` | string | No | \"all\" | Time window: `\"all\"` or `\"24h\"` |\n| `limit` | number | No | 20 | Maximum results (max: 50) |\n\n**Response Schema:**\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**Authentication Requirement:**\n\nSimilar to `list_skills`, this tool requires `SKILLS_SH_API_KEY` for authenticated access.\n\n资料来源：[examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n\n## Retrieval Tools\n\n### fetch_skill\n\nFetch raw skill content directly from GitHub. This tool supports both short identifiers (skill name) and fully-qualified identifiers (`owner/repo` format).\n\n```mermaid\ngraph TD\n A[fetch_skill Request] --> B{Identifier Format?}\n B -->|Short name| C[Query skills.sh directory]\n B -->|owner/repo| D[Direct GitHub URL construction]\n C --> E[Resolve to owner/repo]\n E --> F[Construct GitHub URL]\n D --> F\n F --> G[Fetch from GitHub Raw]\n G --> H[Return Skill Content]\n \n H --> I[Extract YAML frontmatter]\n H --> J[Parse markdown body]\n H --> K[Extract sections]\n```\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `identifier` | string | Yes | Skill name or `owner/repo` format |\n\n**Supported Identifier Formats:**\n\n| Format | Example | Resolution |\n|--------|---------|------------|\n| Short name | `pdf-extractor` | Resolved via skills.sh directory |\n| Fully qualified | `anthropics/pdf-extractor` | Direct GitHub URL |\n\n**Response Schema:**\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**URL Resolution Pattern:**\n\nThe `SkillResolver` class constructs URLs using the pattern:\n```\nhttps://raw.githubusercontent.com/{owner}/{repo}/main/skills/{name}/SKILL.md\n```\n\n资料来源：[src/core/skill-resolver.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/skill-resolver.ts)\n\n## Security Tools\n\n### validate_skill\n\nValidate skill content for security issues before importing. This is a critical security measure that scans for dangerous commands, suspicious patterns, and code injection vulnerabilities.\n\n```mermaid\ngraph TD\n A[Skill Content] --> B[SecurityValidator]\n B --> C{Dangerous Commands?}\n B --> D{Suspicious Patterns?}\n B --> E{Untrusted Sources?}\n \n C -->|rm -rf, sudo, eval| F[dangerous_command]\n D -->|Code injection, special chars| G[suspicious_pattern]\n E -->|Non-GitHub URLs| H[untrusted_source]\n \n F --> I{Severity Assessment}\n G --> I\n H --> I\n I --> J[Validation Result]\n \n J --> K{Result}\n K -->|No issues| L[\"severity: safe\"]\n K -->|Untrusted/Dangerous| M[\"severity: unsafe\"]\n K -->|Suspicious only| N[\"severity: warning\"]\n```\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `content` | string | Yes | Skill content to validate |\n| `url` | string | No | Source URL for verification |\n\n**Detected Security Issues:**\n\n| Issue Type | Description | Severity |\n|------------|-------------|----------|\n| `dangerous_command` | Commands like `rm -rf`, `sudo`, `eval`, `exec` | unsafe |\n| `suspicious_pattern` | Code injection patterns `${...}`, `$(...)` | warning |\n| `untrusted_source` | Non-GitHub URLs in skill content | unsafe |\n\n**Dangerous Patterns Scanned:**\n\n- Recursive delete commands (`rm -rf`)\n- Privilege escalation (`sudo`)\n- Dynamic code execution (`eval`, `exec`)\n- Path traversal attempts (`/etc/`, `/usr/`, `/bin/`)\n- Shell interpolation patterns (`${`, `$(`)\n\n**Response Schema:**\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**Severity Determination Logic:**\n\n| Condition | Result |\n|-----------|--------|\n| No issues found | `safe` |\n| `untrusted_source` or `dangerous_command` present | `unsafe` |\n| Only `suspicious_pattern` issues | `warning` |\n\n资料来源：[src/core/security-validator.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)\n\n## Conversion Tools\n\n### convert_to_steering\n\nConvert skill content to Kiro steering file format. This format is designed for guiding AI behavior through structured markdown with YAML frontmatter.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `content` | string | Yes | Skill content to convert |\n| `sourceUrl` | string | No | Original source URL for metadata |\n\n**Output Format Structure:**\n\n```yaml\n---\noriginal_skill: PDF Extractor\nsource_url: https://raw.githubusercontent.com/anthropics/skills/main/skills/pdf-extractor/SKILL.md\nimported_at: '2024-01-15T10:30:00.000Z'\n---\n\n# PDF Extractor\n\nExtract text from PDF files\n\n[Skill body content...]\n\n---\n\n*Imported from Claude Skills via Skill Loader Power*\n```\n\n**Conversion Process:**\n\n1. Parse YAML frontmatter from skill content\n2. Build new frontmatter with original skill metadata\n3. Add skill name as H1 heading\n4. Include description if present\n5. Preserve skill body content\n6. Add dependencies section if applicable\n7. Append import attribution footer\n\n**Naming Convention:**\n\nThe filename is generated using `toKebabCase()` transformation:\n- `\"PDF Extractor\"` → `\"pdf-extractor\"`\n- `\"React Best Practices\"` → `\"react-best-practices\"`\n\n资料来源：[src/core/conversion-engine.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/conversion-engine.ts)\n\n### convert_to_power\n\nConvert skill content to Kiro power format. This is a more comprehensive format that may generate additional files beyond the main `POWER.md`.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `content` | string | Yes | Skill content to convert |\n| `sourceUrl` | string | No | Original source URL for metadata |\n\n**Generated Files:**\n\n| Condition | File | Purpose |\n|-----------|------|---------|\n| Always | `POWER.md` | Main power definition |\n| Skill has dependencies or tool references | `mcp.json` | MCP server configuration |\n| Skill has 3+ complex sections | `steering/` directory | Structured guidance files |\n\n**mcp.json Generation:**\n\nWhen a skill contains dependencies or MCP server references, the conversion engine generates an `mcp.json` configuration file:\n\n```json\n{\n \"mcpServers\": {\n \"skill-name\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@some/package\"],\n \"env\": {}\n }\n }\n}\n```\n\n**steering/ Directory:**\n\nFor skills with multiple complex sections (3+ sections with content > 200 characters at level 2+), a structured steering directory is generated to provide granular guidance.\n\n**Response Schema:**\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/anthropics/skills/main/skills/pdf-extractor/SKILL.md\",\n \"outputFormat\": \"power\",\n \"validationResult\": {\n \"isValid\": true,\n \"issues\": [],\n \"severity\": \"safe\"\n }\n }\n}\n```\n\n**Dependencies Section:**\n\nWhen present in the original skill, dependencies are converted to a markdown list:\n\n```markdown\n## Dependencies\n\n- dependency-1\n- dependency-2\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## Workflow Tools\n\n### import_skill\n\nComplete end-to-end import workflow that combines fetch, validate, and convert operations into a single atomic action.\n\n```mermaid\ngraph TD\n A[import_skill Request] --> B[Fetch Skill from GitHub]\n B --> C{skipValidation?}\n C -->|No| D[Validate Security]\n C -->|Yes| E[Skip Validation]\n D --> F{isValid?}\n F -->|Yes| G[Convert to Target Format]\n F -->|No| H[Block Import]\n E --> G\n G --> I[Return Converted Content]\n H --> J[Return Validation Error]\n \n I --> K[Optional: Write to Target Path]\n```\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `identifier` | string | Yes | - | Skill name or `owner/repo` format |\n| `outputFormat` | string | Yes | - | Target format: `\"steering\"` or `\"power\"` |\n| `skipValidation` | boolean | No | false | Bypass security validation |\n\n**Workflow Steps:**\n\n1. **Fetch**: Retrieve skill content from GitHub using `fetch_skill`\n2. **Validate**: Run security checks via `validate_skill` (unless skipped)\n3. **Convert**: Transform to requested format (`convert_to_steering` or `convert_to_power`)\n\n**Recommended Workflow Pattern:**\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**Security Considerations:**\n\n- Always validate skills from untrusted sources\n- Use `skipValidation: true` only for locally-verified content\n- Review validation issues before proceeding with imports\n\n**Response Schema:**\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/anthropics/skills/main/skills/pdf-extractor/SKILL.md\",\n \"outputFormat\": \"power\",\n \"validationResult\": {\n \"isValid\": true,\n \"issues\": [],\n \"severity\": \"safe\"\n }\n }\n}\n```\n\n**Error Response:**\n\n```json\n{\n \"error\": \"Error message describing what went wrong\",\n \"tool\": \"import_skill\",\n \"timestamp\": \"2024-01-15T10:30:00.000Z\"\n}\n```\n\n资料来源：[examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n\n## Error Handling\n\nAll MCP tools return errors in a consistent format to enable reliable error handling in clients:\n\n**Error Response Schema:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `error` | string | Human-readable error message |\n| `tool` | string | Name of the tool that failed |\n| `timestamp` | string | ISO 8601 timestamp of the error |\n\n**Common Error Scenarios:**\n\n| Scenario | Cause | Resolution |\n|----------|-------|------------|\n| Network errors | Internet connectivity, GitHub availability | Check connection, retry later |\n| Not found | Invalid skill name or repository | Verify identifier format |\n| Validation errors | Security issues detected | Review and address issues |\n| Parsing errors | Invalid YAML or markdown format | Check skill syntax |\n\n**Error Types:**\n\n| Error Class | Trigger | Context |\n|-------------|---------|---------|\n| `NetworkError` | HTTP request failures | Retry with backoff |\n| `SkillResolutionError` | Skill not found or ambiguous | Provide alternatives |\n| `ValidationError` | Security validation failures | Review skill content |\n| `FileSystemError` | File operations | Check permissions |\n\n资料来源：[src/core/errors.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts)\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Required | Tools | Description |\n|----------|----------|-------|-------------|\n| `SKILLS_SH_API_KEY` | Conditional | `list_skills`, `get_leaderboard` | API key for authenticated endpoints |\n\n**Note:** `search_skills` and `fetch_skill` do not require authentication as they use public APIs.\n\n### Caching Behavior\n\nThe server implements in-memory caching for skills.sh search results:\n\n| Cache | TTL | Scope |\n|-------|-----|-------|\n| Skills.sh directory | 1 hour | All authenticated list operations |\n\nCaching reduces API calls and improves response times for repeated queries.\n\n## Quick Reference\n\n### Tool Summary Table\n\n| Tool | Auth Required | Input | Output |\n|------|---------------|-------|--------|\n| `search_skills` | No | `query`, `limit` | Array of matching skills |\n| `list_skills` | Yes (API Key) | `page`, `pageSize` | Paginated skill directory |\n| `get_leaderboard` | Yes (API Key) | `timeframe`, `limit` | Trending/top skills |\n| `fetch_skill` | No | `identifier` | Raw skill content |\n| `validate_skill` | No | `content`, `url` | Validation result |\n| `convert_to_steering` | No | `content`, `sourceUrl` | Steering file |\n| `convert_to_power` | No | `content`, `sourceUrl` | Power format + extras |\n| `import_skill` | No* | `identifier`, `outputFormat` | Complete import result |\n\n*Security validation can be optionally skipped\n\n### Recommended Workflows\n\n**Discover and Import Trending Skill:**\n\n```json\n[\n { \"tool\": \"get_leaderboard\", \"arguments\": { \"timeframe\": \"24h\", \"limit\": 10 } },\n { \"tool\": \"fetch_skill\", \"arguments\": { \"identifier\": \"owner/skill-name\" } },\n { \"tool\": \"validate_skill\", \"arguments\": { \"content\": \"...\" } },\n { \"tool\": \"convert_to_steering\", \"arguments\": { \"content\": \"...\", \"sourceUrl\": \"...\" } }\n]\n```\n\n**Single-Command Import:**\n\n```json\n{ \"tool\": \"import_skill\", \"arguments\": { \"identifier\": \"owner/skill-name\", \"outputFormat\": \"power\" } }\n\n---\n\n\n\n## Skill Discovery\n\n### 相关页面\n\n相关主题：[MCP Tools Reference](#mcp-tools-reference), [Caching System](#caching-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/skill-resolver.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/skill-resolver.ts)\n- [src/tools/search-skills.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/list-skills.ts)\n- [src/tools/list-skills.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/list-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/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 \n\n# Skill Discovery\n\nSkill Discovery is a core subsystem of the Skill Loader MCP Server that enables users to find, browse, and explore available Claude skills from the skills.sh ecosystem. It provides multiple discovery mechanisms including keyword search, paginated listing, and trending leaderboards.\n\n## Overview\n\nThe Skill Discovery system acts as the front-end interface for exploring the skills.sh marketplace. It abstracts away the complexity of fetching and filtering skills from external APIs, providing a unified interface for skill exploration.\n\n### Key Capabilities\n\n- **Keyword Search**: Find skills by name or description keywords\n- **Paginated Listing**: Browse all available skills with pagination support\n- **Trending Leaderboard**: Discover popular or recently trending skills\n- **Source Resolution**: Resolve skill identifiers to GitHub URLs\n- **Install Statistics**: View install counts for skill popularity metrics\n\n### Architecture Overview\n\n```mermaid\ngraph TD\n A[User Request] --> B[MCP Tools Layer]\n B --> C[search_skills]\n B --> D[list_skills]\n B --> E[get_leaderboard]\n C --> F[SkillResolver]\n D --> F\n E --> F\n F --> G[Skills.sh API]\n F --> H[GitHub Raw Content]\n G --> I[SkillShEntry Parser]\n I --> J[ResolvedSkill Output]\n H --> J\n```\n\n## Core Components\n\n### SkillResolver\n\nThe `SkillResolver` class is the central orchestrator for skill discovery operations. Located at `src/core/skill-resolver.ts`, it handles all interactions with the skills.sh API and provides unified resolution of skill identifiers.\n\n**Primary Methods:**\n\n| Method | Purpose |\n|--------|---------|\n| `resolveSkill()` | Resolve a skill identifier to a full URL |\n| `searchSkills()` | Search skills by keyword |\n| `listSkills()` | List skills with pagination (authenticated) |\n| `getLeaderboard()` | Get trending or top-installed skills |\n\n资料来源：[src/core/skill-resolver.ts:1-50]()\n\n### Data Models\n\n#### SkillShEntry\n\nRepresents a skill entry from the skills.sh API:\n\n```typescript\ninterface SkillShEntry {\n name: string;\n owner: string;\n repo: string;\n installs: number;\n description: string;\n id?: string;\n skillId?: string;\n source?: string;\n metadata?: {\n trending: boolean;\n };\n}\n```\n\n#### ResolvedSkill\n\nInternal representation after resolution:\n\n```typescript\ninterface ResolvedSkill {\n name: string;\n description: string;\n owner: string;\n repo: string;\n skillPath: string;\n url: string;\n installs: number;\n}\n```\n\n资料来源：[src/core/skill-resolver.ts:60-100]()\n\n## Discovery Tools\n\n### 1. search_skills\n\nPerforms keyword-based search across skill names and descriptions. This tool uses the public search API endpoint and does not require authentication.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `query` | string | Yes | - | Search query string |\n| `limit` | number | No | 5 | Maximum results (max: 50) |\n\n**Workflow:**\n\n```mermaid\ngraph LR\n A[query: string] --> B[Call skills.sh Search API]\n B --> C[Parse Response]\n C --> D[Filter by Relevance]\n D --> E[Return Top N Results]\n E --> F[Skills with relevance scores]\n```\n\n**Response Structure:**\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资料来源：[examples/usage-examples.md:30-60]()\n\n### 2. list_skills\n\nRetrieves a paginated list of all available skills from the skills.sh directory. Requires `SKILLS_SH_API_KEY` for authenticated access to the v1 API endpoint.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `page` | number | No | 1 | Page number |\n| `pageSize` | number | No | 50 | Results per page (max: 100) |\n\n**API Integration:**\n\n```typescript\nconst url = `https://skills.sh/api/v1/skills?page=${page}&pageSize=${pageSize}`;\nconst headers = {\n 'Authorization': `Bearer ${apiKey}`,\n 'Content-Type': 'application/json'\n};\n```\n\n**Response Structure:**\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资料来源：[examples/usage-examples.md:20-40]()\n\n### 3. get_leaderboard\n\nRetrieves trending or top-installed skills ranked by popularity metrics.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `timeframe` | string | No | \"all\" | Time period: `'all'` or `'24h'` |\n| `limit` | number | No | 20 | Maximum results (max: 50) |\n\n**Timeframe Behavior:**\n\n| Timeframe | Source | Use Case |\n|-----------|--------|----------|\n| `all` | Historical install counts | All-time popular skills |\n| `24h` | Recent activity metrics | Currently trending skills |\n\n**Response Structure:**\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资料来源：[examples/usage-examples.md:55-80]()\n\n## Skill Resolution Flow\n\nThe resolution process transforms various identifier formats into canonical GitHub URLs:\n\n```mermaid\ngraph TD\n A[Identifier Input] --> B{Normalize Identifier}\n B --> C[\"owner/repo format?\"]\n C -->|Yes| D[Build URL: owner/repo]\n C -->|No| E[Search skills.sh Directory]\n E --> F{Match Found?}\n F -->|Single| G[Use Match]\n F -->|Multiple| H[Raise Error: Multiple Matches]\n F -->|None| I[Raise Error: Not Found]\n D --> J[Build Full GitHub URL]\n G --> J\n J --> K[Return ResolvedSkill]\n```\n\n### Resolution Rules\n\n1. **Explicit Format** (`owner/repo`): Directly constructs GitHub URL\n2. **Name Only**: Searches skills.sh directory for matching name\n3. **Fuzzy Match**: Case-insensitive partial matching on skill names\n4. **Multiple Matches**: Throws `SkillResolutionError` with list of matches\n\n资料来源：[src/core/skill-resolver.ts:100-150]()\n\n## API Integration\n\n### Skills.sh API Endpoints\n\n| Endpoint | Auth Required | Purpose |\n|----------|---------------|---------|\n| `GET /api/v1/skills` | Yes (API Key) | Paginated skill listing |\n| `GET /search?q={query}` | No | Public keyword search |\n\n### Authentication\n\n```typescript\nconst response = await fetch(url, {\n headers: {\n 'Authorization': `Bearer ${process.env.SKILLS_SH_API_KEY}`,\n 'Content-Type': 'application/json'\n }\n});\n```\n\n### Error Handling\n\n| Error Type | HTTP Code | Handling |\n|------------|-----------|----------|\n| `NetworkError` | 4xx/5xx | Retry with exponential backoff |\n| `SkillResolutionError` | N/A | Return helpful suggestions |\n\n资料来源：[src/core/skill-resolver.ts:150-200]()\n\n## Caching Strategy\n\nThe Skill Discovery system implements in-memory caching for the skills.sh directory to reduce API calls and improve performance.\n\n```mermaid\ngraph LR\n A[Request] --> B{Cache Valid?}\n B -->|Yes| C[Return Cached Data]\n B -->|No| D[Fetch from API]\n D --> E[Update Cache]\n E --> F[Return Fresh Data]\n C --> G[Response]\n F --> G\n```\n\n**Cache Configuration:**\n\n| Setting | Value | Description |\n|---------|-------|-------------|\n| TTL | 1 hour | Time-to-live for cached entries |\n| Scope | In-memory | Process-level caching |\n| Invalidation | TTL-based | Automatic refresh on expiry |\n\n资料来源：[examples/usage-examples.md:150-160]()\n\n## Usage Examples\n\n### Discover Skills by Keyword\n\n```json\n{\n \"tool\": \"search_skills\",\n \"arguments\": {\n \"query\": \"pdf\",\n \"limit\": 5\n }\n}\n```\n\n### Browse Available Skills\n\n```json\n{\n \"tool\": \"list_skills\",\n \"arguments\": {\n \"page\": 1,\n \"pageSize\": 10\n }\n}\n```\n\n### Find Trending Skills\n\n```json\n{\n \"tool\": \"get_leaderboard\",\n \"arguments\": {\n \"timeframe\": \"24h\",\n \"limit\": 20\n }\n}\n```\n\n### Complete Discovery Workflow\n\n```mermaid\ngraph TD\n A[Search for Skills] --> B[Found Interesting Skill?]\n B -->|Yes| C[Fetch Skill Details]\n B -->|No| A\n C --> D[Validate Skill Content]\n D --> E{Valid?}\n E -->|Yes| F[Convert to Target Format]\n E -->|No| G[Review Security Issues]\n G --> H[Skip or Find Alternative]\n F --> I[Import Skill]\n I --> J[Complete]\n```\n\n资料来源：[examples/usage-examples.md:170-210]()\n\n## Related Systems\n\n### Conversion Engine Integration\n\nAfter discovery, skills can be converted to target formats:\n\n| Format | Output | Use Case |\n|--------|--------|----------|\n| Steering | `.kiro/steering/` | Kiro steering files |\n| Power | `~/.kiro/powers/` | Kiro power modules |\n\n### Security Validation\n\nAll discovered skills should be validated before import using the `validate_skill` tool to scan for:\n\n- Dangerous commands (`rm -rf`, `sudo`, `eval`)\n- Suspicious file operations (`/etc/`, `/usr/`)\n- Code injection patterns (`${...}`, `$(...)`)\n\n资料来源：[src/core/security-validator.ts:1-50]()\n\n## Summary\n\nSkill Discovery provides the foundational capability to explore and find Claude skills from the skills.sh ecosystem. Through a combination of search, listing, and trending endpoints, users can efficiently discover relevant skills for their needs. The system emphasizes:\n\n- **Performance**: In-memory caching with 1-hour TTL\n- **Reliability**: Retry logic with exponential backoff\n- **Security**: Integration with validation pipeline\n- **Developer Experience**: Clear error messages with actionable suggestions\n\nFor implementation details, refer to the source files listed at the beginning of this page.\n\n---\n\n\n\n## Security Validation\n\n### 相关页面\n\n相关主题：[Error Handling](#error-handling), [Format Conversion](#format-conversion)\n\n\nRelated Source Files
\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/errors.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts)\n- [src/tools/validate-skill.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/validate-skill.ts)\n- [examples/usage-examples.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md)\n \n\n# Security Validation\n\nThe Security Validation system is a critical component of the Skill Loader MCP Server that protects users from potentially malicious or unsafe skill content. It performs comprehensive static analysis on skill markdown files before they are imported, converted, or executed.\n\n## Overview\n\nThe security validation module (`SecurityValidator`) scans skill content for multiple categories of security threats, including dangerous system commands, file system access patterns, code injection vulnerabilities, and untrusted content sources. Skills that fail security validation are blocked from import unless validation is explicitly skipped.\n\n**Purpose:**\n- Prevent execution of harmful system commands\n- Block imports from non-verified sources\n- Detect potential code injection patterns\n- Protect the host system from malicious skills\n\n**Scope:** All skill content passing through the server's import, validation, and conversion workflows.\n\n资料来源：[src/core/security-validator.ts:1-50]()\n\n## Architecture\n\n```mermaid\ngraph TD\n A[Skill Content Input] --> B[SecurityValidator.validate]\n B --> C{Dangerous Commands?}\n C -->|Yes| D[Issue: dangerous_command]\n B --> E{Suspicious File Ops?}\n E -->|Yes| F[Issue: suspicious_file_operation]\n B --> G{Code Injection?}\n G -->|Yes| H[Issue: code_injection]\n B --> I{Untrusted Source?}\n I -->|Yes| J[Issue: untrusted_source]\n B --> K{Suspicious Patterns?}\n K -->|Yes| L[Issue: suspicious_pattern]\n \n D --> M[ValidationResult.issues]\n F --> M\n H --> M\n J --> M\n L --> M\n \n M --> N[getSeverity]\n N --> O{hasDangerousCommand
or untrustedSource?}\n O -->|Yes| P[Severity: unsafe]\n N --> Q{hasIssues?}\n Q -->|Yes| R[Severity: warning]\n N --> S{noIssues?}\n S -->|Yes| T[Severity: safe]\n```\n\n## Validation Checks\n\nThe security validator performs five distinct categories of checks:\n\n### 1. Dangerous Commands\n\nDetects execution of potentially harmful shell commands that could damage the system.\n\n| Pattern | Description | Severity |\n|---------|-------------|----------|\n| `rm -rf` | Recursive force delete | unsafe |\n| `sudo` | Privilege escalation | unsafe |\n| `eval` | Dynamic code execution | unsafe |\n| `exec` | Command execution | unsafe |\n\n资料来源：[src/core/security-validator.ts:60-80]()\n\n**Example detected content:**\n```bash\nrm -rf /\nsudo rm -rf /usr\neval $user_input\nexec sh\n```\n\n### 2. Suspicious File Operations\n\nIdentifies attempts to access or modify sensitive system directories.\n\n| Pattern | Target Directory | Severity |\n|---------|------------------|----------|\n| `/etc/` | System configuration | unsafe |\n| `/usr/` | System binaries | unsafe |\n| `/bin/` | Essential binaries | unsafe |\n| `~/.` | Hidden files | warning |\n\n资料来源：[src/core/security-validator.ts:81-100]()\n\n### 3. Code Injection Patterns\n\nDetects template injection and command substitution vulnerabilities.\n\n| Pattern | Type | Severity |\n|---------|------|----------|\n| `${...}` | Variable expansion | unsafe |\n| `$(...)` | Command substitution | unsafe |\n\n资料来源：[src/core/security-validator.ts:101-120]()\n\n**Example detected content:**\n```bash\necho ${MALICIOUS_VAR}\nResult: $(whoami)\n```\n\n### 4. Untrusted Sources\n\nBlocks content from non-GitHub sources that cannot be verified.\n\n| Source Type | Status | Severity |\n|-------------|--------|----------|\n| GitHub URLs | Trusted | safe |\n| Other URLs | Blocked | unsafe |\n\n资料来源：[src/core/security-validator.ts:121-140]()\n\n### 5. Suspicious Patterns\n\nFlags potentially concerning patterns that warrant review.\n\n| Pattern | Description | Severity |\n|---------|-------------|----------|\n| Hidden file access (`~/.`) | File hiding | warning |\n| Base64 encoded content | Obfuscation | warning |\n\n资料来源：[src/core/security-validator.ts:141-160]()\n\n## Data Models\n\n### ValidationIssue\n\n```typescript\ninterface ValidationIssue {\n type: 'dangerous_command' | 'suspicious_file_operation' | \n 'code_injection' | 'untrusted_source' | 'suspicious_pattern';\n description: string;\n line: number;\n content: string;\n}\n```\n\n资料来源：[src/core/security-validator.ts:20-30]()\n\n### ValidationResult\n\n```typescript\ninterface ValidationResult {\n isValid: boolean;\n issues: ValidationIssue[];\n severity: 'safe' | 'warning' | 'unsafe';\n}\n```\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `isValid` | boolean | True if no blocking issues (dangerous commands or untrusted sources) |\n| `issues` | ValidationIssue[] | Array of detected issues |\n| `severity` | 'safe' \\| 'warning' \\| 'unsafe' | Overall risk assessment |\n\n资料来源：[src/core/security-validator.ts:31-45]()\n\n## Severity Calculation\n\nThe severity determination follows a hierarchical logic:\n\n```mermaid\ngraph LR\n A[Issues Array] --> B{Contains
dangerous_command
or untrusted_source?}\n B -->|Yes| C[unsafe]\n B -->|No| D{Has any
issues?}\n D -->|Yes| E[warning]\n D -->|No| F[safe]\n```\n\n| Condition | Severity |\n|-----------|----------|\n| Contains `dangerous_command` OR `untrusted_source` | `unsafe` |\n| Contains any other issue type | `warning` |\n| No issues detected | `safe` |\n\n资料来源：[src/core/security-validator.ts:170-190]()\n\n## Integration Points\n\nThe security validator is integrated into the skill import workflow at multiple stages:\n\n```mermaid\ngraph TD\n A[import_skill Tool] --> B[fetch_skill]\n B --> C{validate_skill}\n C --> D{skipValidation?}\n D -->|No| E[SecurityValidator.validate]\n D -->|Yes| F[Skip validation]\n E --> G{unsafe?}\n G -->|Yes| H[Block import
Return error]\n G -->|No| I[Proceed]\n F --> I\n I --> J[convert_to_steering
or convert_to_power]\n J --> K[Import complete]\n```\n\n### validate_skill Tool\n\nThe `validate_skill` MCP tool provides standalone security validation:\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `content` | string | Yes | Skill content to validate |\n| `url` | string | No | Source URL for verification |\n\n**Example Request:**\n```json\n{\n \"tool\": \"validate_skill\",\n \"arguments\": {\n \"content\": \"---\\nname: Test\\n---\\n\\n# Test\",\n \"url\": \"https://github.com/example/repo/main/skill.md\"\n }\n}\n```\n\n**Example Response:**\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资料来源：[src/tools/validate-skill.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/tools/validate-skill.ts)\n\n## Error Handling\n\nValidation errors are wrapped in the `ValidationError` class for consistent error handling:\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| Field | Type | Description |\n|-------|------|-------------|\n| `validationType` | 'format' \\| 'security' \\| 'schema' \\| 'content' | Category of validation failure |\n| `lineNumber` | number (optional) | Line where validation failed |\n| `details` | string[] | List of specific validation issues |\n\n资料来源：[src/core/errors.ts:100-130]()\n\n## Testing\n\nThe security validator includes comprehensive test coverage:\n\n| Test Case | Expected Behavior |\n|-----------|-------------------|\n| Content with `rm -rf` | Detects as `dangerous_command`, severity: unsafe |\n| Content with `${VAR}` | Detects as `code_injection`, severity: unsafe |\n| Content with `$(cmd)` | Detects as `code_injection`, severity: unsafe |\n| Content with `~/.` only | Detects as `suspicious_pattern`, severity: warning |\n| Clean content | Severity: safe |\n\n资料来源：[src/core/security-validator.test.ts:1-50]()\n\n**Test Implementation:**\n```typescript\nit('detects dangerous commands', () => {\n const content = makeContent('Run rm -rf /');\n const result = validator.validate(content);\n expect(result.issues.some(i => i.type === 'dangerous_command')).toBe(true);\n expect(result.severity).toBe('unsafe');\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```\n\n## Configuration\n\nSecurity validation behavior can be configured through the import workflow:\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `skipValidation` | boolean | false | Skip security checks entirely |\n\n**Warning:** Setting `skipValidation: true` bypasses all security checks and should only be used for trusted, locally-verified content.\n\n资料来源：[examples/usage-examples.md:80-100]()\n\n## Line Number Tracking\n\nThe validator tracks the line number for each detected issue:\n\n```typescript\nprivate getLineNumber(content: string, index: number): number {\n const lines = content.substring(0, index).split('\\n');\n return lines.length;\n}\n```\n\nThis enables precise error reporting showing exactly where issues were found in the skill content.\n\n资料来源：[src/core/security-validator.ts:200-210]()\n\n## Security Recommendations\n\nWhen working with skills from external sources:\n\n1. **Always validate first** - Use `validate_skill` before importing unknown skills\n2. **Review issue descriptions** - Understand what triggered each warning\n3. **Prefer GitHub sources** - Skills from GitHub are automatically verified\n4. **Use warning-level skills with caution** - Review content before proceeding\n5. **Never skip validation for untrusted sources** - The unsafe designation exists for protection\n\n---\n\n\n\n## Format Conversion\n\n### 相关页面\n\n相关主题：[Core Modules](#core-modules)\n\n\nRelated Source Files
\n\nThe following source files were used to generate this documentation page:\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/core/types.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/types.ts) (referenced)\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 \n\n# Format Conversion\n\nThe Format Conversion system is a core component of the Skill Loader MCP Server that transforms Claude Skills (represented in markdown with YAML frontmatter) into Kiro-compatible formats for use in AI agent contexts. This system provides bidirectional conversion capabilities through the `ConversionEngine` class and exposes conversion functionality via MCP tools.\n\n## Overview\n\nThe conversion system serves as a bridge between two ecosystems:\n\n| Source Format | Target Formats |\n|--------------|----------------|\n| Claude Skills (markdown + YAML) | Kiro Steering Files |\n| | Kiro Powers |\n\nClaude Skills follow a specific structure with YAML frontmatter containing metadata (name, description, dependencies) and a markdown body with instructions and sections. Kiro, by contrast, supports two distinct consumption patterns: lightweight steering files for simple guidance and comprehensive power packages for complex, multi-file skills.\n\n## Architecture\n\n### Core Components\n\n```mermaid\ngraph TD\n A[Claude Skill Markdown] --> B[ConversionEngine]\n B --> C[parseSkill]\n C --> D[ParsedSkill]\n D --> E{Output Format}\n E --> F[toSteeringFile]\n E --> G[toPower]\n F --> H[SteeringFile]\n G --> I[PowerStructure]\n \n H --> J[.kiro/steering/*.md]\n G --> K[POWER.md]\n G --> L[mcp.json]\n G --> M[steering/ directory]\n```\n\nThe `ConversionEngine` class located in `src/core/conversion-engine.ts` is the central orchestrator for all conversion operations. It provides three primary public methods:\n\n| Method | Purpose | Returns |\n|--------|---------|---------|\n| `parseSkill(content)` | Parse raw markdown into structured data | `ParsedSkill` |\n| `toSteeringFile(skill, sourceUrl?)` | Convert to Kiro steering format | `SteeringFile` |\n| `toPower(skill, sourceUrl?)` | Convert to Kiro power format | `PowerStructure` |\n\n资料来源：[src/core/conversion-engine.ts:38-200]()\n\n### Data Models\n\nThe conversion engine works with several interconnected TypeScript interfaces:\n\n```typescript\ninterface SkillFrontmatter {\n name: string;\n description: string;\n dependencies?: string[];\n // ... additional fields\n}\n\ninterface SkillSection {\n heading: string;\n level: number;\n content: string;\n}\n\ninterface ParsedSkill {\n frontmatter: SkillFrontmatter;\n body: string;\n sections: SkillSection[];\n}\n\ninterface SteeringFile {\n filename: string;\n content: string;\n metadata: {\n originalSkill: string;\n sourceUrl?: string;\n importedAt: string;\n };\n}\n\ninterface PowerStructure {\n powerName: string;\n files: Array<{ path: string; content: string }>;\n}\n```\n\n资料来源：[src/core/conversion-engine.ts:1-50]()\n\n## Skill Parsing\n\n### Frontmatter Extraction\n\nThe `parseSkill` method extracts YAML frontmatter using a regex pattern:\n\n```typescript\nconst frontmatterRegex = /^---\\n([\\s\\S]*?)\\n---/;\n```\n\nThis pattern matches content between `---` delimiters at the document start. The extracted YAML is then parsed using the `js-yaml` library into a JavaScript object.\n\n资料来源：[src/core/conversion-engine.ts:55-90]()\n\n### Validation Rules\n\nThe parser enforces the following validation rules:\n\n| Field | Requirement | Error Type |\n|-------|-------------|------------|\n| `name` | Required, non-empty string | `ValidationError` |\n| `description` | Required, non-empty string | `ValidationError` |\n| Content | Must not be empty after trimming | `ValidationError` |\n\n```typescript\nif (!content || content.trim().length === 0) {\n const error = new ValidationError(\n 'Skill content is empty',\n 'content',\n { details: ['The skill file contains no content'] }\n );\n ErrorLogger.log(error);\n throw error;\n}\n```\n\n资料来源：[src/core/conversion-engine.ts:55-65]()\n\n### Section Extraction\n\nThe parser splits the markdown body into hierarchical sections based on heading levels (H1-H6). Each section captures:\n\n- `heading`: The text following the `#` symbols\n- `level`: The heading depth (1-6)\n- `content`: The markdown content following the heading\n\n```typescript\nconst sectionRegex = /^(#{1,6})\\s+(.+)\\n([\\s\\S]*?)(?=\\n#{1,6}\\s|\\n*$)/gm;\n```\n\nThis regex preserves code blocks with language annotations, allowing syntax-highlighted examples to pass through unchanged.\n\n资料来源：[src/core/conversion-engine.ts:70-150]()\n\n### Keyword Extraction\n\nThe private `extractKeywords` method generates up to 5 relevant keywords from the skill description:\n\n1. Converts text to lowercase\n2. Removes special characters\n3. Filters out common stop words\n4. Keeps words with 3+ characters\n5. Returns the first 5 matches\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 // ... additional stop words\n ]);\n \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:180-220]()\n\n## Steering File Conversion\n\n### Output Format\n\nSteering files are designed for simple, single-file skill guidance. They are saved with a kebab-case filename derived from the skill name and placed in `.kiro/steering/` directories.\n\n### Conversion Process\n\n```mermaid\ngraph LR\n A[ParsedSkill] --> B[Generate Filename]\n B --> C[kebab-case + .md]\n A --> D[Build Content]\n D --> E[Title from name]\n D --> F[Description section]\n D --> G[Complex sections]\n D --> H[Dependencies list]\n A --> I[Create Metadata]\n I --> J[originalSkill]\n I --> K[sourceUrl]\n I --> L[importedAt]\n E --> M[SteeringFile]\n F --> M\n G --> M\n H --> M\n I --> M\n```\n\n### Content Structure\n\nA steering file contains these sections in order:\n\n1. **Title**: `# {skill.name} Guidelines`\n2. **Description**: From frontmatter if present\n3. **Complex Sections**: Sections with level ≥ 2 and content length > 200 characters\n4. **Dependencies**: Bulleted list if dependencies exist\n5. **Footer**: Attribution message\n\n### Filename Generation\n\nThe `toSteeringFile` method uses `toKebabCase` to transform skill names:\n\n```typescript\nprivate toKebabCase(str: string): string {\n return str\n .toLowerCase()\n .replace(/[\\s_]+/g, '-')\n .replace(/[^a-z0-9-]/g, '')\n .replace(/-+/g, '-')\n .replace(/^-|-$/g, '');\n}\n```\n\nTransformation examples:\n\n| Input | Output |\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:120-160]()\n\n### Steering File Output\n\n```typescript\nreturn {\n filename,\n content,\n metadata: {\n originalSkill: skill.frontmatter.name,\n sourceUrl,\n importedAt: now\n }\n};\n```\n\n资料来源：[src/core/conversion-engine.ts:190-200]()\n\n## Power Conversion\n\n### Output Format\n\nPower format is more comprehensive, supporting multi-file outputs for complex skills. The `toPower` method can generate up to three files:\n\n| File | Condition | Purpose |\n|------|-----------|---------|\n| `POWER.md` | Always | Main power manifest and content |\n| `mcp.json` | Has dependencies or MCP tool references | MCP server configuration |\n| `steering/` directory | Has 3+ complex sections | Additional guidance files |\n\n资料来源：[src/core/conversion-engine.ts:200-280]()\n\n### Power Manifest Structure\n\nThe `POWER.md` file follows Kiro's power specification:\n\n```markdown\n---\nname: {kebab-case-name}\ndisplayName: {original-name}\ndescription: {description}\nkeywords: [{extracted-keywords}]\n---\n\n# {skill.frontmatter.name}\n\n{skill.body}\n\n## Dependencies\n{dependency-list}\n\n## Import Metadata\n- **Original Skill**: {name}\n- **Source URL**: {url}\n- **Imported At**: {ISO-timestamp}\n- **Imported Via**: Skill Loader Power\n```\n\n资料来源：[src/core/conversion-engine.ts:220-260]()\n\n### MCP.json Generation\n\nThe method `shouldGenerateMcpJson` determines when to create the MCP configuration:\n\n```typescript\nprivate shouldGenerateMcpJson(skill: ParsedSkill): boolean {\n const hasDependencies = skill.frontmatter.dependencies?.length > 0;\n const hasTools = skill.sections.some(s => s.content.includes('mcp__'));\n return hasDependencies || hasTools;\n}\n```\n\n资料来源：[src/core/conversion-engine.ts:280-300]()\n\n### Steering Directory Generation\n\nComplex skills with multiple substantial sections generate additional files in a `steering/` subdirectory:\n\n```typescript\nprivate shouldGenerateSteeringDir(skill: ParsedSkill): 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:300-320]()\n\n### Power Output Structure\n\n```typescript\nconst files: Array<{ path: string; content: string }> = [\n { path: 'POWER.md', content: powerContent }\n];\n\nif (this.shouldGenerateMcpJson(skill)) {\n const mcpJson = this.generateMcpJson(skill);\n files.push({\n path: 'mcp.json',\n content: JSON.stringify(mcpJson, null, 2)\n });\n}\n\nif (this.shouldGenerateSteeringDir(skill)) {\n const steeringContent = this.generateSteeringContent(skill);\n // Add steering files...\n}\n```\n\n资料来源：[src/core/conversion-engine.ts:260-290]()\n\n## MCP Tools Integration\n\n### Available Tools\n\nThe conversion functionality is exposed through two MCP tools:\n\n#### convert_to_steering\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `content` | string | Yes | Raw skill markdown content |\n| `sourceUrl` | string | No | Original source URL for metadata |\n\n```json\n{\n \"tool\": \"convert_to_steering\",\n \"arguments\": {\n \"content\": \"---\\nname: PDF Extractor\\ndescription: Extract text from PDF files\\n---\\n\\n# PDF Extractor\",\n \"sourceUrl\": \"https://example.com/skill.md\"\n }\n}\n```\n\n资料来源：[README.md:80-100]()\n\n#### convert_to_power\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `content` | string | Yes | Raw skill markdown content |\n| `sourceUrl` | string | No | Original source URL for metadata |\n\n```json\n{\n \"tool\": \"convert_to_power\",\n \"arguments\": {\n \"content\": \"---\\nname: PDF Extractor\\ndescription: Extract text from PDF files\\n---\\n\\n# PDF Extractor\",\n \"sourceUrl\": \"https://example.com/skill.md\"\n }\n}\n```\n\n资料来源：[README.md:105-125]()\n\n### Complete Import Workflow\n\nThe `import_skill` tool provides a unified workflow combining fetch, validation, and conversion:\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\nThis workflow:\n1. Fetches skill content from GitHub\n2. Validates for security issues (unless skipped)\n3. Converts to the specified format\n4. Returns the converted content with metadata\n\n资料来源：[README.md:130-150]()\n\n## Error Handling\n\n### Error Types\n\nThe conversion engine uses specialized error classes for different failure scenarios:\n\n| Error Class | Usage | Context Fields |\n|-------------|-------|----------------|\n| `ParsingError` | YAML/frontmatter parsing failures | `field`, `value` |\n| `ValidationError` | Content validation failures | `field`, `details` |\n\n```typescript\nif (!parsed || typeof parsed !== 'object') {\n const error = new ParsingError(\n 'YAML frontmatter is not a valid object',\n 'frontmatter',\n { yamlContent: yamlContent.substring(0, 100) }\n );\n ErrorLogger.log(error);\n throw error;\n}\n```\n\n资料来源：[src/core/conversion-engine.ts:70-85]()\n\n### Error Logging\n\nAll errors are logged through `ErrorLogger` before being thrown, enabling debugging and audit trails:\n\n```typescript\nErrorLogger.log(error);\nthrow error;\n```\n\n资料来源：[src/core/errors.ts:50-100]()\n\n## Testing\n\nThe conversion engine has comprehensive test coverage in `src/core/conversion-engine.test.ts`:\n\n### parseSkill Tests\n\n| Test Case | Input | Expected |\n|-----------|-------|----------|\n| Valid skill with frontmatter | Complete YAML + body | Parsed frontmatter and sections |\n| Empty content | `\"\"` | Throws ValidationError |\n| Missing name | YAML without `name` | Throws ValidationError |\n| Missing description | YAML without `description` | Throws ValidationError |\n| No frontmatter | Plain markdown | Uses \"Untitled Skill\" |\n| Code block preservation | Markdown with code fences | Code blocks intact |\n\n资料来源：[src/core/conversion-engine.test.ts:1-80]()\n\n### Steering Conversion Tests\n\n| Test Case | Description |\n|-----------|-------------|\n| Basic conversion | Validates output structure |\n| Empty dependencies | No dependencies section generated |\n| With dependencies | Dependencies section populated |\n\n### Power Conversion Tests\n\n| Test Case | Expected Behavior |\n|-----------|-------------------|\n| Basic conversion | POWER.md generated with manifest |\n| With dependencies | `mcp.json` added to files array |\n| Without dependencies | No `mcp.json` generated |\n| Complex sections (3+) | `steering/` directory created |\n\n资料来源：[src/core/conversion-engine.test.ts:80-150]()\n\n## Usage Examples\n\n### Convert to Steering File\n\n```typescript\nconst content = `---\nname: PDF Extractor\ndescription: Extract text from PDF files\n---\n\n# PDF Extractor\n\nExtract text content from PDF documents.`;\n\nconst result = engine.toSteeringFile(\n engine.parseSkill(content),\n 'https://example.com/skill.md'\n);\n\n// Result structure:\n// {\n// filename: \"pdf-extractor.md\",\n// content: \"# PDF Extractor Guidelines\\n\\n...\",\n// metadata: { originalSkill: \"PDF Extractor\", ... }\n// }\n```\n\n### Convert to Power\n\n```typescript\nconst content = `---\nname: React Best Practices\ndescription: Guide for React development\ndependencies:\n - react\n - react-dom\n---\n\n# React Best Practices\n\nContent with multiple sections...`;\n\nconst result = engine.toPower(\n engine.parseSkill(content),\n 'https://example.com/skill.md'\n);\n\n// Result structure:\n// {\n// powerName: \"react-best-practices\",\n// files: [\n// { path: \"POWER.md\", content: \"...\" },\n// { path: \"mcp.json\", content: \"...\" }\n// ]\n// }\n```\n\n资料来源：[examples/usage-examples.md:50-120]()\n\n## Summary\n\nThe Format Conversion system provides a robust bridge between Claude Skills and Kiro formats:\n\n- **Single Entry Point**: `ConversionEngine` class handles all conversions\n- **Two Output Formats**: Steering files (simple) and Powers (complex)\n- **Automatic Structure Detection**: Determines output complexity based on content\n- **Security Integration**: Works with the validation system for safe imports\n- **Comprehensive Error Handling**: Typed errors with context for debugging\n- **Full Test Coverage**: Unit tests for all major code paths\n\n---\n\n\n\n## Caching System\n\n### 相关页面\n\n相关主题：[Skill Discovery](#skill-discovery), [Type Definitions](#type-definitions)\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- [src/utils/cache.test.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/utils/cache.test.ts)\n- [README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n \n\n# Caching System\n\n## Overview\n\nThe Caching System in the Skill Loader MCP Server provides an in-memory caching layer with TTL (Time To Live) support. It is designed to reduce redundant API calls to external services like skills.sh, improving response times and reducing network overhead.\n\nThe cache implementation is generic and reusable, supporting any data type through TypeScript generics. It automatically expires entries after a configurable TTL and provides basic cache management operations.\n\n**Key Characteristics:**\n- In-memory storage using `Map` data structure\n- Configurable TTL per cache instance\n- Automatic expiration checking on access\n- Zero external dependencies\n\n资料来源：[src/utils/cache.ts:1-60]()\n\n---\n\n## Architecture\n\n### Component Diagram\n\n```mermaid\ngraph TB\n subgraph \"Caching System Components\"\n Cache[\"Cache Class\"]\n CacheEntry[\"CacheEntry Interface\"]\n end\n \n subgraph \"Data Structure\"\n Map[\"Map>\"]\n Data[\"data: T\"]\n Timestamp[\"timestamp: number\"]\n end\n \n subgraph \"Operations\"\n Get[\"get(key)\"]\n Set[\"set(key, data)\"]\n Has[\"has(key)\"]\n Delete[\"delete(key)\"]\n Clear[\"clear()\"]\n end\n \n Cache --> CacheEntry\n CacheEntry --> Data\n CacheEntry --> Timestamp\n Cache --> Map\n Cache -.-> Get\n Cache -.-> Set\n Cache -.-> Has\n Cache -.-> Delete\n Cache -.-> Clear\n```\n\n### Data Model\n\n```typescript\ninterface CacheEntry {\n data: T; // The cached value\n timestamp: number; // Unix timestamp when entry was created\n}\n```\n\n资料来源：[src/utils/cache.ts:9-13]()\n\n---\n\n## API Reference\n\n### Cache Class\n\n```typescript\nclass Cache {\n constructor(ttl: number)\n get(key: string): T | undefined\n set(key: string, data: T): void\n has(key: string): boolean\n delete(key: string): void\n clear(): void\n}\n```\n\n### Constructor\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `ttl` | `number` | Time to live in milliseconds |\n\n```typescript\nconstructor(ttl: number) {\n this.ttl = ttl;\n}\n```\n\n资料来源：[src/utils/cache.ts:22-28]()\n\n### get()\n\nRetrieves a cached value by key. Returns `undefined` if the key does not exist or the entry has expired.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `key` | `string` | Cache key |\n\n| Return Type | Description |\n|-------------|-------------|\n| `T \\| undefined` | Cached value or undefined if not found/expired |\n\n```typescript\nget(key: string): T | undefined {\n const entry = this.cache.get(key);\n \n if (!entry) {\n return undefined;\n }\n \n // Check if entry has expired\n if (Date.now() - entry.timestamp > this.ttl) {\n this.cache.delete(key);\n return undefined;\n }\n \n return entry.data;\n}\n```\n\n资料来源：[src/utils/cache.ts:37-53]()\n\n### set()\n\nStores a value in the cache with the current timestamp.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `key` | `string` | Cache key |\n| `data` | `T` | Data to cache |\n\n```typescript\nset(key: string, data: T): void {\n this.cache.set(key, {\n data,\n timestamp: Date.now(),\n });\n}\n```\n\n资料来源：[src/utils/cache.ts:60-67]()\n\n### has()\n\nChecks if a key exists in the cache and has not expired.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `key` | `string` | Cache key |\n\n| Return Type | Description |\n|-------------|-------------|\n| `boolean` | True if key exists and is not expired |\n\n```typescript\nhas(key: string): boolean {\n return this.get(key) !== undefined;\n}\n```\n\n资料来源：[src/utils/cache.ts:69-72]()\n\n### delete()\n\nRemoves a specific entry from the cache.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `key` | `string` | Cache key to delete |\n\n```typescript\ndelete(key: string): void {\n this.cache.delete(key);\n}\n```\n\n资料来源：[src/utils/cache.ts:74-76]()\n\n### clear()\n\nRemoves all entries from the cache.\n\n```typescript\nclear(): void {\n this.cache.clear();\n}\n```\n\n资料来源：[src/utils/cache.ts:78-80]()\n\n---\n\n## Cache Lifecycle\n\n### Entry Lifecycle Diagram\n\n```mermaid\ngraph LR\n A[\"set(key, data)\"] --> B[\"Entry Created
timestamp = Date.now()\"]\n B --> C{\"get(key) called?\"}\n C -->|Yes| D{\"Date.now() - timestamp
> TTL?\"}\n D -->|No| E[\"Return cached data\"]\n D -->|Yes| F[\"Delete expired entry\"]\n F --> G[\"Return undefined\"]\n C -->|No| H[\"Entry remains in cache\"]\n E --> H\n G --> I[\"Next get() call\"]\n I --> C\n```\n\n### Expiration Check Flow\n\n```mermaid\nflowchart TD\n A[\"get(key)\"] --> B{\"Entry exists?\"}\n B -->|No| C[\"Return undefined\"]\n B -->|Yes| D{\"Date.now() - timestamp
> TTL?\"}\n D -->|Yes| E[\"Delete entry
from cache\"]\n E --> F[\"Return undefined\"]\n D -->|No| G[\"Return cached data\"]\n```\n\n资料来源：[src/utils/cache.ts:37-53]()\n\n---\n\n## Configuration\n\n### TTL Configuration\n\nThe TTL (Time to Live) determines how long cached entries remain valid.\n\n| TTL Value | Duration | Use Case |\n|-----------|----------|----------|\n| 60,000 ms | 1 minute | Short-lived data, frequent updates |\n| 3,600,000 ms | 1 hour | Skills.sh directory listings |\n| 86,400,000 ms | 24 hours | Stable, rarely changing data |\n\n**Implementation Note:** The skills.sh integration uses a 1-hour TTL to cache search results and directory listings, reducing API calls while ensuring relatively fresh data.\n\n资料来源：[README.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md)\n\n---\n\n## Usage Examples\n\n### Basic Cache Usage\n\n```typescript\nimport { Cache } from './utils/cache.js';\n\n// Create a cache with 60 second TTL\nconst cache = new Cache(60_000);\n\n// Set a value\ncache.set('user:123', JSON.stringify({ name: 'Alice', role: 'admin' }));\n\n// Get the value\nconst userData = cache.get('user:123');\nif (userData) {\n console.log(JSON.parse(userData));\n}\n\n// Check existence\nif (cache.has('user:123')) {\n console.log('User exists in cache');\n}\n\n// Delete specific entry\ncache.delete('user:123');\n\n// Clear all entries\ncache.clear();\n```\n\n资料来源：[src/utils/cache.test.ts:1-22]()\n\n### Type-Safe Caching\n\n```typescript\n// Generic cache works with any type\ninterface Skill {\n name: string;\n description: string;\n owner: string;\n}\n\nconst skillCache = new Cache(3_600_000); // 1 hour TTL\n\nskillCache.set('pdf-extractor', {\n name: 'pdf-extractor',\n description: 'Extract text from PDF files',\n owner: 'anthropics'\n});\n\nconst skill = skillCache.get('pdf-extractor');\n// skill is typed as Skill | undefined\n```\n\n---\n\n## Test Coverage\n\nThe cache implementation includes comprehensive unit tests covering:\n\n| Test Case | Description |\n|-----------|-------------|\n| Stores and retrieves values | Basic set/get operations |\n| Returns undefined for missing keys | Cache miss behavior |\n| Expires entries after TTL | Automatic expiration |\n| `has()` returns true for valid keys | Existence check |\n| `delete()` removes entries | Manual removal |\n| `clear()` removes all entries | Bulk removal |\n\n资料来源：[src/utils/cache.test.ts:1-32]()\n\n### Test Implementation\n\n```typescript\nit('expires entries after TTL', () => {\n const cache = new Cache(1); // 1ms TTL\n cache.set('key1', 'value1');\n // Force expiry by waiting\n const start = Date.now();\n while (Date.now() - start < 5) { /* busy wait */ }\n expect(cache.get('key1')).toBeUndefined();\n});\n```\n\n资料来源：[src/utils/cache.test.ts:16-24]()\n\n---\n\n## Design Decisions\n\n### Why In-Memory Cache?\n\n1. **Simplicity**: No external dependencies required\n2. **Performance**: Direct memory access is extremely fast\n3. **Suitable for Server Use Case**: The MCP server runs as a single process where in-memory caching is appropriate\n\n### Why TTL-Based Expiration?\n\n- Ensures data freshness without manual invalidation\n- Automatic cleanup prevents memory leaks\n- Simple and predictable behavior\n\n### Why Check Expiration on Get?\n\n- Lazy expiration keeps the cache simple\n- No background timer overhead\n- Expired entries are cleaned on next access\n\n---\n\n## Limitations\n\n| Limitation | Impact |\n|------------|--------|\n| Single-process only | Cache not shared between server instances |\n| No persistence | Cache lost on server restart |\n| Memory bound | Large caches consume RAM |\n| No distributed invalidation | Cannot invalidate across processes |\n\n资料来源：[src/utils/cache.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/utils/cache.ts)\n\n---\n\n## Related Components\n\n```mermaid\ngraph LR\n Cache[\"Caching System\"] --> SkillResolver[\"SkillResolver\"]\n SkillResolver[\"SkillResolver\"] -->|Caches directory listings| Cache\n \n Cache --> Usage[\"MCP Tools
list_skills
search_skills\"]\n \n subgraph \"Storage\"\n Cache\n end\n \n subgraph \"Consumers\"\n SkillResolver\n Usage\n end\n```\n\nThe caching system is utilized by the `SkillResolver` for caching skills.sh directory listings to improve performance of listing and searching operations.\n\n---\n\n## Summary\n\nThe Caching System provides a lightweight, generic in-memory cache with TTL support. It serves as the foundational caching layer for the Skill Loader MCP Server, enabling efficient storage of frequently accessed data like skills.sh API responses. The system prioritizes simplicity and reliability over feature complexity, making it suitable for server-side caching in a single-process environment.\n\n---\n\n\n\n## Type Definitions\n\n### 相关页面\n\n相关主题：[Core Modules](#core-modules), [Caching System](#caching-system)\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- [CHANGELOG.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CHANGELOG.md) - 变更日志\n \n\n# Type Definitions\n\nThis page documents the type system for the Skill Loader MCP Server, covering core data models, error classes, and validation types used throughout the application.\n\n## Overview\n\nThe Skill Loader MCP Server uses TypeScript for type-safe development. The type system is organized around several key domains:\n\n- **Skill Data Models**: Structures for representing Claude Skills and their components\n- **Error Handling**: Hierarchical error classes with context and recovery suggestions\n- **Security Validation**: Types for security issue detection and severity levels\n- **API Responses**: Standardized response formats for MCP tools\n\n资料来源：[src/core/types.ts]()，[src/core/errors.ts]()\n\n## Core Data Models\n\n### Skill Structure\n\nThe skill data model represents Claude Skills with their metadata and content sections.\n\n```mermaid\nclassDiagram\n class SkillFrontmatter {\n +string name\n +string description\n +string[] dependencies\n }\n class SkillSection {\n +number level\n +string heading\n +string content\n }\n class ParsedSkill {\n +SkillFrontmatter frontmatter\n +string body\n +SkillSection[] sections\n }\n class ConversionResult {\n +string filename\n +string content\n +Record metadata\n }\n \n ParsedSkill *-- SkillFrontmatter\n ParsedSkill *-- SkillSection\n ConversionResult ..> ParsedSkill\n```\n\n### SkillFrontmatter\n\nThe frontmatter contains skill metadata defined in YAML format at the top of skill files.\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `name` | `string` | The skill name |\n| `description` | `string` | Brief description of the skill |\n| `dependencies` | `string[]` | Optional list of required dependencies |\n\n资料来源：[src/core/conversion-engine.ts]() (示例展示结构)\n\n### ParsedSkill\n\nA fully parsed skill document containing all extracted components.\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `frontmatter` | `SkillFrontmatter` | YAML metadata block |\n| `body` | `string` | Raw skill content body |\n| `sections` | `SkillSection[]` | Extracted markdown sections |\n\n资料来源：[src/core/conversion-engine.ts]()\n\n### SkillSection\n\nRepresents a heading section within a skill document.\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `level` | `number` | Heading level (1-6) |\n| `heading` | `string` | Section title text |\n| `content` | `string` | Section body content |\n\n## Error Class Hierarchy\n\nThe error system uses a hierarchical class structure for granular error handling.\n\n```mermaid\nclassDiagram\n class Error {\n +string message\n +string name\n +Date timestamp\n +string stack\n }\n \n class SkillLoaderError {\n +Date timestamp\n +Record context\n +getDetailedMessage()\n }\n \n class NetworkError {\n +string url\n +number? statusCode\n +number retryCount\n +getUserMessage()\n }\n \n class ValidationError {\n +string validationType\n +number? lineNumber\n +string[] details\n }\n \n class FileSystemError {\n +string operation\n +string filePath\n +string? systemError\n }\n \n class ParsingError {\n +string parseType\n +string? invalidContent\n +getUserMessage()\n }\n \n Error <|-- SkillLoaderError\n SkillLoaderError <|-- NetworkError\n SkillLoaderError <|-- ValidationError\n SkillLoaderError <|-- FileSystemError\n SkillLoaderError <|-- ParsingError\n```\n\n### Base Class: SkillLoaderError\n\nAll application errors extend the base `SkillLoaderError` class.\n\n```typescript\nclass SkillLoaderError extends Error {\n public readonly timestamp: Date;\n public readonly context: Record;\n}\n```\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `timestamp` | `Date` | When the error occurred |\n| `context` | `Record` | Additional error context data |\n\n资料来源：[src/core/errors.ts]()\n\n### NetworkError\n\nHandles network-related failures including connection issues, timeouts, and HTTP errors.\n\n```typescript\nclass NetworkError extends SkillLoaderError {\n public readonly url: string;\n public readonly statusCode?: number;\n public readonly retryCount: number;\n}\n```\n\n资料来源：[src/core/errors.ts]()\n\n**Recovery suggestions by status code:**\n\n| Status Code | Suggestion |\n|-------------|------------|\n| `404` | Verify skill name is correct; check repository exists |\n| `403` | Rate limit hit; wait a few minutes |\n| `>= 500` | Server issues; try again later |\n\n### ValidationError\n\nRepresents validation failures for format, security, schema, or content issues.\n\n```typescript\nclass 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| Property | Type | Description |\n|----------|------|-------------|\n| `validationType` | `ValidationType` | Category of validation failure |\n| `lineNumber` | `number?` | Line where error occurred (if applicable) |\n| `details` | `string[]` | List of specific validation issues |\n\n资料来源：[src/core/errors.ts]()\n\n### FileSystemError\n\nHandles file system operations including read, write, delete, and access errors.\n\n```typescript\nclass 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| Property | Type | Description |\n|----------|------|-------------|\n| `operation` | `FileOperation` | Type of file operation that failed |\n| `filePath` | `string` | Path involved in the error |\n| `systemError` | `string?` | Raw system error message |\n\n**System error code mappings:**\n\n| Error Code | Issue | Recovery |\n|------------|-------|----------|\n| `EACCES` / `EPERM` | Permission denied | Check file permissions |\n| `ENOSPC` | Disk full | Free up disk space |\n| `ENOENT` | Path not found | Verify directory exists |\n| `EEXIST` | File exists | Use --overwrite flag |\n\n资料来源：[src/core/errors.ts]()\n\n## Security Validation Types\n\n### ValidationIssue\n\nRepresents a detected security or content issue.\n\n```typescript\ninterface ValidationIssue {\n type: 'dangerous_command' | 'suspicious_pattern' | 'untrusted_source' | 'suspicious_file_op';\n description: string;\n location: string;\n}\n```\n\n| Type | Severity | Description |\n|------|----------|-------------|\n| `dangerous_command` | unsafe | Commands like `rm -rf`, `sudo`, `eval`, `exec` |\n| `suspicious_pattern` | warning | Code injection patterns like `${...}`, `$(...)` |\n| `untrusted_source` | unsafe | Non-GitHub source URLs |\n| `suspicious_file_op` | warning | Access to system directories (`/etc/`, `/usr/`, `/bin/`) |\n\n资料来源：[src/core/security-validator.ts]()\n\n### ValidationResult\n\nComplete validation outcome with severity classification.\n\n```typescript\ninterface ValidationResult {\n isValid: boolean;\n issues: ValidationIssue[];\n severity: 'safe' | 'warning' | 'unsafe';\n}\n```\n\n**Severity determination rules:**\n\n```mermaid\ngraph TD\n A[ValidationResult] --> B{issues.length === 0?}\n B -->|Yes| C[Return safe]\n B -->|No| D{Has untrusted_source?}\n D -->|Yes| E[Return unsafe]\n D -->|No| F{Has dangerous_command?}\n F -->|Yes| E\n F -->|No| G[Return warning]\n```\n\n资料来源：[src/core/security-validator.ts]()\n\n## API Response Types\n\n### SkillsShEntry\n\nRepresents a skill entry from skills.sh directory.\n\n```typescript\ninterface SkillsShEntry {\n name: string;\n description: string;\n owner: string;\n repo: string;\n installs: number;\n relevance?: number;\n rank?: number;\n trending?: boolean;\n}\n```\n\n### SkillsShV1Response\n\nAPI response wrapper for skills.sh v1 endpoints.\n\n```typescript\ninterface SkillsShV1Response {\n skills: SkillsShEntry[];\n total?: number;\n page?: number;\n pageSize?: number;\n}\n```\n\n### ConversionResponse\n\nResponse format for skill conversion operations.\n\n```typescript\ninterface ConversionResponse {\n success: boolean;\n content: string;\n filename: string;\n targetPath: string;\n metadata: {\n skillName: string;\n sourceUrl?: string;\n outputFormat: 'steering' | 'power';\n validationResult: ValidationResult;\n };\n}\n```\n\n资料来源：[examples/usage-examples.md]()\n\n## MCP Tool Parameters\n\n### Tool Input Schemas\n\n| Tool | Required Parameters | Optional Parameters |\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## Configuration Types\n\n### Server Configuration\n\n```typescript\ninterface ServerConfig {\n SKILLS_SH_API_KEY?: string;\n cache?: {\n skillsTTL: number; // Default: 3600000 (1 hour)\n };\n retry?: {\n maxRetries: number;\n baseDelay: number;\n };\n}\n```\n\n## Type Naming Conventions\n\nPer project coding standards:\n\n| Category | Convention | Example |\n|----------|------------|---------|\n| Files | kebab-case | `skill-fetcher.ts` |\n| Classes | PascalCase | `SkillFetcher` |\n| Functions | camelCase | `fetchSkill` |\n| Constants | UPPER_SNAKE_CASE | `MAX_RETRIES` |\n| Interfaces | PascalCase | `ISkillData` |\n\n资料来源：[CONTRIBUTING.md]()\n\n## Summary\n\nThe type system provides:\n\n1. **Type-safe data models** for skills, sections, and metadata\n2. **Hierarchical error handling** with context and recovery suggestions\n3. **Security validation** with issue categorization and severity levels\n4. **Standardized API responses** for all MCP tools\n\nAll types are defined in TypeScript with proper JSDoc documentation for IDE support and generated documentation.\n\n资料来源：[CHANGELOG.md]()\n\n---\n\n\n\n## Deployment and Configuration\n\n### 相关页面\n\n相关主题：[Getting Started](#getting-started), [Error Handling](#error-handling)\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- [CONTRIBUTING.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CONTRIBUTING.md)\n- [CHANGELOG.md](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CHANGELOG.md)\n- [src/core/errors.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts)\n \n\n# Deployment and Configuration\n\n## Overview\n\nThe Skill Loader MCP Server provides a comprehensive deployment model for integrating Claude skill management capabilities into various AI development environments. The deployment architecture supports multiple integration patterns, including integration with Kiro, Claude Desktop, and standalone operation modes. Configuration is primarily driven through environment variables and MCP server configuration files, enabling flexible deployment scenarios ranging from simple local installations to enterprise-scale distributed setups.\n\nThe server operates as a Model Context Protocol (MCP) server that exposes eight distinct tools for skill management operations. These tools interact with external services including the skills.sh marketplace API and GitHub repositories containing skill definitions. The deployment model emphasizes security through content validation, caching strategies for performance optimization, and comprehensive error handling mechanisms that provide actionable feedback for administrators and users alike.\n\n## Installation Methods\n\n### Global Installation\n\nGlobal installation provides system-wide access to the Skill Loader MCP Server, making it immediately available to all projects and users on a given system. This approach is recommended for scenarios where multiple projects require access to skill management capabilities without individual per-project configuration.\n\nThe global installation is performed using npm with the `-g` flag, which installs the package in the global npm registry location. For systems with multiple Node.js versions or requiring specific version management, npx can be used to execute the package directly without permanent installation.\n\n```bash\nnpm install -g @goldzulu/skill-loader-mcp-server\n```\n\n资料来源：[README.md:49](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md#L49)\n\n### Local Installation\n\nLocal installation is appropriate for project-specific deployments where the skill loader should be tracked as a project dependency. This approach ensures version consistency across team members and facilitates reproducible builds through package.json dependency management.\n\n```bash\nnpm install @goldzulu/skill-loader-mcp-server\n```\n\n资料来源：[README.md:53](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md#L53)\n\n### Development Installation\n\nFor contributors setting up the development environment, the installation process includes additional steps for building the TypeScript source and running tests. The development setup requires Node.js, npm or yarn, and Git for version control.\n\n```bash\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n\n# Run tests\nnpm test\n```\n\n资料来源：[CONTRIBUTING.md:14-19](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CONTRIBUTING.md#L14-L19)\n\n## Environment Variables\n\nThe Skill Loader MCP Server uses environment variables to configure runtime behavior and authentication. Understanding the distinction between required and optional environment variables is critical for successful deployment.\n\n### SKILLS_SH_API_KEY\n\nThe `SKILLS_SH_API_KEY` environment variable provides authentication for the skills.sh marketplace API. This key is required only for tools that access authenticated endpoints of the skills.sh service.\n\n| Tool | SKILLS_SH_API_KEY Required |\n|------|---------------------------|\n| `search_skills` | No (uses public API) |\n| `list_skills` | Yes |\n| `get_leaderboard` | Yes |\n| `fetch_skill` | No |\n| `validate_skill` | No |\n| `convert_to_steering` | No |\n| `convert_to_power` | No |\n| `import_skill` | No |\n\n资料来源：[README.md:57-58](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md#L57-L58)\n\nThe API key must be requested from Vercel, the platform hosting the skills.sh service. Organizations planning to use the authenticated listing and leaderboard features should coordinate with the skills.sh team to obtain appropriate credentials.\n\n## MCP Server Configuration\n\nThe Skill Loader MCP Server implements the Model Context Protocol specification version 1.29, utilizing the official `@modelcontextprotocol/sdk` for protocol compliance. Configuration varies depending on the target platform and deployment scenario.\n\n### Kiro Configuration\n\nIntegration with Kiro requires modification of the `mcp.json` configuration file. The server can be launched using npx for immediate execution or configured as a persistent server service.\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:65-76](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md#L65-L76)\n\nThe configuration specifies the npx command with the `-y` flag to automatically confirm package installation. The `args` array passes the package name as an argument to npx. The `env` block configures the skills.sh API key, which is optional and only required when accessing authenticated endpoints.\n\n### Claude Desktop Configuration\n\nClaude Desktop users can integrate the Skill Loader MCP Server by adding the server configuration to their Claude Desktop configuration file. The configuration structure differs slightly from Kiro, using the `skill-loader-mcp-server` command directly rather than npx invocation.\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资料来源：[README.md:87-97](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md#L87-L97)\n\nThe Claude Desktop configuration omits the `description` field and uses the globally installed command directly. This approach assumes the package has been installed globally via npm.\n\n### Standalone Operation\n\nFor scenarios requiring direct execution without MCP integration, the server can be launched in standalone mode. This mode is useful for testing, debugging, or batch processing operations where the full MCP protocol overhead is unnecessary.\n\n```bash\nskill-loader-mcp-server\n```\n\n资料来源：[README.md:99-101](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md#L99-L101)\n\n## Deployment Architecture\n\nThe deployment architecture follows a layered design that separates concerns between protocol handling, core business logic, and external service integration.\n\n```mermaid\ngraph TD\n A[Client Application] -->|MCP Protocol| B[MCP Server Layer]\n B -->|Request Dispatch| C[Tool Handlers]\n C --> D1[list_skills]\n C --> D2[search_skills]\n C --> D3[get_leaderboard]\n C --> D4[fetch_skill]\n C --> D5[validate_skill]\n C --> D6[convert_to_steering]\n C --> D7[convert_to_power]\n C --> D8[import_skill]\n D1 --> E[Skills.sh API Client]\n D2 --> E\n D3 --> E\n D4 --> F[GitHub Fetcher]\n E --> G[(Skills.sh API)]\n F --> H[(GitHub)]\n D5 --> I[Security Validator]\n D6 --> J[Conversion Engine]\n D7 --> J\n D8 --> K[Complete Workflow]\n K --> D4\n K --> D5\n K --> D7\n J --> L[(Output Files)]\n I --> M[Error Handler]\n M --> N[User Feedback]\n```\n\n## Tool Configuration Parameters\n\nEach MCP tool exposed by the server accepts specific parameters that control its behavior. Understanding these parameters is essential for effective configuration and usage.\n\n### search_skills\n\nThe `search_skills` tool searches the skills.sh marketplace using the public search API. No authentication is required for this endpoint.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `query` | string | Yes | - | Search query string |\n| `limit` | number | No | 20 | Maximum results (max: 50) |\n\n资料来源：[README.md:109-118](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md#L109-L118)\n\n### list_skills\n\nThe `list_skills` tool retrieves paginated results from the authenticated skills.sh directory endpoint. This tool requires the `SKILLS_SH_API_KEY` environment variable.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `page` | number | No | 1 | Page number for pagination |\n| `pageSize` | number | No | 50 | Results per page (max: 100) |\n\n资料来源：[README.md:122-131](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md#L122-L131)\n\n### get_leaderboard\n\nThe `get_leaderboard` tool retrieves trending or top-installed skills, sorted by installation count or trending score.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `timeframe` | string | No | 'all' | Time window: 'all' or '24h' |\n| `limit` | number | No | 20 | Maximum results (max: 50) |\n\n资料来源：[README.md:135-144](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md#L135-L144)\n\n### fetch_skill\n\nThe `fetch_skill` tool retrieves raw skill content directly from GitHub repositories. The tool supports both shorthand skill names and fully-qualified owner/repo identifiers.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `identifier` | string | Yes | Skill name or 'owner/repo' format |\n\n资料来源：[README.md:148-156](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md#L148-L156)\n\n### validate_skill\n\nThe `validate_skill` tool performs security analysis on skill content, scanning for dangerous patterns and potential security risks.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `content` | string | Yes | Skill content to validate |\n| `url` | string | No | Source URL for verification |\n\n资料来源：[README.md:160-168](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md#L160-L168)\n\n### convert_to_steering\n\nThe `convert_to_steering` tool transforms skill content into the Kiro steering file format, which is used for providing behavioral guidelines to AI models.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `content` | string | Yes | Skill content to convert |\n| `sourceUrl` | string | No | Original source URL for metadata |\n\n资料来源：[README.md:173-181](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md#L173-L181)\n\n### convert_to_power\n\nThe `convert_to_power` tool generates the Kiro power format, which includes additional components for complex skills. When a skill has dependencies or MCP server references, the tool automatically generates an `mcp.json` configuration file. For skills containing three or more complex sections, the tool creates a `steering/` subdirectory with structured content.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `content` | string | Yes | Skill content to convert |\n| `sourceUrl` | string | No | Original source URL for metadata |\n\n资料来源：[README.md:185-193](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md#L185-L193)\n\n### import_skill\n\nThe `import_skill` tool orchestrates the complete import workflow, combining fetch, validation, and conversion operations in a single atomic transaction.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `identifier` | string | Yes | - | Skill name or 'owner/repo' format |\n| `outputFormat` | string | Yes | - | 'steering' or 'power' |\n| `skipValidation` | boolean | No | false | Bypass security validation |\n\n资料来源：[README.md:198-207](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md#L198-L207)\n\n## Security Configuration\n\nThe security validation system is a critical component of the deployment configuration, providing defense-in-depth against potentially malicious skill content.\n\n### Validation Checks\n\nThe security validator scans skill content for multiple categories of risk:\n\n| Category | Patterns Detected |\n|----------|------------------|\n| Dangerous Commands | `rm -rf`, `sudo`, `eval`, `exec` |\n| Suspicious Paths | `/etc/`, `/usr/`, `/bin/` |\n| Code Injection | `${...}`, `$(...)` |\n| Untrusted Sources | Non-GitHub URLs |\n\n资料来源：[README.md:212-220](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md#L212-L220)\n\n### Validation Bypass\n\nThe `skipValidation` parameter on the `import_skill` tool allows administrators to bypass security checks when importing trusted skills. This parameter should be used cautiously and only for skills from verified sources.\n\n```json\n{\n \"tool\": \"import_skill\",\n \"arguments\": {\n \"identifier\": \"trusted/author/skill-name\",\n \"outputFormat\": \"power\",\n \"skipValidation\": false\n }\n}\n```\n\n资料来源：[examples/usage-examples.md:175-183](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md#L175-L183)\n\n## Error Handling Configuration\n\nThe error handling system provides structured error responses that enable programmatic error recovery and user-friendly error messages.\n\n### Error Response Format\n\nAll tools return errors in a consistent JSON format that includes the error message, affected tool name, and timestamp:\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:220-226](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md#L220-L226)\n\n### Error Categories\n\nThe error handling system classifies errors into distinct categories, each with specific recovery suggestions:\n\n| Error Type | Description | Recovery Actions |\n|------------|-------------|------------------|\n| Network Errors | Connection failures, timeouts | Check internet connection, verify GitHub availability |\n| Not Found Errors | Invalid skill identifiers | Verify skill name and repository |\n| Validation Errors | Security issues detected | Review security issues before proceeding |\n| Parsing Errors | Invalid YAML or markdown syntax | Check skill format and YAML syntax |\n\n资料来源：[examples/usage-examples.md:228-236](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md#L228-L236)\n\n### Custom Error Classes\n\nThe error handling infrastructure includes specialized error classes that provide contextual information for different failure scenarios. The `FileSystemError` class captures operation type, file path, and system-level error details for file-related failures.\n\n资料来源：[src/core/errors.ts:1-50](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/errors.ts#L1-L50)\n\nThe `ParsingError` class tracks parser type, line numbers, column positions, and code snippets for format-related failures, enabling precise identification of parsing issues in skill content.\n\n## Caching Configuration\n\nThe server implements in-memory caching for skills.sh directory results to optimize performance and reduce API load.\n\n### Cache Behavior\n\n| Setting | Value | Description |\n|---------|-------|-------------|\n| Cache Type | In-memory | Stored in process memory |\n| TTL | 1 hour | Time before automatic refresh |\n| Cache Target | search_skills results | Cached API responses |\n| Refresh | Automatic on expiry | Proactive cache refresh |\n\n资料来源：[README.md:224-228](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/README.md#L224-L228)\n\nThe caching strategy balances performance optimization with data freshness, automatically refreshing cached data when the TTL expires. This approach reduces API calls for frequently accessed data while ensuring users receive current information.\n\n## Typical Workflow Configuration\n\nThe repository documentation provides recommended workflow patterns for common deployment scenarios.\n\n### Discovery and Import Workflow\n\n```mermaid\ngraph LR\n A[Search Skills] --> B[Evaluate Results]\n B --> C{Find Skill?}\n C -->|Yes| D[List with Pagination]\n C -->|No| E[Refine Search]\n D --> F[Fetch Skill]\n F --> G[Validate Content]\n G --> H{Valid?}\n H -->|Yes| I[Convert Format]\n H -->|No| J[Report Issues]\n I --> K[Import Complete]\n```\n\nFor discovering skills, users should first search using the `search_skills` tool to find relevant skills by keyword. When multiple results exist, the `list_skills` tool provides paginated browsing of the full directory.\n\n资料来源：[examples/usage-examples.md:200-212](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md#L200-L212)\n\n### Validation Workflow\n\nWhen importing skills from unknown sources, a two-step validation approach is recommended:\n\n1. **Fetch the skill**: Retrieve the raw content using `fetch_skill`\n2. **Validate the content**: Use `validate_skill` to scan for security issues\n3. **Convert if safe**: Apply `convert_to_steering` or `convert_to_power` if validation passes\n\n```json\n{ \"tool\": \"fetch_skill\", \"arguments\": { \"identifier\": \"unknown/skill\" } }\n```\n\n```json\n{ \"tool\": \"validate_skill\", \"arguments\": { \"content\": \"...\", \"url\": \"...\" } }\n```\n\n资料来源：[examples/usage-examples.md:215-228](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md#L215-L228)\n\n### Complete Import Workflow\n\nFor streamlined operations, the `import_skill` tool combines all steps into a single atomic operation:\n\n1. **Search for trending skills**:\n ```json\n { \"tool\": \"get_leaderboard\", \"arguments\": { \"timeframe\": \"24h\", \"limit\": 20 } }\n ```\n\n2. **Import a trending skill**:\n ```json\n { \"tool\": \"import_skill\", \"arguments\": { \"identifier\": \"owner/skill-name\", \"outputFormat\": \"power\" } }\n ```\n\n资料来源：[examples/usage-examples.md:195-200](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/examples/usage-examples.md#L195-L200)\n\n## Project Structure Reference\n\nThe deployment configuration is organized within a structured project layout that separates core functionality, tool implementations, and utilities:\n\n```\nskill-loader-mcp-server/\n├── src/\n│ ├── core/ # Core functionality\n│ │ ├── conversion-engine.ts\n│ │ └── errors.ts\n│ ├── tools/ # MCP tool implementations\n│ ├── utils/ # Utility functions\n│ ├── index.ts # Main entry point\n│ └── cli.ts # CLI entry point\n├── examples/ # Usage examples\n├── dist/ # Compiled output\n└── tests/ # Test files\n```\n\n资料来源：[CONTRIBUTING.md:26-35](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CONTRIBUTING.md#L26-L35)\n\nThe `dist/` directory contains the compiled JavaScript output from the TypeScript source, which is the code actually executed during deployment. The `examples/` directory provides configuration examples and usage documentation that inform deployment procedures.\n\n## Version History\n\nThe deployment and configuration capabilities have evolved through the following version milestones:\n\n| Version | Date | Key Configuration Changes |\n|---------|------|---------------------------|\n| 1.1.0 | 2026-02-03 | Updated to `@modelcontextprotocol/sdk` v1.29, improved skills.sh API integration |\n| 1.0.0 | 2026-02-03 | Initial release with 9 MCP tools and comprehensive error handling |\n\n资料来源：[CHANGELOG.md:1-40](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/CHANGELOG.md#L1-L40)\n\n---\n\n\n\n## Error Handling\n\n### 相关页面\n\n相关主题：[Security Validation](#security-validation), [Deployment and Configuration](#deployment)\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- [src/core/security-validator.ts](https://github.com/goldzulu/skill-loader-mcp-server/blob/main/src/core/security-validator.ts)\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 \n\n# Error Handling\n\nThe Skill Loader MCP Server implements a comprehensive error handling system designed to provide consistent, informative, and actionable error feedback across all MCP tools. The system follows a hierarchical class structure that categorizes errors by their domain (validation, file system, network) and provides context-rich error messages with recovery suggestions.\n\n## Architecture Overview\n\nThe error handling system is built on a base `SkillLoaderError` class that extends the native `Error` class, adding structured metadata and context tracking. This design enables consistent error formatting across all tools while maintaining type safety and enabling programmatic error handling.\n\n```mermaid\ngraph TD\n A[Error Occurs] --> B{SkillLoaderError}\n B --> C[ValidationError]\n B --> D[FileSystemError]\n B --> E[NetworkError]\n C --> C1[security validation]\n C --> C2[format validation]\n D --> D1[read/write/delete/access]\n E --> E1[connection timeout]\n E --> E2[rate limiting]\n \n style A fill:#ff6b6b\n style B fill:#4ecdc4\n style C fill:#45b7d1\n style D fill:#96ceb4\n style E fill:#ffeaa7\n```\n\n## Error Class Hierarchy\n\n### Base Class: SkillLoaderError\n\nThe base error class provides common functionality for all error types:\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `message` | `string` | Human-readable error message |\n| `code` | `string` | Machine-readable error code |\n| `timestamp` | `Date` | When the error occurred |\n| `context` | `Record` | Additional error context |\n\n资料来源：[src/core/errors.ts:1-50]()\n\n### ValidationError\n\nThrown when skill content fails security or format validation checks:\n\n```typescript\nexport class ValidationError extends SkillLoaderError {\n public readonly validationType: 'security' | 'format';\n public readonly details?: string[];\n}\n```\n\n**Validation Types:**\n\n1. **Security Validation** - Triggered when dangerous patterns are detected:\n - Dangerous commands (`rm -rf`, `sudo`, `eval`, `exec`)\n - Suspicious file operations (`/etc/`, `/usr/`, `/bin/`)\n - Code injection patterns (`${...}`, `$(...)`)\n - Untrusted sources (non-GitHub URLs)\n\n2. **Format Validation** - Triggered when skill structure is invalid:\n - Malformed YAML frontmatter\n - Missing required fields\n - Invalid markdown structure\n\n资料来源：[src/core/errors.ts:60-120]()\n\n### FileSystemError\n\nHandles errors during file operations:\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `operation` | `'read' \\| 'write' \\| 'delete' \\| 'access'` | Type of file operation |\n| `filePath` | `string` | Target file path |\n| `systemError` | `string \\| undefined` | Raw system error message |\n\n**System Error Codes:**\n\n| Code | Meaning | Recovery Action |\n|------|---------|-----------------|\n| `EACCES` / `EPERM` | Permission denied | Check file permissions |\n| `ENOSPC` | Disk full | Free up disk space |\n| `ENOENT` | Path not found | Verify directory exists |\n| `EEXIST` | File exists | Use `--overwrite` flag |\n\n资料来源：[src/core/errors.ts:130-200]()\n\n### NetworkError\n\nHandles connectivity and API-related failures:\n\n```typescript\nexport class NetworkError extends SkillLoaderError {\n public readonly url: string;\n public readonly statusCode?: number;\n public readonly retryable: boolean;\n}\n```\n\n**Retry Behavior:**\n\n- `retryable: true` - Transient errors (timeout, 503, rate limit)\n- `retryable: false` - Permanent failures (404, 401, 403)\n\n资料来源：[src/core/errors.ts:200-280]()\n\n## Security Validation\n\nThe security validator analyzes skill content before import to prevent malicious code execution.\n\n### Security Issue Types\n\n```mermaid\ngraph LR\n A[Skill Content] --> B{Security Validator}\n B --> C[Dangerous Commands]\n B --> D[Suspicious Patterns]\n B --> E[Untrusted Sources]\n \n C --> C1[rm -rf, sudo, eval]\n D --> D1[Code injection, path traversal]\n E --> E1[Non-GitHub URLs]\n```\n\n### Severity Levels\n\n| Severity | Condition | Import Behavior |\n|----------|-----------|------------------|\n| `safe` | No issues found | Allowed |\n| `warning` | Suspicious patterns only | Allowed with notice |\n| `unsafe` | Dangerous commands OR untrusted sources | Blocked by default |\n\n资料来源：[src/core/security-validator.ts:1-50]()\n\n### Validation Response Format\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资料来源：[examples/usage-examples.md:30-40]()\n\n## Error Response Format\n\nAll MCP tools return errors in a standardized JSON format:\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### Common Error Scenarios\n\n| Scenario | Tool | Error Message Pattern |\n|----------|------|----------------------|\n| Network failure | `fetch_skill`, `list_skills` | \"Failed to connect to GitHub/skills.sh\" |\n| Not found | `fetch_skill` | \"Skill not found: {identifier}\" |\n| Validation failure | `validate_skill`, `import_skill` | \"Security validation failed\" |\n| Parsing error | `convert_to_*` | \"Failed to parse skill content\" |\n\n资料来源：[README.md:150-170]()\n\n## Error Recovery Suggestions\n\nThe error system provides actionable recovery guidance based on error type.\n\n### Validation Errors\n\n```\nSuggestions:\n- Review the skill content manually\n- Contact the skill author about security concerns\n- Use a different skill from a trusted source\n```\n\n### File System Errors\n\n```\nSuggestions:\n- Check file permissions (EACCES/EPERM)\n- Free up disk space (ENOSPC)\n- Verify the directory exists (ENOENT)\n- Use the --overwrite flag to replace existing files (EEXIST)\n```\n\n### Network Errors\n\n```\nSuggestions:\n- Check internet connection\n- Verify GitHub availability\n- Retry the request after a short delay\n- Use cached results if available\n```\n\n资料来源：[src/core/errors.ts:180-220]()\n\n## Error Flow Diagram\n\n```mermaid\nsequenceDiagram\n participant Tool as MCP Tool\n participant Engine as Conversion Engine\n participant Validator as Security Validator\n participant FS as File System\n \n Tool->>Engine: process(content)\n Engine->>Validator: validate(content)\n \n alt Validation Failed\n Validator-->>Tool: ValidationError\n Tool->>Tool: Return error with suggestions\n end\n \n Engine->>FS: write(output)\n \n alt File System Error\n FS-->>Tool: FileSystemError\n Tool->>Tool: Return error with path info\n end\n \n alt Success\n Validator-->>Engine: isValid: true\n Engine-->>Tool: Success result\n end\n```\n\n## Best Practices\n\n1. **Always validate before import** - Use `validate_skill` to check content safety\n2. **Handle errors gracefully** - Check for error responses before processing results\n3. **Use try-catch blocks** - Wrap tool calls to handle unexpected errors\n4. **Check severity levels** - Distinguish between warnings and blocking errors\n5. **Preserve error context** - Log error timestamps and tool names for debugging\n\n资料来源：[examples/usage-examples.md:180-200]()\n\n## Configuration\n\nError handling behavior can be influenced through these configuration options:\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `skipValidation` | Bypass security checks during import | `false` |\n| `timeout` | Request timeout in milliseconds | Platform-specific |\n| `maxRetries` | Maximum retry attempts for network errors | Configurable |\n\n资料来源：[README.md:140-150]()\n\n---\n\n---\n\n## Doramagic Pitfall Log\n\nProject: goldzulu/skill-loader-mcp-server\n\nSummary: Found 9 potential pitfall items; 0 are high/blocking. Highest priority: configuration - 可能修改宿主 AI 配置.\n\n## 1. configuration · 可能修改宿主 AI 配置\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- User impact: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Suggested check: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Guardrail action: 涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- Evidence: capability.host_targets | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | host_targets=mcp_host, claude\n\n## 2. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\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\n## 3. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | last_activity_observed missing\n\n## 4. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | no_demo; severity=medium\n\n## 5. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | no_demo; severity=medium\n\n## 6. security_permissions · 来源证据：v1.0.0 - Initial Release\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.0.0 - Initial Release\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_fb2ea148b03e4fb5993d3b2db08b43f6 | https://github.com/goldzulu/skill-loader-mcp-server/releases/tag/v1.0.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 7. security_permissions · 来源证据：v1.1.0 — skills.sh API migration & Power format update\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.1.0 — skills.sh API migration & Power format update\n- User impact: 可能影响升级、迁移或版本选择。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_78c48e3f6caa41a9bf94d3dba01baf0c | https://github.com/goldzulu/skill-loader-mcp-server/releases/tag/v1.1.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | issue_or_pr_quality=unknown\n\n## 9. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: evidence.maintainer_signals | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki output with a Doramagic pitfall appendix.",
"title": "Human Manual"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log\n\nProject: goldzulu/skill-loader-mcp-server\n\nSummary: Found 9 potential pitfall items; 0 are high/blocking. Highest priority: configuration - 可能修改宿主 AI 配置.\n\n## 1. configuration · 可能修改宿主 AI 配置\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- User impact: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Suggested check: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Guardrail action: 涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- Evidence: capability.host_targets | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | host_targets=mcp_host, claude\n\n## 2. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\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\n## 3. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | last_activity_observed missing\n\n## 4. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | no_demo; severity=medium\n\n## 5. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | no_demo; severity=medium\n\n## 6. security_permissions · 来源证据：v1.0.0 - Initial Release\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.0.0 - Initial Release\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_fb2ea148b03e4fb5993d3b2db08b43f6 | https://github.com/goldzulu/skill-loader-mcp-server/releases/tag/v1.0.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 7. security_permissions · 来源证据：v1.1.0 — skills.sh API migration & Power format update\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.1.0 — skills.sh API migration & Power format update\n- User impact: 可能影响升级、迁移或版本选择。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_78c48e3f6caa41a9bf94d3dba01baf0c | https://github.com/goldzulu/skill-loader-mcp-server/releases/tag/v1.1.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | issue_or_pr_quality=unknown\n\n## 9. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: evidence.maintainer_signals | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | release_recency=unknown\n",
"summary": "Identity, installation, configuration, runtime, and safety pitfalls before user trial.",
"title": "Pitfall Log"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# skill-loader-mcp-server - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for goldzulu/skill-loader-mcp-server.\n\nProject:\n- Name: skill-loader-mcp-server\n- Repository: https://github.com/goldzulu/skill-loader-mcp-server\n- Summary: MCP server for discovering, fetching, validating, and converting Claude skills from skills.sh and GitHub repositories\n- Host target: mcp_host, claude\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: MCP server for discovering, fetching, validating, and converting Claude skills from skills.sh and GitHub repositories\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: MCP server for discovering, fetching, validating, and converting Claude skills from skills.sh and GitHub repositories\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. getting-started: Getting Started. Produce one small intermediate artifact and wait for confirmation.\n2. project-structure: Project Structure. Produce one small intermediate artifact and wait for confirmation.\n3. mcp-server-architecture: MCP Server Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. core-modules: Core Modules. Produce one small intermediate artifact and wait for confirmation.\n5. mcp-tools-reference: MCP Tools Reference. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\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/cli.ts\n- tsconfig.json\n- src/core/conversion-engine.ts\n- src/core/security-validator.ts\n- src/core/skill-fetcher.ts\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start\n\nProject: goldzulu/skill-loader-mcp-server\n\n## Official Entry Points\n\n### Node.js / npm · 官方安装入口\n\n```bash\nnpm install -g @goldzulu/skill-loader-mcp-server\n```\n\nSource：https://github.com/goldzulu/skill-loader-mcp-server#readme\n\n## Sources\n\n- repo: https://github.com/goldzulu/skill-loader-mcp-server\n- docs: https://github.com/goldzulu/skill-loader-mcp-server#readme\n",
"summary": "Entry points extracted from official README or installation documentation.",
"title": "Quick Start"
}
},
"validation_id": "dval_8ce4d558491d446bb0dcf2ba3b02b025"
}