{
"canonical_name": "sator-imaging/suggest-skills",
"compilation_id": "pack_80fde0fc8a0d4fe5acd079c947338725",
"created_at": "2026-05-13T14:07:04.490733+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 `npx suggest-skills` 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": "npx suggest-skills",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_a0eb1f63544f42a2a0a89bc287e7ee3f"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_70562eb52600a98edf28d420489a29ce",
"canonical_name": "sator-imaging/suggest-skills",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/sator-imaging/suggest-skills",
"slug": "suggest-skills",
"source_packet_id": "phit_c784c36be0b74ce5922154e5e2e7a722",
"source_validation_id": "dval_1afe90d28f0b42ecb725d94a085efbbf"
},
"merchandising": {
"best_for": "需要工具连接与集成能力，并使用 mcp_host的用户",
"github_forks": 0,
"github_stars": 0,
"one_liner_en": "MCP server that suggests repository-specific AI agent skills.",
"one_liner_zh": "MCP server that suggests repository-specific AI agent skills.",
"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": "suggest-skills",
"title_zh": "suggest-skills 能力包",
"visible_tags": [
{
"label_en": "Browser Agents",
"label_zh": "浏览器 Agent",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-browser-agents",
"type": "product_domain"
},
{
"label_en": "Web Task Automation",
"label_zh": "网页任务自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-web-task-automation",
"type": "user_job"
},
{
"label_en": "Workflow Automation",
"label_zh": "流程自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-workflow-automation",
"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": "Local-first",
"label_zh": "本地优先",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-local-first",
"type": "selection_signal"
}
]
},
"packet_id": "phit_c784c36be0b74ce5922154e5e2e7a722",
"page_model": {
"artifacts": {
"artifact_slug": "suggest-skills",
"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": "npx suggest-skills",
"label": "Node.js / npx · 官方安装入口",
"source": "https://github.com/sator-imaging/suggest-skills#readme",
"verified": true
}
],
"display_tags": [
"浏览器 Agent",
"网页任务自动化",
"流程自动化",
"节点式流程编排",
"本地优先"
],
"eyebrow": "工具连接与集成",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要工具连接与集成能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "MCP server that suggests repository-specific AI agent skills."
},
{
"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:1220908449 | https://github.com/sator-imaging/suggest-skills | 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:1220908449 | https://github.com/sator-imaging/suggest-skills | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.0.1",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_e40d7a86377b444f8d3eca5e8ec2b1a4 | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.0.1 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.0.1",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.1.1",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_d9b5403807304a33aaf39f02f80d14be | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.1.1 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.1.1",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.2.1",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_452c2fc3dc7d4409a8e1a4ae5419599f | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.2.1 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.2.1",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.3.1",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_7cf71c15b4c64e7297db646b5300ba29 | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.3.1 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.3.1",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.0.2",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_2150c52f85274793bfce6c1d64d24f66 | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.0.2 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.0.2",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.0.3",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_ac612b4c6cd44d2194d9df8b4c026220 | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.0.3 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.0.3",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v2.0.0",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_bc9655e0f7c54b22a783ef99c7841b5e | https://github.com/sator-imaging/suggest-skills/releases/tag/v2.0.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v2.0.0",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | 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:1220908449 | https://github.com/sator-imaging/suggest-skills | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "No sandbox install has been executed yet; downstream must verify before user use.",
"category": "安全/权限坑",
"evidence": [
"risks.safety_notes | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | No sandbox install has been executed yet; downstream must verify before user use."
],
"severity": "medium",
"suggested_check": "转成明确权限清单和安全审查提示。",
"title": "存在安全注意事项",
"user_impact": "用户安装前需要知道权限边界和敏感操作。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | 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:1220908449 | https://github.com/sator-imaging/suggest-skills | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 15 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 3,
"forks": 0,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 0
},
"source_url": "https://github.com/sator-imaging/suggest-skills",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "MCP server that suggests repository-specific AI agent skills.",
"title": "suggest-skills 能力包",
"trial_prompt": "# suggest-skills - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 suggest-skills 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client / claude\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: MCP server that suggests repository-specific AI agent skills. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. project-introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. key-features：核心特性。围绕“核心特性”模拟一次用户任务，不展示安装或运行结果。\n3. system-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. mcp-tools：MCP 工具。围绕“MCP 工具”模拟一次用户任务，不展示安装或运行结果。\n5. transport-modes：传输模式。围绕“传输模式”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. project-introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. key-features\n输入：用户提供的“核心特性”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. system-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. mcp-tools\n输入：用户提供的“MCP 工具”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. transport-modes\n输入：用户提供的“传输模式”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / project-introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / key-features：Step 2 必须围绕“核心特性”形成一个小中间产物，并等待用户确认。\n- Step 3 / system-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / mcp-tools：Step 4 必须围绕“MCP 工具”形成一个小中间产物，并等待用户确认。\n- Step 5 / transport-modes：Step 5 必须围绕“传输模式”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/sator-imaging/suggest-skills\n- https://github.com/sator-imaging/suggest-skills#readme\n- README.md\n- package.json\n- src/index.ts\n- src/suggest.ts\n- src/download.ts\n- src/config.ts\n- src/core.ts\n- src/stdio.ts\n- src/http.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 suggest-skills 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_release: v2.0.0（https://github.com/sator-imaging/suggest-skills/releases/tag/v2.0.0）；github/github_release: v1.3.1（https://github.com/sator-imaging/suggest-skills/releases/tag/v1.3.1）；github/github_release: v1.3.0（https://github.com/sator-imaging/suggest-skills/releases/tag/v1.3.0）；github/github_release: v1.2.1（https://github.com/sator-imaging/suggest-skills/releases/tag/v1.2.1）；github/github_release: v1.1.1（https://github.com/sator-imaging/suggest-skills/releases/tag/v1.1.1）；github/github_release: v1.0.3（https://github.com/sator-imaging/suggest-skills/releases/tag/v1.0.3）；github/github_release: v1.0.2（https://github.com/sator-imaging/suggest-skills/releases/tag/v1.0.2）；github/github_release: v1.0.1（https://github.com/sator-imaging/suggest-skills/releases/tag/v1.0.1）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_release",
"source": "github",
"title": "v2.0.0",
"url": "https://github.com/sator-imaging/suggest-skills/releases/tag/v2.0.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.3.1",
"url": "https://github.com/sator-imaging/suggest-skills/releases/tag/v1.3.1"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.3.0",
"url": "https://github.com/sator-imaging/suggest-skills/releases/tag/v1.3.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.2.1",
"url": "https://github.com/sator-imaging/suggest-skills/releases/tag/v1.2.1"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.1.1",
"url": "https://github.com/sator-imaging/suggest-skills/releases/tag/v1.1.1"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.0.3",
"url": "https://github.com/sator-imaging/suggest-skills/releases/tag/v1.0.3"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.0.2",
"url": "https://github.com/sator-imaging/suggest-skills/releases/tag/v1.0.2"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.0.1",
"url": "https://github.com/sator-imaging/suggest-skills/releases/tag/v1.0.1"
}
],
"status": "已收录 8 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "工具连接与集成",
"desc": "MCP server that suggests repository-specific AI agent skills.",
"effort": "安装已验证",
"forks": 0,
"icon": "link",
"name": "suggest-skills 能力包",
"risk": "可发布",
"slug": "suggest-skills",
"stars": 0,
"tags": [
"浏览器 Agent",
"网页任务自动化",
"流程自动化",
"节点式流程编排",
"本地优先"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/sator-imaging/suggest-skills 项目说明书\n\n生成时间：2026-05-13 13:58:02 UTC\n\n## 目录\n\n- [项目介绍](#project-introduction)\n- [核心特性](#key-features)\n- [系统架构](#system-architecture)\n- [项目结构](#project-structure)\n- [MCP 工具](#mcp-tools)\n- [传输模式](#transport-modes)\n- [Generate 命令](#generate-command)\n- [Server 命令](#server-command)\n- [配置指南](#configuration-guide)\n- [部署指南](#deployment-guide)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[核心特性](#key-features), [系统架构](#system-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n- [package.json](https://github.com/sator-imaging/suggest-skills/blob/main/package.json)\n- [src/index.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/index.ts)\n- [src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)\n- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)\n- [src/cmd_generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/cmd_generate.ts)\n \n\n# 项目介绍\n\n`suggest-skills` 是一个用于管理和发现 AI Agent 技能（Skills）的工具项目。该项目通过 MCP（Model Context Protocol）协议提供技能建议功能，支持从 GitHub 仓库自动扫描、本地安装以及远程技能清单管理。\n\n## 项目概述\n\n`suggest-skills` 的核心功能是帮助 AI Agent 智能地发现和推荐可用的技能扩展包。用户可以通过配置技能清单（manifest）URL，系统会自动扫描本地已安装的技能，并与远程清单进行对比，最终呈现可用的技能建议列表。\n\n资料来源：[README.md]()\n\n### 主要特性\n\n| 特性 | 描述 |\n|------|------|\n| MCP 协议支持 | 提供符合 MCP 标准的工具接口 |\n| 多模式运行 | 支持 stdio 模式和 HTTP 服务器模式 |\n| GitHub 集成 | 可从 GitHub 仓库自动发现和下载技能 |\n| 清单生成 | 支持从 GitHub 目录递归扫描生成技能清单 |\n| 多格式配置 | 支持 JSON、逗号分隔、换行分隔的环境变量配置 |\n\n资料来源：[README.md]()\n\n## 技术栈\n\n项目采用现代 TypeScript 技术栈构建，主要依赖包括：\n\n```json\n{\n \"dependencies\": {\n \"@modelcontextprotocol/sdk\": \"^1.0.0\",\n \"zod\": \"^3.23.8\"\n },\n \"devDependencies\": {\n \"bun\": \"latest\"\n }\n}\n```\n\n| 技术组件 | 用途 |\n|----------|------|\n| Bun | JavaScript 运行时和打包工具 |\n| TypeScript | 类型安全的开发语言 |\n| @modelcontextprotocol/sdk | MCP 协议 SDK 实现 |\n| Zod | 运行时配置验证 |\n\n资料来源：[package.json]()\n\n## 架构设计\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[Config 配置] --> B[MCP 工具注册]\n B --> C[stdio 传输模式]\n B --> D[HTTP 传输模式]\n \n E[CLI generate 命令] --> F[GitHub 目录扫描]\n F --> G[生成 manifest markdown]\n \n H[GitHub URL 规范化] --> I[文件夹下载]\n I --> F\n```\n\n项目架构分为两个主要入口：\n\n1. **MCP 服务器模式**：通过 `Config` 配置驱动的 MCP 工具服务\n2. **CLI 生成模式**：命令行工具用于扫描 GitHub 仓库生成技能清单\n\n资料来源：[README.md]()\n\n### 模块职责\n\n| 模块 | 文件路径 | 职责 |\n|------|----------|------|\n| 配置模块 | `src/config.ts` | 环境变量验证与解析 |\n| MCP 工具 | `src/index.ts` | 工具注册与请求处理 |\n| 下载功能 | `src/download.ts` | GitHub 仓库文件下载 |\n| 生成功能 | `src/generate.ts` | 技能清单生成逻辑 |\n| CLI 命令 | `src/cmd_generate.ts` | 命令行参数解析与输出 |\n\n资料来源：[src/download.ts](), [src/generate.ts](), [src/cmd_generate.ts]()\n\n## MCP 工具接口\n\n### suggest_skills\n\n主动建议可用技能的主工具。\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| manifestUrl | string | 否 | 覆盖默认配置的清单 URL |\n\n返回说明：生成一条指令负载，指导 Agent 如何获取可用技能列表、对比本地与远程能力、以及呈现建议。\n\n资料来源：[README.md]()\n\n### fetch_manifest\n\n获取指定清单文件内容。\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| manifestUrl | string | 是 | 技能清单的 GitHub URL |\n\n返回内容：清单文件的完整文本内容。\n\n资料来源：[README.md]()\n\n### download_skill\n\n下载指定 GitHub 文件夹中的所有文件。\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| url | string | 是 | GitHub 文件夹 URL |\n\n返回内容：文件夹中每个文件的路径、UTF-8 文本内容。符号链接会被解析并递归下载。\n\n资料来源：[README.md](), [src/download.ts]()\n\n## 下载流程实现\n\n### GitHub API 调用\n\n项目使用 GitHub Contents API 和 Git Trees API 来获取仓库内容：\n\n```mermaid\nsequenceDiagram\n 参与者 A as 用户请求\n 参与者 G as GitHub API\n 参与者 L as 本地处理\n \n A->>G: 请求目录内容\n G-->>L: 返回 tree 结构\n L->>L: 解析路径并过滤\n L->>G: 获取文件下载 URL\n G-->>A: 返回文件内容\n```\n\n资料来源：[src/download.ts]()\n\n### 路径解析逻辑\n\n下载模块的核心路径处理逻辑位于 `buildContentsApiUrl` 和 `buildTreeApiUrl` 函数中：\n\n```typescript\nfunction buildContentsApiUrl(location: GithubDirectoryLocation): string {\n const pathSuffix = location.path\n .split(\"/\")\n .filter(Boolean)\n .map((part) => encodeURIComponent(part))\n .join(\"/\");\n // 构建 API 路径并添加 ref 参数\n}\n```\n\n关键处理步骤：\n1. 过滤空路径段\n2. 对每个路径段进行 URL 编码\n3. 拼接为标准 GitHub API 路径\n4. 设置 `ref` 参数指定分支/提交\n\n资料来源：[src/download.ts]()\n\n## 清单生成功能\n\n### generate 命令工作流\n\n```mermaid\ngraph LR\n A[GitHub URL] --> B[目录扫描]\n B --> C[识别 SKILL.md]\n B --> D[识别 DESIGN.md]\n B --> E[收集资产文件]\n \n C --> F[生成 skills.md]\n D --> G[生成 designs.md]\n E --> F\n E --> G\n```\n\n生成模式下，系统会：\n1. 递归扫描 GitHub 目录结构\n2. 识别包含 `SKILL.md` 的技能目录\n3. 识别包含 `DESIGN.md` 的设计目录\n4. 收集目录中的其他资产文件\n5. 生成格式化的 Markdown 清单文件\n\n资料来源：[src/generate.ts](), [README.md]()\n\n### 生成选项\n\n| 选项 | 简写 | 描述 |\n|------|------|------|\n| --recursive, -r | 递归扫描子目录 | |\n| --output, -o | 指定输出目录 | 默认输出到 `.agents/skills` |\n\n资料来源：[README.md]()\n\n### 输出文件类型\n\n| 文件类型 | 内容 | 触发条件 |\n|----------|------|----------|\n| `..skills.md` | 技能条目列表 | 目录中包含 `SKILL.md` |\n| `..designs.md` | 设计条目列表 | 目录中包含 `DESIGN.md` |\n| `..agents.md` | Agent 条目列表 | 平面化顶级 markdown 文件 |\n\n资料来源：[README.md]()\n\n## 配置管理\n\n### 环境变量配置\n\n| 变量名 | 必需 | 描述 |\n|--------|------|------|\n| `GITHUB_PAT` | 否 | GitHub 个人访问令牌，用于认证请求 |\n| `SUGGEST_SKILLS_MANIFEST_URLS` | 是 | 技能清单 URL 列表 |\n\n清单 URL 支持三种格式：\n\n| 格式 | 示例 |\n|------|------|\n| JSON 数组 | `[\"https://example.com/manifest.md\"]` |\n| 逗号分隔 | `https://a.com/1.md,https://b.com/2.md` |\n| 换行分隔 | `https://a.com/1.md\\nhttps://b.com/2.md` |\n\n资料来源：[README.md]()\n\n### 启动模式\n\n#### stdio 模式\n\n标准输入输出模式，适合本地集成：\n\n```bash\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://some/skill-manifest.md\"]' \\\n npx suggest-skills\n```\n\n#### HTTP 服务器模式\n\n提供 HTTP API 端点，适合远程访问：\n\n```bash\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://some/skill-manifest.md\"]' \\\n npx suggest-skills server --port 3100\n```\n\n| 端点 | 路径 | 描述 |\n|------|------|------|\n| MCP 服务 | `/mcp` | 主要的 MCP 协议端点 |\n| 健康检查 | `/health` | 服务健康状态检查 |\n\n资料来源：[README.md]()\n\n## 代码规范\n\n项目遵循以下编码标准：\n\n| 规范 | 说明 |\n|------|------|\n| 模块化设计 | 小而专注的模块，按运行时关注点拆分文件 |\n| 配置验证 | 通过 `ConfigError` 进行显式配置验证 |\n| 类型安全 | 使用 Zod 进行运行时类型验证 |\n| 结构化输出 | MCP 工具使用类型化 Schema 和结构化返回 |\n| 传输层抽象 | 最小化传输层封装，围绕共享服务器创建 |\n\n资料来源：[README.md]()\n\n## 使用示例\n\n### 快速开始\n\n1. **配置环境变量**：\n ```bash\n export SUGGEST_SKILLS_MANIFEST_URLS='[\"https://raw.githubusercontent.com/anthropics/skills/main/skills/skills.md\"]'\n ```\n\n2. **运行 MCP 服务器**：\n ```bash\n npx suggest-skills server --port 3100\n ```\n\n3. **生成技能清单**：\n ```bash\n npx suggest-skills generate \\\n https://github.com/OWNER/REPO/tree/main/skills\n ```\n\n### 递归扫描示例\n\n生成包含子目录的完整清单：\n\n```bash\nnpx suggest-skills generate \\\n --recursive \\\n https://github.com/OWNER/REPO/tree/main/skills\n```\n\n这会生成以下文件：\n- `...skills.md`\n- `...designs.md`\n\n资料来源：[README.md]()\n\n## 相关资源\n\n| 资源 | 链接 |\n|------|------|\n| 官方技能库 | [official/skills](./official/skills) |\n| 社区技能库 | [community/skills](./community/skills) |\n| MCP 协议文档 | [@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk) |\n\n---\n\n\n\n## 核心特性\n\n### 相关页面\n\n相关主题：[项目介绍](#project-introduction), [MCP 工具](#mcp-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n- [src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)\n- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)\n- [官方 Skills 清单](https://github.com/anthropics/skills)\n- [OpenAI Skills 清单](https://github.com/openai/skills)\n \n\n# 核心特性\n\n`suggest-skills` 是一个基于 MCP（Model Context Protocol）的技能推荐与管理系统，旨在帮助 AI 代理（Agent）发现、安装和管理来自各类 GitHub 仓库的技能扩展包。本项目采用现代化的技术栈构建，支持灵活的配置方式和多种运行模式。\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n subgraph 配置层\n A[环境变量配置] --> B[Config 验证模块]\n B --> C[ConfigError 异常处理]\n end\n \n subgraph 核心功能层\n D[MCP 工具注册] --> E[suggest_skills]\n D --> F[fetch_manifest]\n D --> G[download_skill]\n end\n \n subgraph 传输层\n H[stdio 传输] \n I[HTTP 传输]\n end\n \n subgraph GitHub 交互层\n J[目录扫描] --> K[SKILL.md 发现]\n J --> L[DESIGN.md 发现]\n J --> M[manifest 生成]\n end\n \n B --> D\n E --> J\n F --> M\n G --> J\n D --> H\n D --> I\n```\n\n### 技术栈\n\n| 技术组件 | 用途说明 |\n|---------|---------|\n| Bun | JavaScript 运行时与打包工具 |\n| TypeScript | 类型安全与开发体验 |\n| @modelcontextprotocol/sdk | MCP 协议实现 |\n| Zod | 配置验证与类型推断 |\n\n资料来源：[README.md:技术栈]()\n\n## MCP 工具集\n\n项目提供三个核心 MCP 工具，供 AI 代理调用以实现技能管理功能。\n\n### 工具功能总览\n\n| 工具名称 | 功能描述 | 输入参数 |\n|---------|---------|---------|\n| `suggest_skills` | 生成技能推荐指令负载 | `manifestUrl`（可选） |\n| `fetch_manifest` | 获取技能清单文本内容 | `manifestUrl` |\n| `download_skill` | 下载指定 GitHub 文件夹的所有文件 | GitHub 文件夹 URL |\n\n### suggest_skills 工具\n\n该工具是系统的核心入口点，负责生成指令负载，指导 AI 代理完成以下任务：\n\n- 从配置的 manifest 文件获取可用技能列表\n- 扫描本地已安装的技能\n- 对比远程与本地能力差异\n- 在用户请求前不执行任何安装操作\n\n```mermaid\ngraph LR\n A[调用 suggest_skills] --> B{是否指定 manifestUrl?}\n B -->|是| C[使用指定 URL]\n B -->|否| D[使用环境变量配置的默认 URL]\n C --> E[生成指令负载]\n D --> E\n E --> F[返回技能发现/推荐指导]\n```\n\n### fetch_manifest 工具\n\n用于获取远程技能清单的原始文本内容，支持自定义技能仓库的 manifest 文件获取。\n\n### download_skill 工具\n\n该工具实现 GitHub 目录的递归下载功能，支持以下特性：\n\n- 接收标准 GitHub 树形 URL 格式：`https://github.com///tree/[/`\n- 返回文件夹内所有文件及其相对路径\n- 自动处理文件 symlink（当 GitHub 提供 `download_url` 时）\n- 解析仓库相对目录 symlink 并递归下载\n\n资料来源：[README.md:MCP Tools]()\n\n## 技能清单生成\n\n### 生成工作流程\n\n```mermaid\ngraph TD\n A[CLI: npx suggest-skills generate] --> B[接收 GitHub URL]\n B --> C{是否指定 --recursive?}\n C -->|是| D[递归扫描目录树]\n C -->|否| E[扫描当前层级]\n D --> F[发现 SKILL.md 文件]\n E --> F\n F --> G[发现 DESIGN.md 文件]\n G --> H[汇总同目录资产文件]\n H --> I[生成清单文件]\n \n I --> J[.skills.md]\n I --> K[.designs.md]\n I --> L[.agents.md]\n```\n\n### 生成规则\n\n| 规则类型 | 说明 |\n|---------|------|\n| 目录发现 | 使用递归树形列表 API 进行 GitHub 目录扫描 |\n| 文件识别 | `SKILL.md` 和 `DESIGN.md` 在技能目录中识别 |\n| 资产打包 | 同目录及嵌套子目录中的其他文件视为资产 |\n| Symlink 处理 | 发现时不作特殊处理，可能出现在资产列表中 |\n| 空输出跳过 | 空生成结果不写入文件，不显示覆盖提示 |\n\n### 输出文件类型\n\n| 文件后缀 | 内容来源 | 文件格式 |\n|---------|---------|---------|\n| `.[.].skills.md` | 包含 `SKILL.md` 的目录 | Markdown 表格 |\n| `.[.].designs.md` | 包含 `DESIGN.md` 的目录 | Markdown 表格 |\n| `.[.].agents.md` | 平面顶级 Markdown 文件 | Name + Description 列 |\n\n资料来源：[README.md:Generate a Manifest]()\n资料来源：[src/generate.ts:SKILL.md/DESIGN.md 发现逻辑]()\n\n## 配置管理\n\n### 环境变量配置\n\n| 环境变量 | 必填 | 用途 |\n|---------|-----|------|\n| `GITHUB_PAT` | 否 | 访问 GitHub API 的个人访问令牌 |\n| `SUGGEST_SKILLS_MANIFEST_URLS` | **是** | 技能清单 URL 列表 |\n\n`SUGGEST_SKILLS_MANIFEST_URLS` 支持三种格式：\n- JSON 数组：`[\"url1\", \"url2\"]`\n- 逗号分隔字符串：`url1,url2`\n- 换行分隔字符串：`url1\\nurl2`\n\n> **注意**：GitHub `blob` URL 会自动转换为 `raw.githubusercontent.com` URL。\n\n资料来源：[README.md:Environment Variables]()\n\n### 配置验证\n\n系统通过 `ConfigError` 异常类实现显式配置验证，确保：\n\n- 至少配置一个 manifest URL\n- URL 格式正确\n- 环境变量解析成功\n\n```mermaid\nstateDiagram-v2\n [*] --> 加载环境变量\n 加载环境变量 --> 验证配置\n 验证配置 --> 配置有效: 通过\n 验证配置 --> ConfigError: 失败\n 配置有效 --> MCP 工具注册\n ConfigError --> [*]\n```\n\n## 运行模式\n\n### stdio 模式\n\n适用于本地集成和管道通信场景：\n\n```bash\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://some/skill-manifest.md\"]' \\\n npx suggest-skills\n```\n\n### HTTP 模式\n\n适用于分布式部署和远程服务场景：\n\n```bash\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://some/skill-manifest.md\"]' \\\n npx suggest-skills server --port 3100\n```\n\n| 端点 | 路径 | 用途 |\n|-----|------|------|\n| MCP 端点 | `http://localhost:3100/mcp` | MCP 协议通信 |\n| 健康检查 | `http://localhost:3100/health` | 服务状态监控 |\n\n资料来源：[README.md:Run in stdio Mode]()\n资料来源：[README.md:Run in HTTP Mode]()\n\n## GitHub API 交互\n\n### API 端点构建\n\n项目封装了多个 GitHub API URL 构建函数：\n\n| 函数 | 功能 |\n|-----|------|\n| `buildContentsApiUrl` | 构建 Contents API URL |\n| `buildTreeApiUrl` | 构建 Tree API URL（支持递归） |\n| `buildGithubRawUrl` | 构建 Raw 文件访问 URL |\n\n### 目录扫描数据结构\n\n```typescript\ninterface ContentEntry {\n path: string; // 文件相对路径\n download_url: string | null; // 下载 URL（文件）或 null（目录）\n type: \"file\" | \"dir\"; // 条目类型\n}\n```\n\n### 路径解析规则\n\n1. 解析 GitHub 目录位置信息（owner、repo、ref、path）\n2. 将相对路径与基础路径拼接\n3. 去除前导斜杠确保路径一致性\n4. 递归处理树形结构\n\n```mermaid\ngraph LR\n A[GitHub Tree API 响应] --> B[遍历 entries]\n B --> C{entry.type === 'tree'?}\n C -->|是| D[创建 dir 条目]\n C -->|否| E[entry.type === 'blob'?]\n E -->|是| F[构建 download_url]\n F --> G[创建 file 条目]\n E -->|否| H[跳过]\n D --> I[返回 ContentEntry 数组]\n G --> I\n```\n\n资料来源：[src/download.ts:ContentEntry 类型定义]()\n资料来源：[src/download.ts:buildContentsApiUrl 函数]()\n\n## CLI 选项\n\n| 选项 | 全写形式 | 说明 |\n|-----|---------|------|\n| `-o ` | `--output ` | 技能安装输出目录 |\n| `generate [-r\\|--recursive]` | 生成模式 | 从 GitHub 技能目录生成清单 |\n| `server --port ` | 服务模式 | 启动 HTTP 服务器 |\n\n默认安装目录：`.agents/skills`\n\n## 代码组织规范\n\n项目遵循以下实现模式：\n\n| 规范类别 | 说明 |\n|---------|------|\n| 模块划分 | 小而专注的模块，按运行时关注点拆分 |\n| 配置验证 | 通过 ConfigError 实现显式验证 |\n| 类型安全 | 使用 Zod 进行工具 schema 验证和结构化输出 |\n| 传输封装 | 最小化传输层包装，围绕共享服务器创建 |\n| 测试策略 | 聚焦可观察行为而非实现细节 |\n\n资料来源：[README.md:Coding Standards]()\n\n## 与官方技能仓库集成\n\n项目内置支持从主流技能仓库生成清单和下载技能：\n\n### Anthropic 官方技能\n\n包含 40+ 个预构建技能，覆盖文档协作、Word 文档处理、PDF 操作、Figma 设计集成、Web 应用测试等领域。\n\n### OpenAI 精选技能\n\n包含 Notion 集成、Linear 项目管理、PDF 处理、Jupyter 笔记本、Figma 协作、Playwright 自动化测试、Vercel/Netlify 部署等企业级工具。\n\n### 社区技能\n\n汇集来自 ComposioHQ 等社区的精选技能，包括主题工厂、Twitter 算法优化、YouTube 下载器等实用工具。\n\n资料来源：[官方 Skills 清单]()\n资料来源：[OpenAI Skills 清单]()\n资料来源：[社区 Skills 清单]()\n\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目结构](#project-structure), [传输模式](#transport-modes)\n\n]\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/index.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/index.ts)\n- [src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)\n- [src/core.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/core.ts)\n- [src/stdio.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/stdio.ts)\n- [src/http.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/http.ts)\n- [src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)\n- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)\n- [src/cmd_generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/cmd_generate.ts)\n \n\n# 系统架构\n\n## 概述\n\n`suggest-skills` 是一个基于 Model Context Protocol (MCP) 的技能推荐与管理工具，旨在帮助 AI Agent 智能地发现、推荐和安装来自各种来源的技能扩展包。 资料来源：[README.md]()\n\n该项目的核心价值在于：**将分散在不同 GitHub 仓库中的技能清单（Manifest）聚合起来，为 Agent 提供统一的技能发现和安装接口**，而无需预先安装任何内容。\n\n## 技术栈\n\n| 技术 | 用途 |\n|------|------|\n| Bun | JavaScript/TypeScript 运行时与打包工具 |\n| TypeScript | 类型安全的开发语言 |\n| @modelcontextprotocol/sdk | MCP 协议实现与工具注册框架 |\n| Zod | 运行时配置验证 |\n\n资料来源：[README.md]()\n\n---\n\n## 整体架构\n\n`suggest-skills` 采用**分层模块化设计**，核心架构遵循以下数据流：\n\n```mermaid\ngraph TD\n A[配置文件
Config] --> B[MCP 工具注册
Tool Registration]\n B --> C{传输层选择}\n C --> D[stdio 模式
标准输入输出]\n C --> E[HTTP 模式
HTTP 服务器]\n \n F[CLI 命令] --> G[GitHub 目录扫描
目录树 API]\n G --> H[Manifest 生成器]\n H --> I[Markdown 清单文件]\n \n J[MCP 客户端] --> K[suggest_skills 工具]\n J --> L[fetch_manifest 工具]\n J --> M[download_skill 工具]\n```\n\n资料来源：[README.md](), [src/index.ts](), [src/stdio.ts](), [src/http.ts]()\n\n---\n\n## 核心模块解析\n\n### 1. 配置层 (Config)\n\n配置层负责加载和验证所有运行时参数，支持两种配置方式：\n\n| 配置方式 | 说明 |\n|----------|------|\n| 环境变量 | `SUGGEST_SKILLS_MANIFEST_URLS`、`GITHUB_PAT` |\n| CLI 参数 | `-o`、`--output`、`--port` 等 |\n\n**关键配置项：**\n\n| 变量名 | 必需 | 说明 |\n|--------|------|------|\n| `SUGGEST_SKILLS_MANIFEST_URLS` | 是 | Manifest URL 列表，支持 JSON 数组、逗号分隔、换行分隔 |\n| `GITHUB_PAT` | 否 | GitHub 个人访问令牌，用于认证请求 |\n| 输出目录 | 否 | 默认为 `.agents/skills` |\n\n支持的 URL 格式：\n- 普通 GitHub URL\n- GitHub `blob` URL（自动转换为 `raw.githubusercontent.com`）\n\n资料来源：[README.md](), [src/config.ts]()\n\n### 2. MCP 工具层 (Core)\n\nMCP 工具层是系统的核心业务逻辑，提供三个主要工具：\n\n| 工具名 | 功能 | 输入参数 |\n|--------|------|----------|\n| `suggest_skills` | 智能推荐技能 | 可选 `manifestUrl` 覆盖默认配置 |\n| `fetch_manifest` | 获取 Manifest 内容 | `manifestUrl` |\n| `download_skill` | 下载技能目录 | GitHub 文件夹 URL |\n\n**`suggest_skills` 工具的工作流程：**\n\n```mermaid\ngraph LR\n A[获取配置的 Manifest URLs] --> B[抓取远程技能列表]\n B --> C[扫描本地已安装技能]\n C --> D[对比远程与本地能力]\n D --> E[生成推荐指令]\n E --> F[展示建议
不自动安装]\n```\n\n资料来源：[README.md](), [src/core.ts]()\n\n### 3. 传输层 (Transport)\n\n传输层负责 MCP 服务器与客户端之间的通信，支持两种模式：\n\n#### 3.1 stdio 模式\n\n适用于本地 CLI 调用和终端交互场景。通过标准输入输出进行 JSON-RPC 通信。\n\n```bash\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://example.com/manifest.md\"]' \\\n npx suggest-skills\n```\n\n资料来源：[src/stdio.ts](), [README.md]()\n\n#### 3.2 HTTP 模式\n\n适用于远程部署和服务化场景，提供 HTTP 端点：\n\n| 端点 | 路径 | 说明 |\n|------|------|------|\n| MCP 协议端点 | `/mcp` | MCP 工具调用入口 |\n| 健康检查 | `/health` | 服务状态检查 |\n\n```bash\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://example.com/manifest.md\"]' \\\n npx suggest-skills server --port 3100\n```\n\n资料来源：[src/http.ts](), [README.md]()\n\n### 4. CLI 生成模块 (Generate)\n\nCLI 生成模块提供命令行工具，用于从 GitHub 仓库自动生成技能清单文件：\n\n```bash\n# 生成单个目录的清单\nnpx suggest-skills generate \\\n https://github.com/OWNER/REPO/tree/main/skills\n\n# 递归生成（含子目录）\nnpx suggest-skills generate --recursive \\\n https://github.com/OWNER/REPO/tree/main/skills\n```\n\n**生成的文件类型：**\n\n| 文件后缀 | 内容 | 发现规则 |\n|----------|------|----------|\n| `.skills.md` | 技能目录清单 | 包含 `SKILL.md` 的目录 |\n| `.designs.md` | 设计清单 | 包含 `DESIGN.md` 的目录 |\n| `.agents.md` | Agent 清单 | 平铺的顶层 Markdown 文件 |\n\n**生成模式规则：**\n\n```mermaid\ngraph TD\n A[GitHub 仓库 URL] --> B{是否包含路径?}\n B -->|是| C[扫描指定目录树]\n B -->|否| D[假设仓库根目录为技能目录]\n C --> E[递归遍历树结构]\n D --> E\n E --> F[发现 SKILL.md 或 DESIGN.md]\n F --> G[收集同目录资源文件]\n G --> H[生成 Markdown 表格]\n```\n\n资料来源：[src/generate.ts](), [src/cmd_generate.ts](), [README.md]()\n\n### 5. 下载模块 (Download)\n\n下载模块负责从 GitHub 仓库获取技能目录及其所有文件：\n\n```typescript\n// 核心数据结构\ninterface ContentEntry {\n path: string; // 相对路径\n download_url: string | null; // 文件下载链接\n type: \"file\" | \"dir\"; // 条目类型\n}\n```\n\n**GitHub API 调用策略：**\n\n| 步骤 | API | 用途 |\n|------|-----|------|\n| 1 | `/repos/{owner}/{repo}/git/trees/{sha}?recursive=1` | 获取目录树 |\n| 2 | `/repos/{owner}/{repo}/contents/{path}` | 获取文件内容 |\n\n资料来源：[src/download.ts]()\n\n---\n\n## 数据模型\n\n### Manifest URL 配置结构\n\n```mermaid\nclassDiagram\n class Config {\n +string[] manifestUrls\n +string? githubPat\n +string outputDir\n }\n \n class Manifest {\n +string url\n +Skill[] skills\n }\n \n class Skill {\n +string name\n +string description\n +string url\n +Asset[] bundledAssets\n }\n \n class Asset {\n +string path\n +string downloadUrl\n }\n \n Config --> Manifest : 引用\n Manifest --> Skill : 包含\n Skill --> Asset : 引用\n```\n\n### 生成的 Markdown 表格结构\n\n| 列 | 来源 | 说明 |\n|----|------|------|\n| Name | 目录名 | 链接到 GitHub 目录 |\n| Description | `SKILL.md`/`DESIGN.md` 首行或摘要 | 技能用途描述 |\n| Bundled Assets | 同目录其他文件 | 附带的资源文件 |\n\n资料来源：[src/cmd_generate.ts](), [src/generate.ts]()\n\n---\n\n## 入口点\n\n### 主入口 (index.ts)\n\n```mermaid\ngraph TD\n A[index.ts
主入口] --> B{命令行参数解析}\n B -->|generate| C[cmd_generate.ts
生成清单]\n B -->|server| D[http.ts
HTTP 服务器]\n B -->|stdio| E[stdio.ts
stdio 传输]\n B -->|默认| F[stdio.ts
stdio 传输]\n```\n\n资料来源：[src/index.ts]()\n\n---\n\n## 关键设计决策\n\n### 1. 惰性安装原则\n\n`suggest_skills` 工具**仅返回推荐指令**，不会自动安装任何内容。用户确认后，需单独触发安装流程。\n\n> \"Present suggestions without installing anything until requested\" 资料来源：[README.md]()\n\n### 2. 空输出跳过机制\n\n在生成清单时，如果某个类型没有任何条目，则不生成对应文件，也不显示覆盖确认提示。\n\n### 3. 符号链接处理\n\n生成模式中，符号链接会被发现并包含在资源列表中，但不会进行递归遍历。\n\n### 4. URL 自动转换\n\nGitHub `blob` 格式的 URL 会自动转换为 `raw.githubusercontent.com` 格式，便于直接获取原始内容。\n\n---\n\n## 模块依赖关系\n\n```mermaid\ngraph TD\n subgraph \"传输层\"\n stdio[stdio.ts
stdio 传输]\n http[http.ts
HTTP 服务器]\n end\n \n subgraph \"业务逻辑层\"\n core[core.ts
MCP 工具实现]\n download[download.ts
文件下载]\n generate[generate.ts
清单生成]\n cmd[cmd_generate.ts
CLI 命令]\n end\n \n subgraph \"基础设施层\"\n config[config.ts
配置管理]\n index[index.ts
入口调度]\n end\n \n config --> core\n config --> download\n config --> generate\n config --> cmd\n \n core --> download\n core --> stdio\n core --> http\n \n generate --> download\n cmd --> generate\n \n stdio --> index\n http --> index\n```\n\n---\n\n## 扩展性与可维护性\n\n该架构具备良好的扩展性：\n\n| 扩展方向 | 实现方式 |\n|----------|----------|\n| 新增 MCP 工具 | 在 `core.ts` 中注册 `Tool` 实例 |\n| 新增传输协议 | 实现 `Server` 接口并添加到 `index.ts` |\n| 新增 Manifest 来源 | 扩展 `config.ts` 中的 URL 解析逻辑 |\n| 新增文件格式支持 | 在 `generate.ts` 中添加 `DESIGN.md` 等文件类型识别 |\n\n---\n\n\n\n## 项目结构\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [Generate 命令](#generate-command)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/index.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/index.ts)\n- [src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)\n- [src/constants.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/constants.ts)\n- [src/utils.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/utils.ts)\n- [src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)\n- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)\n- [src/cmd_generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/cmd_generate.ts)\n \n\n# 项目结构\n\n## 概述\n\nsuggest-skills 是一个基于 Model Context Protocol (MCP) 的技能推荐与管理系统。该项目允许 AI Agent 发现、扫描并推荐可用的技能（Skills），同时支持从 GitHub 下载技能资源。项目的核心架构围绕 MCP 协议展开，通过标准化的工具接口实现远程与本地技能的能力对比与展示。\n\n资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n## 技术栈\n\n| 类别 | 技术/框架 |\n|------|----------|\n| 运行时 | Bun |\n| 开发语言 | TypeScript |\n| 协议层 | @modelcontextprotocol/sdk |\n| 数据验证 | Zod |\n\n资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n## 整体架构\n\n项目采用分层架构设计，核心流程为：配置层 → MCP 工具注册 → 传输层（stdio 或 HTTP）。同时提供独立的 CLI 工具用于生成技能清单。\n\n```mermaid\ngraph TD\n A[配置文件] --> B[MCP 工具注册]\n B --> C[stdio 传输模式]\n B --> D[HTTP 传输模式]\n E[CLI generate] --> F[GitHub 目录扫描]\n F --> G[生成 Manifest Markdown]\n H[下载技能] --> I[download_skill 工具]\n J[推荐技能] --> K[suggest_skills 工具]\n```\n\n资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n## 目录结构\n\n### 源码目录 (`src/`)\n\n| 文件 | 功能说明 |\n|------|----------|\n| `index.ts` | MCP 服务入口，工具注册与传输层初始化 |\n| `config.ts` | 配置管理与验证逻辑 |\n| `constants.ts` | 常量定义 |\n| `utils.ts` | 通用工具函数 |\n| `download.ts` | GitHub 目录下载功能 |\n| `generate.ts` | Manifest 生成器核心逻辑 |\n| `cmd_generate.ts` | CLI generate 命令实现 |\n\n### 技能清单目录\n\n| 目录 | 用途 |\n|------|------|\n| `official/` | 官方维护的技能清单 |\n| `community/` | 社区贡献的技能清单 |\n| `official/skills/` | 官方技能定义 |\n| `community/skills/` | 社区技能定义 |\n\n每个技能目录下应包含 `SKILL.md` 或 `DESIGN.md` 文件，用于描述技能的用途与触发条件。\n\n资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n## 核心模块\n\n### 配置模块 (`src/config.ts`)\n\n配置模块负责验证环境变量与命令行参数，确保 MCP 服务正常运行。\n\n**关键环境变量：**\n\n| 变量名 | 必需 | 说明 |\n|--------|------|------|\n| `GITHUB_PAT` | 否 | GitHub 个人访问令牌，用于认证请求 |\n| `SUGGEST_SKILLS_MANIFEST_URLS` | 是 | 技能清单 URL，支持 JSON 数组、逗号分隔或换行分隔格式 |\n\n**配置格式：**\n\n```json\n{\n \"manifestUrls\": [\"https://some/skill-manifest.md\"]\n}\n```\n\nGitHub `blob` URL 会自动转换为 `raw.githubusercontent.com` URL。\n\n资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n### GitHub 下载模块 (`src/download.ts`)\n\n该模块封装了 GitHub API 调用，实现目录内容的递归下载。\n\n**核心 API 交互：**\n\n```mermaid\ngraph LR\n A[buildContentsApiUrl] --> B[GET /repos/{owner}/{repo}/contents/{path}]\n C[buildTreeApiUrl] --> D[GET /repos/{owner}/{repo}/git/trees/{sha}?recursive=1]\n```\n\n**主要函数：**\n\n| 函数 | 功能 |\n|------|------|\n| `buildContentsApiUrl()` | 构建 GitHub Contents API URL |\n| `buildTreeApiUrl()` | 构建 GitHub Trees API URL（支持递归） |\n| `fetchDirectoryContents()` | 获取目录内容并解析为结构化条目 |\n\n资料来源：[src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)\n\n### Manifest 生成模块 (`src/generate.ts`)\n\n负责扫描技能目录并生成规范化的 Markdown 清单文件。\n\n**处理流程：**\n\n1. 遍历目录树，识别包含 `SKILL.md` 或 `DESIGN.md` 的目录\n2. 收集同目录下的其他资源文件作为 bundled assets\n3. 按目录层级组织输出\n\n```mermaid\ngraph TD\n A[遍历目录树] --> B{文件类型判断}\n B -->|SKILL.md| C[标记为技能目录]\n B -->|DESIGN.md| D[标记为设计目录]\n B -->|其他资源| E[加入 bundled assets]\n C --> F[按层级排序输出]\n D --> F\n```\n\n资料来源：[src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)\n\n### CLI 生成命令 (`src/cmd_generate.ts`)\n\n实现命令行工具的 generate 子命令，支持递归扫描和自定义输出目录。\n\n**CLI 选项：**\n\n| 选项 | 说明 |\n|------|------|\n| `-o `, `--output ` | 指定输出目录，默认为 `.agents/skills` |\n| `generate [-r\\|--recursive] ` | 从 GitHub URL 生成清单 |\n| `server --port ` | 启动 HTTP 服务器 |\n\n**生成的输出文件类型：**\n\n| 文件后缀 | 内容来源 |\n|----------|----------|\n| `.skills.md` | 包含 `SKILL.md` 的技能目录 |\n| `.designs.md` | 包含 `DESIGN.md` 的设计目录 |\n| `.agents.md` | 平面化顶级 Markdown 文件 |\n\n资料来源：[src/cmd_generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/cmd_generate.ts)\n\n## MCP 工具接口\n\n### suggest_skills\n\n推荐可用技能的 MCP 工具，根据用户需求返回相应的技能建议。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `manifestUrl` | string | 否 | 覆盖默认配置的清单 URL |\n\n**返回内容：**\n生成指令负载，指导 Agent 如何获取、扫描、对比远程与本地技能，并展示推荐结果。\n\n### fetch_manifest\n\n获取指定清单文件内容的工具。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `manifestUrl` | string | 是 | 清单文件的 URL |\n\n### download_skill\n\n下载 GitHub 文件夹中的所有文件。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `url` | string | 是 | GitHub 文件夹 URL，格式：`https://github.com///tree/[/` |\n\n**返回内容：**\n文件夹内每个文件的相对路径、UTF-8 文本内容及类型信息。\n\n资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n## 传输模式\n\n### stdio 模式\n\n适用于本地进程间通信的标准化输入输出模式。\n\n```bash\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://some/skill-manifest.md\"]' \\\n npx suggest-skills\n```\n\n### HTTP 模式\n\n适用于网络化的 MCP 客户端连接。\n\n```bash\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://some/skill-manifest.md\"]' \\\n npx suggest-skills server --port 3100\n```\n\n**端点：**\n\n| 端点 | 路径 | 说明 |\n|------|------|------|\n| MCP 服务 | `/mcp` | MCP 协议端点 |\n| 健康检查 | `/health` | 服务健康状态 |\n\n资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n## 编码规范与设计原则\n\n项目遵循以下实现模式：\n\n| 原则 | 说明 |\n|------|------|\n| 模块化 | 小而专注的模块，按职责拆分文件 |\n| 配置验证 | 通过 `ConfigError` 进行显式验证 |\n| 类型安全 | 使用 Zod 验证工具模式和数据模型 |\n| 结构化输出 | MCP 工具使用类型化 Schema |\n| 传输抽象 | 最小化传输层封装，围绕共享服务构建 |\n\n资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n## 扩展方式\n\n### 贡献新技能\n\n1. 在 `community/skills/` 下创建技能目录\n2. 添加 `SKILL.md` 文件描述技能用途与触发条件\n3. 可选：添加相关资源文件作为 bundled assets\n\n### 添加新的清单源\n\n1. 在 `SUGGEST_SKILLS_MANIFEST_URLS` 中添加新的 URL\n2. 遵循现有的 Markdown 清单格式\n\n### 扩展 MCP 工具\n\n新工具应：\n- 在 `src/` 下创建独立的模块文件\n- 使用 Zod 定义输入输出 Schema\n- 在 `index.ts` 中注册到 MCP 服务\n\n---\n\n\n\n## MCP 工具\n\n### 相关页面\n\n相关主题：[传输模式](#transport-modes), [配置指南](#configuration-guide)\n\n]\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/core.ts)\n- [src/suggest.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/suggest.ts)\n- [src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)\n- [src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)\n- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)\n \n\n# MCP 工具\n\n## 概述\n\nMCP 工具是 `suggest-skills` 项目实现的核心功能模块，基于 Model Context Protocol (MCP) 标准提供技能建议、清单获取和技能下载能力。该模块作为 MCP 服务器运行，支持 `stdio` 和 HTTP 两种传输模式，使 AI 代理能够动态发现和推荐可用技能。\n\nMCP 工具的主要职责包括：\n- 从配置的清单 URL 获取远程技能目录\n- 扫描本地已安装的技能\n- 对比远程与本地能力差异\n- 向用户展示技能建议列表\n- 下载指定 GitHub 文件夹中的所有文件\n\n资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n## 架构概览\n\n```\nConfig -> MCP 工具注册 -> stdio 或 HTTP 传输\n```\n\n项目采用分层架构：\n- **配置层**：环境变量和命令行参数解析\n- **工具层**：三个核心 MCP 工具实现\n- **传输层**：stdio 和 HTTP 两种通信协议支持\n- **GitHub 交互层**：仓库扫描和文件下载\n\n技术栈：Bun、TypeScript、@modelcontextprotocol/sdk、Zod\n\n资料来源：[README.md:89-94](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n## 核心工具列表\n\n| 工具名称 | 功能描述 | 输入参数 |\n|---------|---------|---------|\n| `suggest_skills` | 生成技能建议指令负载，指导代理如何获取和推荐技能 | `manifestUrl`（可选） |\n| `fetch_manifest` | 获取指定清单 URL 的文本内容 | `manifestUrl`（必填） |\n| `download_skill` | 下载 GitHub 文件夹中的所有文件 | `url`（必填） |\n\n资料来源：[README.md:53-73](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n## suggest_skills 工具\n\n### 功能说明\n\n`suggest_skills` 是默认的技能推荐工具，返回一个生成的指令负载。该负载指示代理如何：\n\n1. 从配置的清单中获取可用技能\n2. 扫描本地已安装的技能\n3. 对比远程与本地的能力差异\n4. 展示建议而不自动安装\n\n### 参数定义\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|-----|------|\n| `manifestUrl` | string | 否 | 用于覆盖默认配置的清单 URL |\n\n### 返回值\n\n返回包含以下步骤的指令负载：\n- 获取清单中的技能列表\n- 本地技能扫描\n- 差异对比分析\n- 用户建议展示（仅在请求时安装）\n\n资料来源：[src/suggest.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/suggest.ts)\n\n## fetch_manifest 工具\n\n### 功能说明\n\n`fetch_manifest` 工具接受一个清单 URL 参数，返回该清单的完整文本内容。用于获取远程技能目录的详细描述。\n\n### 参数定义\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|-----|------|\n| `manifestUrl` | string | 是 | 技能清单的 GitHub URL |\n\n### 典型使用场景\n\n- 获取第三方技能仓库的清单\n- 动态更新本地缓存的技能列表\n- 跨仓库技能发现\n\n## download_skill 工具\n\n### 功能说明\n\n`download_skill` 工具用于下载 GitHub 文件夹中的所有文件，返回每个文件的相对路径、UTF-8 文本内容和符号链接信息。\n\n### 参数定义\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|-----|------|\n| `url` | string | 是 | GitHub 文件夹 URL，格式为 `https://github.com///tree/[/` |\n\n### 返回数据结构\n\n| 字段 | 类型 | 说明 |\n|-----|------|------|\n| `path` | string | 相对于请求文件夹的文件路径 |\n| `download_url` | string \\| null | 文件的直接下载 URL（目录为 null） |\n| `type` | \"file\" \\| \"dir\" | 条目类型 |\n\n### GitHub URL 解析\n\n工具内部通过以下步骤解析 GitHub 目录位置：\n\n```typescript\ninterface GithubDirectoryLocation {\n owner: string; // 仓库所有者\n repo: string; // 仓库名称\n ref: string; // 分支/标签/提交 SHA\n path: string; // 目录路径\n}\n```\n\n资料来源：[src/download.ts:1-50](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)\n\n## 工作流程图\n\n```mermaid\ngraph TD\n A[启动 MCP 服务器] --> B{传输模式}\n B -->|stdio| C[标准输入输出]\n B -->|HTTP| D[HTTP 端点 /mcp]\n C --> E[注册 MCP 工具]\n D --> E\n E --> F[suggest_skills]\n E --> G[fetch_manifest]\n E --> G --> H[获取清单文本]\n E --> I[download_skill]\n I --> J[解析 GitHub URL]\n J --> K[调用 GitHub Contents API]\n K --> L[递归获取目录树]\n L --> M[构建下载条目列表]\n M --> N[返回文件内容]\n```\n\n## 配置方式\n\n### 环境变量\n\n| 变量名 | 必填 | 说明 |\n|-------|-----|------|\n| `GITHUB_PAT` | 否 | GitHub 个人访问令牌，用于已认证请求 |\n| `SUGGEST_SKILLS_MANIFEST_URLS` | 是 | 至少包含一个 URL 的清单地址 |\n\n`SUGGEST_SKILLS_MANIFEST_URLS` 支持以下格式：\n- JSON 数组：`[\"https://example.com/manifest.md\"]`\n- 逗号分隔字符串：`\"url1,url2,url3\"`\n- 换行分隔字符串：`\"url1\\nurl2\\nurl3\"`\n\n### CLI 选项\n\n| 选项 | 说明 |\n|-----|------|\n| `-o ` / `--output ` | 安装技能的目标目录 |\n| `generate [-r\\|--recursive] ` | 从 GitHub 技能目录生成清单 |\n| `server --port ` | 运行 HTTP 服务器 |\n| `[...args]` | 以 stdio 模式运行（默认） |\n\n默认输出目录：`.agents/skills`\n\n资料来源：[src/config.ts:1-50](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)\n\n## HTTP 模式\n\nHTTP 服务器提供以下端点：\n\n| 端点 | 方法 | 说明 |\n|-----|------|------|\n| `/mcp` | POST | MCP 工具调用端点 |\n| `/health` | GET | 健康检查端点 |\n\n默认端口：3100\n\n### 启动命令\n\n```bash\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://example.com/manifest.md\"]' \\\n npx suggest-skills server --port 3100\n```\n\n## GitHub API 集成\n\n### API 端点\n\n| 功能 | API 端点 |\n|-----|---------|\n| 获取目录内容 | `/repos/{owner}/{repo}/contents/{path}` |\n| 获取目录树 | `/repos/{owner}/{repo}/git/trees/{tree_sha}?recursive=1` |\n\n### URL 转换\n\nGitHub `blob` URL 自动转换为 `raw.githubusercontent.com` URL：\n\n```typescript\nfunction normalizeGithubRawUrl(url: string): string | null {\n // 将 github.com/blob/ 转换为 raw.githubusercontent.com/\n}\n```\n\n资料来源：[src/download.ts:40-70](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)\n\n## 类型定义\n\n### ContentEntry\n\n```typescript\ninterface ContentEntry {\n path: string;\n download_url: string | null;\n type: \"file\" | \"dir\";\n}\n```\n\n### CliRuntimeMode\n\n```typescript\ntype CliRuntimeMode =\n | { kind: \"generate\"; url: string; recursive: boolean; config: Config }\n | { kind: \"download\"; url: string; recursive: boolean; config: Config }\n | { kind: \"server\"; port: number }\n | { kind: \"stdio\"; args: string[] };\n```\n\n### Config\n\n```typescript\ninterface Config {\n manifestUrls: string[];\n outputDirectory: string;\n githubPat?: string;\n}\n```\n\n## 清单文件格式\n\n清单文件为 Markdown 格式，支持以下结构：\n\n```markdown\n| 技能名称 | 描述 | 文件列表 |\n|---------|------|---------|\n| [skill-name](链接) | 功能说明 | `file1.md`, `assets/` |\n```\n\n生成模式自动扫描包含 `SKILL.md` 或 `DESIGN.md` 的目录。\n\n资料来源：[src/generate.ts:1-80](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)\n\n## 最佳实践\n\n### 1. 清单 URL 配置\n\n建议使用多个清单源以覆盖更广泛的技能库：\n\n```bash\nSUGGEST_SKILLS_MANIFEST_URLS='[\n \"https://raw.githubusercontent.com/anthropics/skills/main/README.md\",\n \"https://raw.githubusercontent.com/openai/skills/main/README.md\",\n \"https://raw.githubusercontent.com/sator-imaging/suggest-skills/main/README.md\"\n]'\n```\n\n### 2. 递归下载\n\n对于包含子目录的技能文件夹，使用 `--recursive` 选项确保完整下载：\n\n```bash\nnpx suggest-skills download --recursive \\\n https://github.com/owner/repo/tree/main/skills/my-skill\n```\n\n### 3. GitHub 认证\n\n当访问私有仓库或需要更高 API 限额时，配置 `GITHUB_PAT`：\n\n```bash\nGITHUB_PAT=ghp_xxx npx suggest-skills fetch_manifest\n```\n\n## 相关文档\n\n- [官方技能目录](../official/)\n- [社区技能](../community/)\n- [生成清单命令](./generate.md)\n- [下载技能命令](./download.md)\n\n---\n\n\n\n## 传输模式\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [部署指南](#deployment-guide)\n\n]\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/stdio.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/stdio.ts)\n- [src/http.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/http.ts)\n- [src/index.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/index.ts)\n- [src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)\n- [src/cli.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/cli.ts)\n \n\n# 传输模式\n\n## 概述\n\n`suggest-skills` 项目实现了 MCP (Model Context Protocol) 服务器，支持两种传输模式用于与 AI 代理进行通信。这两种模式分别为 **stdio 模式** 和 **HTTP 模式**，它们共享相同的核心功能和 MCP 工具集，仅在通信机制上有所不同。\n\n传输模式的选择直接影响工具调用方与应用服务器的交互方式：\n\n- **stdio 模式**：适用于本地进程通信，通过标准输入/输出流传递 JSON-RPC 消息\n- **HTTP 模式**：适用于网络远程调用，通过 HTTP REST API 提供 MCP 端点\n\n资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n## 架构设计\n\n### 传输层抽象\n\n项目采用传输层抽象设计，将核心业务逻辑与通信机制分离。配置层负责解析 CLI 参数并确定运行时模式，随后将控制权委托给对应的传输处理器。\n\n```mermaid\ngraph TD\n A[CLI 入口] --> B[配置解析]\n B --> C{运行时模式}\n C -->|stdio| D[stdio.ts]\n C -->|server| E[http.ts]\n D --> F[MCP 工具注册]\n E --> F\n F --> G[核心业务逻辑]\n G --> H[suggest_skills]\n G --> I[fetch_manifest]\n G --> J[download_skill]\n```\n\n资料来源：[src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)\n\n### 运行时模式类型\n\n`CliRuntimeMode` 联合类型定义了所有支持的运行时变体：\n\n| 模式 | 标识 | 用途 | 传输协议 |\n|------|------|------|----------|\n| `stdio` | 默认模式 | 本地进程通信 | stdin/stdout JSON-RPC |\n| `generate` | 生成模式 | 生成技能清单 | 仅 CLI |\n| `download` | 下载模式 | 下载技能资源 | 仅 CLI |\n| `server` | 服务模式 | HTTP 服务器 | HTTP/Streamable |\n\n资料来源：[src/config.ts:1-50](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)\n\n## stdio 模式\n\n### 工作原理\n\nstdio 模式是 MCP 协议的传统实现方式，服务器通过标准输入接收 JSON-RPC 请求，并通过标准输出返回响应消息。此模式无需网络配置，非常适合与本地 AI 代理进程集成。\n\n### 启动方式\n\nstdio 模式作为默认模式运行，当用户未指定任何子命令时自动激活：\n\n```bash\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://some/skill-manifest.md\"]' \\\n npx suggest-skills\n```\n\n环境变量 `SUGGEST_SKILLS_MANIFEST_URLS` 为必需配置，必须包含至少一个技能清单 URL。\n\n### 特性\n\n- **零网络依赖**：无需开放端口，完全在本地运行\n- **进程隔离**：每个会话创建独立进程\n- **低延迟**：直接内存通信，无网络开销\n- **标准化协议**：完全兼容 MCP JSON-RPC 规范\n\n资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n## HTTP 模式\n\n### 工作原理\n\nHTTP 模式启动一个基于 Streamable HTTP 的 MCP 服务器，支持远程调用和持久化连接。此模式适用于需要跨网络访问 MCP 工具的场景。\n\n### 端点配置\n\n| 端点 | 路径 | 功能 |\n|------|------|------|\n| MCP 主端点 | `/mcp` | 处理所有 MCP 协议请求 |\n| 健康检查 | `/health` | 服务状态验证 |\n\n### 启动方式\n\n使用 `server` 子命令启动 HTTP 服务器：\n\n```bash\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://some/skill-manifest.md\"]' \\\n npx suggest-skills server --port 3100\n```\n\n### 端口配置\n\n通过 `--port` 参数指定监听端口，默认情况下服务器绑定至 `0.0.0.0` 接受所有网络接口连接。\n\n### 特性\n\n- **远程访问**：支持跨网络调用 MCP 工具\n- **持久连接**：支持流式响应和连接复用\n- **健康监控**：内置健康检查端点便于运维监控\n- **REST 兼容**：基于标准 HTTP 协议，易于集成\n\n资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n## 配置管理\n\n### 环境变量\n\n| 变量名 | 必填 | 说明 |\n|--------|------|------|\n| `GITHUB_PAT` | 否 | GitHub API 认证令牌，用于提高 API 限制 |\n| `SUGGEST_SKILLS_MANIFEST_URLS` | 是 | 技能清单 URL，支持 JSON 数组、逗号分隔或换行分隔格式 |\n\n### 清单 URL 格式\n\n清单 URL 支持多种格式：\n\n```json\n[\"https://some/skill-manifest.md\"]\n```\n\n```text\nhttps://some/skill-manifest.md,https://other/skill-manifest.md\n```\n\nGitHub `blob` URL 会自动转换为 `raw.githubusercontent.com` URL。\n\n资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n## CLI 命令结构\n\n### 命令速查表\n\n| 命令 | 模式 | 说明 |\n|------|------|------|\n| `suggest-skills` | stdio | 默认启动 stdio 模式 |\n| `suggest-skills server` | http | 启动 HTTP 服务器 |\n| `suggest-skills generate ` | generate | 生成技能清单文档 |\n| `suggest-skills download ` | download | 下载技能资源 |\n\n### 全局选项\n\n- `-o, --output `：设置技能安装输出目录，默认为 `.agents/skills`\n\n### 生成模式选项\n\n- `-r, --recursive`：启用递归扫描子目录\n- `--url`：指定 GitHub 仓库路径\n\n### 服务器模式选项\n\n- `--port `：指定 HTTP 服务器监听端口\n\n资料来源：[src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)\n\n## MCP 工具集\n\n无论采用哪种传输模式，以下 MCP 工具均可用：\n\n### suggest_skills\n\n返回生成的指令负载，指导代理如何：\n\n- 获取已配置清单中的可用技能\n- 扫描本地已安装技能\n- 比较远程与本地能力\n- 在用户请求前呈现建议而不安装任何内容\n\n**参数**：`manifestUrl` (可选) - 覆盖默认配置的清单 URL\n\n### fetch_manifest\n\n获取指定清单 URL 的文本内容。\n\n**参数**：`manifestUrl` - 清单 URL\n\n### download_skill\n\n下载 GitHub 文件夹中的所有文件。\n\n**参数**：`url` - GitHub 文件夹 URL，格式为 `https://github.com///tree/[/`\n\n返回每个文件包含：\n\n- 相对于请求文件夹的路径\n- UTF-8 文本内容\n- 文件 symlink 的目标内容\n\n资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n## 模式选择指南\n\n```mermaid\ngraph TD\n A[开始] --> B{调用场景?}\n B -->|本地 AI 代理| C[stdio 模式]\n B -->|远程服务| D[HTTP 模式]\n B -->|生成清单| E[generate 模式]\n B -->|批量下载| F[download 模式]\n C --> G[低延迟隔离环境]\n D --> H[跨网络访问]\n E --> I[生成 markdown 文档]\n F --> J[获取技能文件]\n```\n\n### 选择建议\n\n| 场景 | 推荐模式 | 原因 |\n|------|----------|------|\n| Claude Code 本地集成 | stdio | 无网络开销，即插即用 |\n| 微服务架构 | HTTP | 支持远程调用和水平扩展 |\n| 持续集成流水线 | stdio | 进程生命周期清晰 |\n| Web 前端集成 | HTTP | 标准 REST 调用方式 |\n| 技能库迁移 | generate/download | 专用 CLI 功能 |\n\n## 技术栈\n\n项目使用的核心技术：\n\n| 技术 | 用途 |\n|------|------|\n| TypeScript | 主开发语言 |\n| Bun | 运行时和打包工具 |\n| @modelcontextprotocol/sdk | MCP 协议实现 |\n| Zod | 配置验证和类型安全 |\n\n资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n## 最佳实践\n\n### 环境配置\n\n```bash\n# 生产环境建议\nexport GITHUB_PAT=\"your_personal_access_token\"\nexport SUGGEST_SKILLS_MANIFEST_URLS='[\"https://raw.githubusercontent.com/anthropics/skills/main/skills/README.md\"]'\n```\n\n### 安全考量\n\n- HTTP 模式部署时应配置 TLS 终止\n- GitHub PAT 应存储在安全密钥管理系统中\n- 避免在日志中输出敏感配置信息\n\n### 性能优化\n\n- stdio 模式适合高频低延迟场景\n- HTTP 模式支持连接池和请求批处理\n- 大型仓库建议使用递归模式以获取完整技能树\n\n---\n\n\n\n## Generate 命令\n\n### 相关页面\n\n相关主题：[项目结构](#project-structure), [配置指南](#configuration-guide)\n\n]\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/cmd_generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/cmd_generate.ts)\n- [src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)\n- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)\n- [README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n \n\n# Generate 命令\n\n## 概述\n\nGenerate 命令是 suggest-skills 工具的核心功能之一，用于从 GitHub 仓库中扫描技能目录并生成标准化的 Markdown 清单文件。该命令通过递归扫描 GitHub 目录结构，自动发现包含 `SKILL.md`、`DESIGN.md` 的技能目录，并将其转换为可读的 Markdown 表格格式。\n\nGenerate 命令的主要职责包括：\n\n- 扫描指定的 GitHub 仓库或目录路径\n- 递归发现技能定义文件\n- 收集每个技能的元数据（名称、描述、关联资产）\n- 生成格式化的 Markdown 清单文件\n- 支持可选的递归扫描模式\n\n## 命令行接口\n\n### 基本语法\n\n```bash\nnpx suggest-skills generate \n```\n\n### 递归扫描模式\n\n```bash\nnpx suggest-skills generate \\\n --recursive \\\n https://github.com/OWNER/REPO/tree/main/skills\n```\n\n### 参数说明\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `` | string | 是 | GitHub 仓库或目录的 URL |\n| `-r, --recursive` | flag | 否 | 启用递归扫描模式，扫描所有子目录 |\n\n## 工作流程\n\n```mermaid\ngraph TD\n A[用户执行 generate 命令] --> B[解析 GitHub URL]\n B --> C{是否为递归模式?}\n C -->|是| D[使用 Tree API 递归获取目录结构]\n C -->|否| E[使用 Contents API 获取单层目录]\n D --> F[扫描 SKILL.md 和 DESIGN.md 文件]\n E --> F\n F --> G[收集技能条目和资产信息]\n G --> H[格式化 Markdown 表格]\n H --> I[生成输出文件]\n I --> J[写入 ...skills.md]\n I --> K[写入 ...designs.md]\n I --> L[写入 ...agents.md]\n```\n\n## 输出文件\n\n执行 generate 命令后，会在当前工作目录生成以下文件：\n\n| 文件类型 | 命名格式 | 内容描述 |\n|----------|----------|----------|\n| 技能清单 | `.[.].skills.md` | 包含 `SKILL.md` 的目录条目 |\n| 设计清单 | `.[.].designs.md` | 包含 `DESIGN.md` 的目录条目 |\n| 代理清单 | `.[.].agents.md` | 顶层 markdown 文件（仅含 Name 和 Description 列） |\n\n### 生成的 Markdown 格式\n\n```markdown\n| Name | Description |\n| -----|-------------|\n| [skill-name](url) | skill description |\n```\n\n当启用资产包含选项时，格式扩展为：\n\n```markdown\n| Name | Description | Bundled Assets |\n| -----|-------------|----------------|\n| [skill-name](url) | description | LICENSE.txt, scripts (5 files) |\n```\n\n## 源码架构\n\n### 核心模块职责\n\n| 模块 | 文件路径 | 职责 |\n|------|----------|------|\n| CLI 配置 | `src/config.ts` | 定义命令行参数解析和运行时模式 |\n| 生成逻辑 | `src/cmd_generate.ts` | 处理 Markdown 表格格式化和条目输出 |\n| 下载服务 | `src/download.ts` | 与 GitHub API 交互获取目录结构 |\n\n### 运行时模式定义\n\n```typescript\ninterface CliRuntimeMode {\n kind: \"generate\" | \"download\" | \"server\" | \"stdio\";\n url: string;\n recursive: boolean;\n config: {\n outputDirectory: string;\n sourceUrls: string[];\n };\n}\n```\n\n资料来源：[src/config.ts:32-38]()\n\n### 表格格式化流程\n\n```mermaid\ngraph LR\n A[Entry 数据] --> B[formatRow 函数]\n B --> C{includeAssets?}\n C -->|是| D[格式化资产列]\n C -->|否| E[仅输出名称和描述]\n D --> F[escapeTableCell 转义特殊字符]\n E --> F\n F --> G[拼接 Markdown 行]\n G --> H[生成完整表格]\n```\n\n## 表格单元格格式化\n\nGenerate 命令使用 `escapeTableCell` 函数处理单元格内容，防止 Markdown 表格解析错误。\n\n### 转义规则\n\n| 原字符 | 转义后 | 说明 |\n|--------|--------|------|\n| `|` | `\\|` | 管道符会破坏表格结构 |\n| 换行符 | 空格 | 单元格内容需保持单行 |\n\n```typescript\nfunction escapeTableCell(value: string): string {\n return value.replaceAll(\"|\", \"\\\\|\").replaceAll(\"\\n\", \" \");\n}\n```\n\n资料来源：[src/cmd_generate.ts:75-77]()\n\n## 资产打包格式\n\n当技能目录包含额外文件时，Generate 命令会将这些文件列为\"关联资产\"。\n\n### 资产显示格式\n\n| 资产数量 | 显示格式 | 示例 |\n|----------|----------|------|\n| 无资产 | `None` | `None` |\n| 单文件 | 文件名 | `LICENSE.txt` |\n| 多文件 | 文件名 + 计数 | `scripts` (5 files) |\n| 文件夹 | 文件夹名 + 计数 | `assets` (4 files) |\n\n### 内联资产数量限制\n\n```typescript\nconst BUNDLED_ASSETS_INLINE_MAX_ITEMS = 3;\n```\n\n当资产数量超过 3 个时，Generate 命令会切换为计数显示模式，避免表格过宽。\n\n## GitHub URL 处理\n\n### URL 规范化\n\nGenerate 命令支持多种 GitHub URL 格式：\n\n| 输入格式 | 处理方式 |\n|----------|----------|\n| `github.com/owner/repo/tree/main/path` | 自动转换为 API 端点 |\n| `raw.githubusercontent.com/...` | 直接使用 |\n| `github.com/owner/repo` | 扫描仓库根目录 |\n\n### API 端点构建\n\n```typescript\nfunction buildContentsApiUrl(location: GithubDirectoryLocation): string {\n const pathSuffix = location.path\n .split(\"/\")\n .filter(Boolean)\n .map((part) => encodeURIComponent(part))\n .join(\"/\");\n \n const pathname = `/repos/${encodeURIComponent(location.owner)}/${encodeURIComponent(location.repo)}/contents/${pathSuffix}`;\n const url = new URL(pathname, GITHUB_API_BASE_URL);\n \n url.searchParams.set(\"ref\", location.ref);\n return url.toString();\n}\n```\n\n资料来源：[src/download.ts:85-98]()\n\n## 空输出处理\n\nGenerate 命令实现了智能的空输出检测机制，避免生成无意义的清单文件。\n\n### 空文档判定\n\n```typescript\nfunction isEmptyGeneratedDocument(document: GeneratedDocument): boolean {\n return document.markdown === \"| Name | Description |\\n| -----|-------------|\\n\"\n || document.markdown === \"| Name | Description | Bundled Assets |\\n| -----|-------------|----------------|\\n\";\n}\n```\n\n资料来源：[src/cmd_generate.ts:64-68]()\n\n当检测到空输出时：\n- 不写入任何文件\n- 不显示覆盖确认提示\n- 静默跳过该类型清单\n\n## 配置集成\n\nGenerate 命令可以通过环境变量进行配置：\n\n### 环境变量\n\n| 变量名 | 必填 | 说明 |\n|--------|------|------|\n| `GITHUB_PAT` | 否 | GitHub 个人访问令牌，用于认证请求 |\n| `SUGGEST_SKILLS_MANIFEST_URLS` | 是 | 至少包含一个 manifest URL |\n\n### Manifest URL 格式\n\n```bash\n# JSON 数组格式\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://some/skill-manifest.md\"]'\n\n# 逗号分隔格式\nSUGGEST_SKILLS_MANIFEST_URLS='url1,url2,url3'\n\n# 换行分隔格式\nSUGGEST_SKILLS_MANIFEST_URLS='url1\nurl2'\n```\n\n## 最佳实践\n\n### 推荐使用场景\n\n1. **初始化新仓库**：首次设置技能目录时生成清单\n2. **同步更新**：每次技能更新后重新生成以保持文档最新\n3. **多仓库管理**：使用递归模式扫描组织下的所有技能\n\n### 性能注意事项\n\n| 模式 | 适用场景 | API 调用次数 |\n|------|----------|-------------|\n| 非递归 | 单层目录结构 | 1-2 次 |\n| 递归 | 多层嵌套技能 | N+1 次（根据深度） |\n\n### GitHub API 限制\n\n- 未认证请求：每小时 60 次\n- 认证请求（使用 GITHUB_PAT）：每小时 5000 次\n\n对于大型仓库或频繁使用场景，建议配置 `GITHUB_PAT` 环境变量。\n\n## 完整使用示例\n\n### 示例 1：扫描官方技能库\n\n```bash\nnpx suggest-skills generate \\\n https://github.com/anthropics/skills/tree/main/skills\n```\n\n输出文件：\n- `anthropics.skills.skills.md`\n- `anthropics.skills.designs.md`\n- `anthropics.skills.agents.md`\n\n### 示例 2：递归扫描社区技能\n\n```bash\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://example.com/manifest.md\"]' \\\nnpx suggest-skills generate \\\n --recursive \\\n https://github.com/ComposioHQ/awesome-claude-skills/tree/master\n```\n\n### 示例 3：集成到 CI/CD\n\n```yaml\n# .github/workflows/generate-skills.yml\nname: Generate Skills Manifest\non:\n schedule:\n - cron: '0 0 * * *' # 每日执行\n push:\n branches:\n - main\n\njobs:\n generate:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - name: Generate skills manifest\n env:\n GITHUB_PAT: ${{ secrets.GITHUB_PAT }}\n SUGGEST_SKILLS_MANIFEST_URLS: '[\"https://raw.githubusercontent.com/anthropics/skills/main/skills-index.json\"]'\n run: npx suggest-skills generate --recursive https://github.com/anthropics/skills/tree/main/skills\n```\n\n## 相关命令\n\n| 命令 | 功能 | 使用场景 |\n|------|------|----------|\n| `download` | 下载技能到本地 | 本地开发或离线使用 |\n| `server` | 启动 HTTP 服务 | 远程代理集成 |\n| `stdio` | 标准输入输出模式 | 与 MCP 客户端集成 |\n\n---\n\n\n\n## Server 命令\n\n### 相关页面\n\n相关主题：[传输模式](#transport-modes), [部署指南](#deployment-guide)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)\n- [src/http.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/http.ts)\n- [README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n- [src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)\n- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)\n \n\n# Server 命令\n\n## 概述\n\n`server` 命令是 `suggest-skills` CLI 工具的核心运行模式之一，用于启动一个基于 HTTP 协议的 MCP（Model Context Protocol）流式服务器。该服务器提供了技能（Skills）发现、清单获取和技能下载等核心功能，使 AI 代理能够在运行时动态获取和推荐可用的技能扩展。\n\nServer 命令的主要职责包括：\n- 注册 MCP 工具接口\n- 提供 RESTful HTTP 端点\n- 处理技能清单的获取与解析\n- 支持技能目录的下载功能\n\n资料来源：[README.md:1-20]()\n\n## 架构设计\n\n### 技术栈\n\nServer 命令基于以下技术构建：\n\n| 组件 | 技术 | 用途 |\n|------|------|------|\n| 运行时 | Bun | 高性能 JavaScript 运行时 |\n| 语言 | TypeScript | 类型安全开发 |\n| 协议框架 | @modelcontextprotocol/sdk | MCP 标准协议实现 |\n| 数据验证 | Zod | 运行时 Schema 验证 |\n\n资料来源：[README.md:89-96]()\n\n### 项目架构\n\n```\nConfig -> MCP tool registration -> stdio or HTTP transport\n\nCLI generate -> GitHub directory scan -> manifest markdown file\n \\-> GitHub URL normalization / folder download\n```\n\n整体架构遵循配置驱动、工具注册、传输层分离的设计模式。HTTP 传输作为独立的传输层实现，与 stdio 模式共享核心业务逻辑。\n\n资料来源：[README.md:98-104]()\n\n## 命令行接口\n\n### 基本用法\n\n```bash\nnpx suggest-skills server --port <端口号>\n```\n\n### 端口配置\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `--port ` | 指定 HTTP 服务器监听端口 | 3100 |\n\n配置示例：\n\n```bash\n# 启动服务器并指定端口\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://some/skill-manifest.md\"]' \\\n npx suggest-skills server --port 3100\n```\n\n资料来源：[src/config.ts:30-33]()\n\n## HTTP 端点\n\n### 端点列表\n\n| 端点 | 方法 | 功能 |\n|------|------|------|\n| `/mcp` | POST | MCP 协议主端点，处理工具调用 |\n| `/health` | GET | 健康检查端点 |\n\n### 服务地址\n\n- **MCP 端点**: `http://localhost:<端口>/mcp`\n- **健康检查**: `http://localhost:<端口>/health`\n\n默认配置下：\n- MCP 端点: `http://localhost:3100/mcp`\n- 健康检查: `http://localhost:3100/health`\n\n资料来源：[README.md:76-77]()\n\n## MCP 工具\n\nServer 命令注册了以下 MCP 工具供 AI 代理调用：\n\n### suggest_skills\n\n获取技能建议的工具，用于告知 AI 代理如何：\n- 从配置的清单中获取可用技能\n- 扫描本地已安装的技能\n- 比较远程与本地能力\n- 在用户请求前仅展示建议而不实际安装\n\n**参数**:\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| manifestUrl | string | 否 | 覆盖默认配置的清单 URL |\n\n资料来源：[README.md:80-92]()\n\n### fetch_manifest\n\n获取指定清单 URL 的文本内容。\n\n**参数**:\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| manifestUrl | string | 是 | 清单文件的完整 URL |\n\n资料来源：[README.md:94-97]()\n\n### download_skill\n\n下载 GitHub 文件夹中的所有文件。\n\n**参数**:\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| url | string | 是 | GitHub 文件夹 URL，格式为 `https://github.com///tree/[/` |\n\n**返回内容**:\n- 文件相对路径\n- UTF-8 编码的文本内容\n- GitHub 提供的 symlink 目标内容\n- 仓库相对目录 symlink 自动解析并递归下载\n\n资料来源：[README.md:99-112]()\n\n## 数据流程\n\n### 技能下载流程\n\n```mermaid\ngraph TD\n A[download_skill 工具调用] --> B[解析 GitHub URL]\n B --> C[构建 Contents API 请求]\n C --> D[获取仓库 Tree SHA]\n D --> E[递归获取文件树]\n E --> F[处理 symlink 解析]\n F --> G[构建下载 URL]\n G --> H[返回文件内容列表]\n \n I[buildGithubRawUrl] --> G\n J[buildTreeApiUrl] --> D\n```\n\n### 清单生成流程\n\n```mermaid\ngraph TD\n A[generate 命令] --> B[扫描 GitHub 目录]\n B --> C[递归发现 SKILL.md]\n C --> D[收集同目录资产文件]\n D --> E[构建 Markdown 表格]\n E --> F[输出清单文件]\n \n G[normalizeGithubRawUrl] --> A\n```\n\n资料来源：[src/download.ts:1-50](), [src/generate.ts:1-80]()\n\n## 环境配置\n\n### 必需环境变量\n\n| 变量名 | 必填 | 说明 |\n|--------|------|------|\n| SUGGEST_SKILLS_MANIFEST_URLS | 是 | 技能清单 URL 列表 |\n\n**支持的格式**:\n- JSON 数组: `[\"url1\", \"url2\"]`\n- 逗号分隔字符串: `\"url1,url2\"`\n- 换行分隔字符串: `\"url1\\nurl2\"`\n\n### 可选环境变量\n\n| 变量名 | 说明 |\n|--------|------|\n| GITHUB_PAT | GitHub 个人访问令牌，用于对 api.github.com 的认证请求 |\n\n### URL 自动转换\n\nGitHub `blob` URLs 会自动转换为 `raw.githubusercontent.com` URLs。\n\n资料来源：[README.md:120-138]()\n\n## 代码实现\n\n### 命令注册\n\nServer 命令通过 `cac` CLI 框架注册：\n\n```typescript\ncli\n .command(\"server [...args]\", \"Run the streamable HTTP server\")\n .option(\"--port \", \"Port number\")\n .action(actions.onServer);\n```\n\n资料来源：[src/config.ts:30-33]()\n\n### 运行时模式\n\nServer 命令解析后生成以下运行时配置：\n\n```typescript\n{\n kind: \"server\",\n port: number,\n config: {\n manifestUrls: string[],\n githubToken?: string\n }\n}\n```\n\n## 传输模式对比\n\n| 特性 | stdio 模式 | HTTP 模式 |\n|------|------------|-----------|\n| 启动方式 | `npx suggest-skills` | `npx suggest-skills server --port 3100` |\n| 通信协议 | 标准输入输出 | HTTP |\n| 适用场景 | 本地 CLI 集成 | 远程服务部署 |\n| 端点支持 | 无 | `/mcp`, `/health` |\n| 并发支持 | 单会话 | 多会话 |\n\n资料来源：[README.md:142-157]()\n\n## 最佳实践\n\n### 生产环境部署\n\n1. **配置清单 URL**: 确保 `SUGGEST_SKILLS_MANIFEST_URLS` 包含所有必需的技能清单\n2. **使用 GitHub Token**: 通过 `GITHUB_PAT` 提升 API 请求频率限制\n3. **健康检查**: 定期调用 `/health` 端点验证服务状态\n\n### 调试建议\n\n- 使用 `--port` 参数指定非默认端口避免冲突\n- 查看服务器日志确认 MCP 工具注册状态\n- 使用 `curl http://localhost:/health` 快速验证服务\n\n## 相关命令\n\n| 命令 | 说明 |\n|------|------|\n| `suggest-skills generate` | 从 GitHub 目录生成技能清单 |\n| `suggest-skills download` | 下载技能到本地目录 |\n| `suggest-skills` | 以 stdio 模式运行（默认） |\n\n资料来源：[src/config.ts:20-35]()\n\n---\n\n\n\n## 配置指南\n\n### 相关页面\n\n相关主题：[MCP 工具](#mcp-tools), [传输模式](#transport-modes)\n\n]\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)\n- [README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n- [src/cmd_generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/cmd_generate.ts)\n- [src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)\n- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)\n \n\n# 配置指南\n\n## 概述\n\n`suggest-skills` 是一个基于 Model Context Protocol (MCP) 的技能建议工具，用于从 GitHub 仓库中发现、管理和推荐 AI 助手技能。该项目支持三种运行时模式：stdio 模式、HTTP 服务模式和生成模式，通过环境变量和命令行参数进行灵活配置。 资料来源：[README.md:1-50]()\n\n## 核心配置架构\n\n```mermaid\ngraph TD\n A[环境变量配置] --> B[CLI 参数解析]\n B --> C{运行时模式}\n C -->|stdio| D[MCP stdio 传输]\n C -->|server| E[MCP HTTP 服务]\n C -->|generate| F[Manifest 生成器]\n \n A1[`SUGGEST_SKILLS_MANIFEST_URLS`] --> A\n A2[`GITHUB_PAT`] --> A\n B1[`-o, --output`] --> B\n B2[`-r, --recursive`] --> B\n B3[`--port`] --> B\n```\n\n## 环境变量配置\n\n### 必需配置\n\n| 环境变量 | 说明 | 格式要求 | 示例 |\n|---------|------|---------|------|\n| `SUGGEST_SKILLS_MANIFEST_URLS` | 技能清单 URL 地址 | JSON 数组、逗号分隔或换行分隔 | 参见下方详细说明 |\n\n`SUGGEST_SKILLS_MANIFEST_URLS` 是必需的配置文件，必须包含至少一个有效的清单 URL。支持的格式如下：\n\n```bash\n# JSON 数组格式\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://example.com/manifest.md\"]'\n\n# 逗号分隔格式\nSUGGEST_SKILLS_MANIFEST_URLS='https://example.com/manifest1.md,https://example.com/manifest2.md'\n\n# 换行分隔格式\nSUGGEST_SKILLS_MANIFEST_URLS='https://example.com/manifest1.md\nhttps://example.com/manifest2.md'\n```\n\nGitHub `blob` URL 会自动转换为 `raw.githubusercontent.com` URL。 资料来源：[README.md:70-90]()\n\n### 可选配置\n\n| 环境变量 | 说明 | 用途 |\n|---------|------|------|\n| `GITHUB_PAT` | GitHub 个人访问令牌 | 用于对 `api.github.com` 的认证请求，提高 API 限制 |\n\n## 命令行接口配置\n\n### 全局选项\n\n| 选项 | 完整格式 | 说明 | 默认值 |\n|-----|---------|------|-------|\n| 输出目录 | `-o `, `--output ` | 安装技能的输出目录 | `.agents/skills` |\n\n输出目录指定安装的技能文件存放位置，相对路径相对于当前工作目录。 资料来源：[src/config.ts:1-50]()\n\n### 子命令配置\n\n#### generate 命令\n\n```bash\nnpx suggest-skills generate [--recursive, -r]\n```\n\n| 参数/选项 | 说明 |\n|---------|------|\n| `` | GitHub 仓库或技能目录 URL |\n| `--recursive`, `-r` | 递归扫描子目录 |\n\n生成模式会扫描指定 GitHub 路径下的所有技能目录，并生成以下文件：\n\n- `.[.].skills.md` - 包含 `SKILL.md` 的技能目录清单\n- `.[.].designs.md` - 包含 `DESIGN.md` 的设计目录清单\n- `.[.].agents.md` - 平面顶级 Markdown 文件中的代理清单\n\n空生成的输出会被跳过，不会覆盖现有文件。 资料来源：[README.md:40-65]()\n\n#### download 命令\n\n```bash\nnpx suggest-skills download [--recursive, -r]\n```\n\n下载技能、代理和设计文件到当前目录。使用 GitHub Contents API 递归获取文件内容。 资料来源：[src/download.ts:1-40]()\n\n#### server 命令\n\n```bash\nnpx suggest-skills server [--port ]\n```\n\n| 选项 | 说明 | 默认值 |\n|-----|------|-------|\n| `--port ` | HTTP 服务监听端口 | `3100` |\n\nHTTP 服务提供两个端点：\n\n- `http://localhost:/mcp` - MCP 协议端点\n- `http://localhost:/health` - 健康检查端点\n\n```mermaid\ngraph LR\n A[客户端] -->|HTTP 请求| B[MCP 端点 /mcp]\n A -->|健康检查| C[Health 端点 /health]\n B --> D[技能清单处理]\n C --> E[服务状态返回]\n```\n\n#### stdio 模式（默认）\n\n当不指定任何子命令时，工具以 stdio 模式运行，作为 MCP 服务器通过标准输入输出通信：\n\n```bash\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://example.com/manifest.md\"]' npx suggest-skills\n```\n\n## 配置验证机制\n\n### ConfigError 异常处理\n\n项目通过 `ConfigError` 类进行显式配置验证，任何配置错误都会抛出该异常并终止程序执行。这确保了配置问题在启动阶段就能被发现。 资料来源：[src/config.ts:1-20]()\n\n### 运行时模式解析\n\n配置解析流程如下：\n\n```mermaid\ngraph TD\n A[解析 process.argv] --> B[解析环境变量]\n B --> C{命令类型判断}\n C -->|generate| D[设置 generate 运行时模式]\n C -->|download| E[设置 download 运行时模式]\n C -->|server| F[设置 server 运行时模式]\n C -->|无命令| G[设置 stdio 运行时模式]\n \n D --> H[构建配置对象]\n E --> H\n F --> H\n G --> H\n```\n\n每个运行时模式包含以下配置属性：\n\n| 属性 | 说明 |\n|-----|------|\n| `kind` | 模式类型：`generate`、`download`、`server`、`stdio` |\n| `url` | GitHub URL（generate/download 模式） |\n| `recursive` | 是否递归扫描 |\n| `config` | 通用配置对象 |\n\n## MCP 工具配置\n\n### suggest_skills 工具\n\n核心建议工具，接受可选的 `manifestUrl` 参数覆盖默认配置。返回生成的指令载荷，指导代理如何：\n\n- 从配置的清单获取可用技能\n- 扫描本地安装的技能\n- 比较远程和本地能力\n- 在请求安装前呈现建议\n\n### fetch_manifest 工具\n\n接受清单 URL 并返回其文本内容。\n\n### download_skill 工具\n\n接受 GitHub 文件夹 URL 格式：\n\n```\nhttps://github.com///tree/[/\n```\n\n返回文件夹中的每个文件，包含相对路径、UTF-8 文本内容和符号链接信息。 资料来源：[README.md:100-130]()\n\n## 清单文件格式\n\n### 技能清单结构\n\n清单文件采用 Markdown 表格格式，每行包含技能名称（链接）、描述和捆绑资源：\n\n```markdown\n| Name | Description | Bundled Assets |\n|------|-------------|----------------|\n| [skill-name](url) | Description text | `file1.txt`, `dir/` (3 files) |\n```\n\n### Manifest 加载流程\n\n```mermaid\nsequenceDiagram\n participant CLI as CLI 工具\n participant Config as 配置模块\n participant Manifest as 清单 URL\n participant MCP as MCP 服务器\n \n CLI->>Config: 解析环境变量\n Config->>Manifest: 获取清单内容\n Manifest-->>Config: 返回 Markdown\n Config->>MCP: 注册工具和资源\n MCP->>CLI: 服务就绪\n```\n\n## 常见配置场景\n\n### 场景一：本地开发环境\n\n```bash\n# 设置清单源\nexport SUGGEST_SKILLS_MANIFEST_URLS='[\"https://raw.githubusercontent.com/anthropics/skills/main/official/skills.skills.md\"]'\n\n# 以 stdio 模式运行\nnpx suggest-skills\n```\n\n### 场景二：HTTP 服务部署\n\n```bash\n# 设置清单源（多源）\nexport SUGGEST_SKILLS_MANIFEST_URLS='[\"https://example.com/manifest1.md\",\"https://example.com/manifest2.md\"]'\n\n# 自定义端口\nnpx suggest-skills server --port 8080\n```\n\n### 场景三：从 GitHub 生成清单\n\n```bash\n# 递归扫描官方技能\nnpx suggest-skills generate https://github.com/anthropics/skills/tree/main/skills --recursive\n\n# 单层扫描\nnpx suggest-skills generate https://github.com/anthropics/skills/tree/main/official/skills\n```\n\n## 技术栈配置依赖\n\n项目使用以下技术栈构建，所有配置都围绕这些核心依赖展开：\n\n| 技术 | 用途 | 配置关联 |\n|-----|------|---------|\n| Bun | 运行时和打包 | `package.json` 定义脚本入口 |\n| TypeScript | 类型安全 | 编译配置 |\n| @modelcontextprotocol/sdk | MCP 协议实现 | 工具和资源注册 |\n| Zod | 配置验证 | 环境变量和参数 schema |\n\n## 配置最佳实践\n\n1. **环境变量优先**：优先通过环境变量配置清单 URL，避免硬编码\n2. **使用认证令牌**：生产环境建议配置 `GITHUB_PAT` 以提高 API 限制\n3. **指定输出目录**：使用 `-o` 选项明确指定技能安装位置\n4. **递归扫描谨慎使用**：大仓库递归扫描会增加 API 调用次数\n5. **健康检查监控**：部署 HTTP 服务时定期检查 `/health` 端点\n\n---\n\n\n\n## 部署指南\n\n### 相关页面\n\n相关主题：[传输模式](#transport-modes), [Server 命令](#server-command)\n\n]\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n- [package.json](https://github.com/sator-imaging/suggest-skills/blob/main/package.json)\n- [src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)\n- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)\n \n\n# 部署指南\n\n本页面详细说明 `suggest-skills` 项目的部署方式、配置方法及运行模式。该项目是一个基于 MCP（Model Context Protocol）的技能推荐服务器，支持通过命令行工具生成技能清单以及作为 MCP 服务器运行。\n\n## 系统要求\n\n| 组件 | 要求 | 说明 |\n|------|------|------|\n| Node.js | v18+ | 运行 MCP 服务器的基础环境 |\n| 包管理器 | npm / yarn / pnpm | 安装项目依赖 |\n| 可选认证 | GitHub Personal Access Token | 提高 GitHub API 请求速率限制 |\n\n资料来源：[README.md:1-10]()\n\n## 安装方式\n\n### 通过 npm 全局安装\n\n```bash\nnpm install -g suggest-skills\n```\n\n### 通过 npx 直接运行\n\n```bash\nnpx suggest-skills \n```\n\n### 从源码构建\n\n```bash\ngit clone https://github.com/sator-imaging/suggest-skills.git\ncd suggest-skills\nnpm install\nnpm run build\n```\n\n## 环境变量配置\n\n### 必需配置\n\n| 环境变量 | 说明 | 格式要求 |\n|----------|------|----------|\n| `SUGGEST_SKILLS_MANIFEST_URLS` | 技能清单 URL 列表 | JSON 数组、逗号分隔字符串或换行分隔字符串 |\n\n```bash\n# JSON 数组格式\nexport SUGGEST_SKILLS_MANIFEST_URLS='[\"https://example.com/manifest.md\"]'\n\n# 逗号分隔格式\nexport SUGGEST_SKILLS_MANIFEST_URLS='https://example.com/manifest1.md,https://example.com/manifest2.md'\n```\n\n### 可选配置\n\n| 环境变量 | 说明 | 默认值 |\n|----------|------|--------|\n| `GITHUB_PAT` | GitHub 个人访问令牌 | 无 |\n\n`GITHUB_PAT` 用于对 `api.github.com` 的认证请求，可有效提高 API 速率限制。\n\n```bash\nexport GITHUB_PAT=\"ghp_xxxxxxxxxxxx\"\n```\n\n资料来源：[README.md:1-20]()\n\n## 运行模式\n\n### stdio 模式\n\nstdio 模式适用于与本地 MCP 客户端直接集成，通过标准输入输出进行通信。\n\n```bash\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://some/skill-manifest.md\"]' \\\n npx suggest-skills\n```\n\n此模式适合集成到支持 MCP 协议的开发工具中。\n\n### HTTP 服务器模式\n\nHTTP 模式提供网络 HTTP 接口，适合远程访问和分布式架构部署。\n\n```bash\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://some/skill-manifest.md\"]' \\\n npx suggest-skills server --port 3100\n```\n\n#### 服务端点\n\n| 端点 | 方法 | 说明 |\n|------|------|------|\n| `/mcp` | GET/POST | MCP 协议主端点，处理技能推荐请求 |\n| `/health` | GET | 健康检查端点，验证服务状态 |\n\n```text\nhttp://localhost:3100/mcp # MCP 协议端点\nhttp://localhost:3100/health # 健康检查端点\n```\n\n资料来源：[README.md:20-35]()\n\n## 命令行接口\n\n### generate 命令\n\n生成技能清单文档，从 GitHub 仓库扫描技能目录。\n\n```bash\nnpx suggest-skills generate \n```\n\n#### 参数说明\n\n| 参数 | 说明 | 示例 |\n|------|------|------|\n| `` | GitHub 仓库或目录 URL | `https://github.com/OWNER/REPO/tree/main/skills` |\n| `-r, --recursive` | 递归扫描子目录 | 扫描嵌套的技能目录 |\n\n#### 基本用法\n\n```bash\n# 从 skills 目录生成清单\nnpx suggest-skills generate https://github.com/OWNER/REPO/tree/main/skills\n\n# 递归生成所有嵌套技能\nnpx suggest-skills generate --recursive https://github.com/OWNER/REPO/tree/main/skills\n```\n\n#### 输出文件\n\ngenerate 命令会在当前工作目录生成以下文件：\n\n| 文件类型 | 命名规则 | 内容 |\n|----------|----------|------|\n| 技能清单 | `.[.].skills.md` | 包含 SKILL.md 的目录条目 |\n| 设计清单 | `.[.].designs.md` | 包含 DESIGN.md 的目录条目 |\n| 智能体清单 | `.[.].agents.md` | 顶级 markdown 智能体定义 |\n\n#### 扫描规则\n\n```mermaid\ngraph TD\n A[GitHub URL] --> B{--recursive 参数}\n B -->|否| C[扫描直接子目录]\n B -->|是| D[递归扫描所有子目录]\n C --> E[发现 SKILL.md 或 DESIGN.md]\n D --> E\n E --> F[收集同目录资源文件]\n F --> G[生成清单文件]\n```\n\n- GitHub `blob` URL 会自动转换为 `raw.githubusercontent.com` URL\n- 符号链接会被下载但不递归遍历\n- 空生成的输出会被跳过，不写入文件\n\n资料来源：[README.md:35-60]()\n\n### server 命令\n\n启动 HTTP 服务器运行 MCP 端点。\n\n```bash\nnpx suggest-skills server --port \n```\n\n#### 参数说明\n\n| 参数 | 说明 | 默认值 |\n|------|------|------|\n| `--port, -p` | HTTP 服务器监听端口 | 3100 |\n\n### CLI 选项汇总\n\n| 选项 | 说明 | 适用于 |\n|------|------|--------|\n| `-o ` | 技能安装输出目录 | install |\n| `--recursive` | 递归扫描子目录 | generate |\n| `--port ` | HTTP 服务器端口 | server |\n\n资料来源：[README.md:15-25]()\n\n## MCP 工具接口\n\n### suggest_skills\n\n推荐可用技能的工具。\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `manifestUrl` | string (可选) | 覆盖默认配置的清单 URL |\n\n**返回内容**：生成的指令负载，指导智能体如何获取技能、扫描本地安装、对比远程与本地能力。\n\n### fetch_manifest\n\n获取清单文件内容。\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `manifestUrl` | string | 清单文件 URL |\n\n**返回内容**：清单文件的原始文本内容。\n\n### download_skill\n\n下载技能目录中的所有文件。\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `url` | string | GitHub 文件夹 URL，格式为 `https://github.com///tree/[/` |\n\n**返回内容**：文件夹中每个文件的路径、UTF-8 文本内容及符号链接信息。\n\n```mermaid\ngraph LR\n A[MCP 客户端] -->|suggest_skills| B[返回推荐指令]\n A -->|fetch_manifest| C[获取清单]\n A -->|download_skill| D[下载技能文件]\n B --> E[用户选择技能]\n E --> D\n D --> F[本地文件]\n```\n\n## Docker 部署（推荐架构）\n\n```dockerfile\nFROM node:18-alpine\n\nWORKDIR /app\n\nCOPY package*.json ./\nRUN npm ci --only=production\n\nCOPY dist/ ./dist/\n\nENV SUGGEST_SKILLS_MANIFEST_URLS=\"https://raw.githubusercontent.com/anthropics/skills/main/skills/skills.md\"\n\nEXPOSE 3100\n\nCMD [\"npx\", \"suggest-skills\", \"server\", \"--port\", \"3100\"]\n```\n\n### Docker Compose 编排\n\n```yaml\nversion: '3.8'\n\nservices:\n suggest-skills:\n image: suggest-skills:latest\n ports:\n - \"3100:3100\"\n environment:\n - SUGGEST_SKILLS_MANIFEST_URLS=https://example.com/manifest.md\n - GITHUB_PAT=${GITHUB_PAT}\n restart: unless-stopped\n healthcheck:\n test: [\"CMD\", \"wget\", \"--spider\", \"-q\", \"http://localhost:3100/health\"]\n interval: 30s\n timeout: 10s\n retries: 3\n```\n\n## 项目架构\n\n```mermaid\ngraph TD\n subgraph 配置层\n A[环境变量] --> B[Config 模块]\n B --> C[配置验证]\n end\n \n subgraph 核心层\n D[MCP 服务器] --> E[工具注册]\n F[CLI 工具] --> G[GitHub 目录扫描]\n G --> H[清单生成器]\n end\n \n subgraph 传输层\n I[stdio 传输] \n J[HTTP 传输]\n end\n \n B --> D\n B --> F\n E --> I\n E --> J\n H --> K[Markdown 输出]\n```\n\n### 核心模块\n\n| 模块 | 文件路径 | 职责 |\n|------|----------|------|\n| MCP 工具注册 | `src/mcp/` | 注册 suggest_skills、fetch_manifest、download_skill 工具 |\n| 配置管理 | `src/config.ts` | 验证环境变量，处理配置错误 |\n| GitHub API | `src/download.ts` | 目录内容获取、树形结构扫描 |\n| 清单生成 | `src/generate.ts` | 解析 SKILL.md、DESIGN.md 生成清单文档 |\n\n## 故障排查\n\n### 常见问题\n\n| 问题 | 可能原因 | 解决方案 |\n|------|----------|----------|\n| `SUGGEST_SKILLS_MANIFEST_URLS` 未设置 | 环境变量缺失 | 设置至少一个清单 URL |\n| GitHub API 速率限制 | 未使用认证令牌 | 配置 `GITHUB_PAT` 环境变量 |\n| 清单生成无输出 | 目录中无 SKILL.md 或 DESIGN.md | 确认目标目录包含技能定义文件 |\n| HTTP 端口占用 | 端口已被占用 | 使用 `--port` 指定其他端口 |\n\n### 健康检查\n\n部署后验证服务状态：\n\n```bash\ncurl http://localhost:3100/health\n```\n\n正常响应返回 HTTP 200 状态码。\n\n### 日志级别\n\n通过环境变量启用调试日志：\n\n```bash\nDEBUG=suggest-skills:* npx suggest-skills server --port 3100\n```\n\n## 最佳实践\n\n1. **始终设置 GitHub PAT**：生产环境建议配置认证令牌以避免 API 限制\n2. **使用版本化的清单 URL**：避免清单更新导致行为不一致\n3. **配置健康检查**：容器编排中设置健康检查探针\n4. **分离配置与部署**：使用环境变量管理配置，便于不同环境切换\n5. **限制网络暴露**：stdio 模式优先用于敏感环境\n\n资料来源：[README.md:1-80]()\n\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：sator-imaging/suggest-skills\n\n摘要：发现 15 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。\n\n## 1. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | host_targets=mcp_host, claude\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | README/documentation is current enough for a first validation pass.\n\n## 3. 运行坑 · 来源证据：v1.0.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.0.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e40d7a86377b444f8d3eca5e8ec2b1a4 | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.0.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 4. 运行坑 · 来源证据：v1.1.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.1.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d9b5403807304a33aaf39f02f80d14be | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.1.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 5. 运行坑 · 来源证据：v1.2.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.2.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_452c2fc3dc7d4409a8e1a4ae5419599f | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.2.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 运行坑 · 来源证据：v1.3.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.3.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7cf71c15b4c64e7297db646b5300ba29 | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.3.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 维护坑 · 来源证据：v1.0.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.0.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2150c52f85274793bfce6c1d64d24f66 | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.0.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 维护坑 · 来源证据：v1.0.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.0.3\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ac612b4c6cd44d2194d9df8b4c026220 | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.0.3 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 维护坑 · 来源证据：v2.0.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v2.0.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bc9655e0f7c54b22a783ef99c7841b5e | https://github.com/sator-imaging/suggest-skills/releases/tag/v2.0.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | last_activity_observed missing\n\n## 11. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 13. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | no_demo; severity=medium\n\n## 14. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | issue_or_pr_quality=unknown\n\n## 15. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | release_recency=unknown\n\n\n",
"markdown_key": "suggest-skills",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:1220908449",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/sator-imaging/suggest-skills"
},
{
"evidence_id": "art_79fff8d00c324dcbbe37730a5201acc9",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/sator-imaging/suggest-skills#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "suggest-skills 说明书",
"toc": [
"https://github.com/sator-imaging/suggest-skills 项目说明书",
"目录",
"项目介绍",
"项目概述",
"技术栈",
"架构设计",
"MCP 工具接口",
"下载流程实现",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "331c05789446d59171abaf53b4b80208eb65dd55",
"repo_inspection_error": null,
"repo_inspection_files": [
"package.json",
"README.md",
"src/utils.ts",
"src/generate.ts",
"src/stdio.ts",
"src/cmd_generate.ts",
"src/constants.ts",
"src/cmd_download.ts",
"src/index.ts",
"src/config.ts",
"src/http.ts",
"src/download.ts",
"src/suggest.ts",
"src/core.ts"
],
"repo_inspection_verified": true,
"review_reasons": [],
"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": "# suggest-skills - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 suggest-skills 编译的 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- **想在安装前理解开源项目价值和边界的用户**：当前证据主要来自项目文档。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `npx suggest-skills generate \\` 证据：`README.md` Claim：`clm_0003` supported 0.86\n- `npx suggest-skills` 证据：`README.md` Claim：`clm_0003` supported 0.86, `clm_0004` supported 0.86, `clm_0005` supported 0.86\n- `npx suggest-skills server --port 3100` 证据：`README.md` Claim：`clm_0005` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做权限沙盒试用\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：先做权限沙盒试用\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、本地环境或项目文件、宿主 AI 上下文\n\n### 现在可以相信\n\n- **适合人群线索：想在安装前理解开源项目价值和边界的用户**（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- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\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_0006` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0007` 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- 文件总数：33\n- 重要文件覆盖：28/33\n- 证据索引条目：28\n- 角色 / Skill 条目：3\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请基于 suggest-skills 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 suggest-skills 当作安装前体验资产，而不是已安装工具或真实运行环境。\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请基于 suggest-skills 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 3 个角色 / Skill / 项目文档条目。\n\n- **Key Features**（project_doc）：! npm https://img.shields.io/npm/v/suggest-skills https://www.npmjs.com/package/suggest-skills ! test https://github.com/sator-imaging/suggest-skills/actions/workflows/test.yml/badge.svg https://github.com/sator-imaging/suggest-skills/actions/workflows/test.yml 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Changelog**（project_doc）：2.0.0 https://github.com/sator-imaging/suggest-skills/compare/v1.3.1...v2.0.0 2026-05-12 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CHANGELOG.md`\n- **License**（project_doc）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`LICENSE.md`\n\n## 证据索引\n\n- 共索引 28 条证据。\n\n- **Key Features**（documentation）：! npm https://img.shields.io/npm/v/suggest-skills https://www.npmjs.com/package/suggest-skills ! test https://github.com/sator-imaging/suggest-skills/actions/workflows/test.yml/badge.svg https://github.com/sator-imaging/suggest-skills/actions/workflows/test.yml 证据：`README.md`\n- **Package**（package_manifest）：{ \"version\": \"2.0.0\", \"name\": \"suggest-skills\", \"description\": \"MCP server that suggests repository-specific AI agent skills.\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/sator-imaging/suggest-skills.git\" }, \"license\": \"Apache-2.0\", \"type\": \"module\", \"bin\": { \"suggest-skills\": \"dist/index.js\" }, \"scripts\": { \"build\": \"bun build --banner \\\" !/usr/bin/env node\\\" src/index.ts --outdir ./dist --target node --drop console --drop debugger --minify --production\", \"start\": \"bun src/index.ts\", \"server\": \"bun src/index.ts server --port 3100\", \"check\": \"bunx tsgo --noEmit && bunx oxlint\", \"test\": \"bun run check && bun test\" }, \"dependencies\": { \"@modelcontextprotocol/sdk\": \"^1.29.0\"… 证据：`package.json`\n- **Changelog**（documentation）：2.0.0 https://github.com/sator-imaging/suggest-skills/compare/v1.3.1...v2.0.0 2026-05-12 证据：`CHANGELOG.md`\n- **License**（documentation）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE.md`\n- **Tsconfig**（structured_config）：\"compilerOptions\": { \"types\": \"bun\" , 证据：`tsconfig.json`\n- **Codeowners**（source_file）：@sator-imaging 证据：`.github/CODEOWNERS`\n- **.gitignore**（source_file）：!package .json !oxlint.config.js !tsconfig.json 证据：`.gitignore`\n- **.npmignore**（source_file）：. / 证据：`.npmignore`\n- **Oxlint.Config**（source_file）：export default { extends: \"oxlint:recommended\" , 证据：`oxlint.config.js`\n- **Perry configuration**（source_file）：Perry configuration https://github.com/PerryTS/perry 证据：`perry.toml`\n- **Cmd Download**（source_file）：import { mkdir, writeFile } from \"node:fs/promises\"; import { join, dirname as nodeDirname } from \"node:path\"; import { downloadGithubFolder, fetchTextContent, listGithubDirectoryRecursive, resolveGithubFolderUrl, } from \"./download.js\"; import { analyzeTreeEntries, basename, dirname, toRelativePath } from \"./generate.js\"; import { logInfo, parseUrl } from \"./utils.js\"; 证据：`src/cmd_download.ts`\n- **Cmd Generate**（source_file）：import { access, writeFile } from \"node:fs/promises\"; import { constants } from \"node:fs\"; import { join } from \"node:path\"; import { createInterface } from \"node:readline/promises\"; import { stdin as input, stdout as output } from \"node:process\"; import { Fibers } from \"ts-fibers\"; import type { GithubDirectoryLocation } from \"./utils.js\"; import { logInfo, logWarning, parseMarkdownFrontMatterFields, parseUrl } from \"./utils.js\"; import { fetchTextContent, listGithubDirectoryRecursive, resolveGithubFolderUrl, type GithubContentEntry, } from \"./download.js\"; import { analyzeTreeEntries, basename, dirname, formatGithubFileUrl, formatGithubFolderUrl, type DirectorySummary, } from \"./generate.… 证据：`src/cmd_generate.ts`\n- **Config**（source_file）：import { cac } from \"cac\"; import { logInfo, normalizeGithubRawUrl } from \"./utils.js\"; import pkg from \"../package.json\"; 证据：`src/config.ts`\n- **Constants**（source_file）：export const SUGGEST TOOL NAME = \"suggest skills\"; export const DOWNLOAD TOOL NAME = \"download skill\"; export const FETCH MANIFEST TOOL NAME = \"fetch manifest\"; 证据：`src/constants.ts`\n- **Core**（source_file）：import { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\"; import as z from \"zod/v4\"; import type { SuggestSkillsConfig } from \"./config.js\"; import { buildSuggestionResponse } from \"./suggest.js\"; import { downloadGithubFolder, fetchManifestText } from \"./download.js\"; import { normalizeGithubRawUrl } from \"./utils.js\"; import pkg from \"../package.json\"; import { SUGGEST TOOL NAME, toolDescriptions, DOWNLOAD TOOL NAME, FETCH MANIFEST TOOL NAME } from \"./constants.js\"; 证据：`src/core.ts`\n- **Download**（source_file）：import { Fibers } from \"ts-fibers\"; import type { GithubDirectoryLocation } from \"./utils.js\"; import { normalizeGithubRawUrl, parseGithubDirectoryUrl, parseUrl, } from \"./utils.js\"; 证据：`src/download.ts`\n- **Generate**（source_file）：import type { GithubContentEntry } from \"./download.js\"; import type { GithubDirectoryLocation } from \"./utils.js\"; 证据：`src/generate.ts`\n- **Http**（source_file）：import { WebStandardStreamableHTTPServerTransport } from \"@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js\"; import type { Server } from \"bun\"; import type { SuggestSkillsConfig } from \"./config.js\"; import { createServer } from \"./core.js\"; import { logError } from \"./utils.js\"; 证据：`src/http.ts`\n- **Index**（source_file）：import { ConfigError, parseCli } from \"./config.js\"; import { runDownloadCommand } from \"./cmd download.js\"; import { runGenerateCommand } from \"./cmd generate.js\"; import { startHttpServer } from \"./http.js\"; import { startStdioServer } from \"./stdio.js\"; import { logError } from \"./utils.js\"; 证据：`src/index.ts`\n- **Stdio**（source_file）：import { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\"; import type { SuggestSkillsConfig } from \"./config.js\"; import { createServer } from \"./core.js\"; 证据：`src/stdio.ts`\n- **Suggest Skills**（source_file）：import type { SuggestSkillsConfig } from \"./config.js\"; import { DOWNLOAD TOOL NAME, FETCH MANIFEST TOOL NAME } from \"./constants.js\"; 证据：`src/suggest.ts`\n- **Utils**（source_file）：export type GithubDirectoryLocation = { owner: string; repo: string; ref: string; path: string; }; 证据：`src/utils.ts`\n- **Cmd Download.Test**（source_file）：import { parseCli } from \"../src/config.js\"; import { expect, test, describe } from \"bun:test\"; 证据：`test/cmd_download.test.ts`\n- **The \"Solace\" Design System**（source_file）：import { describe, expect, mock, test } from \"bun:test\"; import { join } from \"node:path\"; import { generateOutputs, generateSkillsManifest, writeGeneratedManifest, type GeneratedDocument, } from \"../src/cmd generate.js\"; 证据：`test/cmd_generate.test.ts`\n- **Config.Test**（source_file）：import { describe, expect, test } from \"bun:test\"; import type { JSONRPCMessage } from \"@modelcontextprotocol/sdk/types.js\"; import { parseCli } from \"../src/config.js\"; import { createHttpApp } from \"../src/http.js\"; import { logInfo } from \"../src/utils.js\"; 证据：`test/config.test.ts`\n- **Download.Test**（source_file）：import { afterEach, beforeEach, describe, expect, mock, test } from \"bun:test\"; import { downloadGithubFolder, fetchManifestText, clearManifestCache } from \"../src/download.js\"; 证据：`test/download.test.ts`\n- **Index.Test**（source_file）：import { describe, expect, test } from \"bun:test\"; 证据：`test/index.test.ts`\n- **Title**（source_file）：import { describe, expect, test } from \"bun:test\"; import { extractMarkdownFrontMatter, parseMarkdownFrontMatterFields, } from \"../src/utils.js\"; 证据：`test/utils.test.ts`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `package.json`, `CHANGELOG.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `package.json`, `CHANGELOG.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目介绍**：importance `high`\n - source_paths: README.md, package.json, src/index.ts\n- **核心特性**：importance `high`\n - source_paths: README.md, src/suggest.ts, src/download.ts\n- **系统架构**：importance `high`\n - source_paths: src/index.ts, src/config.ts, src/core.ts, src/stdio.ts, src/http.ts\n- **项目结构**：importance `medium`\n - source_paths: src/index.ts, src/config.ts, src/constants.ts, src/utils.ts\n- **MCP 工具**：importance `high`\n - source_paths: src/core.ts, src/suggest.ts, src/download.ts\n- **传输模式**：importance `high`\n - source_paths: src/stdio.ts, src/http.ts, src/index.ts\n- **Generate 命令**：importance `high`\n - source_paths: src/cmd_generate.ts, src/generate.ts\n- **Server 命令**：importance `high`\n - source_paths: src/cmd_download.ts, src/http.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `331c05789446d59171abaf53b4b80208eb65dd55`\n- inspected_files: `package.json`, `README.md`, `src/utils.ts`, `src/generate.ts`, `src/stdio.ts`, `src/cmd_generate.ts`, `src/constants.ts`, `src/cmd_download.ts`, `src/index.ts`, `src/config.ts`, `src/http.ts`, `src/download.ts`, `src/suggest.ts`, `src/core.ts`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 可能修改宿主 AI 配置\n\n- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Evidence: capability.host_targets | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | host_targets=mcp_host, claude\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：v1.0.1\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.0.1\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_e40d7a86377b444f8d3eca5e8ec2b1a4 | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.0.1 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：v1.1.1\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.1.1\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_d9b5403807304a33aaf39f02f80d14be | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.1.1 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：v1.2.1\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.2.1\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_452c2fc3dc7d4409a8e1a4ae5419599f | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.2.1 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：v1.3.1\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.3.1\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_7cf71c15b4c64e7297db646b5300ba29 | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.3.1 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：v1.0.2\n\n- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.0.2\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_2150c52f85274793bfce6c1d64d24f66 | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.0.2 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：v1.0.3\n\n- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.0.3\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_ac612b4c6cd44d2194d9df8b4c026220 | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.0.3 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：v2.0.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v2.0.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_bc9655e0f7c54b22a783ef99c7841b5e | https://github.com/sator-imaging/suggest-skills/releases/tag/v2.0.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 维护活跃度未知\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:1220908449 | https://github.com/sator-imaging/suggest-skills | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：sator-imaging/suggest-skills\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host, claude\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 可能修改宿主 AI 配置（medium）：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 来源证据：v1.0.1（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v1.1.1（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v1.2.1（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/sator-imaging/suggest-skills 项目说明书\n\n生成时间：2026-05-13 13:58:02 UTC\n\n## 目录\n\n- [项目介绍](#project-introduction)\n- [核心特性](#key-features)\n- [系统架构](#system-architecture)\n- [项目结构](#project-structure)\n- [MCP 工具](#mcp-tools)\n- [传输模式](#transport-modes)\n- [Generate 命令](#generate-command)\n- [Server 命令](#server-command)\n- [配置指南](#configuration-guide)\n- [部署指南](#deployment-guide)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[核心特性](#key-features), [系统架构](#system-architecture)\n\n]\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n- [package.json](https://github.com/sator-imaging/suggest-skills/blob/main/package.json)\n- [src/index.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/index.ts)\n- [src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)\n- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)\n- [src/cmd_generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/cmd_generate.ts)\n \n\n# 项目介绍\n\n`suggest-skills` 是一个用于管理和发现 AI Agent 技能（Skills）的工具项目。该项目通过 MCP（Model Context Protocol）协议提供技能建议功能，支持从 GitHub 仓库自动扫描、本地安装以及远程技能清单管理。\n\n## 项目概述\n\n`suggest-skills` 的核心功能是帮助 AI Agent 智能地发现和推荐可用的技能扩展包。用户可以通过配置技能清单（manifest）URL，系统会自动扫描本地已安装的技能，并与远程清单进行对比，最终呈现可用的技能建议列表。\n\n资料来源：[README.md]()\n\n### 主要特性\n\n| 特性 | 描述 |\n|------|------|\n| MCP 协议支持 | 提供符合 MCP 标准的工具接口 |\n| 多模式运行 | 支持 stdio 模式和 HTTP 服务器模式 |\n| GitHub 集成 | 可从 GitHub 仓库自动发现和下载技能 |\n| 清单生成 | 支持从 GitHub 目录递归扫描生成技能清单 |\n| 多格式配置 | 支持 JSON、逗号分隔、换行分隔的环境变量配置 |\n\n资料来源：[README.md]()\n\n## 技术栈\n\n项目采用现代 TypeScript 技术栈构建，主要依赖包括：\n\n```json\n{\n \"dependencies\": {\n \"@modelcontextprotocol/sdk\": \"^1.0.0\",\n \"zod\": \"^3.23.8\"\n },\n \"devDependencies\": {\n \"bun\": \"latest\"\n }\n}\n```\n\n| 技术组件 | 用途 |\n|----------|------|\n| Bun | JavaScript 运行时和打包工具 |\n| TypeScript | 类型安全的开发语言 |\n| @modelcontextprotocol/sdk | MCP 协议 SDK 实现 |\n| Zod | 运行时配置验证 |\n\n资料来源：[package.json]()\n\n## 架构设计\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[Config 配置] --> B[MCP 工具注册]\n B --> C[stdio 传输模式]\n B --> D[HTTP 传输模式]\n \n E[CLI generate 命令] --> F[GitHub 目录扫描]\n F --> G[生成 manifest markdown]\n \n H[GitHub URL 规范化] --> I[文件夹下载]\n I --> F\n```\n\n项目架构分为两个主要入口：\n\n1. **MCP 服务器模式**：通过 `Config` 配置驱动的 MCP 工具服务\n2. **CLI 生成模式**：命令行工具用于扫描 GitHub 仓库生成技能清单\n\n资料来源：[README.md]()\n\n### 模块职责\n\n| 模块 | 文件路径 | 职责 |\n|------|----------|------|\n| 配置模块 | `src/config.ts` | 环境变量验证与解析 |\n| MCP 工具 | `src/index.ts` | 工具注册与请求处理 |\n| 下载功能 | `src/download.ts` | GitHub 仓库文件下载 |\n| 生成功能 | `src/generate.ts` | 技能清单生成逻辑 |\n| CLI 命令 | `src/cmd_generate.ts` | 命令行参数解析与输出 |\n\n资料来源：[src/download.ts](), [src/generate.ts](), [src/cmd_generate.ts]()\n\n## MCP 工具接口\n\n### suggest_skills\n\n主动建议可用技能的主工具。\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| manifestUrl | string | 否 | 覆盖默认配置的清单 URL |\n\n返回说明：生成一条指令负载，指导 Agent 如何获取可用技能列表、对比本地与远程能力、以及呈现建议。\n\n资料来源：[README.md]()\n\n### fetch_manifest\n\n获取指定清单文件内容。\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| manifestUrl | string | 是 | 技能清单的 GitHub URL |\n\n返回内容：清单文件的完整文本内容。\n\n资料来源：[README.md]()\n\n### download_skill\n\n下载指定 GitHub 文件夹中的所有文件。\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| url | string | 是 | GitHub 文件夹 URL |\n\n返回内容：文件夹中每个文件的路径、UTF-8 文本内容。符号链接会被解析并递归下载。\n\n资料来源：[README.md](), [src/download.ts]()\n\n## 下载流程实现\n\n### GitHub API 调用\n\n项目使用 GitHub Contents API 和 Git Trees API 来获取仓库内容：\n\n```mermaid\nsequenceDiagram\n 参与者 A as 用户请求\n 参与者 G as GitHub API\n 参与者 L as 本地处理\n \n A->>G: 请求目录内容\n G-->>L: 返回 tree 结构\n L->>L: 解析路径并过滤\n L->>G: 获取文件下载 URL\n G-->>A: 返回文件内容\n```\n\n资料来源：[src/download.ts]()\n\n### 路径解析逻辑\n\n下载模块的核心路径处理逻辑位于 `buildContentsApiUrl` 和 `buildTreeApiUrl` 函数中：\n\n```typescript\nfunction buildContentsApiUrl(location: GithubDirectoryLocation): string {\n const pathSuffix = location.path\n .split(\"/\")\n .filter(Boolean)\n .map((part) => encodeURIComponent(part))\n .join(\"/\");\n // 构建 API 路径并添加 ref 参数\n}\n```\n\n关键处理步骤：\n1. 过滤空路径段\n2. 对每个路径段进行 URL 编码\n3. 拼接为标准 GitHub API 路径\n4. 设置 `ref` 参数指定分支/提交\n\n资料来源：[src/download.ts]()\n\n## 清单生成功能\n\n### generate 命令工作流\n\n```mermaid\ngraph LR\n A[GitHub URL] --> B[目录扫描]\n B --> C[识别 SKILL.md]\n B --> D[识别 DESIGN.md]\n B --> E[收集资产文件]\n \n C --> F[生成 skills.md]\n D --> G[生成 designs.md]\n E --> F\n E --> G\n```\n\n生成模式下，系统会：\n1. 递归扫描 GitHub 目录结构\n2. 识别包含 `SKILL.md` 的技能目录\n3. 识别包含 `DESIGN.md` 的设计目录\n4. 收集目录中的其他资产文件\n5. 生成格式化的 Markdown 清单文件\n\n资料来源：[src/generate.ts](), [README.md]()\n\n### 生成选项\n\n| 选项 | 简写 | 描述 |\n|------|------|------|\n| --recursive, -r | 递归扫描子目录 | |\n| --output, -o | 指定输出目录 | 默认输出到 `.agents/skills` |\n\n资料来源：[README.md]()\n\n### 输出文件类型\n\n| 文件类型 | 内容 | 触发条件 |\n|----------|------|----------|\n| `..skills.md` | 技能条目列表 | 目录中包含 `SKILL.md` |\n| `..designs.md` | 设计条目列表 | 目录中包含 `DESIGN.md` |\n| `..agents.md` | Agent 条目列表 | 平面化顶级 markdown 文件 |\n\n资料来源：[README.md]()\n\n## 配置管理\n\n### 环境变量配置\n\n| 变量名 | 必需 | 描述 |\n|--------|------|------|\n| `GITHUB_PAT` | 否 | GitHub 个人访问令牌，用于认证请求 |\n| `SUGGEST_SKILLS_MANIFEST_URLS` | 是 | 技能清单 URL 列表 |\n\n清单 URL 支持三种格式：\n\n| 格式 | 示例 |\n|------|------|\n| JSON 数组 | `[\"https://example.com/manifest.md\"]` |\n| 逗号分隔 | `https://a.com/1.md,https://b.com/2.md` |\n| 换行分隔 | `https://a.com/1.md\\nhttps://b.com/2.md` |\n\n资料来源：[README.md]()\n\n### 启动模式\n\n#### stdio 模式\n\n标准输入输出模式，适合本地集成：\n\n```bash\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://some/skill-manifest.md\"]' \\\n npx suggest-skills\n```\n\n#### HTTP 服务器模式\n\n提供 HTTP API 端点，适合远程访问：\n\n```bash\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://some/skill-manifest.md\"]' \\\n npx suggest-skills server --port 3100\n```\n\n| 端点 | 路径 | 描述 |\n|------|------|------|\n| MCP 服务 | `/mcp` | 主要的 MCP 协议端点 |\n| 健康检查 | `/health` | 服务健康状态检查 |\n\n资料来源：[README.md]()\n\n## 代码规范\n\n项目遵循以下编码标准：\n\n| 规范 | 说明 |\n|------|------|\n| 模块化设计 | 小而专注的模块，按运行时关注点拆分文件 |\n| 配置验证 | 通过 `ConfigError` 进行显式配置验证 |\n| 类型安全 | 使用 Zod 进行运行时类型验证 |\n| 结构化输出 | MCP 工具使用类型化 Schema 和结构化返回 |\n| 传输层抽象 | 最小化传输层封装，围绕共享服务器创建 |\n\n资料来源：[README.md]()\n\n## 使用示例\n\n### 快速开始\n\n1. **配置环境变量**：\n ```bash\n export SUGGEST_SKILLS_MANIFEST_URLS='[\"https://raw.githubusercontent.com/anthropics/skills/main/skills/skills.md\"]'\n ```\n\n2. **运行 MCP 服务器**：\n ```bash\n npx suggest-skills server --port 3100\n ```\n\n3. **生成技能清单**：\n ```bash\n npx suggest-skills generate \\\n https://github.com/OWNER/REPO/tree/main/skills\n ```\n\n### 递归扫描示例\n\n生成包含子目录的完整清单：\n\n```bash\nnpx suggest-skills generate \\\n --recursive \\\n https://github.com/OWNER/REPO/tree/main/skills\n```\n\n这会生成以下文件：\n- `...skills.md`\n- `...designs.md`\n\n资料来源：[README.md]()\n\n## 相关资源\n\n| 资源 | 链接 |\n|------|------|\n| 官方技能库 | [official/skills](./official/skills) |\n| 社区技能库 | [community/skills](./community/skills) |\n| MCP 协议文档 | [@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk) |\n\n---\n\n\n\n## 核心特性\n\n### 相关页面\n\n相关主题：[项目介绍](#project-introduction), [MCP 工具](#mcp-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n- [src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)\n- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)\n- [官方 Skills 清单](https://github.com/anthropics/skills)\n- [OpenAI Skills 清单](https://github.com/openai/skills)\n \n\n# 核心特性\n\n`suggest-skills` 是一个基于 MCP（Model Context Protocol）的技能推荐与管理系统，旨在帮助 AI 代理（Agent）发现、安装和管理来自各类 GitHub 仓库的技能扩展包。本项目采用现代化的技术栈构建，支持灵活的配置方式和多种运行模式。\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n subgraph 配置层\n A[环境变量配置] --> B[Config 验证模块]\n B --> C[ConfigError 异常处理]\n end\n \n subgraph 核心功能层\n D[MCP 工具注册] --> E[suggest_skills]\n D --> F[fetch_manifest]\n D --> G[download_skill]\n end\n \n subgraph 传输层\n H[stdio 传输] \n I[HTTP 传输]\n end\n \n subgraph GitHub 交互层\n J[目录扫描] --> K[SKILL.md 发现]\n J --> L[DESIGN.md 发现]\n J --> M[manifest 生成]\n end\n \n B --> D\n E --> J\n F --> M\n G --> J\n D --> H\n D --> I\n```\n\n### 技术栈\n\n| 技术组件 | 用途说明 |\n|---------|---------|\n| Bun | JavaScript 运行时与打包工具 |\n| TypeScript | 类型安全与开发体验 |\n| @modelcontextprotocol/sdk | MCP 协议实现 |\n| Zod | 配置验证与类型推断 |\n\n资料来源：[README.md:技术栈]()\n\n## MCP 工具集\n\n项目提供三个核心 MCP 工具，供 AI 代理调用以实现技能管理功能。\n\n### 工具功能总览\n\n| 工具名称 | 功能描述 | 输入参数 |\n|---------|---------|---------|\n| `suggest_skills` | 生成技能推荐指令负载 | `manifestUrl`（可选） |\n| `fetch_manifest` | 获取技能清单文本内容 | `manifestUrl` |\n| `download_skill` | 下载指定 GitHub 文件夹的所有文件 | GitHub 文件夹 URL |\n\n### suggest_skills 工具\n\n该工具是系统的核心入口点，负责生成指令负载，指导 AI 代理完成以下任务：\n\n- 从配置的 manifest 文件获取可用技能列表\n- 扫描本地已安装的技能\n- 对比远程与本地能力差异\n- 在用户请求前不执行任何安装操作\n\n```mermaid\ngraph LR\n A[调用 suggest_skills] --> B{是否指定 manifestUrl?}\n B -->|是| C[使用指定 URL]\n B -->|否| D[使用环境变量配置的默认 URL]\n C --> E[生成指令负载]\n D --> E\n E --> F[返回技能发现/推荐指导]\n```\n\n### fetch_manifest 工具\n\n用于获取远程技能清单的原始文本内容，支持自定义技能仓库的 manifest 文件获取。\n\n### download_skill 工具\n\n该工具实现 GitHub 目录的递归下载功能，支持以下特性：\n\n- 接收标准 GitHub 树形 URL 格式：`https://github.com///tree/[/`\n- 返回文件夹内所有文件及其相对路径\n- 自动处理文件 symlink（当 GitHub 提供 `download_url` 时）\n- 解析仓库相对目录 symlink 并递归下载\n\n资料来源：[README.md:MCP Tools]()\n\n## 技能清单生成\n\n### 生成工作流程\n\n```mermaid\ngraph TD\n A[CLI: npx suggest-skills generate] --> B[接收 GitHub URL]\n B --> C{是否指定 --recursive?}\n C -->|是| D[递归扫描目录树]\n C -->|否| E[扫描当前层级]\n D --> F[发现 SKILL.md 文件]\n E --> F\n F --> G[发现 DESIGN.md 文件]\n G --> H[汇总同目录资产文件]\n H --> I[生成清单文件]\n \n I --> J[.skills.md]\n I --> K[.designs.md]\n I --> L[.agents.md]\n```\n\n### 生成规则\n\n| 规则类型 | 说明 |\n|---------|------|\n| 目录发现 | 使用递归树形列表 API 进行 GitHub 目录扫描 |\n| 文件识别 | `SKILL.md` 和 `DESIGN.md` 在技能目录中识别 |\n| 资产打包 | 同目录及嵌套子目录中的其他文件视为资产 |\n| Symlink 处理 | 发现时不作特殊处理，可能出现在资产列表中 |\n| 空输出跳过 | 空生成结果不写入文件，不显示覆盖提示 |\n\n### 输出文件类型\n\n| 文件后缀 | 内容来源 | 文件格式 |\n|---------|---------|---------|\n| `.[.].skills.md` | 包含 `SKILL.md` 的目录 | Markdown 表格 |\n| `.[.].designs.md` | 包含 `DESIGN.md` 的目录 | Markdown 表格 |\n| `.[.].agents.md` | 平面顶级 Markdown 文件 | Name + Description 列 |\n\n资料来源：[README.md:Generate a Manifest]()\n资料来源：[src/generate.ts:SKILL.md/DESIGN.md 发现逻辑]()\n\n## 配置管理\n\n### 环境变量配置\n\n| 环境变量 | 必填 | 用途 |\n|---------|-----|------|\n| `GITHUB_PAT` | 否 | 访问 GitHub API 的个人访问令牌 |\n| `SUGGEST_SKILLS_MANIFEST_URLS` | **是** | 技能清单 URL 列表 |\n\n`SUGGEST_SKILLS_MANIFEST_URLS` 支持三种格式：\n- JSON 数组：`[\"url1\", \"url2\"]`\n- 逗号分隔字符串：`url1,url2`\n- 换行分隔字符串：`url1\\nurl2`\n\n> **注意**：GitHub `blob` URL 会自动转换为 `raw.githubusercontent.com` URL。\n\n资料来源：[README.md:Environment Variables]()\n\n### 配置验证\n\n系统通过 `ConfigError` 异常类实现显式配置验证，确保：\n\n- 至少配置一个 manifest URL\n- URL 格式正确\n- 环境变量解析成功\n\n```mermaid\nstateDiagram-v2\n [*] --> 加载环境变量\n 加载环境变量 --> 验证配置\n 验证配置 --> 配置有效: 通过\n 验证配置 --> ConfigError: 失败\n 配置有效 --> MCP 工具注册\n ConfigError --> [*]\n```\n\n## 运行模式\n\n### stdio 模式\n\n适用于本地集成和管道通信场景：\n\n```bash\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://some/skill-manifest.md\"]' \\\n npx suggest-skills\n```\n\n### HTTP 模式\n\n适用于分布式部署和远程服务场景：\n\n```bash\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://some/skill-manifest.md\"]' \\\n npx suggest-skills server --port 3100\n```\n\n| 端点 | 路径 | 用途 |\n|-----|------|------|\n| MCP 端点 | `http://localhost:3100/mcp` | MCP 协议通信 |\n| 健康检查 | `http://localhost:3100/health` | 服务状态监控 |\n\n资料来源：[README.md:Run in stdio Mode]()\n资料来源：[README.md:Run in HTTP Mode]()\n\n## GitHub API 交互\n\n### API 端点构建\n\n项目封装了多个 GitHub API URL 构建函数：\n\n| 函数 | 功能 |\n|-----|------|\n| `buildContentsApiUrl` | 构建 Contents API URL |\n| `buildTreeApiUrl` | 构建 Tree API URL（支持递归） |\n| `buildGithubRawUrl` | 构建 Raw 文件访问 URL |\n\n### 目录扫描数据结构\n\n```typescript\ninterface ContentEntry {\n path: string; // 文件相对路径\n download_url: string | null; // 下载 URL（文件）或 null（目录）\n type: \"file\" | \"dir\"; // 条目类型\n}\n```\n\n### 路径解析规则\n\n1. 解析 GitHub 目录位置信息（owner、repo、ref、path）\n2. 将相对路径与基础路径拼接\n3. 去除前导斜杠确保路径一致性\n4. 递归处理树形结构\n\n```mermaid\ngraph LR\n A[GitHub Tree API 响应] --> B[遍历 entries]\n B --> C{entry.type === 'tree'?}\n C -->|是| D[创建 dir 条目]\n C -->|否| E[entry.type === 'blob'?]\n E -->|是| F[构建 download_url]\n F --> G[创建 file 条目]\n E -->|否| H[跳过]\n D --> I[返回 ContentEntry 数组]\n G --> I\n```\n\n资料来源：[src/download.ts:ContentEntry 类型定义]()\n资料来源：[src/download.ts:buildContentsApiUrl 函数]()\n\n## CLI 选项\n\n| 选项 | 全写形式 | 说明 |\n|-----|---------|------|\n| `-o ` | `--output ` | 技能安装输出目录 |\n| `generate [-r\\|--recursive]` | 生成模式 | 从 GitHub 技能目录生成清单 |\n| `server --port ` | 服务模式 | 启动 HTTP 服务器 |\n\n默认安装目录：`.agents/skills`\n\n## 代码组织规范\n\n项目遵循以下实现模式：\n\n| 规范类别 | 说明 |\n|---------|------|\n| 模块划分 | 小而专注的模块，按运行时关注点拆分 |\n| 配置验证 | 通过 ConfigError 实现显式验证 |\n| 类型安全 | 使用 Zod 进行工具 schema 验证和结构化输出 |\n| 传输封装 | 最小化传输层包装，围绕共享服务器创建 |\n| 测试策略 | 聚焦可观察行为而非实现细节 |\n\n资料来源：[README.md:Coding Standards]()\n\n## 与官方技能仓库集成\n\n项目内置支持从主流技能仓库生成清单和下载技能：\n\n### Anthropic 官方技能\n\n包含 40+ 个预构建技能，覆盖文档协作、Word 文档处理、PDF 操作、Figma 设计集成、Web 应用测试等领域。\n\n### OpenAI 精选技能\n\n包含 Notion 集成、Linear 项目管理、PDF 处理、Jupyter 笔记本、Figma 协作、Playwright 自动化测试、Vercel/Netlify 部署等企业级工具。\n\n### 社区技能\n\n汇集来自 ComposioHQ 等社区的精选技能，包括主题工厂、Twitter 算法优化、YouTube 下载器等实用工具。\n\n资料来源：[官方 Skills 清单]()\n资料来源：[OpenAI Skills 清单]()\n资料来源：[社区 Skills 清单]()\n\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目结构](#project-structure), [传输模式](#transport-modes)\n\n]\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/index.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/index.ts)\n- [src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)\n- [src/core.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/core.ts)\n- [src/stdio.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/stdio.ts)\n- [src/http.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/http.ts)\n- [src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)\n- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)\n- [src/cmd_generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/cmd_generate.ts)\n \n\n# 系统架构\n\n## 概述\n\n`suggest-skills` 是一个基于 Model Context Protocol (MCP) 的技能推荐与管理工具，旨在帮助 AI Agent 智能地发现、推荐和安装来自各种来源的技能扩展包。 资料来源：[README.md]()\n\n该项目的核心价值在于：**将分散在不同 GitHub 仓库中的技能清单（Manifest）聚合起来，为 Agent 提供统一的技能发现和安装接口**，而无需预先安装任何内容。\n\n## 技术栈\n\n| 技术 | 用途 |\n|------|------|\n| Bun | JavaScript/TypeScript 运行时与打包工具 |\n| TypeScript | 类型安全的开发语言 |\n| @modelcontextprotocol/sdk | MCP 协议实现与工具注册框架 |\n| Zod | 运行时配置验证 |\n\n资料来源：[README.md]()\n\n---\n\n## 整体架构\n\n`suggest-skills` 采用**分层模块化设计**，核心架构遵循以下数据流：\n\n```mermaid\ngraph TD\n A[配置文件
Config] --> B[MCP 工具注册
Tool Registration]\n B --> C{传输层选择}\n C --> D[stdio 模式
标准输入输出]\n C --> E[HTTP 模式
HTTP 服务器]\n \n F[CLI 命令] --> G[GitHub 目录扫描
目录树 API]\n G --> H[Manifest 生成器]\n H --> I[Markdown 清单文件]\n \n J[MCP 客户端] --> K[suggest_skills 工具]\n J --> L[fetch_manifest 工具]\n J --> M[download_skill 工具]\n```\n\n资料来源：[README.md](), [src/index.ts](), [src/stdio.ts](), [src/http.ts]()\n\n---\n\n## 核心模块解析\n\n### 1. 配置层 (Config)\n\n配置层负责加载和验证所有运行时参数，支持两种配置方式：\n\n| 配置方式 | 说明 |\n|----------|------|\n| 环境变量 | `SUGGEST_SKILLS_MANIFEST_URLS`、`GITHUB_PAT` |\n| CLI 参数 | `-o`、`--output`、`--port` 等 |\n\n**关键配置项：**\n\n| 变量名 | 必需 | 说明 |\n|--------|------|------|\n| `SUGGEST_SKILLS_MANIFEST_URLS` | 是 | Manifest URL 列表，支持 JSON 数组、逗号分隔、换行分隔 |\n| `GITHUB_PAT` | 否 | GitHub 个人访问令牌，用于认证请求 |\n| 输出目录 | 否 | 默认为 `.agents/skills` |\n\n支持的 URL 格式：\n- 普通 GitHub URL\n- GitHub `blob` URL（自动转换为 `raw.githubusercontent.com`）\n\n资料来源：[README.md](), [src/config.ts]()\n\n### 2. MCP 工具层 (Core)\n\nMCP 工具层是系统的核心业务逻辑，提供三个主要工具：\n\n| 工具名 | 功能 | 输入参数 |\n|--------|------|----------|\n| `suggest_skills` | 智能推荐技能 | 可选 `manifestUrl` 覆盖默认配置 |\n| `fetch_manifest` | 获取 Manifest 内容 | `manifestUrl` |\n| `download_skill` | 下载技能目录 | GitHub 文件夹 URL |\n\n**`suggest_skills` 工具的工作流程：**\n\n```mermaid\ngraph LR\n A[获取配置的 Manifest URLs] --> B[抓取远程技能列表]\n B --> C[扫描本地已安装技能]\n C --> D[对比远程与本地能力]\n D --> E[生成推荐指令]\n E --> F[展示建议
不自动安装]\n```\n\n资料来源：[README.md](), [src/core.ts]()\n\n### 3. 传输层 (Transport)\n\n传输层负责 MCP 服务器与客户端之间的通信，支持两种模式：\n\n#### 3.1 stdio 模式\n\n适用于本地 CLI 调用和终端交互场景。通过标准输入输出进行 JSON-RPC 通信。\n\n```bash\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://example.com/manifest.md\"]' \\\n npx suggest-skills\n```\n\n资料来源：[src/stdio.ts](), [README.md]()\n\n#### 3.2 HTTP 模式\n\n适用于远程部署和服务化场景，提供 HTTP 端点：\n\n| 端点 | 路径 | 说明 |\n|------|------|------|\n| MCP 协议端点 | `/mcp` | MCP 工具调用入口 |\n| 健康检查 | `/health` | 服务状态检查 |\n\n```bash\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://example.com/manifest.md\"]' \\\n npx suggest-skills server --port 3100\n```\n\n资料来源：[src/http.ts](), [README.md]()\n\n### 4. CLI 生成模块 (Generate)\n\nCLI 生成模块提供命令行工具，用于从 GitHub 仓库自动生成技能清单文件：\n\n```bash\n# 生成单个目录的清单\nnpx suggest-skills generate \\\n https://github.com/OWNER/REPO/tree/main/skills\n\n# 递归生成（含子目录）\nnpx suggest-skills generate --recursive \\\n https://github.com/OWNER/REPO/tree/main/skills\n```\n\n**生成的文件类型：**\n\n| 文件后缀 | 内容 | 发现规则 |\n|----------|------|----------|\n| `.skills.md` | 技能目录清单 | 包含 `SKILL.md` 的目录 |\n| `.designs.md` | 设计清单 | 包含 `DESIGN.md` 的目录 |\n| `.agents.md` | Agent 清单 | 平铺的顶层 Markdown 文件 |\n\n**生成模式规则：**\n\n```mermaid\ngraph TD\n A[GitHub 仓库 URL] --> B{是否包含路径?}\n B -->|是| C[扫描指定目录树]\n B -->|否| D[假设仓库根目录为技能目录]\n C --> E[递归遍历树结构]\n D --> E\n E --> F[发现 SKILL.md 或 DESIGN.md]\n F --> G[收集同目录资源文件]\n G --> H[生成 Markdown 表格]\n```\n\n资料来源：[src/generate.ts](), [src/cmd_generate.ts](), [README.md]()\n\n### 5. 下载模块 (Download)\n\n下载模块负责从 GitHub 仓库获取技能目录及其所有文件：\n\n```typescript\n// 核心数据结构\ninterface ContentEntry {\n path: string; // 相对路径\n download_url: string | null; // 文件下载链接\n type: \"file\" | \"dir\"; // 条目类型\n}\n```\n\n**GitHub API 调用策略：**\n\n| 步骤 | API | 用途 |\n|------|-----|------|\n| 1 | `/repos/{owner}/{repo}/git/trees/{sha}?recursive=1` | 获取目录树 |\n| 2 | `/repos/{owner}/{repo}/contents/{path}` | 获取文件内容 |\n\n资料来源：[src/download.ts]()\n\n---\n\n## 数据模型\n\n### Manifest URL 配置结构\n\n```mermaid\nclassDiagram\n class Config {\n +string[] manifestUrls\n +string? githubPat\n +string outputDir\n }\n \n class Manifest {\n +string url\n +Skill[] skills\n }\n \n class Skill {\n +string name\n +string description\n +string url\n +Asset[] bundledAssets\n }\n \n class Asset {\n +string path\n +string downloadUrl\n }\n \n Config --> Manifest : 引用\n Manifest --> Skill : 包含\n Skill --> Asset : 引用\n```\n\n### 生成的 Markdown 表格结构\n\n| 列 | 来源 | 说明 |\n|----|------|------|\n| Name | 目录名 | 链接到 GitHub 目录 |\n| Description | `SKILL.md`/`DESIGN.md` 首行或摘要 | 技能用途描述 |\n| Bundled Assets | 同目录其他文件 | 附带的资源文件 |\n\n资料来源：[src/cmd_generate.ts](), [src/generate.ts]()\n\n---\n\n## 入口点\n\n### 主入口 (index.ts)\n\n```mermaid\ngraph TD\n A[index.ts
主入口] --> B{命令行参数解析}\n B -->|generate| C[cmd_generate.ts
生成清单]\n B -->|server| D[http.ts
HTTP 服务器]\n B -->|stdio| E[stdio.ts
stdio 传输]\n B -->|默认| F[stdio.ts
stdio 传输]\n```\n\n资料来源：[src/index.ts]()\n\n---\n\n## 关键设计决策\n\n### 1. 惰性安装原则\n\n`suggest_skills` 工具**仅返回推荐指令**，不会自动安装任何内容。用户确认后，需单独触发安装流程。\n\n> \"Present suggestions without installing anything until requested\" 资料来源：[README.md]()\n\n### 2. 空输出跳过机制\n\n在生成清单时，如果某个类型没有任何条目，则不生成对应文件，也不显示覆盖确认提示。\n\n### 3. 符号链接处理\n\n生成模式中，符号链接会被发现并包含在资源列表中，但不会进行递归遍历。\n\n### 4. URL 自动转换\n\nGitHub `blob` 格式的 URL 会自动转换为 `raw.githubusercontent.com` 格式，便于直接获取原始内容。\n\n---\n\n## 模块依赖关系\n\n```mermaid\ngraph TD\n subgraph \"传输层\"\n stdio[stdio.ts
stdio 传输]\n http[http.ts
HTTP 服务器]\n end\n \n subgraph \"业务逻辑层\"\n core[core.ts
MCP 工具实现]\n download[download.ts
文件下载]\n generate[generate.ts
清单生成]\n cmd[cmd_generate.ts
CLI 命令]\n end\n \n subgraph \"基础设施层\"\n config[config.ts
配置管理]\n index[index.ts
入口调度]\n end\n \n config --> core\n config --> download\n config --> generate\n config --> cmd\n \n core --> download\n core --> stdio\n core --> http\n \n generate --> download\n cmd --> generate\n \n stdio --> index\n http --> index\n```\n\n---\n\n## 扩展性与可维护性\n\n该架构具备良好的扩展性：\n\n| 扩展方向 | 实现方式 |\n|----------|----------|\n| 新增 MCP 工具 | 在 `core.ts` 中注册 `Tool` 实例 |\n| 新增传输协议 | 实现 `Server` 接口并添加到 `index.ts` |\n| 新增 Manifest 来源 | 扩展 `config.ts` 中的 URL 解析逻辑 |\n| 新增文件格式支持 | 在 `generate.ts` 中添加 `DESIGN.md` 等文件类型识别 |\n\n---\n\n\n\n## 项目结构\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [Generate 命令](#generate-command)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/index.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/index.ts)\n- [src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)\n- [src/constants.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/constants.ts)\n- [src/utils.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/utils.ts)\n- [src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)\n- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)\n- [src/cmd_generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/cmd_generate.ts)\n \n\n# 项目结构\n\n## 概述\n\nsuggest-skills 是一个基于 Model Context Protocol (MCP) 的技能推荐与管理系统。该项目允许 AI Agent 发现、扫描并推荐可用的技能（Skills），同时支持从 GitHub 下载技能资源。项目的核心架构围绕 MCP 协议展开，通过标准化的工具接口实现远程与本地技能的能力对比与展示。\n\n资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n## 技术栈\n\n| 类别 | 技术/框架 |\n|------|----------|\n| 运行时 | Bun |\n| 开发语言 | TypeScript |\n| 协议层 | @modelcontextprotocol/sdk |\n| 数据验证 | Zod |\n\n资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n## 整体架构\n\n项目采用分层架构设计，核心流程为：配置层 → MCP 工具注册 → 传输层（stdio 或 HTTP）。同时提供独立的 CLI 工具用于生成技能清单。\n\n```mermaid\ngraph TD\n A[配置文件] --> B[MCP 工具注册]\n B --> C[stdio 传输模式]\n B --> D[HTTP 传输模式]\n E[CLI generate] --> F[GitHub 目录扫描]\n F --> G[生成 Manifest Markdown]\n H[下载技能] --> I[download_skill 工具]\n J[推荐技能] --> K[suggest_skills 工具]\n```\n\n资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n## 目录结构\n\n### 源码目录 (`src/`)\n\n| 文件 | 功能说明 |\n|------|----------|\n| `index.ts` | MCP 服务入口，工具注册与传输层初始化 |\n| `config.ts` | 配置管理与验证逻辑 |\n| `constants.ts` | 常量定义 |\n| `utils.ts` | 通用工具函数 |\n| `download.ts` | GitHub 目录下载功能 |\n| `generate.ts` | Manifest 生成器核心逻辑 |\n| `cmd_generate.ts` | CLI generate 命令实现 |\n\n### 技能清单目录\n\n| 目录 | 用途 |\n|------|------|\n| `official/` | 官方维护的技能清单 |\n| `community/` | 社区贡献的技能清单 |\n| `official/skills/` | 官方技能定义 |\n| `community/skills/` | 社区技能定义 |\n\n每个技能目录下应包含 `SKILL.md` 或 `DESIGN.md` 文件，用于描述技能的用途与触发条件。\n\n资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n## 核心模块\n\n### 配置模块 (`src/config.ts`)\n\n配置模块负责验证环境变量与命令行参数，确保 MCP 服务正常运行。\n\n**关键环境变量：**\n\n| 变量名 | 必需 | 说明 |\n|--------|------|------|\n| `GITHUB_PAT` | 否 | GitHub 个人访问令牌，用于认证请求 |\n| `SUGGEST_SKILLS_MANIFEST_URLS` | 是 | 技能清单 URL，支持 JSON 数组、逗号分隔或换行分隔格式 |\n\n**配置格式：**\n\n```json\n{\n \"manifestUrls\": [\"https://some/skill-manifest.md\"]\n}\n```\n\nGitHub `blob` URL 会自动转换为 `raw.githubusercontent.com` URL。\n\n资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n### GitHub 下载模块 (`src/download.ts`)\n\n该模块封装了 GitHub API 调用，实现目录内容的递归下载。\n\n**核心 API 交互：**\n\n```mermaid\ngraph LR\n A[buildContentsApiUrl] --> B[GET /repos/{owner}/{repo}/contents/{path}]\n C[buildTreeApiUrl] --> D[GET /repos/{owner}/{repo}/git/trees/{sha}?recursive=1]\n```\n\n**主要函数：**\n\n| 函数 | 功能 |\n|------|------|\n| `buildContentsApiUrl()` | 构建 GitHub Contents API URL |\n| `buildTreeApiUrl()` | 构建 GitHub Trees API URL（支持递归） |\n| `fetchDirectoryContents()` | 获取目录内容并解析为结构化条目 |\n\n资料来源：[src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)\n\n### Manifest 生成模块 (`src/generate.ts`)\n\n负责扫描技能目录并生成规范化的 Markdown 清单文件。\n\n**处理流程：**\n\n1. 遍历目录树，识别包含 `SKILL.md` 或 `DESIGN.md` 的目录\n2. 收集同目录下的其他资源文件作为 bundled assets\n3. 按目录层级组织输出\n\n```mermaid\ngraph TD\n A[遍历目录树] --> B{文件类型判断}\n B -->|SKILL.md| C[标记为技能目录]\n B -->|DESIGN.md| D[标记为设计目录]\n B -->|其他资源| E[加入 bundled assets]\n C --> F[按层级排序输出]\n D --> F\n```\n\n资料来源：[src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)\n\n### CLI 生成命令 (`src/cmd_generate.ts`)\n\n实现命令行工具的 generate 子命令，支持递归扫描和自定义输出目录。\n\n**CLI 选项：**\n\n| 选项 | 说明 |\n|------|------|\n| `-o `, `--output ` | 指定输出目录，默认为 `.agents/skills` |\n| `generate [-r\\|--recursive] ` | 从 GitHub URL 生成清单 |\n| `server --port ` | 启动 HTTP 服务器 |\n\n**生成的输出文件类型：**\n\n| 文件后缀 | 内容来源 |\n|----------|----------|\n| `.skills.md` | 包含 `SKILL.md` 的技能目录 |\n| `.designs.md` | 包含 `DESIGN.md` 的设计目录 |\n| `.agents.md` | 平面化顶级 Markdown 文件 |\n\n资料来源：[src/cmd_generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/cmd_generate.ts)\n\n## MCP 工具接口\n\n### suggest_skills\n\n推荐可用技能的 MCP 工具，根据用户需求返回相应的技能建议。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `manifestUrl` | string | 否 | 覆盖默认配置的清单 URL |\n\n**返回内容：**\n生成指令负载，指导 Agent 如何获取、扫描、对比远程与本地技能，并展示推荐结果。\n\n### fetch_manifest\n\n获取指定清单文件内容的工具。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `manifestUrl` | string | 是 | 清单文件的 URL |\n\n### download_skill\n\n下载 GitHub 文件夹中的所有文件。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `url` | string | 是 | GitHub 文件夹 URL，格式：`https://github.com///tree/[/` |\n\n**返回内容：**\n文件夹内每个文件的相对路径、UTF-8 文本内容及类型信息。\n\n资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n## 传输模式\n\n### stdio 模式\n\n适用于本地进程间通信的标准化输入输出模式。\n\n```bash\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://some/skill-manifest.md\"]' \\\n npx suggest-skills\n```\n\n### HTTP 模式\n\n适用于网络化的 MCP 客户端连接。\n\n```bash\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://some/skill-manifest.md\"]' \\\n npx suggest-skills server --port 3100\n```\n\n**端点：**\n\n| 端点 | 路径 | 说明 |\n|------|------|------|\n| MCP 服务 | `/mcp` | MCP 协议端点 |\n| 健康检查 | `/health` | 服务健康状态 |\n\n资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n## 编码规范与设计原则\n\n项目遵循以下实现模式：\n\n| 原则 | 说明 |\n|------|------|\n| 模块化 | 小而专注的模块，按职责拆分文件 |\n| 配置验证 | 通过 `ConfigError` 进行显式验证 |\n| 类型安全 | 使用 Zod 验证工具模式和数据模型 |\n| 结构化输出 | MCP 工具使用类型化 Schema |\n| 传输抽象 | 最小化传输层封装，围绕共享服务构建 |\n\n资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n## 扩展方式\n\n### 贡献新技能\n\n1. 在 `community/skills/` 下创建技能目录\n2. 添加 `SKILL.md` 文件描述技能用途与触发条件\n3. 可选：添加相关资源文件作为 bundled assets\n\n### 添加新的清单源\n\n1. 在 `SUGGEST_SKILLS_MANIFEST_URLS` 中添加新的 URL\n2. 遵循现有的 Markdown 清单格式\n\n### 扩展 MCP 工具\n\n新工具应：\n- 在 `src/` 下创建独立的模块文件\n- 使用 Zod 定义输入输出 Schema\n- 在 `index.ts` 中注册到 MCP 服务\n\n---\n\n\n\n## MCP 工具\n\n### 相关页面\n\n相关主题：[传输模式](#transport-modes), [配置指南](#configuration-guide)\n\n]\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/core.ts)\n- [src/suggest.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/suggest.ts)\n- [src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)\n- [src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)\n- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)\n \n\n# MCP 工具\n\n## 概述\n\nMCP 工具是 `suggest-skills` 项目实现的核心功能模块，基于 Model Context Protocol (MCP) 标准提供技能建议、清单获取和技能下载能力。该模块作为 MCP 服务器运行，支持 `stdio` 和 HTTP 两种传输模式，使 AI 代理能够动态发现和推荐可用技能。\n\nMCP 工具的主要职责包括：\n- 从配置的清单 URL 获取远程技能目录\n- 扫描本地已安装的技能\n- 对比远程与本地能力差异\n- 向用户展示技能建议列表\n- 下载指定 GitHub 文件夹中的所有文件\n\n资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n## 架构概览\n\n```\nConfig -> MCP 工具注册 -> stdio 或 HTTP 传输\n```\n\n项目采用分层架构：\n- **配置层**：环境变量和命令行参数解析\n- **工具层**：三个核心 MCP 工具实现\n- **传输层**：stdio 和 HTTP 两种通信协议支持\n- **GitHub 交互层**：仓库扫描和文件下载\n\n技术栈：Bun、TypeScript、@modelcontextprotocol/sdk、Zod\n\n资料来源：[README.md:89-94](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n## 核心工具列表\n\n| 工具名称 | 功能描述 | 输入参数 |\n|---------|---------|---------|\n| `suggest_skills` | 生成技能建议指令负载，指导代理如何获取和推荐技能 | `manifestUrl`（可选） |\n| `fetch_manifest` | 获取指定清单 URL 的文本内容 | `manifestUrl`（必填） |\n| `download_skill` | 下载 GitHub 文件夹中的所有文件 | `url`（必填） |\n\n资料来源：[README.md:53-73](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n## suggest_skills 工具\n\n### 功能说明\n\n`suggest_skills` 是默认的技能推荐工具，返回一个生成的指令负载。该负载指示代理如何：\n\n1. 从配置的清单中获取可用技能\n2. 扫描本地已安装的技能\n3. 对比远程与本地的能力差异\n4. 展示建议而不自动安装\n\n### 参数定义\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|-----|------|\n| `manifestUrl` | string | 否 | 用于覆盖默认配置的清单 URL |\n\n### 返回值\n\n返回包含以下步骤的指令负载：\n- 获取清单中的技能列表\n- 本地技能扫描\n- 差异对比分析\n- 用户建议展示（仅在请求时安装）\n\n资料来源：[src/suggest.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/suggest.ts)\n\n## fetch_manifest 工具\n\n### 功能说明\n\n`fetch_manifest` 工具接受一个清单 URL 参数，返回该清单的完整文本内容。用于获取远程技能目录的详细描述。\n\n### 参数定义\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|-----|------|\n| `manifestUrl` | string | 是 | 技能清单的 GitHub URL |\n\n### 典型使用场景\n\n- 获取第三方技能仓库的清单\n- 动态更新本地缓存的技能列表\n- 跨仓库技能发现\n\n## download_skill 工具\n\n### 功能说明\n\n`download_skill` 工具用于下载 GitHub 文件夹中的所有文件，返回每个文件的相对路径、UTF-8 文本内容和符号链接信息。\n\n### 参数定义\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|-----|------|\n| `url` | string | 是 | GitHub 文件夹 URL，格式为 `https://github.com///tree/[/` |\n\n### 返回数据结构\n\n| 字段 | 类型 | 说明 |\n|-----|------|------|\n| `path` | string | 相对于请求文件夹的文件路径 |\n| `download_url` | string \\| null | 文件的直接下载 URL（目录为 null） |\n| `type` | \"file\" \\| \"dir\" | 条目类型 |\n\n### GitHub URL 解析\n\n工具内部通过以下步骤解析 GitHub 目录位置：\n\n```typescript\ninterface GithubDirectoryLocation {\n owner: string; // 仓库所有者\n repo: string; // 仓库名称\n ref: string; // 分支/标签/提交 SHA\n path: string; // 目录路径\n}\n```\n\n资料来源：[src/download.ts:1-50](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)\n\n## 工作流程图\n\n```mermaid\ngraph TD\n A[启动 MCP 服务器] --> B{传输模式}\n B -->|stdio| C[标准输入输出]\n B -->|HTTP| D[HTTP 端点 /mcp]\n C --> E[注册 MCP 工具]\n D --> E\n E --> F[suggest_skills]\n E --> G[fetch_manifest]\n E --> G --> H[获取清单文本]\n E --> I[download_skill]\n I --> J[解析 GitHub URL]\n J --> K[调用 GitHub Contents API]\n K --> L[递归获取目录树]\n L --> M[构建下载条目列表]\n M --> N[返回文件内容]\n```\n\n## 配置方式\n\n### 环境变量\n\n| 变量名 | 必填 | 说明 |\n|-------|-----|------|\n| `GITHUB_PAT` | 否 | GitHub 个人访问令牌，用于已认证请求 |\n| `SUGGEST_SKILLS_MANIFEST_URLS` | 是 | 至少包含一个 URL 的清单地址 |\n\n`SUGGEST_SKILLS_MANIFEST_URLS` 支持以下格式：\n- JSON 数组：`[\"https://example.com/manifest.md\"]`\n- 逗号分隔字符串：`\"url1,url2,url3\"`\n- 换行分隔字符串：`\"url1\\nurl2\\nurl3\"`\n\n### CLI 选项\n\n| 选项 | 说明 |\n|-----|------|\n| `-o ` / `--output ` | 安装技能的目标目录 |\n| `generate [-r\\|--recursive] ` | 从 GitHub 技能目录生成清单 |\n| `server --port ` | 运行 HTTP 服务器 |\n| `[...args]` | 以 stdio 模式运行（默认） |\n\n默认输出目录：`.agents/skills`\n\n资料来源：[src/config.ts:1-50](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)\n\n## HTTP 模式\n\nHTTP 服务器提供以下端点：\n\n| 端点 | 方法 | 说明 |\n|-----|------|------|\n| `/mcp` | POST | MCP 工具调用端点 |\n| `/health` | GET | 健康检查端点 |\n\n默认端口：3100\n\n### 启动命令\n\n```bash\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://example.com/manifest.md\"]' \\\n npx suggest-skills server --port 3100\n```\n\n## GitHub API 集成\n\n### API 端点\n\n| 功能 | API 端点 |\n|-----|---------|\n| 获取目录内容 | `/repos/{owner}/{repo}/contents/{path}` |\n| 获取目录树 | `/repos/{owner}/{repo}/git/trees/{tree_sha}?recursive=1` |\n\n### URL 转换\n\nGitHub `blob` URL 自动转换为 `raw.githubusercontent.com` URL：\n\n```typescript\nfunction normalizeGithubRawUrl(url: string): string | null {\n // 将 github.com/blob/ 转换为 raw.githubusercontent.com/\n}\n```\n\n资料来源：[src/download.ts:40-70](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)\n\n## 类型定义\n\n### ContentEntry\n\n```typescript\ninterface ContentEntry {\n path: string;\n download_url: string | null;\n type: \"file\" | \"dir\";\n}\n```\n\n### CliRuntimeMode\n\n```typescript\ntype CliRuntimeMode =\n | { kind: \"generate\"; url: string; recursive: boolean; config: Config }\n | { kind: \"download\"; url: string; recursive: boolean; config: Config }\n | { kind: \"server\"; port: number }\n | { kind: \"stdio\"; args: string[] };\n```\n\n### Config\n\n```typescript\ninterface Config {\n manifestUrls: string[];\n outputDirectory: string;\n githubPat?: string;\n}\n```\n\n## 清单文件格式\n\n清单文件为 Markdown 格式，支持以下结构：\n\n```markdown\n| 技能名称 | 描述 | 文件列表 |\n|---------|------|---------|\n| [skill-name](链接) | 功能说明 | `file1.md`, `assets/` |\n```\n\n生成模式自动扫描包含 `SKILL.md` 或 `DESIGN.md` 的目录。\n\n资料来源：[src/generate.ts:1-80](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)\n\n## 最佳实践\n\n### 1. 清单 URL 配置\n\n建议使用多个清单源以覆盖更广泛的技能库：\n\n```bash\nSUGGEST_SKILLS_MANIFEST_URLS='[\n \"https://raw.githubusercontent.com/anthropics/skills/main/README.md\",\n \"https://raw.githubusercontent.com/openai/skills/main/README.md\",\n \"https://raw.githubusercontent.com/sator-imaging/suggest-skills/main/README.md\"\n]'\n```\n\n### 2. 递归下载\n\n对于包含子目录的技能文件夹，使用 `--recursive` 选项确保完整下载：\n\n```bash\nnpx suggest-skills download --recursive \\\n https://github.com/owner/repo/tree/main/skills/my-skill\n```\n\n### 3. GitHub 认证\n\n当访问私有仓库或需要更高 API 限额时，配置 `GITHUB_PAT`：\n\n```bash\nGITHUB_PAT=ghp_xxx npx suggest-skills fetch_manifest\n```\n\n## 相关文档\n\n- [官方技能目录](../official/)\n- [社区技能](../community/)\n- [生成清单命令](./generate.md)\n- [下载技能命令](./download.md)\n\n---\n\n\n\n## 传输模式\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [部署指南](#deployment-guide)\n\n]\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/stdio.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/stdio.ts)\n- [src/http.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/http.ts)\n- [src/index.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/index.ts)\n- [src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)\n- [src/cli.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/cli.ts)\n \n\n# 传输模式\n\n## 概述\n\n`suggest-skills` 项目实现了 MCP (Model Context Protocol) 服务器，支持两种传输模式用于与 AI 代理进行通信。这两种模式分别为 **stdio 模式** 和 **HTTP 模式**，它们共享相同的核心功能和 MCP 工具集，仅在通信机制上有所不同。\n\n传输模式的选择直接影响工具调用方与应用服务器的交互方式：\n\n- **stdio 模式**：适用于本地进程通信，通过标准输入/输出流传递 JSON-RPC 消息\n- **HTTP 模式**：适用于网络远程调用，通过 HTTP REST API 提供 MCP 端点\n\n资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n## 架构设计\n\n### 传输层抽象\n\n项目采用传输层抽象设计，将核心业务逻辑与通信机制分离。配置层负责解析 CLI 参数并确定运行时模式，随后将控制权委托给对应的传输处理器。\n\n```mermaid\ngraph TD\n A[CLI 入口] --> B[配置解析]\n B --> C{运行时模式}\n C -->|stdio| D[stdio.ts]\n C -->|server| E[http.ts]\n D --> F[MCP 工具注册]\n E --> F\n F --> G[核心业务逻辑]\n G --> H[suggest_skills]\n G --> I[fetch_manifest]\n G --> J[download_skill]\n```\n\n资料来源：[src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)\n\n### 运行时模式类型\n\n`CliRuntimeMode` 联合类型定义了所有支持的运行时变体：\n\n| 模式 | 标识 | 用途 | 传输协议 |\n|------|------|------|----------|\n| `stdio` | 默认模式 | 本地进程通信 | stdin/stdout JSON-RPC |\n| `generate` | 生成模式 | 生成技能清单 | 仅 CLI |\n| `download` | 下载模式 | 下载技能资源 | 仅 CLI |\n| `server` | 服务模式 | HTTP 服务器 | HTTP/Streamable |\n\n资料来源：[src/config.ts:1-50](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)\n\n## stdio 模式\n\n### 工作原理\n\nstdio 模式是 MCP 协议的传统实现方式，服务器通过标准输入接收 JSON-RPC 请求，并通过标准输出返回响应消息。此模式无需网络配置，非常适合与本地 AI 代理进程集成。\n\n### 启动方式\n\nstdio 模式作为默认模式运行，当用户未指定任何子命令时自动激活：\n\n```bash\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://some/skill-manifest.md\"]' \\\n npx suggest-skills\n```\n\n环境变量 `SUGGEST_SKILLS_MANIFEST_URLS` 为必需配置，必须包含至少一个技能清单 URL。\n\n### 特性\n\n- **零网络依赖**：无需开放端口，完全在本地运行\n- **进程隔离**：每个会话创建独立进程\n- **低延迟**：直接内存通信，无网络开销\n- **标准化协议**：完全兼容 MCP JSON-RPC 规范\n\n资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n## HTTP 模式\n\n### 工作原理\n\nHTTP 模式启动一个基于 Streamable HTTP 的 MCP 服务器，支持远程调用和持久化连接。此模式适用于需要跨网络访问 MCP 工具的场景。\n\n### 端点配置\n\n| 端点 | 路径 | 功能 |\n|------|------|------|\n| MCP 主端点 | `/mcp` | 处理所有 MCP 协议请求 |\n| 健康检查 | `/health` | 服务状态验证 |\n\n### 启动方式\n\n使用 `server` 子命令启动 HTTP 服务器：\n\n```bash\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://some/skill-manifest.md\"]' \\\n npx suggest-skills server --port 3100\n```\n\n### 端口配置\n\n通过 `--port` 参数指定监听端口，默认情况下服务器绑定至 `0.0.0.0` 接受所有网络接口连接。\n\n### 特性\n\n- **远程访问**：支持跨网络调用 MCP 工具\n- **持久连接**：支持流式响应和连接复用\n- **健康监控**：内置健康检查端点便于运维监控\n- **REST 兼容**：基于标准 HTTP 协议，易于集成\n\n资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n## 配置管理\n\n### 环境变量\n\n| 变量名 | 必填 | 说明 |\n|--------|------|------|\n| `GITHUB_PAT` | 否 | GitHub API 认证令牌，用于提高 API 限制 |\n| `SUGGEST_SKILLS_MANIFEST_URLS` | 是 | 技能清单 URL，支持 JSON 数组、逗号分隔或换行分隔格式 |\n\n### 清单 URL 格式\n\n清单 URL 支持多种格式：\n\n```json\n[\"https://some/skill-manifest.md\"]\n```\n\n```text\nhttps://some/skill-manifest.md,https://other/skill-manifest.md\n```\n\nGitHub `blob` URL 会自动转换为 `raw.githubusercontent.com` URL。\n\n资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n## CLI 命令结构\n\n### 命令速查表\n\n| 命令 | 模式 | 说明 |\n|------|------|------|\n| `suggest-skills` | stdio | 默认启动 stdio 模式 |\n| `suggest-skills server` | http | 启动 HTTP 服务器 |\n| `suggest-skills generate ` | generate | 生成技能清单文档 |\n| `suggest-skills download ` | download | 下载技能资源 |\n\n### 全局选项\n\n- `-o, --output `：设置技能安装输出目录，默认为 `.agents/skills`\n\n### 生成模式选项\n\n- `-r, --recursive`：启用递归扫描子目录\n- `--url`：指定 GitHub 仓库路径\n\n### 服务器模式选项\n\n- `--port `：指定 HTTP 服务器监听端口\n\n资料来源：[src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)\n\n## MCP 工具集\n\n无论采用哪种传输模式，以下 MCP 工具均可用：\n\n### suggest_skills\n\n返回生成的指令负载，指导代理如何：\n\n- 获取已配置清单中的可用技能\n- 扫描本地已安装技能\n- 比较远程与本地能力\n- 在用户请求前呈现建议而不安装任何内容\n\n**参数**：`manifestUrl` (可选) - 覆盖默认配置的清单 URL\n\n### fetch_manifest\n\n获取指定清单 URL 的文本内容。\n\n**参数**：`manifestUrl` - 清单 URL\n\n### download_skill\n\n下载 GitHub 文件夹中的所有文件。\n\n**参数**：`url` - GitHub 文件夹 URL，格式为 `https://github.com///tree/[/`\n\n返回每个文件包含：\n\n- 相对于请求文件夹的路径\n- UTF-8 文本内容\n- 文件 symlink 的目标内容\n\n资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n## 模式选择指南\n\n```mermaid\ngraph TD\n A[开始] --> B{调用场景?}\n B -->|本地 AI 代理| C[stdio 模式]\n B -->|远程服务| D[HTTP 模式]\n B -->|生成清单| E[generate 模式]\n B -->|批量下载| F[download 模式]\n C --> G[低延迟隔离环境]\n D --> H[跨网络访问]\n E --> I[生成 markdown 文档]\n F --> J[获取技能文件]\n```\n\n### 选择建议\n\n| 场景 | 推荐模式 | 原因 |\n|------|----------|------|\n| Claude Code 本地集成 | stdio | 无网络开销，即插即用 |\n| 微服务架构 | HTTP | 支持远程调用和水平扩展 |\n| 持续集成流水线 | stdio | 进程生命周期清晰 |\n| Web 前端集成 | HTTP | 标准 REST 调用方式 |\n| 技能库迁移 | generate/download | 专用 CLI 功能 |\n\n## 技术栈\n\n项目使用的核心技术：\n\n| 技术 | 用途 |\n|------|------|\n| TypeScript | 主开发语言 |\n| Bun | 运行时和打包工具 |\n| @modelcontextprotocol/sdk | MCP 协议实现 |\n| Zod | 配置验证和类型安全 |\n\n资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n\n## 最佳实践\n\n### 环境配置\n\n```bash\n# 生产环境建议\nexport GITHUB_PAT=\"your_personal_access_token\"\nexport SUGGEST_SKILLS_MANIFEST_URLS='[\"https://raw.githubusercontent.com/anthropics/skills/main/skills/README.md\"]'\n```\n\n### 安全考量\n\n- HTTP 模式部署时应配置 TLS 终止\n- GitHub PAT 应存储在安全密钥管理系统中\n- 避免在日志中输出敏感配置信息\n\n### 性能优化\n\n- stdio 模式适合高频低延迟场景\n- HTTP 模式支持连接池和请求批处理\n- 大型仓库建议使用递归模式以获取完整技能树\n\n---\n\n\n\n## Generate 命令\n\n### 相关页面\n\n相关主题：[项目结构](#project-structure), [配置指南](#configuration-guide)\n\n]\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/cmd_generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/cmd_generate.ts)\n- [src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)\n- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)\n- [README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n \n\n# Generate 命令\n\n## 概述\n\nGenerate 命令是 suggest-skills 工具的核心功能之一，用于从 GitHub 仓库中扫描技能目录并生成标准化的 Markdown 清单文件。该命令通过递归扫描 GitHub 目录结构，自动发现包含 `SKILL.md`、`DESIGN.md` 的技能目录，并将其转换为可读的 Markdown 表格格式。\n\nGenerate 命令的主要职责包括：\n\n- 扫描指定的 GitHub 仓库或目录路径\n- 递归发现技能定义文件\n- 收集每个技能的元数据（名称、描述、关联资产）\n- 生成格式化的 Markdown 清单文件\n- 支持可选的递归扫描模式\n\n## 命令行接口\n\n### 基本语法\n\n```bash\nnpx suggest-skills generate \n```\n\n### 递归扫描模式\n\n```bash\nnpx suggest-skills generate \\\n --recursive \\\n https://github.com/OWNER/REPO/tree/main/skills\n```\n\n### 参数说明\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `` | string | 是 | GitHub 仓库或目录的 URL |\n| `-r, --recursive` | flag | 否 | 启用递归扫描模式，扫描所有子目录 |\n\n## 工作流程\n\n```mermaid\ngraph TD\n A[用户执行 generate 命令] --> B[解析 GitHub URL]\n B --> C{是否为递归模式?}\n C -->|是| D[使用 Tree API 递归获取目录结构]\n C -->|否| E[使用 Contents API 获取单层目录]\n D --> F[扫描 SKILL.md 和 DESIGN.md 文件]\n E --> F\n F --> G[收集技能条目和资产信息]\n G --> H[格式化 Markdown 表格]\n H --> I[生成输出文件]\n I --> J[写入 ...skills.md]\n I --> K[写入 ...designs.md]\n I --> L[写入 ...agents.md]\n```\n\n## 输出文件\n\n执行 generate 命令后，会在当前工作目录生成以下文件：\n\n| 文件类型 | 命名格式 | 内容描述 |\n|----------|----------|----------|\n| 技能清单 | `.[.].skills.md` | 包含 `SKILL.md` 的目录条目 |\n| 设计清单 | `.[.].designs.md` | 包含 `DESIGN.md` 的目录条目 |\n| 代理清单 | `.[.].agents.md` | 顶层 markdown 文件（仅含 Name 和 Description 列） |\n\n### 生成的 Markdown 格式\n\n```markdown\n| Name | Description |\n| -----|-------------|\n| [skill-name](url) | skill description |\n```\n\n当启用资产包含选项时，格式扩展为：\n\n```markdown\n| Name | Description | Bundled Assets |\n| -----|-------------|----------------|\n| [skill-name](url) | description | LICENSE.txt, scripts (5 files) |\n```\n\n## 源码架构\n\n### 核心模块职责\n\n| 模块 | 文件路径 | 职责 |\n|------|----------|------|\n| CLI 配置 | `src/config.ts` | 定义命令行参数解析和运行时模式 |\n| 生成逻辑 | `src/cmd_generate.ts` | 处理 Markdown 表格格式化和条目输出 |\n| 下载服务 | `src/download.ts` | 与 GitHub API 交互获取目录结构 |\n\n### 运行时模式定义\n\n```typescript\ninterface CliRuntimeMode {\n kind: \"generate\" | \"download\" | \"server\" | \"stdio\";\n url: string;\n recursive: boolean;\n config: {\n outputDirectory: string;\n sourceUrls: string[];\n };\n}\n```\n\n资料来源：[src/config.ts:32-38]()\n\n### 表格格式化流程\n\n```mermaid\ngraph LR\n A[Entry 数据] --> B[formatRow 函数]\n B --> C{includeAssets?}\n C -->|是| D[格式化资产列]\n C -->|否| E[仅输出名称和描述]\n D --> F[escapeTableCell 转义特殊字符]\n E --> F\n F --> G[拼接 Markdown 行]\n G --> H[生成完整表格]\n```\n\n## 表格单元格格式化\n\nGenerate 命令使用 `escapeTableCell` 函数处理单元格内容，防止 Markdown 表格解析错误。\n\n### 转义规则\n\n| 原字符 | 转义后 | 说明 |\n|--------|--------|------|\n| `|` | `\\|` | 管道符会破坏表格结构 |\n| 换行符 | 空格 | 单元格内容需保持单行 |\n\n```typescript\nfunction escapeTableCell(value: string): string {\n return value.replaceAll(\"|\", \"\\\\|\").replaceAll(\"\\n\", \" \");\n}\n```\n\n资料来源：[src/cmd_generate.ts:75-77]()\n\n## 资产打包格式\n\n当技能目录包含额外文件时，Generate 命令会将这些文件列为\"关联资产\"。\n\n### 资产显示格式\n\n| 资产数量 | 显示格式 | 示例 |\n|----------|----------|------|\n| 无资产 | `None` | `None` |\n| 单文件 | 文件名 | `LICENSE.txt` |\n| 多文件 | 文件名 + 计数 | `scripts` (5 files) |\n| 文件夹 | 文件夹名 + 计数 | `assets` (4 files) |\n\n### 内联资产数量限制\n\n```typescript\nconst BUNDLED_ASSETS_INLINE_MAX_ITEMS = 3;\n```\n\n当资产数量超过 3 个时，Generate 命令会切换为计数显示模式，避免表格过宽。\n\n## GitHub URL 处理\n\n### URL 规范化\n\nGenerate 命令支持多种 GitHub URL 格式：\n\n| 输入格式 | 处理方式 |\n|----------|----------|\n| `github.com/owner/repo/tree/main/path` | 自动转换为 API 端点 |\n| `raw.githubusercontent.com/...` | 直接使用 |\n| `github.com/owner/repo` | 扫描仓库根目录 |\n\n### API 端点构建\n\n```typescript\nfunction buildContentsApiUrl(location: GithubDirectoryLocation): string {\n const pathSuffix = location.path\n .split(\"/\")\n .filter(Boolean)\n .map((part) => encodeURIComponent(part))\n .join(\"/\");\n \n const pathname = `/repos/${encodeURIComponent(location.owner)}/${encodeURIComponent(location.repo)}/contents/${pathSuffix}`;\n const url = new URL(pathname, GITHUB_API_BASE_URL);\n \n url.searchParams.set(\"ref\", location.ref);\n return url.toString();\n}\n```\n\n资料来源：[src/download.ts:85-98]()\n\n## 空输出处理\n\nGenerate 命令实现了智能的空输出检测机制，避免生成无意义的清单文件。\n\n### 空文档判定\n\n```typescript\nfunction isEmptyGeneratedDocument(document: GeneratedDocument): boolean {\n return document.markdown === \"| Name | Description |\\n| -----|-------------|\\n\"\n || document.markdown === \"| Name | Description | Bundled Assets |\\n| -----|-------------|----------------|\\n\";\n}\n```\n\n资料来源：[src/cmd_generate.ts:64-68]()\n\n当检测到空输出时：\n- 不写入任何文件\n- 不显示覆盖确认提示\n- 静默跳过该类型清单\n\n## 配置集成\n\nGenerate 命令可以通过环境变量进行配置：\n\n### 环境变量\n\n| 变量名 | 必填 | 说明 |\n|--------|------|------|\n| `GITHUB_PAT` | 否 | GitHub 个人访问令牌，用于认证请求 |\n| `SUGGEST_SKILLS_MANIFEST_URLS` | 是 | 至少包含一个 manifest URL |\n\n### Manifest URL 格式\n\n```bash\n# JSON 数组格式\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://some/skill-manifest.md\"]'\n\n# 逗号分隔格式\nSUGGEST_SKILLS_MANIFEST_URLS='url1,url2,url3'\n\n# 换行分隔格式\nSUGGEST_SKILLS_MANIFEST_URLS='url1\nurl2'\n```\n\n## 最佳实践\n\n### 推荐使用场景\n\n1. **初始化新仓库**：首次设置技能目录时生成清单\n2. **同步更新**：每次技能更新后重新生成以保持文档最新\n3. **多仓库管理**：使用递归模式扫描组织下的所有技能\n\n### 性能注意事项\n\n| 模式 | 适用场景 | API 调用次数 |\n|------|----------|-------------|\n| 非递归 | 单层目录结构 | 1-2 次 |\n| 递归 | 多层嵌套技能 | N+1 次（根据深度） |\n\n### GitHub API 限制\n\n- 未认证请求：每小时 60 次\n- 认证请求（使用 GITHUB_PAT）：每小时 5000 次\n\n对于大型仓库或频繁使用场景，建议配置 `GITHUB_PAT` 环境变量。\n\n## 完整使用示例\n\n### 示例 1：扫描官方技能库\n\n```bash\nnpx suggest-skills generate \\\n https://github.com/anthropics/skills/tree/main/skills\n```\n\n输出文件：\n- `anthropics.skills.skills.md`\n- `anthropics.skills.designs.md`\n- `anthropics.skills.agents.md`\n\n### 示例 2：递归扫描社区技能\n\n```bash\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://example.com/manifest.md\"]' \\\nnpx suggest-skills generate \\\n --recursive \\\n https://github.com/ComposioHQ/awesome-claude-skills/tree/master\n```\n\n### 示例 3：集成到 CI/CD\n\n```yaml\n# .github/workflows/generate-skills.yml\nname: Generate Skills Manifest\non:\n schedule:\n - cron: '0 0 * * *' # 每日执行\n push:\n branches:\n - main\n\njobs:\n generate:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - name: Generate skills manifest\n env:\n GITHUB_PAT: ${{ secrets.GITHUB_PAT }}\n SUGGEST_SKILLS_MANIFEST_URLS: '[\"https://raw.githubusercontent.com/anthropics/skills/main/skills-index.json\"]'\n run: npx suggest-skills generate --recursive https://github.com/anthropics/skills/tree/main/skills\n```\n\n## 相关命令\n\n| 命令 | 功能 | 使用场景 |\n|------|------|----------|\n| `download` | 下载技能到本地 | 本地开发或离线使用 |\n| `server` | 启动 HTTP 服务 | 远程代理集成 |\n| `stdio` | 标准输入输出模式 | 与 MCP 客户端集成 |\n\n---\n\n\n\n## Server 命令\n\n### 相关页面\n\n相关主题：[传输模式](#transport-modes), [部署指南](#deployment-guide)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)\n- [src/http.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/http.ts)\n- [README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n- [src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)\n- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)\n \n\n# Server 命令\n\n## 概述\n\n`server` 命令是 `suggest-skills` CLI 工具的核心运行模式之一，用于启动一个基于 HTTP 协议的 MCP（Model Context Protocol）流式服务器。该服务器提供了技能（Skills）发现、清单获取和技能下载等核心功能，使 AI 代理能够在运行时动态获取和推荐可用的技能扩展。\n\nServer 命令的主要职责包括：\n- 注册 MCP 工具接口\n- 提供 RESTful HTTP 端点\n- 处理技能清单的获取与解析\n- 支持技能目录的下载功能\n\n资料来源：[README.md:1-20]()\n\n## 架构设计\n\n### 技术栈\n\nServer 命令基于以下技术构建：\n\n| 组件 | 技术 | 用途 |\n|------|------|------|\n| 运行时 | Bun | 高性能 JavaScript 运行时 |\n| 语言 | TypeScript | 类型安全开发 |\n| 协议框架 | @modelcontextprotocol/sdk | MCP 标准协议实现 |\n| 数据验证 | Zod | 运行时 Schema 验证 |\n\n资料来源：[README.md:89-96]()\n\n### 项目架构\n\n```\nConfig -> MCP tool registration -> stdio or HTTP transport\n\nCLI generate -> GitHub directory scan -> manifest markdown file\n \\-> GitHub URL normalization / folder download\n```\n\n整体架构遵循配置驱动、工具注册、传输层分离的设计模式。HTTP 传输作为独立的传输层实现，与 stdio 模式共享核心业务逻辑。\n\n资料来源：[README.md:98-104]()\n\n## 命令行接口\n\n### 基本用法\n\n```bash\nnpx suggest-skills server --port <端口号>\n```\n\n### 端口配置\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `--port ` | 指定 HTTP 服务器监听端口 | 3100 |\n\n配置示例：\n\n```bash\n# 启动服务器并指定端口\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://some/skill-manifest.md\"]' \\\n npx suggest-skills server --port 3100\n```\n\n资料来源：[src/config.ts:30-33]()\n\n## HTTP 端点\n\n### 端点列表\n\n| 端点 | 方法 | 功能 |\n|------|------|------|\n| `/mcp` | POST | MCP 协议主端点，处理工具调用 |\n| `/health` | GET | 健康检查端点 |\n\n### 服务地址\n\n- **MCP 端点**: `http://localhost:<端口>/mcp`\n- **健康检查**: `http://localhost:<端口>/health`\n\n默认配置下：\n- MCP 端点: `http://localhost:3100/mcp`\n- 健康检查: `http://localhost:3100/health`\n\n资料来源：[README.md:76-77]()\n\n## MCP 工具\n\nServer 命令注册了以下 MCP 工具供 AI 代理调用：\n\n### suggest_skills\n\n获取技能建议的工具，用于告知 AI 代理如何：\n- 从配置的清单中获取可用技能\n- 扫描本地已安装的技能\n- 比较远程与本地能力\n- 在用户请求前仅展示建议而不实际安装\n\n**参数**:\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| manifestUrl | string | 否 | 覆盖默认配置的清单 URL |\n\n资料来源：[README.md:80-92]()\n\n### fetch_manifest\n\n获取指定清单 URL 的文本内容。\n\n**参数**:\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| manifestUrl | string | 是 | 清单文件的完整 URL |\n\n资料来源：[README.md:94-97]()\n\n### download_skill\n\n下载 GitHub 文件夹中的所有文件。\n\n**参数**:\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| url | string | 是 | GitHub 文件夹 URL，格式为 `https://github.com///tree/[/` |\n\n**返回内容**:\n- 文件相对路径\n- UTF-8 编码的文本内容\n- GitHub 提供的 symlink 目标内容\n- 仓库相对目录 symlink 自动解析并递归下载\n\n资料来源：[README.md:99-112]()\n\n## 数据流程\n\n### 技能下载流程\n\n```mermaid\ngraph TD\n A[download_skill 工具调用] --> B[解析 GitHub URL]\n B --> C[构建 Contents API 请求]\n C --> D[获取仓库 Tree SHA]\n D --> E[递归获取文件树]\n E --> F[处理 symlink 解析]\n F --> G[构建下载 URL]\n G --> H[返回文件内容列表]\n \n I[buildGithubRawUrl] --> G\n J[buildTreeApiUrl] --> D\n```\n\n### 清单生成流程\n\n```mermaid\ngraph TD\n A[generate 命令] --> B[扫描 GitHub 目录]\n B --> C[递归发现 SKILL.md]\n C --> D[收集同目录资产文件]\n D --> E[构建 Markdown 表格]\n E --> F[输出清单文件]\n \n G[normalizeGithubRawUrl] --> A\n```\n\n资料来源：[src/download.ts:1-50](), [src/generate.ts:1-80]()\n\n## 环境配置\n\n### 必需环境变量\n\n| 变量名 | 必填 | 说明 |\n|--------|------|------|\n| SUGGEST_SKILLS_MANIFEST_URLS | 是 | 技能清单 URL 列表 |\n\n**支持的格式**:\n- JSON 数组: `[\"url1\", \"url2\"]`\n- 逗号分隔字符串: `\"url1,url2\"`\n- 换行分隔字符串: `\"url1\\nurl2\"`\n\n### 可选环境变量\n\n| 变量名 | 说明 |\n|--------|------|\n| GITHUB_PAT | GitHub 个人访问令牌，用于对 api.github.com 的认证请求 |\n\n### URL 自动转换\n\nGitHub `blob` URLs 会自动转换为 `raw.githubusercontent.com` URLs。\n\n资料来源：[README.md:120-138]()\n\n## 代码实现\n\n### 命令注册\n\nServer 命令通过 `cac` CLI 框架注册：\n\n```typescript\ncli\n .command(\"server [...args]\", \"Run the streamable HTTP server\")\n .option(\"--port \", \"Port number\")\n .action(actions.onServer);\n```\n\n资料来源：[src/config.ts:30-33]()\n\n### 运行时模式\n\nServer 命令解析后生成以下运行时配置：\n\n```typescript\n{\n kind: \"server\",\n port: number,\n config: {\n manifestUrls: string[],\n githubToken?: string\n }\n}\n```\n\n## 传输模式对比\n\n| 特性 | stdio 模式 | HTTP 模式 |\n|------|------------|-----------|\n| 启动方式 | `npx suggest-skills` | `npx suggest-skills server --port 3100` |\n| 通信协议 | 标准输入输出 | HTTP |\n| 适用场景 | 本地 CLI 集成 | 远程服务部署 |\n| 端点支持 | 无 | `/mcp`, `/health` |\n| 并发支持 | 单会话 | 多会话 |\n\n资料来源：[README.md:142-157]()\n\n## 最佳实践\n\n### 生产环境部署\n\n1. **配置清单 URL**: 确保 `SUGGEST_SKILLS_MANIFEST_URLS` 包含所有必需的技能清单\n2. **使用 GitHub Token**: 通过 `GITHUB_PAT` 提升 API 请求频率限制\n3. **健康检查**: 定期调用 `/health` 端点验证服务状态\n\n### 调试建议\n\n- 使用 `--port` 参数指定非默认端口避免冲突\n- 查看服务器日志确认 MCP 工具注册状态\n- 使用 `curl http://localhost:/health` 快速验证服务\n\n## 相关命令\n\n| 命令 | 说明 |\n|------|------|\n| `suggest-skills generate` | 从 GitHub 目录生成技能清单 |\n| `suggest-skills download` | 下载技能到本地目录 |\n| `suggest-skills` | 以 stdio 模式运行（默认） |\n\n资料来源：[src/config.ts:20-35]()\n\n---\n\n\n\n## 配置指南\n\n### 相关页面\n\n相关主题：[MCP 工具](#mcp-tools), [传输模式](#transport-modes)\n\n]\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)\n- [README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n- [src/cmd_generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/cmd_generate.ts)\n- [src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)\n- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)\n \n\n# 配置指南\n\n## 概述\n\n`suggest-skills` 是一个基于 Model Context Protocol (MCP) 的技能建议工具，用于从 GitHub 仓库中发现、管理和推荐 AI 助手技能。该项目支持三种运行时模式：stdio 模式、HTTP 服务模式和生成模式，通过环境变量和命令行参数进行灵活配置。 资料来源：[README.md:1-50]()\n\n## 核心配置架构\n\n```mermaid\ngraph TD\n A[环境变量配置] --> B[CLI 参数解析]\n B --> C{运行时模式}\n C -->|stdio| D[MCP stdio 传输]\n C -->|server| E[MCP HTTP 服务]\n C -->|generate| F[Manifest 生成器]\n \n A1[`SUGGEST_SKILLS_MANIFEST_URLS`] --> A\n A2[`GITHUB_PAT`] --> A\n B1[`-o, --output`] --> B\n B2[`-r, --recursive`] --> B\n B3[`--port`] --> B\n```\n\n## 环境变量配置\n\n### 必需配置\n\n| 环境变量 | 说明 | 格式要求 | 示例 |\n|---------|------|---------|------|\n| `SUGGEST_SKILLS_MANIFEST_URLS` | 技能清单 URL 地址 | JSON 数组、逗号分隔或换行分隔 | 参见下方详细说明 |\n\n`SUGGEST_SKILLS_MANIFEST_URLS` 是必需的配置文件，必须包含至少一个有效的清单 URL。支持的格式如下：\n\n```bash\n# JSON 数组格式\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://example.com/manifest.md\"]'\n\n# 逗号分隔格式\nSUGGEST_SKILLS_MANIFEST_URLS='https://example.com/manifest1.md,https://example.com/manifest2.md'\n\n# 换行分隔格式\nSUGGEST_SKILLS_MANIFEST_URLS='https://example.com/manifest1.md\nhttps://example.com/manifest2.md'\n```\n\nGitHub `blob` URL 会自动转换为 `raw.githubusercontent.com` URL。 资料来源：[README.md:70-90]()\n\n### 可选配置\n\n| 环境变量 | 说明 | 用途 |\n|---------|------|------|\n| `GITHUB_PAT` | GitHub 个人访问令牌 | 用于对 `api.github.com` 的认证请求，提高 API 限制 |\n\n## 命令行接口配置\n\n### 全局选项\n\n| 选项 | 完整格式 | 说明 | 默认值 |\n|-----|---------|------|-------|\n| 输出目录 | `-o `, `--output ` | 安装技能的输出目录 | `.agents/skills` |\n\n输出目录指定安装的技能文件存放位置，相对路径相对于当前工作目录。 资料来源：[src/config.ts:1-50]()\n\n### 子命令配置\n\n#### generate 命令\n\n```bash\nnpx suggest-skills generate [--recursive, -r]\n```\n\n| 参数/选项 | 说明 |\n|---------|------|\n| `` | GitHub 仓库或技能目录 URL |\n| `--recursive`, `-r` | 递归扫描子目录 |\n\n生成模式会扫描指定 GitHub 路径下的所有技能目录，并生成以下文件：\n\n- `.[.].skills.md` - 包含 `SKILL.md` 的技能目录清单\n- `.[.].designs.md` - 包含 `DESIGN.md` 的设计目录清单\n- `.[.].agents.md` - 平面顶级 Markdown 文件中的代理清单\n\n空生成的输出会被跳过，不会覆盖现有文件。 资料来源：[README.md:40-65]()\n\n#### download 命令\n\n```bash\nnpx suggest-skills download [--recursive, -r]\n```\n\n下载技能、代理和设计文件到当前目录。使用 GitHub Contents API 递归获取文件内容。 资料来源：[src/download.ts:1-40]()\n\n#### server 命令\n\n```bash\nnpx suggest-skills server [--port ]\n```\n\n| 选项 | 说明 | 默认值 |\n|-----|------|-------|\n| `--port ` | HTTP 服务监听端口 | `3100` |\n\nHTTP 服务提供两个端点：\n\n- `http://localhost:/mcp` - MCP 协议端点\n- `http://localhost:/health` - 健康检查端点\n\n```mermaid\ngraph LR\n A[客户端] -->|HTTP 请求| B[MCP 端点 /mcp]\n A -->|健康检查| C[Health 端点 /health]\n B --> D[技能清单处理]\n C --> E[服务状态返回]\n```\n\n#### stdio 模式（默认）\n\n当不指定任何子命令时，工具以 stdio 模式运行，作为 MCP 服务器通过标准输入输出通信：\n\n```bash\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://example.com/manifest.md\"]' npx suggest-skills\n```\n\n## 配置验证机制\n\n### ConfigError 异常处理\n\n项目通过 `ConfigError` 类进行显式配置验证，任何配置错误都会抛出该异常并终止程序执行。这确保了配置问题在启动阶段就能被发现。 资料来源：[src/config.ts:1-20]()\n\n### 运行时模式解析\n\n配置解析流程如下：\n\n```mermaid\ngraph TD\n A[解析 process.argv] --> B[解析环境变量]\n B --> C{命令类型判断}\n C -->|generate| D[设置 generate 运行时模式]\n C -->|download| E[设置 download 运行时模式]\n C -->|server| F[设置 server 运行时模式]\n C -->|无命令| G[设置 stdio 运行时模式]\n \n D --> H[构建配置对象]\n E --> H\n F --> H\n G --> H\n```\n\n每个运行时模式包含以下配置属性：\n\n| 属性 | 说明 |\n|-----|------|\n| `kind` | 模式类型：`generate`、`download`、`server`、`stdio` |\n| `url` | GitHub URL（generate/download 模式） |\n| `recursive` | 是否递归扫描 |\n| `config` | 通用配置对象 |\n\n## MCP 工具配置\n\n### suggest_skills 工具\n\n核心建议工具，接受可选的 `manifestUrl` 参数覆盖默认配置。返回生成的指令载荷，指导代理如何：\n\n- 从配置的清单获取可用技能\n- 扫描本地安装的技能\n- 比较远程和本地能力\n- 在请求安装前呈现建议\n\n### fetch_manifest 工具\n\n接受清单 URL 并返回其文本内容。\n\n### download_skill 工具\n\n接受 GitHub 文件夹 URL 格式：\n\n```\nhttps://github.com///tree/[/\n```\n\n返回文件夹中的每个文件，包含相对路径、UTF-8 文本内容和符号链接信息。 资料来源：[README.md:100-130]()\n\n## 清单文件格式\n\n### 技能清单结构\n\n清单文件采用 Markdown 表格格式，每行包含技能名称（链接）、描述和捆绑资源：\n\n```markdown\n| Name | Description | Bundled Assets |\n|------|-------------|----------------|\n| [skill-name](url) | Description text | `file1.txt`, `dir/` (3 files) |\n```\n\n### Manifest 加载流程\n\n```mermaid\nsequenceDiagram\n participant CLI as CLI 工具\n participant Config as 配置模块\n participant Manifest as 清单 URL\n participant MCP as MCP 服务器\n \n CLI->>Config: 解析环境变量\n Config->>Manifest: 获取清单内容\n Manifest-->>Config: 返回 Markdown\n Config->>MCP: 注册工具和资源\n MCP->>CLI: 服务就绪\n```\n\n## 常见配置场景\n\n### 场景一：本地开发环境\n\n```bash\n# 设置清单源\nexport SUGGEST_SKILLS_MANIFEST_URLS='[\"https://raw.githubusercontent.com/anthropics/skills/main/official/skills.skills.md\"]'\n\n# 以 stdio 模式运行\nnpx suggest-skills\n```\n\n### 场景二：HTTP 服务部署\n\n```bash\n# 设置清单源（多源）\nexport SUGGEST_SKILLS_MANIFEST_URLS='[\"https://example.com/manifest1.md\",\"https://example.com/manifest2.md\"]'\n\n# 自定义端口\nnpx suggest-skills server --port 8080\n```\n\n### 场景三：从 GitHub 生成清单\n\n```bash\n# 递归扫描官方技能\nnpx suggest-skills generate https://github.com/anthropics/skills/tree/main/skills --recursive\n\n# 单层扫描\nnpx suggest-skills generate https://github.com/anthropics/skills/tree/main/official/skills\n```\n\n## 技术栈配置依赖\n\n项目使用以下技术栈构建，所有配置都围绕这些核心依赖展开：\n\n| 技术 | 用途 | 配置关联 |\n|-----|------|---------|\n| Bun | 运行时和打包 | `package.json` 定义脚本入口 |\n| TypeScript | 类型安全 | 编译配置 |\n| @modelcontextprotocol/sdk | MCP 协议实现 | 工具和资源注册 |\n| Zod | 配置验证 | 环境变量和参数 schema |\n\n## 配置最佳实践\n\n1. **环境变量优先**：优先通过环境变量配置清单 URL，避免硬编码\n2. **使用认证令牌**：生产环境建议配置 `GITHUB_PAT` 以提高 API 限制\n3. **指定输出目录**：使用 `-o` 选项明确指定技能安装位置\n4. **递归扫描谨慎使用**：大仓库递归扫描会增加 API 调用次数\n5. **健康检查监控**：部署 HTTP 服务时定期检查 `/health` 端点\n\n---\n\n\n\n## 部署指南\n\n### 相关页面\n\n相关主题：[传输模式](#transport-modes), [Server 命令](#server-command)\n\n]\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)\n- [package.json](https://github.com/sator-imaging/suggest-skills/blob/main/package.json)\n- [src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)\n- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)\n \n\n# 部署指南\n\n本页面详细说明 `suggest-skills` 项目的部署方式、配置方法及运行模式。该项目是一个基于 MCP（Model Context Protocol）的技能推荐服务器，支持通过命令行工具生成技能清单以及作为 MCP 服务器运行。\n\n## 系统要求\n\n| 组件 | 要求 | 说明 |\n|------|------|------|\n| Node.js | v18+ | 运行 MCP 服务器的基础环境 |\n| 包管理器 | npm / yarn / pnpm | 安装项目依赖 |\n| 可选认证 | GitHub Personal Access Token | 提高 GitHub API 请求速率限制 |\n\n资料来源：[README.md:1-10]()\n\n## 安装方式\n\n### 通过 npm 全局安装\n\n```bash\nnpm install -g suggest-skills\n```\n\n### 通过 npx 直接运行\n\n```bash\nnpx suggest-skills \n```\n\n### 从源码构建\n\n```bash\ngit clone https://github.com/sator-imaging/suggest-skills.git\ncd suggest-skills\nnpm install\nnpm run build\n```\n\n## 环境变量配置\n\n### 必需配置\n\n| 环境变量 | 说明 | 格式要求 |\n|----------|------|----------|\n| `SUGGEST_SKILLS_MANIFEST_URLS` | 技能清单 URL 列表 | JSON 数组、逗号分隔字符串或换行分隔字符串 |\n\n```bash\n# JSON 数组格式\nexport SUGGEST_SKILLS_MANIFEST_URLS='[\"https://example.com/manifest.md\"]'\n\n# 逗号分隔格式\nexport SUGGEST_SKILLS_MANIFEST_URLS='https://example.com/manifest1.md,https://example.com/manifest2.md'\n```\n\n### 可选配置\n\n| 环境变量 | 说明 | 默认值 |\n|----------|------|--------|\n| `GITHUB_PAT` | GitHub 个人访问令牌 | 无 |\n\n`GITHUB_PAT` 用于对 `api.github.com` 的认证请求，可有效提高 API 速率限制。\n\n```bash\nexport GITHUB_PAT=\"ghp_xxxxxxxxxxxx\"\n```\n\n资料来源：[README.md:1-20]()\n\n## 运行模式\n\n### stdio 模式\n\nstdio 模式适用于与本地 MCP 客户端直接集成，通过标准输入输出进行通信。\n\n```bash\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://some/skill-manifest.md\"]' \\\n npx suggest-skills\n```\n\n此模式适合集成到支持 MCP 协议的开发工具中。\n\n### HTTP 服务器模式\n\nHTTP 模式提供网络 HTTP 接口，适合远程访问和分布式架构部署。\n\n```bash\nSUGGEST_SKILLS_MANIFEST_URLS='[\"https://some/skill-manifest.md\"]' \\\n npx suggest-skills server --port 3100\n```\n\n#### 服务端点\n\n| 端点 | 方法 | 说明 |\n|------|------|------|\n| `/mcp` | GET/POST | MCP 协议主端点，处理技能推荐请求 |\n| `/health` | GET | 健康检查端点，验证服务状态 |\n\n```text\nhttp://localhost:3100/mcp # MCP 协议端点\nhttp://localhost:3100/health # 健康检查端点\n```\n\n资料来源：[README.md:20-35]()\n\n## 命令行接口\n\n### generate 命令\n\n生成技能清单文档，从 GitHub 仓库扫描技能目录。\n\n```bash\nnpx suggest-skills generate \n```\n\n#### 参数说明\n\n| 参数 | 说明 | 示例 |\n|------|------|------|\n| `` | GitHub 仓库或目录 URL | `https://github.com/OWNER/REPO/tree/main/skills` |\n| `-r, --recursive` | 递归扫描子目录 | 扫描嵌套的技能目录 |\n\n#### 基本用法\n\n```bash\n# 从 skills 目录生成清单\nnpx suggest-skills generate https://github.com/OWNER/REPO/tree/main/skills\n\n# 递归生成所有嵌套技能\nnpx suggest-skills generate --recursive https://github.com/OWNER/REPO/tree/main/skills\n```\n\n#### 输出文件\n\ngenerate 命令会在当前工作目录生成以下文件：\n\n| 文件类型 | 命名规则 | 内容 |\n|----------|----------|------|\n| 技能清单 | `.[.].skills.md` | 包含 SKILL.md 的目录条目 |\n| 设计清单 | `.[.].designs.md` | 包含 DESIGN.md 的目录条目 |\n| 智能体清单 | `.[.].agents.md` | 顶级 markdown 智能体定义 |\n\n#### 扫描规则\n\n```mermaid\ngraph TD\n A[GitHub URL] --> B{--recursive 参数}\n B -->|否| C[扫描直接子目录]\n B -->|是| D[递归扫描所有子目录]\n C --> E[发现 SKILL.md 或 DESIGN.md]\n D --> E\n E --> F[收集同目录资源文件]\n F --> G[生成清单文件]\n```\n\n- GitHub `blob` URL 会自动转换为 `raw.githubusercontent.com` URL\n- 符号链接会被下载但不递归遍历\n- 空生成的输出会被跳过，不写入文件\n\n资料来源：[README.md:35-60]()\n\n### server 命令\n\n启动 HTTP 服务器运行 MCP 端点。\n\n```bash\nnpx suggest-skills server --port \n```\n\n#### 参数说明\n\n| 参数 | 说明 | 默认值 |\n|------|------|------|\n| `--port, -p` | HTTP 服务器监听端口 | 3100 |\n\n### CLI 选项汇总\n\n| 选项 | 说明 | 适用于 |\n|------|------|--------|\n| `-o ` | 技能安装输出目录 | install |\n| `--recursive` | 递归扫描子目录 | generate |\n| `--port ` | HTTP 服务器端口 | server |\n\n资料来源：[README.md:15-25]()\n\n## MCP 工具接口\n\n### suggest_skills\n\n推荐可用技能的工具。\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `manifestUrl` | string (可选) | 覆盖默认配置的清单 URL |\n\n**返回内容**：生成的指令负载，指导智能体如何获取技能、扫描本地安装、对比远程与本地能力。\n\n### fetch_manifest\n\n获取清单文件内容。\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `manifestUrl` | string | 清单文件 URL |\n\n**返回内容**：清单文件的原始文本内容。\n\n### download_skill\n\n下载技能目录中的所有文件。\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `url` | string | GitHub 文件夹 URL，格式为 `https://github.com///tree/[/` |\n\n**返回内容**：文件夹中每个文件的路径、UTF-8 文本内容及符号链接信息。\n\n```mermaid\ngraph LR\n A[MCP 客户端] -->|suggest_skills| B[返回推荐指令]\n A -->|fetch_manifest| C[获取清单]\n A -->|download_skill| D[下载技能文件]\n B --> E[用户选择技能]\n E --> D\n D --> F[本地文件]\n```\n\n## Docker 部署（推荐架构）\n\n```dockerfile\nFROM node:18-alpine\n\nWORKDIR /app\n\nCOPY package*.json ./\nRUN npm ci --only=production\n\nCOPY dist/ ./dist/\n\nENV SUGGEST_SKILLS_MANIFEST_URLS=\"https://raw.githubusercontent.com/anthropics/skills/main/skills/skills.md\"\n\nEXPOSE 3100\n\nCMD [\"npx\", \"suggest-skills\", \"server\", \"--port\", \"3100\"]\n```\n\n### Docker Compose 编排\n\n```yaml\nversion: '3.8'\n\nservices:\n suggest-skills:\n image: suggest-skills:latest\n ports:\n - \"3100:3100\"\n environment:\n - SUGGEST_SKILLS_MANIFEST_URLS=https://example.com/manifest.md\n - GITHUB_PAT=${GITHUB_PAT}\n restart: unless-stopped\n healthcheck:\n test: [\"CMD\", \"wget\", \"--spider\", \"-q\", \"http://localhost:3100/health\"]\n interval: 30s\n timeout: 10s\n retries: 3\n```\n\n## 项目架构\n\n```mermaid\ngraph TD\n subgraph 配置层\n A[环境变量] --> B[Config 模块]\n B --> C[配置验证]\n end\n \n subgraph 核心层\n D[MCP 服务器] --> E[工具注册]\n F[CLI 工具] --> G[GitHub 目录扫描]\n G --> H[清单生成器]\n end\n \n subgraph 传输层\n I[stdio 传输] \n J[HTTP 传输]\n end\n \n B --> D\n B --> F\n E --> I\n E --> J\n H --> K[Markdown 输出]\n```\n\n### 核心模块\n\n| 模块 | 文件路径 | 职责 |\n|------|----------|------|\n| MCP 工具注册 | `src/mcp/` | 注册 suggest_skills、fetch_manifest、download_skill 工具 |\n| 配置管理 | `src/config.ts` | 验证环境变量，处理配置错误 |\n| GitHub API | `src/download.ts` | 目录内容获取、树形结构扫描 |\n| 清单生成 | `src/generate.ts` | 解析 SKILL.md、DESIGN.md 生成清单文档 |\n\n## 故障排查\n\n### 常见问题\n\n| 问题 | 可能原因 | 解决方案 |\n|------|----------|----------|\n| `SUGGEST_SKILLS_MANIFEST_URLS` 未设置 | 环境变量缺失 | 设置至少一个清单 URL |\n| GitHub API 速率限制 | 未使用认证令牌 | 配置 `GITHUB_PAT` 环境变量 |\n| 清单生成无输出 | 目录中无 SKILL.md 或 DESIGN.md | 确认目标目录包含技能定义文件 |\n| HTTP 端口占用 | 端口已被占用 | 使用 `--port` 指定其他端口 |\n\n### 健康检查\n\n部署后验证服务状态：\n\n```bash\ncurl http://localhost:3100/health\n```\n\n正常响应返回 HTTP 200 状态码。\n\n### 日志级别\n\n通过环境变量启用调试日志：\n\n```bash\nDEBUG=suggest-skills:* npx suggest-skills server --port 3100\n```\n\n## 最佳实践\n\n1. **始终设置 GitHub PAT**：生产环境建议配置认证令牌以避免 API 限制\n2. **使用版本化的清单 URL**：避免清单更新导致行为不一致\n3. **配置健康检查**：容器编排中设置健康检查探针\n4. **分离配置与部署**：使用环境变量管理配置，便于不同环境切换\n5. **限制网络暴露**：stdio 模式优先用于敏感环境\n\n资料来源：[README.md:1-80]()\n\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：sator-imaging/suggest-skills\n\n摘要：发现 15 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。\n\n## 1. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | host_targets=mcp_host, claude\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | README/documentation is current enough for a first validation pass.\n\n## 3. 运行坑 · 来源证据：v1.0.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.0.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e40d7a86377b444f8d3eca5e8ec2b1a4 | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.0.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 4. 运行坑 · 来源证据：v1.1.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.1.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d9b5403807304a33aaf39f02f80d14be | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.1.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 5. 运行坑 · 来源证据：v1.2.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.2.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_452c2fc3dc7d4409a8e1a4ae5419599f | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.2.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 运行坑 · 来源证据：v1.3.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.3.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7cf71c15b4c64e7297db646b5300ba29 | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.3.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 维护坑 · 来源证据：v1.0.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.0.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2150c52f85274793bfce6c1d64d24f66 | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.0.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 维护坑 · 来源证据：v1.0.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.0.3\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ac612b4c6cd44d2194d9df8b4c026220 | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.0.3 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 维护坑 · 来源证据：v2.0.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v2.0.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bc9655e0f7c54b22a783ef99c7841b5e | https://github.com/sator-imaging/suggest-skills/releases/tag/v2.0.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | last_activity_observed missing\n\n## 11. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 13. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | no_demo; severity=medium\n\n## 14. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | issue_or_pr_quality=unknown\n\n## 15. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：sator-imaging/suggest-skills\n\n摘要：发现 15 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。\n\n## 1. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | host_targets=mcp_host, claude\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | README/documentation is current enough for a first validation pass.\n\n## 3. 运行坑 · 来源证据：v1.0.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.0.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e40d7a86377b444f8d3eca5e8ec2b1a4 | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.0.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 4. 运行坑 · 来源证据：v1.1.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.1.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d9b5403807304a33aaf39f02f80d14be | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.1.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 5. 运行坑 · 来源证据：v1.2.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.2.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_452c2fc3dc7d4409a8e1a4ae5419599f | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.2.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 运行坑 · 来源证据：v1.3.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.3.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7cf71c15b4c64e7297db646b5300ba29 | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.3.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 维护坑 · 来源证据：v1.0.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.0.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2150c52f85274793bfce6c1d64d24f66 | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.0.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 维护坑 · 来源证据：v1.0.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.0.3\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ac612b4c6cd44d2194d9df8b4c026220 | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.0.3 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 维护坑 · 来源证据：v2.0.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v2.0.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bc9655e0f7c54b22a783ef99c7841b5e | https://github.com/sator-imaging/suggest-skills/releases/tag/v2.0.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | last_activity_observed missing\n\n## 11. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 13. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | no_demo; severity=medium\n\n## 14. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | issue_or_pr_quality=unknown\n\n## 15. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# suggest-skills - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 suggest-skills 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client / claude\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: MCP server that suggests repository-specific AI agent skills. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. project-introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. key-features：核心特性。围绕“核心特性”模拟一次用户任务，不展示安装或运行结果。\n3. system-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. mcp-tools：MCP 工具。围绕“MCP 工具”模拟一次用户任务，不展示安装或运行结果。\n5. transport-modes：传输模式。围绕“传输模式”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. project-introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. key-features\n输入：用户提供的“核心特性”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. system-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. mcp-tools\n输入：用户提供的“MCP 工具”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. transport-modes\n输入：用户提供的“传输模式”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / project-introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / key-features：Step 2 必须围绕“核心特性”形成一个小中间产物，并等待用户确认。\n- Step 3 / system-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / mcp-tools：Step 4 必须围绕“MCP 工具”形成一个小中间产物，并等待用户确认。\n- Step 5 / transport-modes：Step 5 必须围绕“传输模式”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/sator-imaging/suggest-skills\n- https://github.com/sator-imaging/suggest-skills#readme\n- README.md\n- package.json\n- src/index.ts\n- src/suggest.ts\n- src/download.ts\n- src/config.ts\n- src/core.ts\n- src/stdio.ts\n- src/http.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 suggest-skills 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：sator-imaging/suggest-skills\n\n## 官方安装入口\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx suggest-skills\n```\n\n来源：https://github.com/sator-imaging/suggest-skills#readme\n\n## 来源\n\n- repo: https://github.com/sator-imaging/suggest-skills\n- docs: https://github.com/sator-imaging/suggest-skills#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_1afe90d28f0b42ecb725d94a085efbbf"
}
]