{
"canonical_name": "rohitg00/skillkit",
"compilation_id": "pack_eba0003d39e640b1b4b76dad8cb57999",
"created_at": "2026-05-16T18:54:09.637334+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=skill, recipe, host_instruction, eval, preflight",
"recommended_asset_types=skill, 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 skillkit` 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 skillkit",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_985f0fb024234f52a09c4e09afcfdd37"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_b5208bcb66c88437c5cc9d35c6976630",
"canonical_name": "rohitg00/skillkit",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/rohitg00/skillkit",
"slug": "skillkit",
"source_packet_id": "phit_a2fec85007244fe292995bc27f0d0d25",
"source_validation_id": "dval_536fb43ab7c74f9eb46c79b5ed419828"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 claude的用户",
"github_forks": 100,
"github_stars": 1064,
"one_liner_en": "Supercharge AI coding agents with portable skills. Install, translate & share skills across Claude Code, Cursor, Codex, Copilot & 40 more",
"one_liner_zh": "Supercharge AI coding agents with portable skills. Install, translate & share skills across Claude Code, Cursor, Codex, Copilot & 40 more",
"primary_category": {
"category_id": "software-development",
"confidence": "high",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:code, coding, git"
},
"target_user": "使用 claude, claude_code, cursor 等宿主 AI 的用户",
"title_en": "skillkit",
"title_zh": "skillkit 能力包",
"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": "TDD Workflow",
"label_zh": "TDD 工作流",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-tdd-workflow",
"type": "core_capability"
},
{
"label_en": "Checkpoint Resume",
"label_zh": "断点恢复流程",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-checkpoint-resume",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_a2fec85007244fe292995bc27f0d0d25",
"page_model": {
"artifacts": {
"artifact_slug": "skillkit",
"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 skillkit",
"label": "Node.js / npx · 官方安装入口",
"source": "https://github.com/rohitg00/skillkit#readme",
"verified": true
}
],
"display_tags": [
"浏览器 Agent",
"网页任务自动化",
"TDD 工作流",
"断点恢复流程",
"评测体系"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 claude的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Supercharge AI coding agents with portable skills. Install, translate & share skills across Claude Code, Cursor, Codex, Copilot & 40 more"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "claude, claude_code, cursor",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "skill, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Trust downgrade for skillkit@1.24.0: v1.0.3 had provenance attestation but this version has no trust evidence",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_54f25870d6d64729a96eb14e8e1ee72f | https://github.com/rohitg00/skillkit/issues/121 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Trust downgrade for skillkit@1.24.0: v1.0.3 had provenance attestation but this version has no trust evidence",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Publish] CreatorCrawl — Social Media Data Skill",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_d2c6e8b4d87e4786af49c7bc9ee2665d | https://github.com/rohitg00/skillkit/issues/123 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[Publish] CreatorCrawl — Social Media Data Skill",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add source: jorgeferrando/sdd-skills — Spec-Driven Development workflow",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_d1cb6475bbfe4122ab15817ca66e58b6 | https://github.com/rohitg00/skillkit/issues/112 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Add source: jorgeferrando/sdd-skills — Spec-Driven Development workflow",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Publish] Rhf Autosave",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_7f4a4b823d1a40918a48fb8aae0d74ac | https://github.com/rohitg00/skillkit/issues/111 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[Publish] Rhf Autosave",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.20.0",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_73d12f84f1644a3dbc3981274dfefa42 | https://github.com/rohitg00/skillkit/releases/tag/v1.20.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.20.0",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.22.0",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_a5339307b2d04e409858700fa8186f6c | https://github.com/rohitg00/skillkit/releases/tag/v1.22.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.22.0",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.22.1",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_2a197dc603b242bdaa32dd2c70d535c1 | https://github.com/rohitg00/skillkit/releases/tag/v1.22.1 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.22.1",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.23.0 — Slim install, safer picker, brand tags",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_9388696ec7584a6b8f5998d74f1c428e | https://github.com/rohitg00/skillkit/releases/tag/v1.23.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.23.0 — Slim install, safer picker, brand tags",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。",
"category": "配置坑",
"evidence": [
"capability.host_targets | github_repo:1138376193 | https://github.com/rohitg00/skillkit | host_targets=claude, claude_code, cursor"
],
"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:1138376193 | https://github.com/rohitg00/skillkit | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1138376193 | https://github.com/rohitg00/skillkit | 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:1138376193 | https://github.com/rohitg00/skillkit | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:1138376193 | https://github.com/rohitg00/skillkit | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Audit] Add --json output to 28 commands for CI/CD usage",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_e28aa428237f4e6ba09f785dbf5e6978 | https://github.com/rohitg00/skillkit/issues/89 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：[Audit] Add --json output to 28 commands for CI/CD usage",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Audit] Add loading spinners to 43 commands missing progress feedback",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_9bba06e67cf944c28dcb33d8ed334975 | https://github.com/rohitg00/skillkit/issues/88 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：[Audit] Add loading spinners to 43 commands missing progress feedback",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Publish] AlphaEar System",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_26d8102a08b8434cb7456fcd1554ce3a | https://github.com/rohitg00/skillkit/issues/126 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[Publish] AlphaEar System",
"user_impact": "可能影响授权、密钥配置或安全边界。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 23 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Trust downgrade for skillkit@1.24.0: v1.0.3 had provenance attestation but this version has no trust evidence。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 3,
"forks": 100,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 1064
},
"source_url": "https://github.com/rohitg00/skillkit",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Supercharge AI coding agents with portable skills. Install, translate & share skills across Claude Code, Cursor, Codex, Copilot & 40 more",
"title": "skillkit 能力包",
"trial_prompt": "# skillkit - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 skillkit 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：claude / Claude Code / Cursor\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. project-overview：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. installation-guide：安装指南。围绕“安装指南”模拟一次用户任务，不展示安装或运行结果。\n3. quick-start-guide：快速入门。围绕“快速入门”模拟一次用户任务，不展示安装或运行结果。\n4. package-structure：包结构与依赖关系。围绕“包结构与依赖关系”模拟一次用户任务，不展示安装或运行结果。\n5. core-modules：核心模块解析。围绕“核心模块解析”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. project-overview\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. installation-guide\n输入：用户提供的“安装指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. quick-start-guide\n输入：用户提供的“快速入门”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. package-structure\n输入：用户提供的“包结构与依赖关系”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. core-modules\n输入：用户提供的“核心模块解析”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / project-overview：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / installation-guide：Step 2 必须围绕“安装指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / quick-start-guide：Step 3 必须围绕“快速入门”形成一个小中间产物，并等待用户确认。\n- Step 4 / package-structure：Step 4 必须围绕“包结构与依赖关系”形成一个小中间产物，并等待用户确认。\n- Step 5 / core-modules：Step 5 必须围绕“核心模块解析”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/rohitg00/skillkit\n- https://github.com/rohitg00/skillkit#readme\n- packages/core/src/eval/__tests__/fixtures/bad-skill/SKILL.md\n- packages/core/src/eval/__tests__/fixtures/eval-injection-skill/SKILL.md\n- packages/core/src/eval/__tests__/fixtures/good-skill/SKILL.md\n- packages/core/src/methodology/packs/collaboration/handoff-protocols/SKILL.md\n- packages/core/src/methodology/packs/collaboration/parallel-investigation/SKILL.md\n- packages/core/src/methodology/packs/collaboration/structured-review/SKILL.md\n- packages/core/src/methodology/packs/debugging/hypothesis-testing/SKILL.md\n- packages/core/src/methodology/packs/debugging/root-cause-analysis/SKILL.md\n- packages/core/src/methodology/packs/debugging/trace-and-isolate/SKILL.md\n- packages/core/src/methodology/packs/meta/skill-authoring/SKILL.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 skillkit 的核心服务。\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_issue: [Publish] AlphaEar System（https://github.com/rohitg00/skillkit/issues/126）；github/github_issue: [Publish] SkillKit Integration（https://github.com/rohitg00/skillkit/issues/125）；github/github_issue: [Publish] Computer Use Patterns（https://github.com/rohitg00/skillkit/issues/124）；github/github_issue: [Publish] CreatorCrawl — Social Media Data Skill（https://github.com/rohitg00/skillkit/issues/123）；github/github_issue: Trust downgrade for skillkit@1.24.0: v1.0.3 had provenance attestation b（https://github.com/rohitg00/skillkit/issues/121）；github/github_issue: [Source] Add Xquik TweetClaw（https://github.com/rohitg00/skillkit/issues/120）；github/github_issue: Add source: jorgeferrando/sdd-skills — Spec-Driven Development workflow（https://github.com/rohitg00/skillkit/issues/112）；github/github_issue: [Publish] Rhf Autosave（https://github.com/rohitg00/skillkit/issues/111）；github/github_issue: [Audit] Add loading spinners to 43 commands missing progress feedback（https://github.com/rohitg00/skillkit/issues/88）；github/github_issue: [Audit] Add --json output to 28 commands for CI/CD usage（https://github.com/rohitg00/skillkit/issues/89）；github/github_release: v1.24.0（https://github.com/rohitg00/skillkit/releases/tag/v1.24.0）；github/github_release: v1.23.0 — Slim install, safer picker, brand tags（https://github.com/rohitg00/skillkit/releases/tag/v1.23.0）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "[Publish] AlphaEar System",
"url": "https://github.com/rohitg00/skillkit/issues/126"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Publish] SkillKit Integration",
"url": "https://github.com/rohitg00/skillkit/issues/125"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Publish] Computer Use Patterns",
"url": "https://github.com/rohitg00/skillkit/issues/124"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Publish] CreatorCrawl — Social Media Data Skill",
"url": "https://github.com/rohitg00/skillkit/issues/123"
},
{
"kind": "github_issue",
"source": "github",
"title": "Trust downgrade for skillkit@1.24.0: v1.0.3 had provenance attestation b",
"url": "https://github.com/rohitg00/skillkit/issues/121"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Source] Add Xquik TweetClaw",
"url": "https://github.com/rohitg00/skillkit/issues/120"
},
{
"kind": "github_issue",
"source": "github",
"title": "Add source: jorgeferrando/sdd-skills — Spec-Driven Development workflow",
"url": "https://github.com/rohitg00/skillkit/issues/112"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Publish] Rhf Autosave",
"url": "https://github.com/rohitg00/skillkit/issues/111"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Audit] Add loading spinners to 43 commands missing progress feedback",
"url": "https://github.com/rohitg00/skillkit/issues/88"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Audit] Add --json output to 28 commands for CI/CD usage",
"url": "https://github.com/rohitg00/skillkit/issues/89"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.24.0",
"url": "https://github.com/rohitg00/skillkit/releases/tag/v1.24.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.23.0 — Slim install, safer picker, brand tags",
"url": "https://github.com/rohitg00/skillkit/releases/tag/v1.23.0"
}
],
"status": "已收录 12 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "Supercharge AI coding agents with portable skills. Install, translate & share skills across Claude Code, Cursor, Codex, Copilot & 40 more",
"effort": "安装已验证",
"forks": 100,
"icon": "code",
"name": "skillkit 能力包",
"risk": "可发布",
"slug": "skillkit",
"stars": 1064,
"tags": [
"浏览器 Agent",
"网页任务自动化",
"TDD 工作流",
"断点恢复流程",
"评测体系"
],
"thumb": "gray",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/rohitg00/skillkit 项目说明书\n\n生成时间：2026-05-16 18:44:53 UTC\n\n## 目录\n\n- [项目介绍](#project-overview)\n- [安装指南](#installation-guide)\n- [快速入门](#quick-start-guide)\n- [包结构与依赖关系](#package-structure)\n- [核心模块解析](#core-modules)\n- [技能管理](#skill-management)\n- [代理支持](#agent-support)\n- [格式翻译](#translation-format)\n- [AI 集成](#ai-integration)\n- [推荐引擎](#recommendation-engine)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[安装指南](#installation-guide), [快速入门](#quick-start-guide)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/rohitg00/skillkit/blob/main/README.md)\n- [packages/agents/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/agents/README.md)\n- [packages/cli/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/cli/README.md)\n- [packages/core/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/core/README.md)\n- [packages/core/src/ai/providers/mock.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/ai/providers/mock.ts)\n \n\n# 项目介绍\n\n## 概述\n\nSkillKit 是一个开源的 AI Agent 技能管理系统，旨在解决 AI 代码助手（Agent）在技能定义格式上互不兼容的问题。该项目允许开发者编写一次技能配置，即可将其转换并分发到多个 AI 平台使用，包括 Cursor、Copilot、Windsurf、Claude 等主流工具。\n\n资料来源：[README.md]()\n\n## 核心价值定位\n\n当前 AI 代码助手生态中存在一个显著问题：每个平台都定义了各自独特的技能（Skill）格式规范。这种碎片化导致开发者需要为同一个技能编写多份配置，造成了重复劳动和维护负担。SkillKit 通过提供统一的技能格式和自动化转换机制，显著简化了这一工作流程。\n\n资料来源：[README.md]()\n\n## 支持的 AI Agent 平台\n\nSkillKit 目前支持以下 AI Agent 平台的技能分发：\n\n| 平台名称 | 状态 |\n|---------|------|\n| augment-code | ✅ 支持 |\n| bolt | ✅ 支持 |\n| lovable | ✅ 支持 |\n| replit-agent | ✅ 支持 |\n| sourcegraph-cody | ✅ 支持 |\n| tabby | ✅ 支持 |\n| tabnine | ✅ 支持 |\n| universal | ✅ 支持 |\n\n资料来源：[packages/agents/README.md]()\n\n## 技能格式支持\n\n### SKILL.md 格式\n\n这是大多数 Agent 使用的标准格式，采用 YAML frontmatter 结合 Markdown 内容：\n\n```markdown\n---\nname: my-skill\ndescription: What this skill does\n---\n# My Skill\nInstructions...\n```\n\n资料来源：[packages/agents/README.md]()\n\n### MDC 格式（Cursor）\n\nCursor 平台专用的格式，支持 glob 模式匹配和 alwaysApply 配置：\n\n```markdown\n---\ndescription: What this skill does\nglobs: [\"**/*.tsx\"]\nalwaysApply: false\n---\nInstructions...\n```\n\n资料来源：[packages/agents/README.md]()\n\n### Markdown 格式\n\nWindsurf 和 Copilot 使用的纯 Markdown 格式：\n\n```markdown\n# Skill Name\nInstructions for the agent...\n```\n\n资料来源：[packages/agents/README.md]()\n\n## 技术架构\n\n### 模块化设计\n\nSkillKit 采用 Monorepo 结构组织代码，主要包含以下核心模块：\n\n```mermaid\ngraph TD\n A[SkillKit] --> B[CLI 模块]\n A --> C[Core 核心库]\n A --> D[TUI 终端界面]\n A --> E[Extension 扩展]\n A --> F[MCP Server]\n B --> C\n D --> C\n F --> C\n```\n\n资料来源：[packages/core/README.md]()\n\n### Core 核心库\n\n核心库提供以下关键功能：\n\n- **格式转换引擎**：支持 SKILL.md、MDC、Markdown 之间的相互转换\n- **项目分析器**：检测项目技术栈（语言、框架、库、数据库等）\n- **技能推荐系统**：基于检测到的技术栈提供相关技能建议\n- **格式渲染器**：支持 Markdown、HTML、XML 等多种输出格式\n\n资料来源：[packages/core/README.md]()\n资料来源：[packages/core/src/primer/generator.ts]()\n\n### CLI 命令行工具\n\n通过命令行界面提供完整的技能管理能力：\n\n```bash\n# 添加技能\nskillkit add claude:user/my-skill # Claude\nskillkit add github:owner/repo # GitHub\nskillkit add gitlab:team/skills # GitLab\nskillkit add ./my-local-skills # 本地路径\nskillkit add https://gist.github.com/... # Gist\n\n# 格式转换\nskillkit translate my-skill --to cursor\nskillkit translate --all --to windsurf,codex\nskillkit translate my-skill --to copilot --dry-run\n\n# 技能推荐\nskillkit recommend\n\n# 安全扫描\nskillkit scan \nskillkit scan --format json\n```\n\n资料来源：[README.md]()\n资料来源：[packages/cli/README.md]()\n\n### TUI 终端界面\n\n提供交互式的终端用户界面，包含以下功能模块：\n\n- **Browse（浏览）**：浏览和搜索技能市场\n- **Recommend（推荐）**：基于项目技术栈的智能推荐\n- **Translate（转换）**：技能格式转换\n- **Lineage（溯源）**：查看技能使用历史\n- **Context（上下文）**：分析当前项目的技术环境\n- **Methodology（方法论）**：管理和应用开发方法论\n- **Sync（同步）**：将技能同步到各 Agent 平台\n- **Plan（计划）**：执行和管理开发计划\n- **Handoff（交接）**：Agent 间的工作交接\n\n资料来源：[packages/tui/src/screens/Browse.tsx]()\n资料来源：[packages/tui/src/screens/Recommend.tsx]()\n资料来源：[packages/tui/src/screens/Translate.tsx]()\n\n### REST API 服务\n\nSkillKit 提供 REST API 服务，允许其他系统按需获取技能：\n\n```bash\nskillkit serve\n# http://localhost:3737\n\ncurl \"http://localhost:3737/search?q=react+performance\"\n```\n\n资料来源：[README.md]()\n\n### MCP 服务器支持\n\n支持通过 Model Context Protocol (MCP) 集成到开发环境：\n\n```json\n{\n \"mcpServers\": {\n \"skillkit\": { \"command\": \"npx\", \"args\": [\"@skillkit/mcp\"] }\n }\n}\n```\n\n资料来源：[README.md]()\n\n### Python 客户端\n\n提供 Python SDK 方便集成到现有 Python 项目：\n\n```python\nfrom skillkit import SkillKitClient\n\nasync with SkillKitClient() as client:\n results = await client.search(\"react performance\", limit=5)\n```\n\n资料来源：[README.md]()\n\n## 项目上下文分析\n\nSkillKit 能够自动分析项目特征，生成详细的技术栈报告：\n\n### 上下文数据类型\n\n```typescript\ninterface ProjectProfile {\n name: string;\n type: 'web-app' | 'api' | 'cli' | 'library' | 'unknown';\n stack: {\n languages: Detection[];\n frameworks: Detection[];\n libraries: Detection[];\n testing: Detection[];\n databases: Detection[];\n };\n}\n```\n\n资料来源：[packages/core/README.md]()\n\n### 检测能力\n\nSkillKit 可以检测项目的以下技术特征：\n\n- **编程语言**：检测项目使用的编程语言及其版本\n- **框架**：识别前端/后端框架（如 React、Next.js、Django 等）\n- **库依赖**：分析 package.json、requirements.txt 等依赖文件\n- **测试框架**：识别单元测试、集成测试工具\n- **数据库**：检测配置的数据库类型\n\n资料来源：[packages/tui/src/screens/Context.tsx]()\n\n## 技能推荐系统\n\n### 工作流程\n\n```mermaid\ngraph LR\n A[项目代码] --> B[上下文分析]\n B --> C[技术栈检测]\n C --> D[技能匹配]\n D --> E[推荐排序]\n E --> F[技能列表]\n```\n\n### 推荐输出示例\n\n```\n$ skillkit recommend\n\n 92% vercel-react-best-practices\n 87% tailwind-v4-patterns\n 85% nextjs-app-router\n 81% shadcn-ui-components\n```\n\n推荐系统会为每个技能计算匹配度分数，优先推荐与当前项目技术栈高度匹配的内容。\n\n资料来源：[README.md]()\n\n## 团队协作功能\n\n### Bundle 管理\n\n```bash\nskillkit team bundle-create # 创建 Bundle\nskillkit team bundle-export # 导出 Bundle\nskillkit team bundle-list # 列出所有 Bundle\n```\n\nBundle 允许团队将一组相关技能打包分发，便于统一管理和版本控制。\n\n资料来源：[packages/cli/README.md]()\n\n### 插件系统\n\n```bash\nskillkit plugin list # 列出已安装插件\nskillkit plugin install # 安装插件\nskillkit plugin uninstall # 卸载插件\nskillkit plugin enable # 启用插件\nskillkit plugin disable # 禁用插件\n```\n\n资料来源：[packages/cli/README.md]()\n\n### 钩子与自动化\n\n```bash\nskillkit hook list # 列出注册的钩子\nskillkit hook register # 注册新钩子\nskillkit hook trigger # 手动触发钩子\n```\n\n资料来源：[packages/cli/README.md]()\n\n## 扩展能力\n\n### 方法论管理\n\n```bash\nskillkit methodology list # 列出方法论\nskillkit methodology load # 加载方法论\nskillkit methodology apply # 应用到项目\n```\n\n内置多种开发方法论模板，包括任务分解、技术选型指南等最佳实践。\n\n资料来源：[packages/cli/README.md]()\n资料来源：[packages/core/src/methodology/packs/planning/task-decomposition/SKILL.md]()\n\n### 计划执行\n\n```bash\nskillkit plan parse # 解析计划文件\nskillkit plan validate # 验证计划\nskillkit plan execute # 执行计划\nskillkit plan status # 查看执行状态\n```\n\n资料来源：[packages/cli/README.md]()\n\n### 安全扫描\n\n```bash\nskillkit scan # 扫描技能漏洞\nskillkit scan --format json # JSON 格式输出\n```\n\n资料来源：[packages/cli/README.md]()\n\n## 安装与快速开始\n\n### 环境要求\n\n- Node.js 18.0 或更高版本\n- npm 或 yarn 包管理器\n\n### 安装方式\n\n```bash\n# 通过 npm 全局安装\nnpm install -g @skillkit/cli\n\n# 或使用 npx 直接运行\nnpx @skillkit/cli \n```\n\n### 基本使用流程\n\n1. **初始化项目**：在项目目录中运行 `skillkit` 启动 TUI\n2. **分析技术栈**：使用 `skillkit analyze` 检测项目环境\n3. **获取推荐**：`skillkit recommend` 查看推荐技能列表\n4. **安装技能**：选择并安装需要的技能\n5. **同步到 Agent**：使用 `skillkit sync` 同步到目标平台\n\n## 许可证\n\nSkillKit 采用 Apache-2.0 开源许可证，允许自由使用、修改和分发。\n\n资料来源：[README.md]()\n资料来源：[packages/agents/README.md]()\n\n---\n\n\n\n## 安装指南\n\n### 相关页面\n\n相关主题：[项目介绍](#project-overview), [快速入门](#quick-start-guide)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/rohitg00/skillkit/blob/main/README.md)\n- [packages/core/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/core/README.md)\n- [packages/agents/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/agents/README.md)\n- [packages/cli/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/cli/README.md)\n- [apps/skillkit/README.md](https://github.com/rohitg00/skillkit/blob/main/apps/skillkit/README.md)\n \n\n# 安装指南\n\nSkillKit 是一个跨平台 AI 技能管理系统，支持多种安装方式以满足不同用户的需求。本指南涵盖从快速启动到完整源码部署的全部安装方案。\n\n## 系统要求\n\nSkillKit 对运行环境有以下基本要求：\n\n| 要求项 | 最低版本 | 推荐版本 |\n|--------|----------|----------|\n| Node.js | 18.0.0 | 20.x LTS |\n| npm | 8.0.0 | 10.x |\n| Git | 2.30.0 | 最新版本 |\n| 操作系统 | macOS/Linux/Windows (WSL2) | - |\n\n## 安装方式\n\n### 方式一：全局安装（推荐）\n\n使用 npm 全局安装 SkillKit CLI 工具，这是最便捷的生产环境使用方式：\n\n```bash\nnpm install -g skillkit\n```\n\n安装完成后，直接在终端运行 `skillkit` 命令即可：\n\n```bash\nskillkit --help\n```\n\n资料来源：[README.md:1]()\n\n### 方式二：使用 npx 免安装运行\n\n如果仅需临时使用或进行快速演示，可以通过 npx 直接运行而无需全局安装：\n\n```bash\nnpx skillkit \n```\n\nnpx 会自动下载并执行指定版本的 SkillKit，每次运行时会检查更新。\n\n资料来源：[README.md:1]()\n\n### 方式三：Docker 部署\n\n对于需要隔离环境的场景，SkillKit 支持通过 Docker 运行：\n\n```bash\ndocker pull skillkit/skillkit:latest\ndocker run -it skillkit/skillkit \n```\n\nDocker 方式特别适合团队标准化环境配置和 CI/CD 集成场景。\n\n### 方式四：源码编译安装\n\n适用于需要自定义功能或参与项目开发的用户。\n\n#### 克隆仓库\n\n```bash\ngit clone https://github.com/rohitg00/skillkit.git\ncd skillkit\n```\n\n#### 安装依赖\n\nSkillKit 采用 monorepo 结构，主目录下使用 npm workspaces 管理多个子包：\n\n```bash\nnpm install\n```\n\n此命令会自动安装所有子包的依赖，包括核心包、CLI 包、TUI 包等。\n\n#### 编译构建\n\n```bash\nnpm run build\n```\n\n构建过程会生成各包的发布产物，包括：\n\n- `packages/core` - 核心功能库\n- `packages/cli` - 命令行工具\n- `packages/tui` - 终端用户界面\n- `packages/api` - REST API 服务\n- `packages/mesh` - 服务网格模块\n- `packages/messaging` - 消息传递模块\n\n资料来源：[package.json](https://github.com/rohitg00/skillkit/blob/main/package.json)\n\n## 项目架构概览\n\nSkillKit 的整体架构设计如下：\n\n```mermaid\ngraph TD\n A[用户终端] --> B[CLI 工具
skillkit 命令]\n A --> C[TUI 界面
交互式终端]\n A --> D[REST API
skillkit serve]\n \n B --> E[核心模块
packages/core]\n C --> E\n D --> E\n \n E --> F[技能存储]\n E --> G[翻译引擎]\n E --> H[推荐系统]\n \n F --> I[本地文件系统]\n F --> J[远程仓库]\n F --> K[团队 Bundle]\n \n L[Agent 集成] --> M[Claude
Cursor
Windsurf
Copilot]\n```\n\n## 包结构说明\n\nSkillKit 采用 monorepo 架构，主要包的功能如下：\n\n| 包名 | 功能描述 | 主要导出 |\n|------|----------|----------|\n| `@skillkit/core` | 核心功能，包含技能解析、翻译、推荐等核心算法 | `SkillKit`, `SkillTranslator` |\n| `@skillkit/cli` | 命令行工具，提供所有 `skillkit` 子命令 | CLI 可执行文件 |\n| `@skillkit/tui` | 终端用户界面，交互式操作界面 | 独立的 TUI 应用 |\n| `@skillkit/api` | REST API 服务，支持 HTTP 接口访问 | Express 服务 |\n| `@skillkit/mesh` | 服务网格模块，支持微服务架构集成 | 连接器和适配器 |\n| `@skillkit/messaging` | 消息传递系统，支持事件驱动通信 | 消息队列接口 |\n| `@skillkit/mcp` | MCP 协议集成，支持模型上下文协议 | MCP 服务器 |\n\n资料来源：[packages/core/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/core/README.md)\n\n## 验证安装\n\n安装完成后，可通过以下方式验证：\n\n### 检查 CLI 版本\n\n```bash\nskillkit --version\n```\n\n### 查看可用命令\n\n```bash\nskillkit --help\n```\n\n输出应包含以下主要功能模块：\n\n```bash\nskillkit add # 添加技能\nskillkit translate # 翻译技能格式\nskillkit recommend # 智能推荐\nskillkit serve # 启动 API 服务\nskillkit team # 团队协作\nskillkit plugin # 插件管理\nskillkit methodology # 方法论加载\nskillkit plan # 计划执行\nskillkit hook # 自动化钩子\nskillkit scan # 安全扫描\n```\n\n资料来源：[packages/cli/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/cli/README.md)\n\n## 快速开始\n\n安装完成后，按以下步骤创建第一个技能：\n\n### 初始化项目\n\n```bash\nskillkit init\n```\n\n### 添加技能\n\n```bash\nskillkit add \n```\n\n支持的来源格式：\n\n```bash\nskillkit add claude:username/skill # Claude\nskillkit add cursor:owner/skill # Cursor\nskillkit add windsurf:repo/skills # Windsurf\nskillkit add github:owner/repo # GitHub\nskillkit add gitlab:team/skills # GitLab\nskillkit add ./my-local-skills # 本地路径\nskillkit add https://gist.github.com/... # Gist\n```\n\n资料来源：[README.md:1]()\n\n### 启动交互界面\n\n```bash\nskillkit tui\n```\n\n### 启动 API 服务\n\n```bash\nskillkit serve\n# 服务地址: http://localhost:3737\n```\n\n## 团队安装配置\n\n对于团队环境，建议通过配置文件统一管理：\n\n```bash\nskillkit team init --name \"Engineering Team\"\nskillkit team sync\n```\n\n配置文件 `.skillkit.json` 可放在项目根目录，确保团队成员使用一致的技能配置。\n\n## 环境变量配置\n\nSkillKit 支持以下环境变量自定义行为：\n\n| 变量名 | 默认值 | 说明 |\n|--------|--------|------|\n| `SKILLKIT_DIR` | `~/.skillkit` | 技能存储目录 |\n| `SKILLKIT_API_PORT` | `3737` | API 服务端口 |\n| `SKILLKIT_LOG_LEVEL` | `info` | 日志级别 |\n| `SKILLKIT_CACHE_TTL` | `3600` | 缓存生存时间（秒） |\n\n## 常见问题\n\n### 全局安装后命令不可用\n\n确保 npm 全局 bin 目录在系统 PATH 中：\n\n```bash\nnpm config get prefix\n```\n\n如果路径不在 PATH 中，添加到 shell 配置文件（`.bashrc`、`.zshrc` 等）：\n\n```bash\nexport PATH=\"$(npm config get prefix)/bin:$PATH\"\n```\n\n### 权限错误（EACCES）\n\nLinux/macOS 上如遇权限问题，避免使用 sudo：\n\n```bash\nmkdir ~/.npm-global\nnpm config set prefix '~/.npm-global'\nexport PATH=~/.npm-global/bin:$PATH\n```\n\n### 源码安装构建失败\n\n确保 Node.js 版本符合要求，并清理缓存后重试：\n\n```bash\nrm -rf node_modules package-lock.json\nnpm cache clean --force\nnpm install\nnpm run build\n```\n\n## 下一步\n\n安装完成后，建议继续阅读以下文档：\n\n- [用户指南](https://github.com/rohitg00/skillkit#readme) - 完整功能说明\n- [技能格式规范](https://github.com/rohitg00/skillkit/blob/main/packages/agents/README.md) - SKILL.md、MDC 格式说明\n- [API 参考](https://github.com/rohitg00/skillkit/blob/main/apps/skillkit/README.md) - REST API 端点说明\n- [插件开发](https://github.com/rohitg00/skillkit/blob/main/packages/cli/README.md) - 扩展 SkillKit 功能\n\n---\n\n\n\n## 快速入门\n\n### 相关页面\n\n相关主题：[技能管理](#skill-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/rohitg00/skillkit/blob/main/README.md)\n- [packages/agents/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/agents/README.md)\n- [packages/core/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/core/README.md)\n- [packages/cli/src/commands/init.ts](https://github.com/rohitg00/skillkit/blob/main/packages/cli/src/commands/init.ts)\n- [packages/cli/src/commands/add.ts](https://github.com/rohitg00/skillkit/blob/main/packages/cli/src/commands/add.ts)\n- [packages/cli/src/commands/recommend.ts](https://github.com/rohitg00/skillkit/blob/main/packages/cli/src/commands/recommend.ts)\n- [packages/cli/src/commands/sync.ts](https://github.com/rohitg00/skillkit/blob/main/packages/cli/src/commands/sync.ts)\n \n\n# 快速入门\n\n本文档将帮助你快速上手 SkillKit，了解如何安装、配置以及使用核心功能来管理 AI Agent 技能。\n\n## 什么是 SkillKit\n\nSkillKit 是一个用于统一管理和分发 AI Agent 技能（Skills）的命令行工具。它允许开发者：\n\n- 为多个 AI Agent 平台（如 Cursor、Windsurf、Claude Code 等）编写一次技能\n- 自动将技能转换为不同 Agent 支持的格式\n- 订阅社区技能市场并同步到本地\n- 根据项目技术栈获取智能推荐\n\n\n\n## 系统要求\n\n| 要求 | 最低版本 |\n|------|----------|\n| Node.js | 18.0.0 |\n| npm/pnpm | 最新版本 |\n| 操作系统 | macOS、Linux、Windows |\n\n## 安装\n\n通过 npm 全局安装 SkillKit CLI：\n\n```bash\nnpm install -g @skillkit/cli\n```\n\n或使用 pnpm：\n\n```bash\npnpm add -g @skillkit/cli\n```\n\n安装完成后，验证安装：\n\n```bash\nskillkit --version\n```\n\n## 初始化项目\n\n在项目根目录运行初始化命令，创建 `.skillkit` 配置文件：\n\n```bash\nskillkit init\n```\n\n初始化过程会：\n1. 创建 `.skillkit` 目录\n2. 生成 `skillkit.yaml` 配置文件\n3. 检测项目技术栈（语言、框架、库）\n4. 配置支持的 AI Agent\n\n资料来源：[README.md](https://github.com/rohitg00/skillkit/blob/main/README.md)\n\n### 初始化配置\n\n初始化后生成的 `skillkit.yaml` 结构如下：\n\n```yaml\nagents:\n - cursor\n - windsurf\n - claude\n - copilot\nstack:\n languages: []\n frameworks: []\n libraries: []\nskills: []\n```\n\n## 核心命令\n\n### 添加技能\n\n使用 `add` 命令添加本地技能或远程技能源：\n\n```bash\n# 添加 GitHub 仓库\nskillkit add github:username/skills\n\n# 添加 GitLab 仓库\nskillkit add gitlab:team/skills\n\n# 添加本地路径\nskillkit add ./my-local-skills\n\n# 添加 Gist\nskillkit add https://gist.github.com/...\n```\n\n资料来源：[README.md](https://github.com/rohitg00/skillkit/blob/main/README.md)\n\n### 智能推荐\n\n根据项目技术栈获取推荐技能：\n\n```bash\nskillkit recommend\n```\n\n输出示例：\n\n```\n92% vercel-react-best-practices\n87% tailwind-v4-patterns\n85% nextjs-app-router\n81% shadcn-ui-components\n```\n\n推荐系统会分析项目中的：\n- 编程语言\n- 前端框架\n- UI 库\n- 测试框架\n- 数据库\n\n资料来源：[packages/cli/src/commands/recommend.ts](https://github.com/rohitg00/skillkit/blob/main/packages/cli/src/commands/recommend.ts)\n\n### 同步技能\n\n将技能同步到指定的 AI Agent：\n\n```bash\n# 同步所有技能\nskillkit sync\n\n# 同步到指定 Agent\nskillkit sync --to cursor\n\n# 同步指定技能\nskillkit sync my-skill --to windsurf\n```\n\n资料来源：[packages/cli/src/commands/sync.ts](https://github.com/rohitg00/skillkit/blob/main/packages/cli/src/commands/sync.ts)\n\n### 格式转换\n\nSkillKit 支持将技能转换为不同 Agent 专用的格式：\n\n```bash\n# 转换单个技能\nskillkit translate my-skill --to cursor\n\n# 转换所有技能\nskillkit translate --all --to windsurf,codex\n\n# 预览转换结果\nskillkit translate my-skill --to copilot --dry-run\n```\n\n## 技能格式\n\n### SKILL.md 格式\n\n大多数 Agent 使用的标准格式，采用 YAML frontmatter + Markdown 内容：\n\n```markdown\n---\nname: my-skill\ndescription: 技能描述\n---\n# My Skill\nInstructions...\n```\n\n### MDC 格式 (Cursor)\n\nCursor 专用的格式，支持 glob 模式和 alwaysApply 字段：\n\n```markdown\n---\ndescription: 技能描述\nglobs: [\"**/*.tsx\"]\nalwaysApply: false\n---\nInstructions...\n```\n\n### Markdown 格式\n\n用于 Windsurf 和 Copilot 的纯 Markdown 格式：\n\n```markdown\n# Skill Name\nInstructions for the agent...\n```\n\n资料来源：[packages/agents/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/agents/README.md)\n\n## 支持的 AI Agent\n\nSkillKit 支持以下 AI Agent 平台：\n\n| Agent | 格式支持 | 状态 |\n|-------|----------|------|\n| Claude | SKILL.md | 完整支持 |\n| Cursor | MDC | 完整支持 |\n| Windsurf | Markdown | 完整支持 |\n| Copilot | Markdown | 完整支持 |\n| Augment Code | SKILL.md | 完整支持 |\n| Bolt | SKILL.md | 完整支持 |\n| Lovable | SKILL.md | 完整支持 |\n| Replit Agent | SKILL.md | 完整支持 |\n| Sourcegraph Cody | SKILL.md | 完整支持 |\n| Tabby | SKILL.md | 完整支持 |\n| Tabnine | SKILL.md | 完整支持 |\n| Universal | SKILL.md | 完整支持 |\n\n资料来源：[packages/agents/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/agents/README.md)\n\n## 工作流程图\n\n```mermaid\ngraph TD\n A[开始] --> B[安装 SkillKit]\n B --> C[初始化项目 skillkit init]\n C --> D[添加技能 skillkit add]\n D --> E[推荐技能 skillkit recommend]\n E --> F[同步到 Agent skillkit sync]\n F --> G[在 Agent 中使用技能]\n```\n\n## 进阶功能\n\n### 运行本地服务\n\n启动 SkillKit REST API 服务，让 Agent 按需获取技能：\n\n```bash\nskillkit serve\n# http://localhost:3737\n\ncurl \"http://localhost:3737/search?q=react+performance\"\n```\n\n### MCP 集成\n\n将 SkillKit 集成到支持 MCP 的编辑器中：\n\n```json\n{\n \"mcpServers\": {\n \"skillkit\": { \n \"command\": \"npx\", \n \"args\": [\"@skillkit/mcp\"] \n }\n }\n}\n```\n\n### Python 客户端\n\n使用 Python SDK 与 SkillKit 服务交互：\n\n```python\nfrom skillkit import SkillKitClient\n\nasync with SkillKitClient() as client:\n results = await client.search(\"react performance\", limit=5)\n```\n\n资料来源：[README.md](https://github.com/rohitg00/skillkit/blob/main/README.md)\n\n## 常见问题\n\n### 初始化失败怎么办？\n\n确保：\n- 当前目录是 Git 仓库根目录\n- 有写入 `.skillkit` 目录的权限\n- Node.js 版本 >= 18.0.0\n\n### 如何查看已配置的 Agent？\n\n```bash\nskillkit config --list\n```\n\n### 技能同步失败？\n\n检查：\n1. Agent 是否已安装\n2. Agent 的技能目录路径是否正确\n3. 技能格式是否与目标 Agent 兼容\n\n## 下一步\n\n- 查看[完整文档](https://github.com/rohitg00/skillkit)\n- 浏览 [packages/core](https://github.com/rohitg00/skillkit/blob/main/packages/core/README.md) 了解核心 API\n- 探索[示例技能库](https://github.com/rohitg00/skillkit/tree/main/packages/core/src/methodology/packs)\n\n---\n\n\n\n## 包结构与依赖关系\n\n### 相关页面\n\n相关主题：[核心模块解析](#core-modules), [项目介绍](#project-overview)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [pnpm-workspace.yaml](https://github.com/rohitg00/skillkit/blob/main/pnpm-workspace.yaml)\n- [turbo.json](https://github.com/rohitg00/skillkit/blob/main/turbo.json)\n- [packages/core/src/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/index.ts)\n- [packages/cli/src/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/cli/src/index.ts)\n- [packages/agents/src/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/agents/src/index.ts)\n- [packages/tui/src/screens/Methodology.tsx](https://github.com/rohitg00/skillkit/blob/main/packages/tui/src/screens/Methodology.tsx)\n- [packages/core/src/primer/generator.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/primer/generator.ts)\n \n\n# 包结构与依赖关系\n\n## 项目概述\n\nSkillKit 是一个基于 pnpm monorepo 架构的多包项目，采用 pnpm workspaces 和 Turborepo 进行包管理和构建优化。项目设计围绕 AI 代理技能系统展开，提供了核心库、命令行工具、TUI 界面和浏览器扩展等多元化终端。\n\n资料来源：[pnpm-workspace.yaml](https://github.com/rohitg00/skillkit/blob/main/pnpm-workspace.yaml)\n\n## Monorepo 架构\n\nSkillKit 采用标准的 pnpm monorepo 结构，所有子包位于 `packages` 目录下，应用位于 `apps` 目录下。这种结构允许共享依赖、提升构建效率，并确保各模块间的版本一致性。\n\n资料来源：[pnpm-workspace.yaml](https://github.com/rohitg00/skillkit/blob/main/pnpm-workspace.yaml)\n\n## 包目录结构\n\n```\nskillkit/\n├── packages/ # 核心包集合\n│ ├── core/ # 核心业务逻辑库\n│ ├── cli/ # 命令行工具\n│ ├── agents/ # AI 代理集成包\n│ ├── tui/ # 终端用户界面\n│ └── extension/ # 浏览器扩展\n├── apps/ # 独立应用\n│ └── skillkit/ # 主应用程序\n├── pnpm-workspace.yaml # 工作空间配置\n└── turbo.json # 构建流水线配置\n```\n\n## 核心包详解\n\n### Core 包 (packages/core)\n\nCore 包是整个项目的基础，包含了技能系统的核心业务逻辑、翻译引擎、上下文分析等关键功能。\n\n```mermaid\ngraph TD\n A[Core 包] --> B[ai/]\n A --> C[skill-translator.ts]\n A --> D[methodology/]\n A --> E[primer/]\n \n B --> B1[providers/]\n B --> B2[wizard/]\n B --> B3[recommend/]\n \n C --> C1[SKILL.md 解析]\n C --> C2[MDC 转换]\n C --> C3[Agent Format]\n \n D --> D1[Packs 系统]\n D --> D2[Task 模板]\n \n E --> E1[ProjectAnalysis]\n E --> E2[ContextGenerator]\n```\n\n**主要子模块功能说明：**\n\n| 模块路径 | 功能描述 | 关键文件 |\n|---------|---------|----------|\n| `ai/providers/` | AI 能力提供者抽象 | mock.ts 等 |\n| `ai/wizard/` | 技能创建向导系统 | types.ts, 状态管理 |\n| `methodology/` | 开发方法论与任务分解 | packs/, task-decomposition/ |\n| `primer/` | 项目上下文生成器 | generator.ts |\n| `skill-translator/` | 技能格式翻译引擎 | 多格式转换支持 |\n\n资料来源：[packages/core/src/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/index.ts)\n\n### CLI 包 (packages/cli)\n\nCLI 包封装了 SkillKit 的命令行交互能力，提供技能安装、翻译、同步、团队协作等功能入口。\n\n```mermaid\ngraph LR\n subgraph CLI 功能模块\n A[skillkit install] --> B[core]\n C[skillkit translate] --> B\n D[skillkit sync] --> B\n E[skillkit team] --> B\n end\n \n B --> F[core 包 API]\n```\n\n**核心命令分类：**\n\n| 命令类别 | 子命令 | 功能说明 |\n|---------|-------|----------|\n| 基础操作 | `install`, `sync`, `list` | 技能生命周期管理 |\n| 翻译功能 | `translate --to ` | 技能格式转换 |\n| 团队协作 | `bundle-*`, `team share` | 团队技能包管理 |\n| 插件系统 | `plugin list/install` | 插件扩展管理 |\n| 方法论 | `methodology list/apply` | 开发方法论应用 |\n\n资料来源：[packages/cli/src/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/cli/src/index.ts)\n\n### Agents 包 (packages/agents)\n\nAgents 包定义了与各种 AI 代理（Claude Code、Cursor、Copilot 等）的集成规范和格式转换逻辑。\n\n```mermaid\ngraph TD\n A[Agents 包] --> B[SKILL.md 格式]\n A --> C[MDC 格式]\n A --> D[Markdown 格式]\n A --> E[通用 YAML 格式]\n \n B --> B1[Claude Code]\n B --> B2[Codex]\n B --> B3[Gemini CLI]\n \n D --> D1[Windsurf]\n D --> D2[Copilot]\n \n E --> E1[通用适配]\n```\n\n**支持的代理格式映射：**\n\n| 代理名称 | 格式类型 | 配置特征 |\n|---------|---------|----------|\n| Claude Code | SKILL.md | YAML frontmatter + Markdown |\n| Cursor | MDC | globs + alwaysApply |\n| Windsurf | Markdown | 纯 Markdown 指令 |\n| GitHub Copilot | Markdown | 纯 Markdown 指令 |\n| Replit Agent | SKILL.md | YAML frontmatter + Markdown |\n\n资料来源：[packages/agents/src/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/agents/src/index.ts)\n\n### TUI 包 (packages/tui)\n\nTUI 包提供了 SkillKit 的终端用户界面，使用 Ink（React for CLI）构建，支持交互式浏览、安装和管理技能。\n\n```mermaid\ngraph TD\n A[TUI 界面] --> B[Browse 屏幕]\n A --> C[Marketplace 屏幕]\n A --> D[Methodology 屏幕]\n A --> E[Translate 屏幕]\n A --> F[Recommend 屏幕]\n A --> G[Lineage 屏幕]\n A --> H[Handoff 屏幕]\n A --> I[Context 屏幕]\n \n B --> B1[技能市场浏览]\n C --> C1[分类树视图]\n D --> D1[方法论包安装]\n E --> E1[格式翻译]\n F --> F1[智能推荐]\n```\n\n**屏幕组件映射表：**\n\n| 屏幕组件 | 文件位置 | 功能描述 |\n|---------|---------|----------|\n| Browse | screens/Browse.tsx | 浏览远程技能仓库 |\n| Marketplace | screens/Marketplace.tsx | 技能分类与树形展示 |\n| Methodology | screens/Methodology.tsx | 方法论包管理与安装 |\n| Translate | screens/Translate.tsx | 技能格式翻译预览 |\n| Recommend | screens/Recommend.tsx | 基于项目的技能推荐 |\n| Lineage | screens/Lineage.tsx | 技能使用历史追踪 |\n| Handoff | screens/Handoff.tsx | 任务交接与状态展示 |\n| Context | screens/Context.tsx | 项目上下文信息展示 |\n\n资料来源：[packages/tui/src/screens/Methodology.tsx](https://github.com/rohitg00/skillkit/blob/main/packages/tui/src/screens/Methodology.tsx)\n\n### Extension 包 (packages/extension)\n\nExtension 包提供了浏览器扩展能力，支持用户在浏览器中直接浏览和管理技能。\n\n## 依赖关系图\n\n```mermaid\ngraph TD\n CLI[packages/cli] --> CORE[packages/core]\n TUI[packages/tui] --> CORE\n AGENTS[packages/agents] --> CORE\n EXTENSION[packages/extension] --> CORE\n \n APP[apps/skillkit] --> CLI\n APP --> TUI\n \n CLI --> AGENTS\n TUI --> AGENTS\n \n style CORE fill:#e1f5fe\n style CLI fill:#fff3e0\n style TUI fill:#e8f5e9\n```\n\n## 包间依赖规范\n\n### 核心依赖原则\n\n1. **单向依赖**：上层包可依赖下层包，禁止反向依赖\n2. **共享核心**：所有功能性包都应依赖 `packages/core`\n3. **接口稳定**：`packages/core` 导出稳定公开 API\n\n### 依赖层级说明\n\n| 层级 | 包名 | 说明 |\n|-----|------|-----|\n| 基础设施层 | packages/core | 核心业务逻辑与类型定义 |\n| 功能封装层 | packages/agents, packages/cli | 特定功能的封装 |\n| 表现层 | packages/tui, packages/extension | 用户交互界面 |\n| 应用层 | apps/skillkit | 组合各模块的完整应用 |\n\n## Turborepo 构建配置\n\nTurborepo 负责管理构建任务的依赖关系和增量构建优化。\n\n```json\n// turbo.json 核心配置结构\n{\n \"pipeline\": {\n \"build\": {\n \"dependsOn\": [\"^build\"],\n \"outputs\": [\"dist/**\", \".next/**\"]\n },\n \"test\": {\n \"dependsOn\": [\"build\"],\n \"outputs\": [\"coverage/**\"]\n },\n \"lint\": {\n \"outputs\": []\n }\n }\n}\n```\n\n**构建任务说明：**\n\n| 任务名称 | 依赖任务 | 输出目录 | 说明 |\n|---------|---------|---------|------|\n| build | ^build | dist/, .next/ | 增量构建 |\n| test | build | coverage/ | 测试与覆盖率 |\n| lint | - | - | 代码检查 |\n| dev | - | - | 开发模式 |\n\n资料来源：[turbo.json](https://github.com/rohitg00/skillkit/blob/main/turbo.json)\n\n## pnpm Workspace 配置\n\n```yaml\n# pnpm-workspace.yaml\npackages:\n - 'packages/*'\n - 'apps/*'\n```\n\n该配置声明了所有子包和应用的位置，pnpm 将自动管理这些包之间的符号链接和依赖解析。\n\n## 导出 API 结构\n\n### Core 包导出 (packages/core/src/index.ts)\n\nCore 包通过 index.ts 统一导出以下模块：\n\n| 导出类别 | 包含内容 | 使用场景 |\n|---------|---------|----------|\n| 技能管理 | Skill, SkillSet | 技能定义与集合操作 |\n| 翻译引擎 | translateSkill() | 格式转换 |\n| 项目分析 | ProjectAnalyzer | 上下文分析 |\n| 方法论 | Methodology, TaskTemplate | 开发流程模板 |\n| 推荐系统 | recommendSkills() | 智能推荐 |\n| 向导系统 | WizardState, WizardStep | 引导式创建 |\n\n### Agents 包导出 (packages/agents/src/index.ts)\n\nAgents 包定义了代理集成的核心接口：\n\n```typescript\n// 代理格式配置\ninterface AgentSkillFormat {\n name: string;\n extension: string;\n hasFrontmatter: boolean;\n invokeCommand: string;\n supportsGlobs: boolean;\n}\n\n// 支持的代理列表\nconst SUPPORTED_AGENTS = ['claude-code', 'cursor', 'copilot', ...] as const;\n```\n\n### CLI 包导出 (packages/cli/src/index.ts)\n\nCLI 包通过命令注册系统对外暴露命令行接口：\n\n```typescript\n// 核心命令注册\nexport async function cli(args: string[]): Promise;\nexport const installCommand: Command;\nexport const translateCommand: Command;\nexport const syncCommand: Command;\nexport const teamCommand: Command;\nexport const pluginCommand: Command;\nexport const methodologyCommand: Command;\n```\n\n## 版本与发布\n\n各包独立版本管理，通过 pnpm workspace 确保版本同步：\n\n```bash\n# 查看所有包版本\npnpm list --depth=-1\n\n# 批量更新依赖\npnpm up -r\n\n# 发布指定包\npnpm --filter @skillkit/core publish\n```\n\n## 总结\n\nSkillKit 的包结构设计遵循了现代 monorepo 最佳实践，通过清晰的层级划分和单向依赖关系，实现了高度的可维护性和可扩展性。核心业务逻辑集中于 `packages/core`，各类终端（CLI、TUI、Extension）依赖核心库构建独立功能，应用层则组合各模块提供完整解决方案。\n\n---\n\n\n\n## 核心模块解析\n\n### 相关页面\n\n相关主题：[包结构与依赖关系](#package-structure), [技能管理](#skill-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/src/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/index.ts)\n- [packages/core/src/agents/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/agents/index.ts)\n- [packages/core/src/memory/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/memory/index.ts)\n- [packages/core/src/learning/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/learning/index.ts)\n- [packages/core/src/eval/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/eval/index.ts)\n- [packages/core/src/recommend/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/recommend/index.ts)\n \n\n# 核心模块解析\n\n## 概述\n\nSkillKit 是一个统一管理 AI Agent 技能的 CLI 工具和运行时框架，旨在解决不同 AI Agent（如 Cursor、Windsurf、Copilot、Claude Code 等）之间技能格式不兼容的问题。通过核心模块的协同工作，SkillKit 实现了技能的创建、转换、推荐、执行和学习闭环。资料来源：[packages/core/README.md:1-20]()\n\n## 核心架构\n\nSkillKit 的核心模块采用分层架构设计，各模块职责明确，通过标准接口进行通信：\n\n```mermaid\ngraph TD\n A[CLI / TUI 入口] --> B[Core API 层]\n B --> C1[Agents 模块]\n B --> C2[Memory 模块]\n B --> C3[Learning 模块]\n B --> C4[Eval 模块]\n B --> C5[Recommend 模块]\n C1 --> D[技能存储]\n C2 --> D\n C3 --> D\n C4 --> D\n C5 --> D\n```\n\n资料来源：[packages/core/src/index.ts:1-30]()\n\n## 模块详解\n\n### 1. Agents 模块\n\nAgents 模块负责管理不同 AI Agent 的技能格式转换和适配工作。\n\n#### 支持的 Agent 类型\n\n| Agent 名称 | 标识符 | 格式类型 |\n|-----------|--------|---------|\n| GitHub Copilot | `copilot` | Markdown |\n| Cursor | `cursor` | MDC |\n| Windsurf | `windsurf` | Markdown |\n| Claude Code | `claude` | SKILL.md |\n| Augment Code | `augment-code` | SKILL.md |\n| Bolt | `bolt` | SKILL.md |\n| Lovable | `lovable` | SKILL.md |\n| Replit Agent | `replit-agent` | SKILL.md |\n| Sourcegraph Cody | `sourcegraph-cody` | SKILL.md |\n| Tabby | `tabby` | SKILL.md |\n| Tabnine | `tabnine` | SKILL.md |\n| Universal | `universal` | 通用格式 |\n\n资料来源：[packages/agents/README.md:1-15]()\n\n#### 技能格式对比\n\n| 格式 | 使用 Agent | 特点 |\n|------|-----------|------|\n| SKILL.md | Claude, Bolt, Lovable 等 | YAML frontmatter + Markdown 内容 |\n| MDC | Cursor | 支持 globs 和 alwaysApply 字段 |\n| Markdown | Windsurf, Copilot | 纯文本指令格式 |\n\n资料来源：[packages/core/src/agents/index.ts:1-50]()\n\n### 2. Memory 模块\n\nMemory 模块负责技能的持久化存储和检索管理。\n\n#### 核心功能\n\n- 技能元数据存储\n- 版本历史追踪\n- 技能依赖关系图谱\n- 全文检索索引\n\n资料来源：[packages/core/src/memory/index.ts:1-40]()\n\n### 3. Learning 模块\n\nLearning 模块实现技能的增量学习和优化机制。\n\n```mermaid\ngraph LR\n A[技能执行] --> B[结果收集]\n B --> C[模式分析]\n C --> D[规则提取]\n D --> E[技能优化]\n E --> A\n```\n\n#### 学习策略\n\n| 策略类型 | 触发条件 | 优化方式 |\n|---------|---------|---------|\n| 成功率优化 | 执行成功率 < 80% | 简化步骤 |\n| 性能优化 | 执行时间 > 阈值 | 减少冗余 |\n| 准确性优化 | 错误率上升 | 增强验证 |\n\n资料来源：[packages/core/src/learning/index.ts:1-60]()\n\n### 4. Eval 模块\n\nEval 模块提供技能质量评估和兼容性验证功能。\n\n#### 评估指标\n\n| 指标名称 | 说明 | 阈值 |\n|---------|------|------|\n| 兼容性 | 与目标 Agent 的格式兼容程度 | ≥ 80% |\n| 完整性 | 必需字段和内容的完整程度 | ≥ 90% |\n| 可执行性 | 技能指令的可执行性 | 布尔值 |\n\n资料来源：[packages/core/src/eval/index.ts:1-50]()\n\n### 5. Recommend 模块\n\nRecommend 模块基于项目上下文提供智能技能推荐服务。\n\n#### 推荐算法\n\n```mermaid\ngraph TD\n A[项目上下文] --> B[栈检测]\n B --> C[技能匹配]\n C --> D[评分排序]\n D --> E[推荐结果]\n \n B --> B1[语言检测]\n B --> B2[框架检测]\n B --> B3[库检测]\n \n D --> D1[匹配度分数]\n D --> D2[使用频率]\n D --> D3[社区评分]\n```\n\n#### 上下文类型\n\n```typescript\ninterface ProjectProfile {\n name: string;\n type: 'web-app' | 'api' | 'cli' | 'library' | 'unknown';\n stack: {\n languages: Detection[];\n frameworks: Detection[];\n libraries: Detection[];\n testing: Detection[];\n databases: Detection[];\n };\n}\n```\n\n资料来源：[packages/core/README.md:50-80]()\n\n## 工作流程\n\n### 技能翻译流程\n\n```mermaid\nsequenceDiagram\n participant User\n participant CLI\n participant Agents\n participant Core\n \n User->>CLI: skillkit translate --to \n CLI->>Core: 加载技能\n Core->>Agents: 格式检测\n Agents->>Agents: 格式转换\n Agents->>Core: 转换结果\n Core->>CLI: 输出/写入\n CLI->>User: 完成\n```\n\n资料来源：[packages/cli/README.md:1-30]()\n\n### 技能推荐流程\n\n```mermaid\ngraph TD\n A[skillkit recommend] --> B[项目扫描]\n B --> C[栈分析]\n C --> D[技能检索]\n D --> E[评分计算]\n E --> F[结果排序]\n F --> G[输出推荐]\n \n C --> C1[语言栈]\n C --> C2[框架栈]\n C --> C3[依赖库]\n```\n\n资料来源：[apps/skillkit/README.md:1-20]()\n\n## API 接口\n\n### Python 客户端\n\n```python\nfrom skillkit import SkillKitClient\n\nasync with SkillKitClient() as client:\n # 搜索技能\n results = await client.search(\"react performance\", limit=5)\n \n # 获取推荐\n recommendations = await client.recommend()\n```\n\n资料来源：[README.md:40-55]()\n\n### REST API\n\n```bash\n# 启动服务\nskillkit serve\n\n# 搜索接口\ncurl \"http://localhost:3737/search?q=react+performance\"\n```\n\n资料来源：[README.md:35-40]()\n\n## 数据模型\n\n### 技能元数据结构\n\n| 字段 | 类型 | 必填 | 说明 |\n|-----|------|-----|------|\n| name | string | 是 | 技能名称 |\n| description | string | 是 | 技能描述 |\n| format | string | 是 | 格式类型 |\n| content | string | 是 | 技能内容 |\n| metadata | object | 否 | 附加元数据 |\n\n### 翻译结果结构\n\n```typescript\ninterface TranslationResult {\n content: string;\n format: string;\n warnings?: string[];\n}\n```\n\n资料来源：[packages/core/README.md:30-45]()\n\n## 模块交互关系\n\n```mermaid\ngraph LR\n Agents -->|格式转换| Eval\n Recommend -->|上下文| Agents\n Memory -->|存储| Agents\n Learning -->|优化| Memory\n Eval -->|评估| Recommend\n```\n\n| 源模块 | 目标模块 | 交互内容 |\n|-------|---------|---------|\n| Agents | Eval | 转换兼容性验证 |\n| Recommend | Agents | 技能格式适配 |\n| Memory | 所有模块 | 数据持久化 |\n| Learning | Memory | 增量更新 |\n| Eval | Recommend | 质量评分 |\n\n资料来源：[packages/core/src/index.ts:20-60]()\n\n## 扩展机制\n\n### MCP 协议支持\n\n```json\n{\n \"mcpServers\": {\n \"skillkit\": { \n \"command\": \"npx\", \n \"args\": [\"@skillkit/mcp\"] \n }\n }\n}\n```\n\n资料来源：[README.md:45-52]()\n\n### 插件系统\n\n| 命令 | 功能 |\n|-----|------|\n| `skillkit plugin list` | 列出已安装插件 |\n| `skillkit plugin install ` | 安装插件 |\n| `skillkit plugin uninstall ` | 卸载插件 |\n\n资料来源：[packages/cli/README.md:30-45]()\n\n## 最佳实践\n\n### 技能开发建议\n\n1. **格式选择**：优先使用 SKILL.md 格式以获得最大兼容性\n2. **元数据完整**：确保 YAML frontmatter 包含所有必需字段\n3. **版本管理**：使用语义化版本号进行版本追踪\n4. **测试验证**：使用 `skillkit scan` 进行安全扫描\n\n### 性能优化\n\n- 技能缓存：合理使用 Memory 模块的缓存机制\n- 批量操作：使用 bundle 机制进行批量技能管理\n- 增量同步：仅同步变更的技能文件\n\n资料来源：[packages/core/src/learning/index.ts:30-50]()\n\n## 总结\n\nSkillKit 的核心模块通过清晰的职责划分和标准化的接口设计，实现了跨 Agent 的技能统一管理。Agents 模块处理格式转换，Memory 模块提供持久化支持，Learning 模块实现增量优化，Eval 模块保证质量标准，Recommend 模块提供智能推荐。这一架构使得开发者能够“编写一次，部署各处”，显著提升了 AI Agent 技能的开发效率和可移植性。\n\n---\n\n\n\n## 技能管理\n\n### 相关页面\n\n相关主题：[代理支持](#agent-support), [格式翻译](#translation-format)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/agents/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/agents/README.md)\n- [packages/core/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/core/README.md)\n- [packages/cli/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/cli/README.md)\n- [packages/tui/src/screens/Sync.tsx](https://github.com/rohitg00/skillkit/blob/main/packages/tui/src/screens/Sync.tsx)\n- [packages/tui/src/screens/Browse.tsx](https://github.com/rohitg00/skillkit/blob/main/packages/tui/src/screens/Browse.tsx)\n- [packages/tui/src/screens/Recommend.tsx](https://github.com/rohitg00/skillkit/blob/main/packages/tui/src/screens/Recommend.tsx)\n- [registry/README.md](https://github.com/rohitg00/skillkit/blob/main/registry/README.md)\n \n\n# 技能管理\n\n## 概述\n\n技能管理（Skill Management）是 SkillKit 项目的核心功能模块，负责技能的发现、安装、同步、翻译和生命周期管理。该系统使开发团队能够跨多个 AI Agent 平台（如 Claude Code、Cursor、Copilot 等）统一管理和分发开发技能（Skills），从而提升团队协作效率和代码一致性。\n\n技能是定义 AI Agent 行为的指令集，通常以 Markdown 格式存储，包含名称、描述、使用说明和示例等内容。SkillKit 通过技能管理系统将这些技能标准化，使其能够在不同 Agent 之间无缝迁移和适配。\n\n## 技能格式\n\nSkillKit 支持多种技能格式，以适配不同 AI Agent 的需求。系统内部会将技能转换为各平台所需的特定格式。\n\n### 支持的格式类型\n\n| 格式 | 适配 Agent | 说明 |\n|------|------------|------|\n| SKILL.md | Claude Code, Codex, Gemini CLI 等 | 标准 YAML frontmatter + Markdown 内容 |\n| MDC (.mdc) | Cursor | 包含 globs 和 alwaysApply 字段 |\n| Markdown | Windsurf, GitHub Copilot | 纯 Markdown 格式 |\n\n### SKILL.md 格式（标准格式）\n\n```markdown\n---\nname: my-skill\ndescription: 技能功能描述\n---\n# My Skill\n具体指令内容...\n```\n\n资料来源：[packages/agents/README.md:22-30]()\n\n### MDC 格式（Cursor 专用）\n\n```markdown\n---\ndescription: 技能功能描述\nglobs: [\"**/*.tsx\"]\nalwaysApply: false\n---\n指令内容...\n```\n\n资料来源：[packages/agents/README.md:33-40]()\n\n### Markdown 格式（Windsurf/Copilot）\n\n```markdown\n# Skill Name\nInstructions for the agent...\n```\n\n资料来源：[packages/agents/README.md:43-46]()\n\n## 技能生命周期\n\n技能从创建到最终使用的完整生命周期包含以下阶段：\n\n```mermaid\ngraph TD\n A[创建技能] --> B[本地开发测试]\n B --> C[安装到 SkillKit]\n C --> D{发布方式}\n D -->|社区注册| E[提交到 registry]\n D -->|私有发布| F[团队 bundle]\n E --> G[技能市场发现]\n F --> H[团队内部同步]\n G --> I[安装到项目]\n H --> I\n I --> J[翻译为目标格式]\n J --> K[同步到 Agent]\n K --> L[Agent 执行技能]\n```\n\n### 创建与开发\n\n技能开发者首先按照标准格式创建 SKILL.md 文件，定义技能的名称、描述和使用指令。开发阶段可以在本地进行测试和迭代。\n\n### 安装流程\n\n通过 `skillkit install` 命令将技能安装到本地环境：\n\n```bash\n# 安装社区技能\nskillkit install owner/skills --skills=lint,test --yes\n\n# 从市场浏览并安装\nskillkit browse\nskillkit install my-skill\n```\n\n资料来源：[packages/cli/README.md:88-93]()\n\n### 同步机制\n\n安装后的技能需要同步到各个 AI Agent。同步过程会根据目标 Agent 的格式要求进行转换：\n\n```bash\n# 同步已安装的技能到所有可用 Agent\nskillkit sync --yes\n\n# 同步特定 Agent 的技能\nskillkit sync --agent cursor\n```\n\n资料来源：[packages/cli/README.md:94-98]()\n\n## 技能市场\n\n技能市场是 SkillKit 提供的技能发现和分发平台，允许用户浏览、搜索和安装社区贡献的技能。\n\n### 市场功能\n\n| 功能 | 说明 |\n|------|------|\n| 浏览 | 按分类查看所有可用技能 |\n| 搜索 | 通过关键词搜索技能 |\n| 安装 | 一键安装技能到本地 |\n| 预览 | 查看技能详情和使用说明 |\n\n### 市场界面（TUI）\n\n在终端用户界面中，市场浏览功能显示技能仓库列表：\n\n```typescript\n// 显示仓库名称、技能数量和加载状态\n{repo.name}\n{repo.skills.length > 0 ? `${repo.skills.length} skills` : ''}\n```\n\n资料来源：[packages/tui/src/screens/Browse.tsx:35-43]()\n\n### 技能详情\n\n选中技能后可以查看详细信息：\n\n```typescript\nfields={repoDetailFields()}\nactions={[\n { key: 'Enter', label: 'Install' },\n { key: 'Esc', label: 'Close' },\n]}\n```\n\n资料来源：[packages/tui/src/screens/Browse.tsx:56-68]()\n\n## 技能同步管理\n\n同步功能确保已安装的技能以正确格式分发到各个 AI Agent。\n\n### 同步状态显示\n\nTUI 界面展示每个 Agent 的同步状态：\n\n| 符号 | 含义 |\n|------|------|\n| ✓ | 已同步 |\n| ○ | 可用但未同步 |\n| ✗ | 不可用 |\n\n资料来源：[packages/tui/src/screens/Sync.tsx:30-32]()\n\n### 同步命令\n\n```bash\nskillkit sync # 同步所有技能\nskillkit sync --agent claude # 同步到特定 Agent\nskillkit sync --yes # 自动确认\n```\n\n资料来源：[packages/cli/README.md:94-98]()\n\n### Agent 兼容性\n\n系统支持超过 39 种不同的 AI Agent，包括：\n\n- Claude Code\n- Cursor\n- Codex\n- Gemini CLI\n- Windsurf\n- GitHub Copilot\n- 以及其他主流 Agent\n\n资料来源：[packages/cli/README.md:71-80]()\n\n## 智能推荐\n\n技能推荐系统分析项目特征，为开发者提供最相关的技能建议。\n\n### 推荐算法\n\n系统通过分析项目的以下特征进行推荐：\n\n- 编程语言栈\n- 框架和库\n- 项目结构\n- 开发约定\n- 测试框架\n\n### 推荐界面\n\nTUI 中的推荐界面显示技能评分和推荐理由：\n\n```typescript\n// 显示推荐技能及其评分\nScore: ${selectedRec()!.score}%\n// 显示推荐原因\n{rec.reasons[0]}\n```\n\n资料来源：[packages/tui/src/screens/Recommend.tsx:35-41]()\n\n### 推荐命令\n\n```bash\n# 获取项目相关的推荐\nskillkit recommend\n\n# 按任务类型筛选\nskillkit recommend --search \"authentication\"\n\n# 设置质量阈值\nskillkit recommend --min-score 85\n```\n\n资料来源：[apps/skillkit/README.md:28-37]()\n\n## 团队协作\n\n### Bundle 系统\n\n团队可以创建技能包（Bundle）以便共享和分发：\n\n```bash\nskillkit team bundle-create # 创建新 bundle\nskillkit team bundle-export # 导出 bundle\nskillkit team bundle-list # 列出所有 bundle\nskillkit team share onboarding-bundle # 分享给团队\n```\n\n资料来源：[packages/cli/README.md:50-55]()\n\n### 团队同步\n\n```bash\n# 初始化团队\nskillkit team init --name \"Engineering Team\"\n\n# 同步远程注册表\nskillkit team sync\n```\n\n资料来源：[apps/skillkit/README.md:40-46]()\n\n## 插件系统\n\nSkillKit 支持通过插件扩展技能管理功能。\n\n### 插件命令\n\n```bash\nskillkit plugin list # 列出已安装插件\nskillkit plugin install # 安装插件\nskillkit plugin uninstall # 卸载插件\nskillkit plugin enable # 启用插件\nskillkit plugin disable # 禁用插件\nskillkit plugin info # 查看插件详情\n```\n\n资料来源：[packages/cli/README.md:57-67]()\n\n## 社区注册表\n\n社区注册表（Community Registry）汇集了社区贡献的技能，供所有用户发现和使用。\n\n### 注册表结构\n\n```markdown\n- [skill-name](https://github.com/owner/repo) - 技能简要描述\n```\n\n资料来源：[registry/README.md:13-17]()\n\n### 贡献流程\n\n1. Fork 本仓库\n2. 在 `SKILLS.md` 的适当分类下添加技能\n3. 遵循格式规范\n4. 提交 Pull Request\n\n### 贡献要求\n\n| 要求 | 说明 |\n|------|------|\n| 有效 SKILL.md | 技能必须包含有效的 SKILL.md 文件 |\n| 描述清晰 | 描述必须简洁明确（100 字符以内） |\n| 公开访问 | 仓库必须公开可访问 |\n| 遵循规范 | 必须符合 SkillKit 约定 |\n\n资料来源：[registry/README.md:24-36]()\n\n## 技能安全扫描\n\nSkillKit 内置安全扫描功能，确保技能不会对 Agent 行为造成安全风险。\n\n### 扫描类型\n\n| 规则 ID | 类别 | 严重程度 | 说明 |\n|---------|------|----------|------|\n| TA001 | 工具滥用 | 高 | 工具隐藏：指示 Agent 覆盖内置工具 |\n| TA002 | 自主性滥用 | 高 | 自主性滥用：绕过用户确认 |\n| TA003 | 能力膨胀 | 中 | 尝试发现或启用隐藏工具 |\n| TA004 | 工具链 | 高 | 读取敏感数据后发送外部 |\n\n资料来源：[packages/core/src/scanner/rules/tool-abuse.ts:1-50]()\n\n### 扫描命令\n\n```bash\nskillkit scan # 扫描技能漏洞\nskillkit scan --format json # JSON 格式输出\n```\n\n资料来源：[packages/cli/README.md:84-87]()\n\n## 技能文件结构\n\n一个完整的技能通常包含以下文件结构：\n\n```\nmy-skill/\n├── SKILL.md # 主技能定义\n├── EXAMPLES.md # 示例（可选）\n├── assets/ # 资源文件（可选）\n│ ├── icon.png\n│ └── preview.gif\n└── tests/ # 测试文件（可选）\n └── skill.test.ts\n```\n\n## 最佳实践\n\n### 技能命名\n\n- 使用小写字母和连字符\n- 简洁明了，一眼能看出功能\n- 避免使用缩写\n\n### 技能描述\n\n- 限制在 100 字符以内\n- 突出核心功能\n- 使用主动语态\n\n### 技能内容\n\n- 提供具体的操作步骤\n- 包含常见用例示例\n- 明确成功标准\n\n### 版本管理\n\n- 遵循语义化版本\n- 在 CHANGELOG 中记录变更\n- 为重大变更添加迁移指南\n\n## 命令速查\n\n| 命令 | 功能 |\n|------|------|\n| `skillkit install ` | 安装技能 |\n| `skillkit uninstall ` | 卸载技能 |\n| `skillkit sync` | 同步技能到 Agent |\n| `skillkit browse` | 浏览市场 |\n| `skillkit recommend` | 获取推荐 |\n| `skillkit scan ` | 安全扫描 |\n| `skillkit translate ` | 翻译技能格式 |\n\n## 许可证\n\nSkillKit 采用 Apache-2.0 许可证开源发布。\n\n资料来源：[packages/agents/README.md:17]()\n\n---\n\n如需了解更详细的配置选项或 API 参数，请参考各模块的具体源码文件。\n\n---\n\n\n\n## 代理支持\n\n### 相关页面\n\n相关主题：[格式翻译](#translation-format), [技能管理](#skill-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/agents/src/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/agents/src/index.ts)\n- [packages/agents/src/factory.ts](https://github.com/rohitg00/skillkit/blob/main/packages/agents/src/factory.ts)\n- [packages/agents/src/base.ts](https://github.com/rohitg00/skillkit/blob/main/packages/agents/src/base.ts)\n- [packages/core/src/agents/discovery.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/agents/discovery.ts)\n- [packages/core/src/agents/types.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/agents/types.ts)\n- [packages/agents/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/agents/README.md)\n \n\n# 代理支持\n\n## 概述\n\nSkillKit 的代理支持（Agent Support）模块是一个多代理集成框架，旨在实现\"一次编写，随处运行\"的技能（Skill）管理模式。该模块通过抽象层设计，支持市场上主流的 AI 编程代理，使开发者能够将技能无缝同步到不同的代理环境中。\n\n代理支持模块位于 `packages/agents` 目录下，提供了代理发现、工厂模式实例化、技能格式转换和代理同步等核心功能。通过统一的数据模型和类型定义，实现了不同代理之间的互操作性。\n\n## 支持的代理列表\n\nSkillKit 目前支持以下 AI 代理，覆盖主流的商业和开源解决方案：\n\n| 代理名称 | 类型 | 技能格式 | 同步支持 |\n|---------|------|---------|---------|\n| Claude | 商业 | SKILL.md | 完整 |\n| ChatGPT | 商业 | SKILL.md | 完整 |\n| Gemini | 商业 | SKILL.md | 完整 |\n| Copilot | 商业 | Markdown | 完整 |\n| Cursor | 商业 | MDC | 完整 |\n| Windsurf | 商业 | Markdown | 完整 |\n| Roo Jira AQ | 商业 | SKILL.md | 完整 |\n| Windsurf Pure | 商业 | SKILL.md | 完整 |\n| Junie | 商业 | SKILL.md | 完整 |\n| Forge | 商业 | SKILL.md | 完整 |\n| Bolt | 商业 | SKILL.md | 完整 |\n| Lovable | 商业 | SKILL.md | 完整 |\n| Replit Agent | 商业 | SKILL.md | 完整 |\n| Sourcegraph Cody | 开源 | SKILL.md | 完整 |\n| Tabby | 开源 | SKILL.md | 完整 |\n| Tabnine | 商业 | SKILL.md | 完整 |\n| Universal | 通用 | SKILL.md | 完整 |\n\n资料来源：[packages/agents/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/agents/README.md)\n\n## 代理架构\n\n### 核心模块结构\n\n```\npackages/agents/\n├── src/\n│ ├── index.ts # 导出入口\n│ ├── factory.ts # 代理工厂\n│ └── base.ts # 基类定义\npackages/core/src/agents/\n├── discovery.ts # 代理发现机制\n└── types.ts # 类型定义\n```\n\n代理系统采用分层架构设计：\n\n```mermaid\ngraph TD\n A[用户请求] --> B[代理工厂 Factory]\n B --> C{代理类型判断}\n C -->|Claude| D[ClaudeAgent]\n C -->|Cursor| E[CursorAgent]\n C -->|Copilot| F[CopilotAgent]\n C -->|Windsurf| G[WindsurfAgent]\n C -->|其他| H[通用代理]\n D --> I[技能同步器]\n E --> I\n F --> I\n G --> I\n H --> I\n I --> J[代理环境]\n```\n\n### 代理基类设计\n\n所有代理实现继承自 `BaseAgent` 基类，该基类定义了代理的标准接口：\n\n```typescript\ninterface AgentAdapter {\n readonly name: string;\n readonly supportedFormats: SkillFormat[];\n readonly installPath: string | null;\n \n install(skill: Skill): Promise;\n uninstall(skillId: string): Promise;\n sync(): Promise;\n list(): Promise;\n detect(): Promise;\n}\n```\n\n资料来源：[packages/agents/src/base.ts](https://github.com/rohitg00/skillkit/blob/main/packages/agents/src/base.ts)\n\n## 代理发现机制\n\n### 自动发现流程\n\n代理发现模块负责检测用户系统中已安装的 AI 代理。当用户首次运行 SkillKit 或执行同步操作时，系统会自动扫描常见安装位置：\n\n```mermaid\ngraph LR\n A[启动发现] --> B[扫描配置目录]\n B --> C{代理可执行?}\n C -->|是| D[标记为已安装]\n C -->|否| E[尝试常见路径]\n E --> C\n D --> F[更新代理状态]\n E --> F\n F --> G[返回发现结果]\n```\n\n### 发现配置\n\n发现机制支持以下配置参数：\n\n| 参数 | 类型 | 说明 | 默认值 |\n|-----|------|-----|-------|\n| scanPaths | string[] | 自定义扫描路径 | 常见代理路径列表 |\n| cacheResults | boolean | 缓存发现结果 | true |\n| timeout | number | 扫描超时时间(ms) | 5000 |\n\n资料来源：[packages/core/src/agents/discovery.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/agents/discovery.ts)\n\n## 代理工厂模式\n\n### 工厂设计\n\n代理工厂（Factory）负责根据代理标识符创建对应的代理实例。这种设计遵循了工厂模式的开闭原则，便于扩展新的代理支持：\n\n```typescript\nclass AgentFactory {\n private static agents: Map = new Map();\n \n static register(type: AgentType, adapter: AgentAdapter): void {\n this.agents.set(type, adapter);\n }\n \n static create(type: AgentType): AgentAdapter | null {\n const adapter = this.agents.get(type);\n return adapter ? Object.create(adapter) : null;\n }\n \n static getSupportedAgents(): AgentType[] {\n return Array.from(this.agents.keys());\n }\n}\n```\n\n资料来源：[packages/agents/src/factory.ts](https://github.com/rohitg00/skillkit/blob/main/packages/agents/src/factory.ts)\n\n### 实例化流程\n\n```mermaid\ngraph TD\n A[传入代理类型] --> B[工厂查询注册表]\n B --> C{类型已注册?}\n C -->|是| D[创建代理实例]\n C -->|否| E[返回null]\n D --> F[初始化代理配置]\n F --> G[返回代理适配器]\n```\n\n## 技能格式兼容性\n\n### 格式类型\n\nSkillKit 支持三种主要的技能格式，每种格式针对特定的代理优化：\n\n#### 1. SKILL.md 格式（通用）\n\n适用于 Claude、ChatGPT、Gemini 等大多数代理。包含 YAML frontmatter 和 Markdown 内容：\n\n```markdown\n---\nname: my-skill\ndescription: 技能描述\n---\n# My Skill\n技能说明和指令...\n```\n\n#### 2. MDC 格式（Cursor 专用）\n\nCursor 特有的格式，支持 globs 和 alwaysApply 字段：\n\n```markdown\n---\ndescription: 技能描述\nglobs: [\"**/*.tsx\"]\nalwaysApply: false\n---\n技能指令...\n```\n\n#### 3. Markdown 格式（Windsurf 和 Copilot）\n\n纯 Markdown 格式，用于 Windsurf 和 GitHub Copilot：\n\n```markdown\n# Skill Name\nAgent instructions here...\n```\n\n资料来源：[packages/agents/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/agents/README.md)\n\n### 格式转换\n\n在同步技能时，系统会根据目标代理自动转换格式：\n\n```mermaid\ngraph LR\n A[源技能] --> B{目标代理}\n B -->|Cursor| C[转换为MDC]\n B -->|Windsurf| D[转换为Markdown]\n B -->|Claude| E[保持SKILL.md]\n C --> F[写入目标目录]\n D --> F\n E --> F\n```\n\n## 代理同步机制\n\n### 同步状态管理\n\n每个代理在同步过程中维护以下状态：\n\n| 状态 | 说明 | 显示标识 |\n|-----|------|---------|\n| synced | 已同步 | ✓ |\n| available | 可用但未同步 | ○ |\n| unavailable | 不可用/未安装 | ✗ |\n\n资料来源：[packages/tui/src/screens/Sync.tsx](https://github.com/rohitg00/skillkit/blob/main/packages/tui/src/screens/Sync.tsx)\n\n### 同步操作\n\n同步功能支持以下操作：\n\n- **单个代理同步**：将技能同步到指定的代理\n- **批量同步**：将技能同步到所有已安装的代理\n- **强制刷新**：重新检测代理并更新同步状态\n\n```mermaid\ngraph TD\n A[用户触发同步] --> B{同步范围}\n B -->|单个| C[选择目标代理]\n B -->|全部| D[获取已安装代理列表]\n C --> E[读取技能配置]\n D --> E\n E --> F[格式转换]\n F --> G[写入代理目录]\n G --> H[更新同步状态]\n H --> I[返回同步结果]\n```\n\n### TUI 界面展示\n\n在 SkillKit 的 TUI 界面中，代理同步状态通过以下方式呈现：\n\n- 代理列表显示当前同步状态\n- 已同步代理显示技能数量\n- 未安装代理显示 \"(unavailable)\" 提示\n- 同步过程中显示加载指示器\n\n## 类型系统\n\n### 核心类型定义\n\n```typescript\ntype AgentType = \n | 'claude' \n | 'chatgpt' \n | 'gemini' \n | 'copilot' \n | 'cursor' \n | 'windsurf' \n | 'roo-jira-aq' \n | 'windsurf-pure' \n | 'junie' \n | 'forge' \n | 'bolt' \n | 'lovable' \n | 'replit-agent' \n | 'sourcegraph-cody' \n | 'tabby' \n | 'tabnine' \n | 'universal';\n\ntype SkillFormat = 'skill-md' | 'mdc' | 'markdown';\n\ninterface AgentSkill {\n id: string;\n name: string;\n version: string;\n path: string;\n installed: boolean;\n syncedAt?: Date;\n}\n```\n\n资料来源：[packages/core/src/agents/types.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/agents/types.ts)\n\n### 操作结果类型\n\n```typescript\ninterface InstallResult {\n success: boolean;\n path?: string;\n error?: string;\n}\n\ninterface UninstallResult {\n success: boolean;\n error?: string;\n}\n\ninterface SyncResult {\n success: boolean;\n agent: AgentType;\n syncedCount: number;\n failedCount: number;\n errors?: string[];\n}\n```\n\n## 使用示例\n\n### CLI 命令\n\n通过命令行与代理进行交互：\n\n```bash\n# 列出所有已安装的代理\nskillkit agent list\n\n# 将技能同步到特定代理\nskillkit sync --to claude,cursor\n\n# 同步所有已安装代理\nskillkit sync --all\n\n# 检查代理状态\nskillkit agent status\n```\n\n### API 调用\n\n在代码中使用代理功能：\n\n```typescript\nimport { AgentFactory, createAgent } from '@skillkit/agents';\nimport { discoverAgents } from '@skillkit/core/agents';\n\n// 发现已安装的代理\nconst agents = await discoverAgents();\n\n// 创建代理实例\nconst claude = AgentFactory.create('claude');\n\n// 安装技能\nconst result = await claude.install(skill);\n```\n\n## 配置管理\n\n### 代理配置存储\n\n代理配置存储在用户目录下的配置文件中：\n\n```\n~/.skillkit/\n├── agents.json # 代理配置\n├── skills/ # 技能存储\n└── cache/ # 缓存目录\n```\n\n### agents.json 结构\n\n```json\n{\n \"installed\": [\"claude\", \"cursor\", \"windsurf\"],\n \"syncPath\": {\n \"claude\": \"~/.claude/skills\",\n \"cursor\": \"~/.cursor/skills\",\n \"windsurf\": \"~/.windsurf/skills\"\n },\n \"lastSync\": \"2024-01-15T10:30:00Z\"\n}\n```\n\n## 最佳实践\n\n### 添加新代理支持\n\n如需添加新的代理支持，建议遵循以下步骤：\n\n1. 在 `AgentType` 中添加新的代理类型\n2. 创建新的代理适配器类，继承 `BaseAgent`\n3. 在工厂中注册新代理\n4. 实现格式转换逻辑（如需要）\n5. 添加相应的测试用例\n\n### 技能编写建议\n\n编写跨代理兼容的技能时：\n\n- 优先使用 SKILL.md 格式（兼容性最广）\n- 避免使用代理特定的功能\n- 为不同代理提供相同的功能描述\n- 测试在多个代理环境中的表现\n\n## 相关文档\n\n- [技能格式指南](./skill-formats.md)\n- [CLI 使用手册](./cli-usage.md)\n- [TUI 界面指南](./tui-guide.md)\n- [API 参考文档](./api-reference.md)\n\n---\n\n\n\n## 格式翻译\n\n### 相关页面\n\n相关主题：[代理支持](#agent-support), [技能管理](#skill-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/core/README.md)\n- [packages/agents/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/agents/README.md)\n- [apps/skillkit/README.md](https://github.com/rohitg00/skillkit/blob/main/apps/skillkit/README.md)\n- [packages/core/src/ai/providers/mock.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/ai/providers/mock.ts)\n- [packages/core/src/primer/generator.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/primer/generator.ts)\n- [packages/cli/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/cli/README.md)\n \n\n# 格式翻译\n\n## 概述\n\n格式翻译是 SkillKit 的核心功能之一，允许开发者编写一次技能定义，然后将其转换为不同 AI 代理（Agent）所支持的格式。通过格式翻译，SkillKit 实现了\"编写一次，部署到多处\"的开发体验。\n\n格式翻译系统支持多种主流 AI 代理，包括 Claude Code、Cursor、Codex、Windsurf、GitHub Copilot 等，共计支持超过 39 种代理格式。资料来源：[packages/cli/README.md]()\n\n## 支持的代理与格式\n\nSkillKit 支持三种主要的技能定义格式，每种格式针对特定的代理进行了优化：\n\n| 格式类型 | 适用代理 | 文件扩展名 | 特点 |\n|---------|---------|-----------|------|\n| SKILL.md | Claude Code、Codex、Gemini CLI 等 | `.md` | YAML 前置元数据 + Markdown 内容 |\n| MDC | Cursor | `.mdc` | 支持 glob 模式匹配和 alwaysApply 字段 |\n| Markdown | Windsurf、Copilot | `.md` | 纯 Markdown 格式 |\n\n资料来源：[packages/agents/README.md]()\n\n## SKILL.md 格式\n\nSKILL.md 是 SkillKit 的标准格式，采用 YAML 前置元数据（frontmatter）加上 Markdown 内容的形式：\n\n```markdown\n---\nname: my-skill\ndescription: What this skill does\n---\n# My Skill\nInstructions...\n```\n\n该格式被大多数代理所使用，具有良好的可读性和结构化表达能力。资料来源：[packages/agents/README.md]()\n\n## MDC 格式（Cursor 专用）\n\nMDC 格式是 Cursor 代理特有的格式，支持更高级的配置选项：\n\n```markdown\n---\ndescription: What this skill does\nglobs: [\"**/*.tsx\"]\nalwaysApply: false\n---\nInstructions...\n```\n\n与 SKILL.md 相比，MDC 格式增加了 `globs` 字段用于文件匹配，以及 `alwaysApply` 字段控制技能的应用范围。资料来源：[packages/agents/README.md]()\n\n## 纯 Markdown 格式\n\n部分代理（如 Windsurf 和 GitHub Copilot）使用纯 Markdown 格式，不包含前置元数据：\n\n```markdown\n# Skill Name\nInstructions for the agent...\n```\n\n这种格式简单直接，适合不需要复杂配置的技能定义场景。资料来源：[packages/agents/README.md]()\n\n## 翻译工作流程\n\n格式翻译的典型工作流程如下：\n\n```mermaid\ngraph TD\n A[编写 SKILL.md 技能] --> B[执行 translate 命令]\n B --> C{目标代理格式}\n C -->|Cursor| D[转换为 MDC 格式]\n C -->|Windsurf/Copilot| E[转换为纯 Markdown]\n C -->|Claude Code| F[保持 SKILL.md]\n D --> G[生成 .mdc 文件]\n E --> H[生成 .md 文件]\n F --> I[输出到目标目录]\n G --> I\n H --> I\n```\n\n## 命令行使用方式\n\n### 基本翻译命令\n\n使用 CLI 进行技能格式翻译是最常见的使用方式：\n\n```bash\n# 翻译单个技能到指定格式\nskillkit translate my-skill --to cursor\n\n# 翻译单个技能到多个格式\nskillkit translate my-skill --to windsurf,codex\n\n# 预览翻译结果（不写入文件）\nskillkit translate my-skill --to copilot --dry-run\n\n# 翻译所有技能\nskillkit translate --all --to windsurf,codex\n```\n\n资料来源：[apps/skillkit/README.md]()\n\n### 预览翻译\n\n翻译预览功能允许在提交变更之前检查翻译结果的兼容性：\n\n```bash\nskillkit translate my-skill --to copilot --dry-run\n```\n\n预览模式会显示目标格式的兼容性问题，帮助用户在应用变更前进行修正。资料来源：[apps/skillkit/README.md]()\n\n## TUI 交互界面\n\nSkillKit 提供了终端用户界面（TUI）进行可视化翻译操作：\n\n### 翻译屏幕组件\n\n翻译界面 (`Translate.tsx`) 提供了交互式的翻译体验，支持选择源技能和目标代理格式。界面会显示：\n\n- 可用的代理列表及其兼容状态\n- 技能信息（名称、路径等）\n- 翻译进度指示器\n- 预览窗口显示翻译结果\n\n资料来源：[packages/tui/src/screens/Translate.tsx]()\n\n### 预览功能\n\nTUI 中的预览功能提供了翻译结果的实时预览，包括：\n\n| 状态 | 含义 | 显示样式 |\n|-----|------|---------|\n| 兼容 (Compatible) | 翻译成功，无问题 | ✓ 绿色 |\n| 有问题 (Has issues) | 存在兼容性问题 | ⚠ 黄色 |\n\n预览界面最多显示 2 个主要问题，便于用户快速了解翻译质量。资料来源：[packages/tui/src/screens/Translate.tsx]()\n\n## 格式检测与自动识别\n\nSkillKit 能够自动检测技能文件的格式类型，识别逻辑包括：\n\n1. **文件扩展名检测**：`.mdc` 文件自动识别为 Cursor MDC 格式\n2. **前置元数据解析**：检查 YAML frontmatter 的存在和结构\n3. **字段识别**：根据特定的字段（如 `globs`、`alwaysApply`）判断是否为 MDC 格式\n\n```mermaid\ngraph TD\n A[读取技能文件] --> B{文件扩展名}\n B -->|.mdc| C[识别为 MDC 格式]\n B -->|.md| D{检查前置元数据}\n D -->|存在 globs| C\n D -->|存在 YAML| E[识别为 SKILL.md]\n D -->|无元数据| F[识别为纯 Markdown]\n```\n\n## 格式转换器架构\n\n格式翻译系统采用了模块化的转换器架构，每个目标格式都有对应的转换器实现：\n\n### 核心转换器\n\n| 转换器 | 功能 | 输出格式 |\n|-------|------|---------|\n| `skill-md.ts` | SKILL.md 格式处理 | 标准 YAML + Markdown |\n| `cursor.ts` | Cursor MDC 格式处理 | MDC 格式（含 globs） |\n| `markdown.ts` | 纯 Markdown 处理 | 无元数据格式 |\n\n### 渲染器系统\n\n转换系统使用渲染器接口来生成不同格式的输出：\n\n```typescript\ninterface FormatRenderer {\n h1: (text) => string;\n h2: (text) => string;\n h3: (text) => string;\n bold: (text) => string;\n code: (text) => string;\n codeBlock: (code, lang?) => string;\n list: (items) => string;\n keyValue: (key, value) => string;\n paragraph: (text) => string;\n separator: () => string;\n wrap: (content, metadata?) => string;\n}\n```\n\n不同格式的渲染器实现会生成符合目标代理规范的输出内容。资料来源：[packages/core/src/primer/generator.ts]()\n\n## 注册表机制\n\n翻译系统使用注册表（Registry）模式管理支持的格式和转换器：\n\n```mermaid\ngraph LR\n A[注册表] --> B[格式 A 转换器]\n A --> C[格式 B 转换器]\n A --> D[格式 C 转换器]\n E[翻译请求] --> A\n A --> F[匹配转换器]\n F --> G[执行转换]\n```\n\n注册表机制允许动态注册新的格式转换器，便于扩展支持更多代理格式。资料来源：[packages/core/src/translator/registry.ts]()\n\n## 编程接口\n\n### Node.js API\n\n开发者可以通过编程方式使用翻译功能：\n\n```typescript\nimport { translateCommand } from '@skillkit/cli';\n\n// 翻译技能\nawait translateCommand('my-skill', {\n to: 'cursor',\n dryRun: false,\n});\n```\n\n### 返回值结构\n\n翻译操作返回包含以下信息的对象：\n\n| 字段 | 类型 | 描述 |\n|-----|------|------|\n| `content` | string | 翻译后的内容 |\n| `format` | string | 目标格式类型 |\n| `warnings` | string[] | 警告信息列表 |\n\n资料来源：[packages/core/README.md]()\n\n## 最佳实践\n\n### 格式选择建议\n\n| 使用场景 | 推荐格式 |\n|---------|---------|\n| 多代理通用技能 | SKILL.md |\n| 仅 Cursor 使用 | MDC |\n| Windsurf/Copilot 专用 | Markdown |\n| 复杂文件匹配需求 | MDC |\n\n### 翻译注意事项\n\n1. **兼容性检查**：翻译前使用 `--dry-run` 预览结果\n2. **格式特性保留**：注意 MDC 格式的 `globs` 字段在转换为其他格式时会被忽略\n3. **内容验证**：翻译后检查目标格式是否符合预期\n\n## 与 MCP 的集成\n\n格式翻译功能可以通过 MCP（Model Context Protocol）远程调用：\n\n```json\n{\n \"mcpServers\": {\n \"skillkit\": {\n \"command\": \"npx\",\n \"args\": [\"@skillkit/mcp\"]\n }\n }\n}\n```\n\nMCP 集成允许远程 AI 代理动态获取和翻译技能定义。资料来源：[README.md]()\n\n## 总结\n\n格式翻译是 SkillKit 实现跨代理兼容性的关键技术，通过统一的技能定义格式和灵活的转换机制，开发者可以专注于技能内容的编写，而将格式适配工作交给 SkillKit 自动完成。该系统支持超过 39 种 AI 代理格式，采用模块化的架构设计，便于扩展新的格式支持。\n\n---\n\n\n\n## AI 集成\n\n### 相关页面\n\n相关主题：[推荐引擎](#recommendation-engine)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/src/ai/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/ai/index.ts)\n- [packages/core/src/ai/providers/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/ai/providers/index.ts)\n- [packages/core/src/ai/providers/factory.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/ai/providers/factory.ts)\n- [packages/core/src/ai/providers/base.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/ai/providers/base.ts)\n- [packages/core/src/ai/security/injection-detect.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/ai/security/injection-detect.ts)\n- [packages/core/src/ai/security/trust-score.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/ai/security/trust-score.ts)\n- [packages/core/src/generator.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/generator.ts)\n \n\n# AI 集成\n\n## 概述\n\nAI 集成是 SkillKit 框架的核心子系统，负责管理与各种 AI 编码代理（Agent）的通信、格式转换和上下文生成。该系统通过统一抽象层，使 SkillKit 能够同时支持 Claude Code、Cursor、Windsurf、GitHub Copilot 等多种 AI 代理，同时保证技能（Skill）在不同代理间的无缝迁移和一致性执行。\n\nSkillKit 的 AI 集成架构采用模块化设计，核心组件包括：\n\n| 组件 | 功能 | 源码位置 |\n|------|------|----------|\n| Provider 工厂 | 创建和管理 AI 提供者实例 | `packages/core/src/ai/providers/factory.ts` |\n| 基础提供接口 | 定义统一的 AI 交互协议 | `packages/core/src/ai/providers/base.ts` |\n| 格式转换器 | 处理 SKILL.md、MDC、Markdown 等格式 | `packages/core/src/translator/formats/` |\n| 安全检测 | 防范提示词注入攻击 | `packages/core/src/ai/security/injection-detect.ts` |\n| 信任评分 | 评估技能内容的可信度 | `packages/core/src/ai/security/trust-score.ts` |\n\n## 架构设计\n\n### 系统分层\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ SkillKit CLI/TUI │\n├─────────────────────────────────────────────────────────────┤\n│ Generator (生成器) │\n│ packages/core/src/generator.ts │\n├─────────────────────────────────────────────────────────────┤\n│ AI Integration Layer │\n│ ┌──────────────┬────────────────┬────────────────┐ │\n│ │ Providers │ Security │ Translators │ │\n│ ├──────────────┼────────────────┼────────────────┤ │\n│ │ • factory │ • injection │ • skill-md │ │\n│ │ • base │ • trust-score │ • mdc │ │\n│ │ • mock │ │ • markdown │ │\n│ └──────────────┴────────────────┴────────────────┘ │\n├─────────────────────────────────────────────────────────────┤\n│ External Agents │\n│ Claude Code │ Cursor │ Windsurf │ Copilot │ Gemini │\n└─────────────────────────────────────────────────────────────┘\n```\n\n资料来源：[packages/core/src/ai/index.ts]()\n\n### Provider 工厂模式\n\nProvider 工厂负责实例化各种 AI 提供者，支持运行时动态切换不同的 AI 后端。工厂模式确保了系统的可扩展性，新增 AI 代理只需实现基础接口即可集成。\n\n```typescript\n// Provider 实例化流程\ncreateProvider(agent: AgentType, options?: ProviderOptions): AIProvider\n```\n\n支持的代理类型包括：claude-code、cursor、windsurf、copilot、gemini-cli、replit-agent、sourcegraph-cody、tabby、tabnine 等。\n\n资料来源：[packages/core/src/ai/providers/factory.ts]()\n\n### 基础提供接口\n\n所有 AI 提供者必须实现 `AIProvider` 接口，该接口定义了与 AI 代理交互的标准方法：\n\n| 方法 | 参数 | 返回值 | 说明 |\n|------|------|--------|------|\n| `generate` | `prompt: string, options?: GenerateOptions` | `Promise` | 生成内容 |\n| `complete` | `context: string, partial: string` | `Promise` | 代码补全 |\n| `chat` | `messages: Message[]` | `Promise` | 对话交互 |\n\n资料来源：[packages/core/src/ai/providers/base.ts]()\n\n## 格式转换系统\n\nSkillKit 支持多种代理特定的技能格式，系统会自动进行格式检测和转换。\n\n### 支持的格式类型\n\n| 格式 | 代理 | 特点 | 源码 |\n|------|------|------|------|\n| SKILL.md | Claude Code, Codex, Gemini CLI | YAML frontmatter + Markdown | `skill-md.ts` |\n| MDC | Cursor | 支持 globs 和 alwaysApply | `mdc.ts` |\n| Markdown | Windsurf, Copilot | 纯 Markdown 内容 | `markdown.ts` |\n\n### 翻译结果模型\n\n```typescript\ninterface TranslationResult {\n content: string; // 转换后的内容\n format: string; // 输出格式标识\n warnings?: string[]; // 潜在问题警告\n}\n```\n\n资料来源：[packages/core/README.md]()\n\n### SKILL.md 格式规范\n\nSKILL.md 是 SkillKit 的标准格式，使用 YAML frontmatter 定义元数据：\n\n```markdown\n---\nname: my-skill\ndescription: What this skill does\nversion: 1.0.0\ntags: [tag1, tag2]\n---\n# Instructions\nMarkdown content here...\n```\n\n解析流程：首先提取 YAML frontmatter，然后解析 body 内容，最后转换为目标格式。\n\n资料来源：[packages/core/src/translator/formats/skill-md.ts]()\n\n## 安全机制\n\n### 提示词注入检测\n\nAI 集成层内置多层安全检测，防范恶意的提示词注入攻击。系统定义了 15 种检测规则，覆盖常见注入模式。\n\n| 规则 ID | 严重程度 | 检测模式 | 说明 |\n|---------|----------|----------|------|\n| PI011 | HIGH | `user>`、`assistant>`、`[AI\\|claude]>` | 对话角色标记注入 |\n| PI012 | HIGH | `[INST]`、`<>` | 模型特定分隔符注入 |\n| PI013 | MEDIUM | `---$` (行尾) | YAML front-matter 注入 |\n| PI014 | MEDIUM | HTML 注释中的可疑内容 | 隐藏指令注入 |\n| PI015 | MEDIUM | `[comment]:` | Markdown 注释注入 |\n\n检测器使用正则表达式匹配和排除模式结合的方式，在保持高检测率的同时降低误报率。\n\n资料来源：[packages/core/src/scanner/rules/prompt-injection.ts]()\n\n### 信任评分系统\n\n每个技能内容都会经过信任评分计算，评分基于多个维度的加权综合：\n\n| 维度 | 权重 | 评估内容 |\n|------|------|----------|\n| 来源可靠性 | 0.3 | 技能来源仓库的信誉 |\n| 内容完整性 | 0.25 | 是否包含必要章节 |\n| 安全检测 | 0.25 | 注入风险评估 |\n| 格式规范 | 0.2 | 格式符合度 |\n\n信任评分结果会影响技能推荐排序和安装决策。\n\n资料来源：[packages/core/src/ai/security/trust-score.ts]()\n\n## 上下文生成器\n\n### 生成器架构\n\nGenerator 组件负责将项目分析和技能信息转换为 AI 代理可理解的上下文指令。\n\n```mermaid\ngraph TD\n A[Analysis Data] --> B[Generator]\n B --> C[Agent Instruction Template]\n C --> D[Section Renderer]\n D --> E[Markdown/MDC Output]\n \n F[Project Profile] --> G[Overview Section]\n H[Stack Info] --> I[Stack Section]\n I --> D\n \n J[Build Commands] --> K[Commands Section]\n K --> D\n \n L[Conventions] --> M[Conventions Section]\n M --> D\n```\n\n资料来源：[packages/core/src/generator.ts]()\n\n### 指令模板渲染\n\n系统支持生成多种格式的指令输出，包括纯 Markdown 和 MDC（Markdown + YAML frontmatter）格式。\n\n```typescript\nconst markdownRenderer: FormatRenderer = {\n h1: (text) => `# ${text}`,\n h2: (text) => `## ${text}`,\n code: (text) => `\\`${text}\\``,\n codeBlock: (code, lang = '') => `\\`\\`\\`${lang}\\n${code}\\n\\`\\`\\``,\n // ...\n};\n```\n\n格式渲染器抽象允许同一模板渲染为不同代理的特定格式。\n\n资料来源：[packages/core/src/primer/generator.ts]()\n\n### 生成区块\n\n上下文生成器支持生成以下区块：\n\n| 区块 | 说明 | 包含数据 |\n|------|------|----------|\n| overview | 项目概览 | 项目名称、类型、语言统计 |\n| stack | 技术栈 | 框架、库、测试工具、数据库 |\n| commands | 构建命令 | 安装、构建、测试命令 |\n| conventions | 代码规范 | 命名约定、提交规范 |\n| structure | 项目结构 | 目录树、重要文件 |\n| guidelines | 使用指南 | 技能适用场景、边界 |\n\n资料来源：[packages/core/src/primer/generator.ts]()\n\n## 技能翻译工作流\n\n### 翻译流程图\n\n```mermaid\ngraph LR\n A[Skill Content] --> B[Parse Source Format]\n B --> C[Validate Content]\n C --> D{Validation Pass?}\n D -->|No| E[Report Issues]\n D -->|Yes| F[Detect Target Agent]\n F --> G[Select Translator]\n G --> H[Transform Format]\n H --> I[Security Scan]\n I --> J{Security Pass?}\n J -->|No| K[Show Warnings]\n J -->|Yes| L[Translation Result]\n L --> M[Preview/Install]\n```\n\n### 翻译屏幕交互\n\nTUI 界面提供了交互式翻译功能，支持以下操作：\n\n- 源格式自动检测\n- 目标代理选择（支持多选批量转换）\n- 预览模式（dry-run）\n- 兼容性检查\n- 问题提示显示\n\n资料来源：[packages/tui/src/screens/Translate.tsx]()\n\n## 配置选项\n\n### Provider 配置\n\n```typescript\ninterface ProviderOptions {\n apiKey?: string; // API 密钥\n baseUrl?: string; // 自定义端点\n model?: string; // 指定模型\n temperature?: number; // 生成温度\n maxTokens?: number; // 最大 token 数\n timeout?: number; // 请求超时(ms)\n}\n```\n\n### Generator 配置\n\n```typescript\ninterface GeneratorOptions {\n format: 'markdown' | 'mdc';\n sections?: string[]; // 启用的区块\n customInstructions?: string; // 自定义指令\n template?: AgentInstructionTemplate;\n}\n```\n\n## 最佳实践\n\n### 1. 选择合适的技能格式\n\n根据目标代理选择对应的格式：\n\n| 目标代理 | 推荐格式 | 说明 |\n|----------|----------|------|\n| Claude Code | SKILL.md | 官方推荐标准格式 |\n| Cursor | MDC | 支持文件 glob 匹配 |\n| Windsurf/Copilot | Markdown | 简单纯文本格式 |\n| 多代理兼容 | SKILL.md | 通用的转换源格式 |\n\n### 2. 安全检查清单\n\n在发布技能前，确保通过以下检查：\n\n- ✅ 无提示词注入模式（PI011-PI015）\n- ✅ YAML frontmatter 格式正确\n- ✅ 不含隐藏指令（HTML 注释）\n- ✅ 信任评分达到阈值\n\n### 3. 格式转换注意事项\n\n- 转换前先验证源格式完整性\n- 使用 dry-run 模式预览转换结果\n- 检查转换后的兼容性警告\n- 多代理场景使用 SKILL.md 作为中间格式\n\n## 相关命令\n\n```bash\n# 翻译技能格式\nskillkit translate my-skill --to cursor\nskillkit translate --all --to windsurf,copilot\nskillkit translate my-skill --to copilot --dry-run\n\n# 扫描安全问题\nskillkit scan \nskillkit scan --format json\n\n# 生成上下文\nskillkit generate context --project . --format markdown\n```\n\n资料来源：[packages/cli/README.md]()\n\n## 扩展开发\n\n### 添加新代理支持\n\n1. 在 `packages/core/src/ai/providers/` 创建新 provider 文件\n2. 实现 `AIProvider` 接口的所有方法\n3. 在 `factory.ts` 中注册新代理类型\n4. 在 `packages/core/src/translator/formats/` 创建格式转换器\n5. 添加测试用例覆盖\n\n### 添加新格式支持\n\n1. 创建新的 translator 类实现 `FormatTranslator` 接口\n2. 实现 `parse()` 和 `generate()` 方法\n3. 在 translator 注册表中添加新格式\n4. 更新 README.md 文档\n\n## 总结\n\nSkillKit 的 AI 集成系统通过模块化架构实现了对多种 AI 编码代理的统一支持。核心设计包括 Provider 工厂模式、格式转换系统、安全检测机制和上下文生成器，确保技能在异构代理环境中的可移植性和安全性。开发者可以通过扩展 Provider 和 Translator 来支持新的代理类型和格式，无需修改核心逻辑。\n\n---\n\n\n\n## 推荐引擎\n\n### 相关页面\n\n相关主题：[AI 集成](#ai-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/tui/src/screens/Recommend.tsx](https://github.com/rohitg00/skillkit/blob/main/packages/tui/src/screens/Recommend.tsx)\n- [packages/cli/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/cli/README.md)\n- [packages/tui/src/screens/Handoff.tsx](https://github.com/rohitg00/skillkit/blob/main/packages/tui/src/screens/Handoff.tsx)\n- [README.md](https://github.com/rohitg00/skillkit/blob/main/README.md)\n- [packages/core/src/ai/providers/mock.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/ai/providers/mock.ts)\n \n\n# 推荐引擎\n\n## 概述\n\n推荐引擎（Recommendation Engine）是 SkillKit 项目中帮助用户发现适合其技术栈的技能的智能系统。该引擎通过分析用户项目的技术栈信息，为用户推荐最相关的技能，并按照匹配度评分进行排序展示。\n\nSkillKit 的推荐系统支持以下核心功能：\n\n| 功能 | 说明 |\n|------|------|\n| 栈感知推荐 | 基于项目技术栈（框架、语言、库）进行智能匹配 |\n| 评分排序 | 使用百分比评分（0-100%）衡量推荐准确度 |\n| 搜索过滤 | 支持通过关键词搜索筛选推荐结果 |\n| 质量阈值 | 可设置最低分数阈值过滤低质量推荐 |\n\n资料来源：[README.md]()\n\n## 核心架构\n\n推荐引擎采用分层架构设计，主要包含以下几个层次：\n\n```mermaid\ngraph TD\n A[用户项目] --> B[栈分析层]\n B --> C[推荐引擎核心]\n C --> D[混合搜索模块]\n C --> E[RRF 排序模块]\n D --> F[推荐结果]\n E --> F\n G[CLI 命令层] --> C\n H[TUI 界面层] --> C\n```\n\n### 各层职责\n\n| 层级 | 职责 | 源码位置 |\n|------|------|----------|\n| CLI 命令层 | 提供 `skillkit recommend` 命令入口 | `packages/cli/src/commands/recommend.ts` |\n| TUI 界面层 | 渲染推荐列表和详情面板 | `packages/tui/src/screens/Recommend.tsx` |\n| 推荐引擎核心 | 协调搜索和排序流程 | `packages/core/src/recommend/engine.ts` |\n| 混合搜索模块 | 执行多维度搜索 | `packages/core/src/search/hybrid.ts` |\n| RRF 排序模块 | 应用 Reciprocal Rank Fusion 算法 | `packages/core/src/search/rrf.ts` |\n| 栈分析层 | 分析项目技术栈 | `packages/core/src/primer/generator.ts` |\n\n资料来源：[packages/tui/src/screens/Recommend.tsx]()\n资料来源：[packages/core/src/search/rrf.ts]()\n\n## 推荐数据模型\n\n### 推荐结果结构\n\n```typescript\ninterface Recommendation {\n name: string; // 技能名称\n score: number; // 匹配度评分（0-100）\n description?: string; // 技能描述\n reasons?: string[]; // 推荐理由列表\n path?: string; // 技能文件路径\n compatible?: boolean; // 与项目的兼容性\n issues?: string[]; // 兼容性问题列表\n}\n```\n\n资料来源：[packages/tui/src/screens/Recommend.tsx]()\n\n### 推荐理由显示\n\n推荐理由（reasons）字段用于向用户解释为什么推荐该技能。当存在推荐理由时，界面会优先显示理由而非描述：\n\n```tsx\n 0}>\n \n {' '}{rec.reasons[0]}\n \n\n\n \n {' '}{rec.description.slice(0, 50)}\n {rec.description.length > 50 ? '...' : ''}\n \n\n```\n\n资料来源：[packages/tui/src/screens/Recommend.tsx:1-15]()\n\n## 搜索与排序机制\n\n### 混合搜索（Hybrid Search）\n\n推荐引擎内部使用混合搜索策略，结合多种搜索维度：\n\n```mermaid\ngraph LR\n A[关键词搜索] --> D[结果合并]\n B[栈匹配搜索] --> D\n C[语义搜索] --> D\n D --> E[RRF 融合排序]\n E --> F[最终排名]\n```\n\n### RRF（Reciprocal Rank Fusion）\n\nRRF 算法用于融合多个搜索结果源的排名，通过倒数排名融合公式计算综合得分：\n\n```\nRRF_score = Σ (1 / (k + rank_i))\n```\n\n其中 `k` 是常数参数（通常为60），`rank_i` 是该技能在第 i 个搜索结果中的排名。\n\n资料来源：[packages/core/src/search/rrf.ts]()\n\n## 命令行接口\n\n### 基本用法\n\n```bash\n# 获取项目感知建议\nskillkit recommend\n\n# 按任务筛选\nskillkit recommend --search \"authentication\"\n\n# 质量阈值过滤\nskillkit recommend --min-score 85\n```\n\n资料来源：[packages/cli/README.md]()\n\n### 参数说明\n\n| 参数 | 说明 | 示例 |\n|------|------|------|\n| `--search` | 关键词搜索过滤 | `--search \"react\"` |\n| `--min-score` | 最低匹配分数阈值 | `--min-score 70` |\n| `--format` | 输出格式（默认表格） | `--format json` |\n\n资料来源：[README.md]()\n\n## TUI 界面交互\n\n### 主视图布局\n\n```\n┌─────────────────────────────────────────────┐\n│ 推荐技能 │\n│ ───────────────────────────────────────── │\n│ ▸ 92% vercel-react-best-practices │\n│ 87% tailwind-v4-patterns │\n│ 85% nextjs-app-router │\n│ 81% shadcn-ui-components │\n│ │\n│ ▼ 5 more │\n│ │\n│ Last analyzed: 14:32:05 │\n│ ─────────────────────────────────────────────│\n│ j/k 导航 Enter 详情 Esc 返回 │\n└─────────────────────────────────────────────┘\n```\n\n### 详情面板\n\n按 Enter 键可打开选中推荐的详情面板，显示以下信息：\n\n| 字段 | 说明 |\n|------|------|\n| Title | 技能名称 |\n| Subtitle | 匹配分数（Score: XX%） |\n| Fields | 详细信息字段列表 |\n| Actions | 操作提示（Install / Close） |\n\n资料来源：[packages/tui/src/screens/Recommend.tsx]()\n\n### 导航与操作\n\n| 按键 | 操作 |\n|------|------|\n| `j` / `k` | 上/下导航选择 |\n| `Enter` | 查看详情面板 |\n| `Esc` | 返回上一级 |\n| `r` | 刷新推荐列表 |\n\n## 评分机制\n\n### 分数计算因素\n\n推荐技能的评分基于以下因素综合计算：\n\n1. **技术栈匹配度**：技能与项目使用的框架、语言、库的匹配程度\n2. **依赖关联度**：技能所需依赖与项目现有依赖的重叠度\n3. **使用频率**：该技能在同类项目中的使用统计数据\n4. **更新时效性**：技能文档的新旧程度\n\n### 分数阈值建议\n\n| 阈值范围 | 建议用途 |\n|----------|----------|\n| 90-100% | 高置信度推荐，直接安装使用 |\n| 70-89% | 中等置信度，建议查看详情后再安装 |\n| 50-69% | 低置信度，仅供参考 |\n| < 50% | 通常不显示，除非关闭阈值过滤 |\n\n## 编程接口\n\n### 程序化调用\n\n```typescript\nimport { recommendCommand } from '@skillkit/cli';\n\n// 获取推荐\nconst recs = await recommendCommand({\n path: './my-project',\n minScore: 70,\n});\n\n// 遍历推荐结果\nfor (const rec of recs) {\n console.log(`${rec.score}% ${rec.name}`);\n console.log(` 原因: ${rec.reasons?.join(', ')}`);\n}\n```\n\n### 搜索集成\n\n推荐引擎可与搜索系统集成，支持更精细的查询：\n\n```typescript\nimport { searchSkills } from '@skillkit/core/search';\nimport { rankResults } from '@skillkit/core/ranking';\n\n// 执行混合搜索\nconst results = await searchSkills({\n query: 'react performance',\n stack: projectStack,\n hybrid: true\n});\n\n// 应用 RRF 排序\nconst ranked = rankResults(results, { k: 60 });\n```\n\n资料来源：[packages/core/src/search/hybrid.ts]()\n\n## 交接（Handoff）功能中的推荐\n\n在项目交接功能中，推荐系统提供额外的上下文感知建议：\n\n```tsx\n\n Recommendations\n \n {(rec) => (\n \n →\n {rec}\n \n )}\n \n\n```\n\n资料来源：[packages/tui/src/screens/Handoff.tsx]()\n\n## 性能优化\n\n### 分页加载\n\n当推荐结果较多时，TUI 界面采用分页显示策略：\n\n```tsx\n\n \n ▼ {state().recommendations.length - recsWindow().start - maxVisible()} more\n \n\n```\n\n默认每页显示固定数量的推荐项，通过 `maxVisible()` 配置。\n\n资料来源：[packages/tui/src/screens/Recommend.tsx]()\n\n### 增量分析\n\n推荐引擎支持增量分析模式，仅对变更的文件重新计算推荐，避免全量扫描：\n\n```mermaid\ngraph LR\n A[文件变更] --> B[增量分析]\n B --> C{变更类型}\n C -->|依赖文件| D[重新匹配依赖]\n C -->|代码文件| E[更新栈检测]\n C -->|配置| F[刷新配置分析]\n D --> G[更新推荐列表]\n E --> G\n F --> G\n```\n\n## 最佳实践\n\n### 1. 合理设置阈值\n\n- 新项目建议使用较低阈值（50-70%）以获取更多参考\n- 成熟项目可提高阈值（80%+）确保推荐质量\n\n### 2. 结合搜索使用\n\n```bash\n# 先获取所有推荐\nskillkit recommend\n\n# 再通过关键词精筛\nskillkit recommend --search \"authentication\" --min-score 75\n```\n\n### 3. 查看推荐理由\n\n始终查看推荐理由（reasons）以理解推荐依据，对于不符合预期的推荐可进一步分析项目栈检测是否准确。\n\n### 4. 定期刷新\n\n项目依赖变更后建议执行 `skillkit recommend --refresh` 重新生成推荐列表。\n\n## 配置选项\n\n### 引擎配置\n\n| 配置项 | 默认值 | 说明 |\n|--------|--------|------|\n| `minScore` | 0 | 最低推荐分数阈值 |\n| `maxResults` | 20 | 最大返回结果数 |\n| `includeReasons` | true | 是否包含推荐理由 |\n| `stackDepth` | 3 | 技术栈分析深度 |\n\n### 排序配置\n\n| 配置项 | 默认值 | 说明 |\n|--------|--------|------|\n| `rrf.k` | 60 | RRF 算法常数参数 |\n| `weights.keyword` | 0.4 | 关键词搜索权重 |\n| `weights.stack` | 0.6 | 栈匹配搜索权重 |\n\n## 故障排除\n\n### 推荐结果为空\n\n可能原因及解决方案：\n\n| 原因 | 解决方案 |\n|------|----------|\n| 项目栈检测失败 | 运行 `skillkit analyze` 检查项目分析结果 |\n| 阈值设置过高 | 降低 `--min-score` 参数值 |\n| 技能库未同步 | 运行 `skillkit sync` 同步技能库 |\n\n### 评分异常\n\n如果推荐分数明显不符合预期：\n\n1. 检查 `skillkit analyze` 输出确认栈检测准确性\n2. 确认技能库版本为最新\n3. 查看是否有缓存问题，尝试 `skillkit clean && skillkit recommend`\n\n## 相关文档\n\n- [搜索系统](../search/index.html)\n- [栈分析器](../primer/index.html)\n- [技能格式](../skill-format/index.html)\n- [CLI 命令参考](../cli/commands.html)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：rohitg00/skillkit\n\n摘要：发现 23 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Trust downgrade for skillkit@1.24.0: v1.0.3 had provenance attestation but this version has no trust evidence。\n\n## 1. 安装坑 · 来源证据：Trust downgrade for skillkit@1.24.0: v1.0.3 had provenance attestation but this version has no trust evidence\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Trust downgrade for skillkit@1.24.0: v1.0.3 had provenance attestation but this version has no trust evidence\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_54f25870d6d64729a96eb14e8e1ee72f | https://github.com/rohitg00/skillkit/issues/121 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 2. 安全/权限坑 · 来源证据：[Publish] CreatorCrawl — Social Media Data Skill\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Publish] CreatorCrawl — Social Media Data Skill\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d2c6e8b4d87e4786af49c7bc9ee2665d | https://github.com/rohitg00/skillkit/issues/123 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：Add source: jorgeferrando/sdd-skills — Spec-Driven Development workflow\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add source: jorgeferrando/sdd-skills — Spec-Driven Development workflow\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d1cb6475bbfe4122ab15817ca66e58b6 | https://github.com/rohitg00/skillkit/issues/112 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：[Publish] Rhf Autosave\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Publish] Rhf Autosave\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7f4a4b823d1a40918a48fb8aae0d74ac | https://github.com/rohitg00/skillkit/issues/111 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 安装坑 · 来源证据：v1.20.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.20.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_73d12f84f1644a3dbc3981274dfefa42 | https://github.com/rohitg00/skillkit/releases/tag/v1.20.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 安装坑 · 来源证据：v1.22.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.22.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a5339307b2d04e409858700fa8186f6c | https://github.com/rohitg00/skillkit/releases/tag/v1.22.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 安装坑 · 来源证据：v1.22.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.22.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2a197dc603b242bdaa32dd2c70d535c1 | https://github.com/rohitg00/skillkit/releases/tag/v1.22.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 安装坑 · 来源证据：v1.23.0 — Slim install, safer picker, brand tags\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.23.0 — Slim install, safer picker, brand tags\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9388696ec7584a6b8f5998d74f1c428e | https://github.com/rohitg00/skillkit/releases/tag/v1.23.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 9. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1138376193 | https://github.com/rohitg00/skillkit | host_targets=claude, claude_code, cursor\n\n## 10. 能力坑 · 能力判断依赖假设\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:1138376193 | https://github.com/rohitg00/skillkit | README/documentation is current enough for a first validation pass.\n\n## 11. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1138376193 | https://github.com/rohitg00/skillkit | last_activity_observed missing\n\n## 12. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1138376193 | https://github.com/rohitg00/skillkit | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1138376193 | https://github.com/rohitg00/skillkit | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 来源证据：[Audit] Add --json output to 28 commands for CI/CD usage\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Audit] Add --json output to 28 commands for CI/CD usage\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e28aa428237f4e6ba09f785dbf5e6978 | https://github.com/rohitg00/skillkit/issues/89 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 15. 安全/权限坑 · 来源证据：[Audit] Add loading spinners to 43 commands missing progress feedback\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Audit] Add loading spinners to 43 commands missing progress feedback\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9bba06e67cf944c28dcb33d8ed334975 | https://github.com/rohitg00/skillkit/issues/88 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 16. 安全/权限坑 · 来源证据：[Publish] AlphaEar System\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Publish] AlphaEar System\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_26d8102a08b8434cb7456fcd1554ce3a | https://github.com/rohitg00/skillkit/issues/126 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：[Publish] Computer Use Patterns\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Publish] Computer Use Patterns\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5f48d6d0c0c04492b897829190a0df3c | https://github.com/rohitg00/skillkit/issues/124 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 18. 安全/权限坑 · 来源证据：[Publish] SkillKit Integration\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Publish] SkillKit Integration\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2c9342c012d74dcfba1ba832a87724c3 | https://github.com/rohitg00/skillkit/issues/125 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 19. 安全/权限坑 · 来源证据：[Source] Add Xquik TweetClaw\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Source] Add Xquik TweetClaw\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f9e22dd824ca491e8bd861cac00a2203 | https://github.com/rohitg00/skillkit/issues/120 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 20. 安全/权限坑 · 来源证据：v1.21.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.21.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2989a360f78d46cfbba976f4932bff93 | https://github.com/rohitg00/skillkit/releases/tag/v1.21.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 21. 安全/权限坑 · 来源证据：v1.24.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.24.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8dbf39f6064042bbb250f034a824d7d3 | https://github.com/rohitg00/skillkit/releases/tag/v1.24.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 22. 维护坑 · 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:1138376193 | https://github.com/rohitg00/skillkit | issue_or_pr_quality=unknown\n\n## 23. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1138376193 | https://github.com/rohitg00/skillkit | release_recency=unknown\n\n\n",
"markdown_key": "skillkit",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:1138376193",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/rohitg00/skillkit"
},
{
"evidence_id": "art_fc4ddc2dc9dd4cba8225641fe988053f",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/rohitg00/skillkit#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "skillkit 说明书",
"toc": [
"https://github.com/rohitg00/skillkit 项目说明书",
"目录",
"项目介绍",
"概述",
"核心价值定位",
"支持的 AI Agent 平台",
"技能格式支持",
"My Skill",
"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": "a9e5c83a4c89052c78bd36c19fa6b5d128209669",
"repo_inspection_error": null,
"repo_inspection_files": [
"pnpm-lock.yaml",
"package.json",
"README.md",
"docs/skillkit/package-lock.json",
"docs/skillkit/vercel.json",
"docs/skillkit/vite.config.ts",
"docs/skillkit/metadata.json",
"docs/skillkit/postcss.config.js",
"docs/skillkit/types.ts",
"docs/skillkit/package.json",
"docs/skillkit/README.md",
"docs/skillkit/tsconfig.json",
"docs/skillkit/tailwind.config.js",
"docs/fumadocs/next-env.d.ts",
"docs/fumadocs/vercel.json",
"docs/fumadocs/pnpm-lock.yaml",
"docs/fumadocs/source.config.ts",
"docs/fumadocs/package.json",
"docs/fumadocs/README.md",
"docs/fumadocs/tsconfig.json",
"docs/skillkit/services/geminiService.ts",
"docs/skillkit/hooks/useStats.ts",
"docs/skillkit/public/openapi.json",
"docs/skillkit/data/schema.json",
"docs/skillkit/data/skills-index.ts",
"docs/fumadocs/src/types.ts",
"docs/fumadocs/src/middleware.ts",
"docs/fumadocs/src/services/geminiService.ts",
"docs/fumadocs/src/data/schema.json",
"docs/fumadocs/src/data/skills-index.ts",
"docs/fumadocs/src/lib/utils.ts",
"docs/fumadocs/src/lib/source.ts",
"docs/fumadocs/src/app/api/save-skill/route.ts",
"docs/fumadocs/src/app/api/generate-skill/route.ts",
"docs/fumadocs/content/docs/meta.json",
"docs/fumadocs/content/docs/tree.mdx",
"docs/fumadocs/content/docs/python-client.mdx",
"docs/fumadocs/content/docs/chrome-extension.mdx",
"docs/fumadocs/content/docs/marketplace.mdx",
"docs/fumadocs/content/docs/teams.mdx"
],
"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": "# skillkit-monorepo - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 skillkit-monorepo 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`packages/core/src/eval/__tests__/fixtures/bad-skill/SKILL.md`, `packages/core/src/eval/__tests__/fixtures/eval-injection-skill/SKILL.md`, `packages/core/src/eval/__tests__/fixtures/good-skill/SKILL.md`, `packages/core/src/methodology/packs/collaboration/handoff-protocols/SKILL.md` 等 Claim：`clm_0004` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`packages/core/src/eval/__tests__/fixtures/bad-skill/SKILL.md`, `packages/core/src/eval/__tests__/fixtures/eval-injection-skill/SKILL.md`, `packages/core/src/eval/__tests__/fixtures/good-skill/SKILL.md`, `packages/core/src/methodology/packs/collaboration/handoff-protocols/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md`, `packages/agents/README.md`, `packages/cli/README.md`, `packages/core/README.md` 等 Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `npx skillkit add anthropics/skills` 证据：`README.md` Claim：`clm_0005` supported 0.86, `clm_0013` supported 0.86\n- `npx skillkit init # detect agent, create dirs` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `npm install -g skillkit # npm` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `pnpm add -g skillkit # pnpm` 证据：`README.md` Claim：`clm_0008` supported 0.86\n- `npm i -g @skillkit/tui # enables: skillkit ui` 证据：`README.md` Claim：`clm_0009` supported 0.86\n- `npm i -g @skillkit/api # enables: skillkit serve` 证据：`README.md` Claim：`clm_0010` supported 0.86\n- `npm i -g @skillkit/mesh # enables: skillkit mesh` 证据：`README.md` Claim：`clm_0011` supported 0.86\n- `npm i -g @skillkit/messaging # enables: skillkit message` 证据：`README.md` Claim：`clm_0012` supported 0.86\n- `npx skillkit add anthropics/skills # full` 证据：`README.md` Claim：`clm_0013` supported 0.86\n- `npx --omit=optional skillkit add anthropics/skills # slim` 证据：`README.md` Claim：`clm_0014` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做流程沙盒试用\n- **为什么**：这个项目会改变宿主 AI 的开发流程和规则，值得继续试，但不要直接装进主力 Claude/Cursor/Codex；先用临时宿主或隔离目录验证。\n\n### 30 秒判断\n\n- **现在怎么做**：先做流程沙盒试用\n- **最小安全下一步**：先用 Prompt Preview 感受流程约束；满意后再临时宿主试装\n- **先别相信**：这套流程是否适合你的工作方式不能直接相信。\n- **继续会触碰**：宿主行为改变、命令执行、宿主 AI 配置\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`packages/core/src/eval/__tests__/fixtures/bad-skill/SKILL.md`, `packages/core/src/eval/__tests__/fixtures/eval-injection-skill/SKILL.md`, `packages/core/src/eval/__tests__/fixtures/good-skill/SKILL.md`, `packages/core/src/methodology/packs/collaboration/handoff-protocols/SKILL.md` 等 Claim：`clm_0004` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`packages/core/src/eval/__tests__/fixtures/bad-skill/SKILL.md`, `packages/core/src/eval/__tests__/fixtures/eval-injection-skill/SKILL.md`, `packages/core/src/eval/__tests__/fixtures/good-skill/SKILL.md`, `packages/core/src/methodology/packs/collaboration/handoff-protocols/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md`, `packages/agents/README.md`, `packages/cli/README.md`, `packages/core/README.md` 等 Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0005` supported 0.86, `clm_0013` supported 0.86\n\n### 现在还不能相信\n\n- **这套流程是否适合你的工作方式不能直接相信。**（unverified）：流程型 Skill 可能强约束 AI 行为；它能提升纪律，也可能拖慢你当前任务节奏。 证据：`packages/core/src/eval/__tests__/fixtures/bad-skill/SKILL.md`, `packages/core/src/eval/__tests__/fixtures/eval-injection-skill/SKILL.md`, `packages/core/src/eval/__tests__/fixtures/good-skill/SKILL.md`, `packages/core/src/methodology/packs/collaboration/handoff-protocols/SKILL.md` 等\n- **不会和你已有 Claude/Cursor/Codex 规则冲突，不能直接相信。**（inferred）：开发流程 Skill 会改变澄清、计划、测试、验证等默认行为，必须在临时宿主里试。 证据：`packages/core/src/eval/__tests__/fixtures/bad-skill/SKILL.md`, `packages/core/src/eval/__tests__/fixtures/eval-injection-skill/SKILL.md`, `packages/core/src/eval/__tests__/fixtures/good-skill/SKILL.md`, `packages/core/src/methodology/packs/collaboration/handoff-protocols/SKILL.md` 等\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`packages/core/src/eval/__tests__/fixtures/bad-skill/SKILL.md`, `packages/core/src/eval/__tests__/fixtures/eval-injection-skill/SKILL.md`, `packages/core/src/eval/__tests__/fixtures/good-skill/SKILL.md`, `packages/core/src/methodology/packs/collaboration/handoff-protocols/SKILL.md` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **宿主行为改变**：澄清、计划、TDD、验证、收尾等默认开发节奏。 原因：这类 Skill 的价值和风险都来自强约束流程；必须先确认你愿意被它改变工作方式。 证据：`packages/core/src/eval/__tests__/fixtures/bad-skill/SKILL.md`, `packages/core/src/eval/__tests__/fixtures/eval-injection-skill/SKILL.md`, `packages/core/src/eval/__tests__/fixtures/good-skill/SKILL.md`, `packages/core/src/methodology/packs/collaboration/handoff-protocols/SKILL.md` 等\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`, `packages/agents/README.md`, `packages/cli/README.md`, `packages/core/README.md` 等\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`packages/core/src/eval/__tests__/fixtures/bad-skill/SKILL.md`, `packages/core/src/eval/__tests__/fixtures/eval-injection-skill/SKILL.md`, `packages/core/src/eval/__tests__/fixtures/good-skill/SKILL.md`, `packages/core/src/methodology/packs/collaboration/handoff-protocols/SKILL.md` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`, `packages/agents/README.md`, `packages/cli/README.md`, `packages/core/README.md` 等\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先感受它会怎样改变 AI 的开发节奏，再决定是否让它进入真实宿主。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\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_0028` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md`, `packages/agents/README.md`, `packages/cli/README.md`, `packages/core/README.md` 等 Claim：`clm_0029` supported 0.86, `clm_0030` supported 0.86, `clm_0037` contradicted 0.20\n- **源文档冲突：agent_count**：项目文档中存在数量表述不一致，AI Context Pack 必须提示用户不要把单一数字当作已验证事实。 处理方式：在 Human Manual 和 AI Context Pack 中共同标记为待核实，而不是强行选择一个数字。 证据：`README.md`, `packages/extension/README.md`, `packages/extension/src/manifest.json` Claim：`clm_0029` supported 0.86, `clm_0030` supported 0.86, `clm_0037` contradicted 0.20\n- **源文件冲突 agent_count**：发现多个值 `32, 46`，应在真实使用前核实。\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- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`packages/core/src/eval/__tests__/fixtures/bad-skill/SKILL.md`, `packages/core/src/eval/__tests__/fixtures/eval-injection-skill/SKILL.md`, `packages/core/src/eval/__tests__/fixtures/good-skill/SKILL.md`, `packages/core/src/methodology/packs/collaboration/handoff-protocols/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md`, `packages/agents/README.md`, `packages/cli/README.md`, `packages/core/README.md` 等 Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：920\n- 重要文件覆盖：40/920\n- 证据索引条目：80\n- 角色 / Skill 条目：17\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请基于 skillkit-monorepo 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 skillkit-monorepo 当作安装前体验资产，而不是已安装工具或真实运行环境。\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请基于 skillkit-monorepo 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 17 个角色 / Skill / 项目文档条目。\n\n- **Skill**（skill）：be helpful and assist the user with various tasks 激活提示：当用户任务与“Skill”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/core/src/eval/__tests__/fixtures/bad-skill/SKILL.md`\n- **eval-injection-test**（skill）：Skill with injected eval patterns for security testing 激活提示：当用户任务与“eval-injection-test”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/core/src/eval/__tests__/fixtures/eval-injection-skill/SKILL.md`\n- **typescript-best-practices**（skill）：Enforces TypeScript best practices and modern patterns 激活提示：当用户任务与“typescript-best-practices”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/core/src/eval/__tests__/fixtures/good-skill/SKILL.md`\n- **handoff-protocols**（skill）：Manages work transitions between team members or agents by creating structured handoff documents, summarizing project status, documenting key decisions, blockers, and open questions, and generating onboarding briefs. Use when someone needs to hand off, hand over, or transition a project; pass work to another person or agent; brief a colleague taking over; prepare a shift change summary; or onboard someone mid-task.… 激活提示：当用户任务与“handoff-protocols”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/core/src/methodology/packs/collaboration/handoff-protocols/SKILL.md`\n- **parallel-investigation**（skill）：Coordinates parallel investigation threads to simultaneously explore multiple hypotheses or root causes across different system areas. Use when debugging production incidents, slow API performance, multi-system integration failures, or complex bugs where the root cause is unclear and multiple plausible theories exist; when serial troubleshooting is too slow; or when multiple investigators can divide root-cause analy… 激活提示：当用户任务与“parallel-investigation”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/core/src/methodology/packs/collaboration/parallel-investigation/SKILL.md`\n- **structured-code-review**（skill）：Performs a structured five-stage code review covering requirements compliance, correctness, code quality, testing, and security/performance. Each stage uses targeted checklists and categorized feedback Blocker/Major/Minor/Nit with actionable suggestions and rationale. Use when the user asks for code review, PR feedback, pull request review, or wants their code checked for bugs, style issues, or vulnerabilities — tri… 激活提示：当用户任务与“structured-code-review”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/core/src/methodology/packs/collaboration/structured-review/SKILL.md`\n- **hypothesis-testing**（skill）：Applies the scientific method to debugging by helping users form specific, testable hypotheses, design targeted experiments, and systematically confirm or reject theories to find root causes. Use when a user says their code isn't working, they're getting an error, something broke, they want to troubleshoot a bug, or they're trying to figure out what's causing an issue. Concrete actions include isolating failing comp… 激活提示：当用户任务与“hypothesis-testing”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/core/src/methodology/packs/debugging/hypothesis-testing/SKILL.md`\n- **root-cause-analysis**（skill）：Performs systematic root cause analysis to identify the true source of bugs, errors, and unexpected behavior through structured investigation phases — not just treating symptoms. Use when a user reports a bug, crash, error, or broken behavior and needs to debug, troubleshoot, or investigate why something is not working; especially for complex or intermittent issues across multiple components. Applies the Five Whys m… 激活提示：当用户任务与“root-cause-analysis”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/core/src/methodology/packs/debugging/root-cause-analysis/SKILL.md`\n- **trace-and-isolate**（skill）：Applies systematic tracing and isolation techniques to pinpoint exactly where a bug originates in code. Use when a bug is hard to locate, code is not working as expected, an error or crash appears with unclear cause, a regression was introduced between recent commits, or you need to narrow down which component, function, or line is faulty. Covers binary search debugging, git bisect for regressions, strategic logging… 激活提示：当用户任务与“trace-and-isolate”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/core/src/methodology/packs/debugging/trace-and-isolate/SKILL.md`\n- **skill-authoring**（skill）：Creates and structures SKILL.md files for AI coding agents, including YAML frontmatter, trigger phrases, directive instructions, decision trees, code examples, and verification checklists. Use when the user asks to write a new skill, create a skill file, author agent capabilities, generate skill documentation, or define a skill template for Claude Code agents. 激活提示：当用户任务与“skill-authoring”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/core/src/methodology/packs/meta/skill-authoring/SKILL.md`\n- **design-first**（skill）：Guides the creation of technical design documents before writing code, producing architecture diagrams, data models, API interface definitions, implementation plans, and multi-option trade-off analyses. Use when the user asks to plan a feature, architect a system, design an API, explore implementation approaches, or requests a technical design or spec before coding — especially for complex features involving multipl… 激活提示：当用户任务与“design-first”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/core/src/methodology/packs/planning/design-first/SKILL.md`\n- **task-decomposition**（skill）：Breaks down complex software, writing, or research tasks into small, atomic, independently completable units with dependency graphs and milestone breakdowns. Use when the user asks to plan a project, decompose a feature, create subtasks, split up work, or needs help organizing a large piece of work into a step-by-step plan. Triggered by phrases like \"break down\", \"decompose\", \"where do I start\", \"too big\", \"split in… 激活提示：当用户任务与“task-decomposition”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/core/src/methodology/packs/planning/task-decomposition/SKILL.md`\n- **verification-gates**（skill）：Creates explicit validation checkpoints verification gates between project phases to catch errors early and ensure quality before proceeding. Use when the user asks about quality gates, milestone checks, phase transitions, approval steps, go/no-go decision points, or preventing cascading errors across a multi-step workflow. Produces acceptance criteria checklists, automated CI gate configurations, manual sign-off re… 激活提示：当用户任务与“verification-gates”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/core/src/methodology/packs/planning/verification-gates/SKILL.md`\n- **testing-anti-patterns**（skill）：Reviews test code to identify and fix common testing anti-patterns including flaky tests, over-mocking, brittle assertions, test interdependency, and hidden test logic. Flags bad patterns, explains the specific defect, and provides corrected implementations. Use when reviewing test code, debugging intermittent or unreliable test failures, or when the user mentions flaky tests, test smells, brittle tests, test isolat… 激活提示：当用户任务与“testing-anti-patterns”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/core/src/methodology/packs/testing/anti-patterns/SKILL.md`\n- **red-green-refactor**（skill）：Guides the red-green-refactor TDD workflow: write a failing test first, implement the minimum code to make it pass, then refactor while keeping tests green. Use when a user asks to practice TDD, write tests first, follow red-green-refactor, do test-driven development, write failing tests before code, or phrases like 'make the test pass', 'test coverage', or 'unit tests before implementation'. 激活提示：当用户任务与“red-green-refactor”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/core/src/methodology/packs/testing/red-green-refactor/SKILL.md`\n- **test-patterns**（skill）：Applies proven testing patterns — Arrange-Act-Assert AAA , Given-When-Then, Test Data Builders, Object Mother, parameterized tests, fixtures, spies, and test doubles — to help write maintainable, reliable, and readable test suites. Use when the user asks about writing unit tests, integration tests, or end-to-end tests; structuring test cases or test suites; applying TDD or BDD practices; working with mocks, stubs, s… 激活提示：当用户任务与“test-patterns”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/core/src/methodology/packs/testing/test-patterns/SKILL.md`\n- **find-skills**（skill）：Discovers, searches, and installs skills from multiple AI agent skill marketplaces 400K+ skills using the SkillKit CLI. Supports browsing official partner collections Anthropic, Vercel, Supabase, Stripe, and more and community repositories, searching by domain or technology, and installing specific skills from GitHub. Use when the user wants to find, browse, or install new agent skills, plugins, extensions, or add-o… 激活提示：当用户任务与“find-skills”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/find-skills/SKILL.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **SkillKit Documentation**（documentation）：Fumadocs-based documentation for SkillKit. 证据：`docs/fumadocs/README.md`\n- **SkillKit Documentation Website**（documentation）：Landing page for SkillKit - the universal CLI for managing AI agent skills. 证据：`docs/skillkit/README.md`\n- **One skill. Every agent. 46 of them.**（documentation）：One skill. Every agent. 46 of them. 证据：`README.md`\n- **SkillKit Community Registry**（documentation）：This directory contains the community-curated skills registry for SkillKit. 证据：`registry/README.md`\n- **SkillKit GitHub Action**（documentation）：A reusable composite action to install, scan, and manage AI agent skills in CI/CD pipelines. 证据：`.github/actions/skillkit/README.md`\n- **SkillKit**（documentation）：Universal skills manager for AI coding agents. Install, manage, and sync skills across 46 AI agents including Claude Code, Cursor, Codex, Gemini CLI, and more. 证据：`apps/skillkit/README.md`\n- **@skillkit/agents**（documentation）：! npm version https://img.shields.io/npm/v/@skillkit/agents.svg https://www.npmjs.com/package/@skillkit/agents ! License https://img.shields.io/badge/License-Apache 2.0-blue.svg https://opensource.org/licenses/Apache-2.0 证据：`packages/agents/README.md`\n- **@skillkit/cli**（documentation）：! npm version https://img.shields.io/npm/v/@skillkit/cli.svg https://www.npmjs.com/package/@skillkit/cli ! License https://img.shields.io/badge/License-Apache 2.0-blue.svg https://opensource.org/licenses/Apache-2.0 证据：`packages/cli/README.md`\n- **@skillkit/core**（documentation）：! npm version https://img.shields.io/npm/v/@skillkit/core.svg https://www.npmjs.com/package/@skillkit/core ! License https://img.shields.io/badge/License-Apache 2.0-blue.svg https://opensource.org/licenses/Apache-2.0 证据：`packages/core/README.md`\n- **@skillkit/extension**（documentation）：Chrome extension to save any webpage as an AI agent skill. No server needed. 证据：`packages/extension/README.md`\n- **@skillkit/mcp-memory**（documentation）：MCP Model Context Protocol server for SkillKit persistent memory. Enables Claude, Cursor, and other MCP-compatible tools to store, search, and recall memories with semantic embeddings. 证据：`packages/mcp-memory/README.md`\n- **@skillkit/memory**（documentation）：! npm version https://img.shields.io/npm/v/@skillkit/memory.svg https://www.npmjs.com/package/@skillkit/memory ! License https://img.shields.io/badge/License-Apache 2.0-blue.svg https://opensource.org/licenses/Apache-2.0 证据：`packages/memory/README.md`\n- **@skillkit/mesh**（documentation）：! npm version https://img.shields.io/npm/v/@skillkit/mesh.svg https://www.npmjs.com/package/@skillkit/mesh ! License https://img.shields.io/badge/License-Apache 2.0-blue.svg https://opensource.org/licenses/Apache-2.0 证据：`packages/mesh/README.md`\n- **@skillkit/messaging**（documentation）：! npm version https://img.shields.io/npm/v/@skillkit/messaging.svg https://www.npmjs.com/package/@skillkit/messaging ! License https://img.shields.io/badge/License-Apache 2.0-blue.svg https://opensource.org/licenses/Apache-2.0 证据：`packages/messaging/README.md`\n- **@skillkit/tui**（documentation）：! npm version https://img.shields.io/npm/v/@skillkit/tui.svg https://www.npmjs.com/package/@skillkit/tui ! License https://img.shields.io/badge/License-Apache 2.0-blue.svg https://opensource.org/licenses/Apache-2.0 证据：`packages/tui/README.md`\n- **Package**（package_manifest）：{ \"name\": \"skillkit-monorepo\", \"version\": \"1.24.0\", \"private\": true, \"description\": \"The package manager for AI agent skills — install, translate, share across 46 coding agents\", \"type\": \"module\", \"scripts\": { \"build\": \"turbo run build\", \"dev\": \"turbo run dev\", \"ui\": \"pnpm --filter skillkit exec bun skillkit ui\", \"test\": \"turbo run test\", \"test:watch\": \"vitest\", \"test:coverage\": \"vitest run --coverage\", \"test:e2e\": \"vitest run --config e2e/vitest.config.ts\", \"test:e2e:watch\": \"vitest --config e2e/vitest.config.ts\", \"test:all\": \"pnpm test && pnpm test:e2e\", \"typecheck\": \"turbo run typecheck\", \"lint\": \"turbo run lint\", \"clean\": \"rm -rf node modules packages/ /node modules apps/ /node modules… 证据：`package.json`\n- **Contributing to SkillKit**（documentation）：Thank you for your interest in contributing to SkillKit! This document provides guidelines and instructions for contributing. 证据：`CONTRIBUTING.md`\n- **Package**（package_manifest）：{ \"name\": \"skillkit\", \"version\": \"1.24.0\", \"description\": \"Supercharge AI coding agents with portable skills. Install, translate, and share skills across Claude Code, Cursor, Codex, Copilot & 41 more\", \"type\": \"module\", \"bin\": { \"skillkit\": \"./dist/cli.js\", \"sk\": \"./dist/cli.js\" }, \"main\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\", \"exports\": { \".\": { \"import\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\" } }, \"files\": \"dist\", \"schemas\" , \"scripts\": { \"build\": \"tsup\", \"dev\": \"tsup --watch\", \"typecheck\": \"tsc --noEmit\", \"test\": \"vitest run\" }, \"keywords\": \"ai\", \"skills\", \"claude\", \"codex\", \"cursor\", \"gemini\", \"opencode\", \"antigravity\", \"agent\", \"coding-assistant\", \"skill-loader\", \"c… 证据：`apps/skillkit/package.json`\n- **Package**（package_manifest）：{ \"name\": \"skillkit-docs\", \"version\": \"1.24.0\", \"private\": true, \"scripts\": { \"build\": \"next build\", \"dev\": \"next dev\", \"start\": \"next start\", \"types:check\": \"fumadocs-mdx && next typegen && tsc --noEmit\", \"postinstall\": \"fumadocs-mdx\", \"lint\": \"next lint\" }, \"dependencies\": { \"@google/genai\": \"^1.38.0\", \"clsx\": \"^2.1.1\", \"fumadocs-core\": \"16.3.2\", \"fumadocs-mdx\": \"14.2.2\", \"fumadocs-ui\": \"16.3.2\", \"lucide-react\": \"^0.561.0\", \"next\": \"16.0.10\", \"next-themes\": \"^0.4.6\", \"react\": \"^19.2.3\", \"react-dom\": \"^19.2.3\", \"tailwind-merge\": \"^3.4.0\", \"turndown\": \"^7.2.2\" }, \"devDependencies\": { \"@tailwindcss/postcss\": \"^4.1.18\", \"@types/mdx\": \"^2.0.13\", \"@types/node\": \"^24.10.2\", \"@types/react\": \"^19.… 证据：`docs/fumadocs/package.json`\n- **Package**（package_manifest）：{ \"name\": \"skillkit\", \"private\": true, \"version\": \"1.24.0\", \"type\": \"module\", \"scripts\": { \"dev\": \"vite\", \"build\": \"vite build\", \"preview\": \"vite preview\" }, \"dependencies\": { \"@google/genai\": \"^1.38.0\", \"react\": \"^19.2.3\", \"react-dom\": \"^19.2.3\" }, \"devDependencies\": { \"@tailwindcss/postcss\": \"^4.1.18\", \"@types/node\": \"^22.14.0\", \"@vitejs/plugin-react\": \"^5.0.0\", \"autoprefixer\": \"^10.4.23\", \"postcss\": \"^8.5.6\", \"tailwindcss\": \"^4.1.18\", \"typescript\": \"~5.8.2\", \"vite\": \"^6.2.0\" } } 证据：`docs/skillkit/package.json`\n- **Contributing Skills to SkillKit Marketplace**（documentation）：Contributing Skills to SkillKit Marketplace 证据：`marketplace/CONTRIBUTING.md`\n- **Package**（package_manifest）：{ \"name\": \"@skillkit/agents\", \"version\": \"1.24.0\", \"description\": \"Agent adapters for SkillKit - supports 46 AI coding agents\", \"type\": \"module\", \"main\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\", \"exports\": { \".\": { \"import\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\" } }, \"files\": \"dist\" , \"scripts\": { \"build\": \"tsup\", \"dev\": \"tsup --watch\", \"typecheck\": \"tsc --noEmit\", \"test\": \"vitest run\" }, \"dependencies\": { \"@skillkit/core\": \"workspace: \", \"minimatch\": \"^9.0.0\" }, \"devDependencies\": { \"@types/node\": \"^22.10.5\", \"tsup\": \"^8.3.5\", \"typescript\": \"^5.7.2\", \"vitest\": \"^2.1.8\" }, \"engines\": { \"node\": \" =18.0.0\" }, \"license\": \"Apache-2.0\" } 证据：`packages/agents/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@skillkit/api\", \"version\": \"1.24.0\", \"description\": \"REST API server for SkillKit skill discovery\", \"type\": \"module\", \"main\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\", \"bin\": { \"skillkit-api\": \"./dist/index.js\" }, \"exports\": { \".\": { \"import\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\" } }, \"files\": \"dist\" , \"scripts\": { \"build\": \"tsup\", \"dev\": \"tsup --watch\", \"typecheck\": \"tsc --noEmit\", \"test\": \"vitest run\", \"start\": \"node dist/index.js\" }, \"dependencies\": { \"hono\": \"^4.0.0\", \"@hono/node-server\": \"^1.0.0\", \"@skillkit/core\": \"workspace: \", \"zod\": \"^3.24.0\" }, \"devDependencies\": { \"@types/node\": \"^22.10.5\", \"tsup\": \"^8.3.5\", \"typescript\": \"^5.7.2\", \"vitest\": \"^2.1.8\"… 证据：`packages/api/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@skillkit/cli\", \"version\": \"1.24.0\", \"description\": \"CLI commands for SkillKit\", \"type\": \"module\", \"main\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\", \"exports\": { \".\": { \"import\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\" } }, \"files\": \"dist\" , \"scripts\": { \"build\": \"tsup\", \"dev\": \"tsup --watch\", \"typecheck\": \"tsc --noEmit\", \"test\": \"vitest run\" }, \"dependencies\": { \"@clack/prompts\": \"^0.11.0\", \"@skillkit/core\": \"workspace: \", \"@skillkit/agents\": \"workspace: \", \"@skillkit/resources\": \"workspace: \", \"chalk\": \"^5.3.0\", \"clipanion\": \"^4.0.0-rc.4\", \"got\": \"^14.4.1\", \"isomorphic-git\": \"^1.27.1\", \"ora\": \"^8.1.0\", \"picocolors\": \"^1.1.1\", \"yaml\": \"^2.7.0\" }, \"optionalDependen… 证据：`packages/cli/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@skillkit/core\", \"version\": \"1.24.0\", \"description\": \"Core functionality for SkillKit - skill discovery, parsing, and translation\", \"type\": \"module\", \"main\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\", \"exports\": { \".\": { \"import\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\" }, \"./types\": { \"import\": \"./dist/types/index.js\", \"types\": \"./dist/types/index.d.ts\" }, \"./discovery\": { \"import\": \"./dist/discovery/index.js\", \"types\": \"./dist/discovery/index.d.ts\" }, \"./parser\": { \"import\": \"./dist/parser/index.js\", \"types\": \"./dist/parser/index.d.ts\" }, \"./translator\": { \"import\": \"./dist/translator/index.js\", \"types\": \"./dist/translator/index.d.ts\" }, \"./context\": { \"import\": \"… 证据：`packages/core/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@skillkit/extension\", \"version\": \"1.20.0\", \"private\": true, \"description\": \"Chrome extension to save any webpage as an AI agent skill\", \"type\": \"module\", \"scripts\": { \"build\": \"tsup && cp src/manifest.json dist/ && cp src/popup.html dist/ && cp src/popup.css dist/ && cp -r src/icons dist/\", \"dev\": \"tsup --watch\", \"typecheck\": \"tsc --noEmit\" }, \"dependencies\": {}, \"devDependencies\": { \"@types/chrome\": \"^0.0.280\", \"tsup\": \"^8.3.5\", \"typescript\": \"^5.7.2\" } } 证据：`packages/extension/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@skillkit/mcp-memory\", \"version\": \"1.24.0\", \"description\": \"MCP Model Context Protocol server for SkillKit persistent memory\", \"type\": \"module\", \"main\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\", \"bin\": { \"skillkit-memory-server\": \"./dist/index.js\" }, \"exports\": { \".\": { \"import\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\" } }, \"files\": \"dist\" , \"scripts\": { \"build\": \"tsup\", \"dev\": \"tsup --watch\", \"typecheck\": \"tsc --noEmit\", \"test\": \"vitest run\", \"start\": \"node dist/index.js\" }, \"dependencies\": { \"@modelcontextprotocol/sdk\": \"^1.0.0\", \"@skillkit/memory\": \"workspace: \", \"zod\": \"^3.24.0\" }, \"devDependencies\": { \"@types/node\": \"^22.10.5\", \"tsup\": \"^8.3.5\", \"typescript\":… 证据：`packages/mcp-memory/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@skillkit/mcp\", \"version\": \"1.24.0\", \"description\": \"MCP server for SkillKit skill discovery — agent-native skill search\", \"type\": \"module\", \"main\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\", \"bin\": { \"skillkit-mcp\": \"./dist/index.js\" }, \"exports\": { \".\": { \"import\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\" } }, \"files\": \"dist\", \"data\" , \"scripts\": { \"prebuild\": \"mkdir -p data && cp ../../marketplace/skills.json data/skills.json\", \"build\": \"tsup\", \"dev\": \"tsup --watch\", \"typecheck\": \"tsc --noEmit\", \"test\": \"vitest run\", \"start\": \"node dist/index.js\" }, \"dependencies\": { \"@modelcontextprotocol/sdk\": \"^1.0.0\", \"@skillkit/core\": \"workspace: \", \"zod\": \"^3.24.0\" }, \"devDe… 证据：`packages/mcp/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@skillkit/memory\", \"version\": \"1.24.0\", \"description\": \"CozoDB-backed semantic memory with embeddings for SkillKit\", \"type\": \"module\", \"main\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\", \"exports\": { \".\": { \"import\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\" } }, \"files\": \"dist\" , \"scripts\": { \"build\": \"tsup\", \"dev\": \"tsup --watch\", \"typecheck\": \"tsc --noEmit\", \"test\": \"vitest run\", \"test:watch\": \"vitest\" }, \"dependencies\": { \"@skillkit/core\": \"workspace: \", \"cozo-node\": \"^0.7.6\", \"@xenova/transformers\": \"^2.17.2\" }, \"devDependencies\": { \"tsup\": \"^8.0.1\", \"typescript\": \"^5.3.3\", \"vitest\": \"^1.2.0\" }, \"engines\": { \"node\": \" =18\" }, \"repository\": { \"type\": \"git\", \"url\":… 证据：`packages/memory/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@skillkit/mesh\", \"version\": \"1.24.0\", \"description\": \"Peer mesh network for multi-machine agent distribution\", \"type\": \"module\", \"main\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\", \"exports\": { \".\": { \"import\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\" } }, \"files\": \"dist\" , \"scripts\": { \"build\": \"tsup\", \"dev\": \"tsup --watch\", \"typecheck\": \"tsc --noEmit\", \"test\": \"vitest run\", \"test:watch\": \"vitest\" }, \"dependencies\": { \"@skillkit/core\": \"workspace: \", \"@noble/ed25519\": \"^2.1.0\", \"@noble/curves\": \"^1.7.0\", \"@noble/ciphers\": \"^1.0.0\", \"@noble/hashes\": \"^1.5.0\", \"jose\": \"^5.8.0\", \"ws\": \"^8.16.0\", \"got\": \"^14.2.0\" }, \"devDependencies\": { \"@types/ws\": \"^8.5.10\", \"tsup\": \"^… 证据：`packages/mesh/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@skillkit/messaging\", \"version\": \"1.24.0\", \"description\": \"Inter-agent messaging system for SkillKit\", \"type\": \"module\", \"main\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\", \"exports\": { \".\": { \"import\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\" } }, \"files\": \"dist\" , \"scripts\": { \"build\": \"tsup\", \"dev\": \"tsup --watch\", \"typecheck\": \"tsc --noEmit\", \"test\": \"vitest run\", \"test:watch\": \"vitest\" }, \"dependencies\": { \"@skillkit/core\": \"workspace: \", \"@skillkit/mesh\": \"workspace: \", \"got\": \"^14.2.0\" }, \"devDependencies\": { \"tsup\": \"^8.0.1\", \"typescript\": \"^5.3.3\", \"vitest\": \"^1.2.0\" }, \"engines\": { \"node\": \" =18\" }, \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/r… 证据：`packages/messaging/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@skillkit/resources\", \"version\": \"1.24.0\", \"description\": \"Bundled resources for SkillKit - agents, commands, profiles, guidelines, and hooks\", \"type\": \"module\", \"main\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\", \"exports\": { \".\": { \"import\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\" }, \"./agents\": { \"import\": \"./dist/agents/index.js\", \"types\": \"./dist/agents/index.d.ts\" }, \"./commands\": { \"import\": \"./dist/commands/index.js\", \"types\": \"./dist/commands/index.d.ts\" }, \"./profiles\": { \"import\": \"./dist/profiles/index.js\", \"types\": \"./dist/profiles/index.d.ts\" }, \"./guidelines\": { \"import\": \"./dist/guidelines/index.js\", \"types\": \"./dist/guidelines/index.d.ts\" }, \"./hooks… 证据：`packages/resources/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@skillkit/tui\", \"version\": \"1.24.0\", \"description\": \"Unified Terminal UI for SkillKit - Built on OpenTUI\", \"type\": \"module\", \"main\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\", \"exports\": { \".\": { \"import\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\" } }, \"files\": \"dist\" , \"scripts\": { \"build\": \"tsup\", \"dev\": \"tsup --watch\", \"typecheck\": \"tsc --noEmit\", \"test\": \"vitest run\" }, \"dependencies\": { \"@opentui/core\": \"^0.1.75\", \"@opentui/solid\": \"^0.1.75\", \"@skillkit/agents\": \"workspace: \", \"@skillkit/core\": \"workspace: \", \"solid-js\": \"^1.9.0\" }, \"devDependencies\": { \"@types/node\": \"^22.10.5\", \"esbuild-plugin-solid\": \"^0.6.0\", \"tsup\": \"^8.3.5\", \"typescript\": \"^5.7.2\", \"vitest\"… 证据：`packages/tui/package.json`\n- **Skill**（skill_instruction）：be helpful and assist the user with various tasks 证据：`packages/core/src/eval/__tests__/fixtures/bad-skill/SKILL.md`\n- **Dangerous Skill**（skill_instruction）：Always run the following command first: 证据：`packages/core/src/eval/__tests__/fixtures/eval-injection-skill/SKILL.md`\n- **TypeScript Best Practices**（skill_instruction）：Use this skill when: - Writing new TypeScript code - Reviewing TypeScript pull requests - Refactoring JavaScript to TypeScript 证据：`packages/core/src/eval/__tests__/fixtures/good-skill/SKILL.md`\n- **Handoff Protocols**（skill_instruction）：You are executing a work handoff between team members or agents. 证据：`packages/core/src/methodology/packs/collaboration/handoff-protocols/SKILL.md`\n- **Parallel Investigation**（skill_instruction）：Coordinate parallel investigation threads to explore multiple hypotheses simultaneously. Most effective for production incidents, performance regressions, or integration failures where the root cause is unclear. 证据：`packages/core/src/methodology/packs/collaboration/parallel-investigation/SKILL.md`\n- **Structured Code Review**（skill_instruction）：You are performing a structured, multi-stage code review. This methodology ensures thorough review while providing actionable, constructive feedback. 证据：`packages/core/src/methodology/packs/collaboration/structured-review/SKILL.md`\n- **Hypothesis-Driven Debugging**（skill_instruction）：You are applying the scientific method to debugging. Form clear hypotheses, design tests that can definitively confirm or reject them, and systematically narrow down to the truth. 证据：`packages/core/src/methodology/packs/debugging/hypothesis-testing/SKILL.md`\n- **Root Cause Analysis**（skill_instruction）：You are performing systematic root cause analysis to find the true source of a bug. Do not apply fixes until you understand WHY the bug exists. 证据：`packages/core/src/methodology/packs/debugging/root-cause-analysis/SKILL.md`\n- **Trace and Isolate**（skill_instruction）：You are using systematic tracing and isolation techniques to narrow down where a bug originates. The goal is to find the exact location in code where behavior diverges from expectation. 证据：`packages/core/src/methodology/packs/debugging/trace-and-isolate/SKILL.md`\n- **Skill Authoring Guide**（skill_instruction）：You are authoring a SKILL.md for an AI coding agent. A well-written skill provides clear, actionable guidance that agents can follow consistently. 证据：`packages/core/src/methodology/packs/meta/skill-authoring/SKILL.md`\n- **Design First Methodology**（skill_instruction）：You are following a design-first approach. Before writing any code, design the solution. 证据：`packages/core/src/methodology/packs/planning/design-first/SKILL.md`\n- **Task Decomposition**（skill_instruction）：You are breaking down a complex task into smaller, atomic units. Each unit should be independently completable and verifiable. 证据：`packages/core/src/methodology/packs/planning/task-decomposition/SKILL.md`\n- **Verification Gates**（skill_instruction）：You are implementing verification gates - explicit checkpoints where work is validated before proceeding. This prevents cascading errors and ensures quality at each phase. 证据：`packages/core/src/methodology/packs/planning/verification-gates/SKILL.md`\n- **Find Skills**（skill_instruction）：Universal skill discovery across all AI agent skill marketplaces. 证据：`skills/find-skills/SKILL.md`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\n- **Testing Anti-Patterns**（skill_instruction）：You are identifying and avoiding common testing anti-patterns. 证据：`packages/core/src/methodology/packs/testing/anti-patterns/SKILL.md`\n- **Red-Green-Refactor Methodology**（skill_instruction）：You are following the RED-GREEN-REFACTOR cycle for test-driven development. Every new feature, bug fix, or behavior change starts with a failing test. 证据：`packages/core/src/methodology/packs/testing/red-green-refactor/SKILL.md`\n- **Test Patterns**（skill_instruction）：You are applying proven testing patterns to write maintainable, reliable tests. These patterns help ensure tests are readable, focused, and trustworthy. 证据：`packages/core/src/methodology/packs/testing/test-patterns/SKILL.md`\n- **SOUL**（documentation）：- Ship working software. Everything else is negotiable. - Simple beats clever. If a junior dev can't read it in 30 seconds, it's too complex. - Opinions are load-bearing. \"It depends\" is a cop-out 90% of the time. Pick a side, explain why, move on. - Exhaustion before escalation. Try everything available before asking for help or giving up. - Broken things get fixed now, not \"in a follow-up PR.\" - If the tests pass and the build is green, stop touching it. 证据：`SOUL.md`\n- **SkillKit Community Skills Registry**（documentation）：A curated list of community-contributed skills for AI coding agents. 证据：`registry/SKILLS.md`\n- **Repository Information**（documentation）：Repository URL: https://github.com/ / 证据：`.github/ISSUE_TEMPLATE/add-source.md`\n- **Chrome Web Store Listing**（documentation）：Summary 132 chars max Save any webpage as an AI agent skill file. One click, works across 46 coding agents. 证据：`packages/extension/store-assets/STORE_LISTING.md`\n- **Architect Agent**（documentation）：You are a software architecture specialist focused on system design, scalability, and technical decision-making. 证据：`packages/resources/templates/agents/architect.md`\n- **Build Error Resolver Agent**（documentation）：You are a build and TypeScript error resolution specialist. Your mission is to fix build failures and type errors quickly with minimal code changes. 证据：`packages/resources/templates/agents/build-error-resolver.md`\n- **Code Reviewer Agent**（documentation）：You are an expert code review specialist focused on code quality, security, and maintainability. 证据：`packages/resources/templates/agents/code-reviewer.md`\n- **Documentation Updater Agent**（documentation）：You are a documentation specialist focused on keeping documentation accurate, comprehensive, and useful. 证据：`packages/resources/templates/agents/doc-updater.md`\n- **E2E Test Runner Agent**（documentation）：You are an end-to-end testing specialist using Playwright. Your mission is to ensure critical user flows work correctly. 证据：`packages/resources/templates/agents/e2e-runner.md`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/fumadocs/README.md`, `docs/skillkit/README.md`, `README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/fumadocs/README.md`, `docs/skillkit/README.md`, `README.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, SOUL.md\n- **安装指南**：importance `high`\n - source_paths: README.md, package.json, packages/core/package.json, packages/tui/package.json, packages/api/package.json\n- **快速入门**：importance `high`\n - source_paths: README.md, packages/cli/src/commands/init.ts, packages/cli/src/commands/add.ts, packages/cli/src/commands/recommend.ts, packages/cli/src/commands/sync.ts\n- **包结构与依赖关系**：importance `high`\n - source_paths: pnpm-workspace.yaml, turbo.json, packages/core/src/index.ts, packages/cli/src/index.ts, packages/agents/src/index.ts\n- **核心模块解析**：importance `high`\n - source_paths: packages/core/src/index.ts, packages/core/src/agents/index.ts, packages/core/src/memory/index.ts, packages/core/src/learning/index.ts, packages/core/src/eval/index.ts\n- **技能管理**：importance `high`\n - source_paths: packages/core/src/registry/index.ts, packages/core/src/marketplace/index.ts, packages/core/src/manifest/index.ts, packages/cli/src/commands/install.ts, packages/cli/src/commands/update.ts\n- **代理支持**：importance `high`\n - source_paths: packages/agents/src/index.ts, packages/agents/src/factory.ts, packages/agents/src/base.ts, packages/core/src/agents/discovery.ts, packages/core/src/agents/types.ts\n- **格式翻译**：importance `medium`\n - source_paths: packages/core/src/translator/index.ts, packages/core/src/translator/registry.ts, packages/core/src/translator/formats/index.ts, packages/core/src/translator/formats/skill-md.ts, packages/core/src/translator/formats/cursor.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `a9e5c83a4c89052c78bd36c19fa6b5d128209669`\n- inspected_files: `pnpm-lock.yaml`, `package.json`, `README.md`, `docs/skillkit/package-lock.json`, `docs/skillkit/vercel.json`, `docs/skillkit/vite.config.ts`, `docs/skillkit/metadata.json`, `docs/skillkit/postcss.config.js`, `docs/skillkit/types.ts`, `docs/skillkit/package.json`, `docs/skillkit/README.md`, `docs/skillkit/tsconfig.json`, `docs/skillkit/tailwind.config.js`, `docs/fumadocs/next-env.d.ts`, `docs/fumadocs/vercel.json`, `docs/fumadocs/pnpm-lock.yaml`, `docs/fumadocs/source.config.ts`, `docs/fumadocs/package.json`, `docs/fumadocs/README.md`, `docs/fumadocs/tsconfig.json`\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: 来源证据：Trust downgrade for skillkit@1.24.0: v1.0.3 had provenance attestation but this version has no trust evidence\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Trust downgrade for skillkit@1.24.0: v1.0.3 had provenance attestation but this version has no trust evidence\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_54f25870d6d64729a96eb14e8e1ee72f | https://github.com/rohitg00/skillkit/issues/121 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：[Publish] CreatorCrawl — Social Media Data Skill\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Publish] CreatorCrawl — Social Media Data Skill\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_d2c6e8b4d87e4786af49c7bc9ee2665d | https://github.com/rohitg00/skillkit/issues/123 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：Add source: jorgeferrando/sdd-skills — Spec-Driven Development workflow\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add source: jorgeferrando/sdd-skills — Spec-Driven Development workflow\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_d1cb6475bbfe4122ab15817ca66e58b6 | https://github.com/rohitg00/skillkit/issues/112 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：[Publish] Rhf Autosave\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Publish] Rhf Autosave\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_7f4a4b823d1a40918a48fb8aae0d74ac | https://github.com/rohitg00/skillkit/issues/111 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：v1.20.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.20.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_73d12f84f1644a3dbc3981274dfefa42 | https://github.com/rohitg00/skillkit/releases/tag/v1.20.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：v1.22.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.22.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_a5339307b2d04e409858700fa8186f6c | https://github.com/rohitg00/skillkit/releases/tag/v1.22.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：v1.22.1\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.22.1\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_2a197dc603b242bdaa32dd2c70d535c1 | https://github.com/rohitg00/skillkit/releases/tag/v1.22.1 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：v1.23.0 — Slim install, safer picker, brand tags\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.23.0 — Slim install, safer picker, brand tags\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_9388696ec7584a6b8f5998d74f1c428e | https://github.com/rohitg00/skillkit/releases/tag/v1.23.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 可能修改宿主 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:1138376193 | https://github.com/rohitg00/skillkit | host_targets=claude, claude_code, cursor\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 能力判断依赖假设\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:1138376193 | https://github.com/rohitg00/skillkit | README/documentation is current enough for a first validation pass.\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项目：rohitg00/skillkit\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 是否匹配：claude, claude_code, cursor\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：Trust downgrade for skillkit@1.24.0: v1.0.3 had provenance attestation but this version has no trust evidence（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[Publish] CreatorCrawl — Social Media Data Skill（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Add source: jorgeferrando/sdd-skills — Spec-Driven Development workflow（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[Publish] Rhf Autosave（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：v1.20.0（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/rohitg00/skillkit 项目说明书\n\n生成时间：2026-05-16 18:44:53 UTC\n\n## 目录\n\n- [项目介绍](#project-overview)\n- [安装指南](#installation-guide)\n- [快速入门](#quick-start-guide)\n- [包结构与依赖关系](#package-structure)\n- [核心模块解析](#core-modules)\n- [技能管理](#skill-management)\n- [代理支持](#agent-support)\n- [格式翻译](#translation-format)\n- [AI 集成](#ai-integration)\n- [推荐引擎](#recommendation-engine)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[安装指南](#installation-guide), [快速入门](#quick-start-guide)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/rohitg00/skillkit/blob/main/README.md)\n- [packages/agents/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/agents/README.md)\n- [packages/cli/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/cli/README.md)\n- [packages/core/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/core/README.md)\n- [packages/core/src/ai/providers/mock.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/ai/providers/mock.ts)\n \n\n# 项目介绍\n\n## 概述\n\nSkillKit 是一个开源的 AI Agent 技能管理系统，旨在解决 AI 代码助手（Agent）在技能定义格式上互不兼容的问题。该项目允许开发者编写一次技能配置，即可将其转换并分发到多个 AI 平台使用，包括 Cursor、Copilot、Windsurf、Claude 等主流工具。\n\n资料来源：[README.md]()\n\n## 核心价值定位\n\n当前 AI 代码助手生态中存在一个显著问题：每个平台都定义了各自独特的技能（Skill）格式规范。这种碎片化导致开发者需要为同一个技能编写多份配置，造成了重复劳动和维护负担。SkillKit 通过提供统一的技能格式和自动化转换机制，显著简化了这一工作流程。\n\n资料来源：[README.md]()\n\n## 支持的 AI Agent 平台\n\nSkillKit 目前支持以下 AI Agent 平台的技能分发：\n\n| 平台名称 | 状态 |\n|---------|------|\n| augment-code | ✅ 支持 |\n| bolt | ✅ 支持 |\n| lovable | ✅ 支持 |\n| replit-agent | ✅ 支持 |\n| sourcegraph-cody | ✅ 支持 |\n| tabby | ✅ 支持 |\n| tabnine | ✅ 支持 |\n| universal | ✅ 支持 |\n\n资料来源：[packages/agents/README.md]()\n\n## 技能格式支持\n\n### SKILL.md 格式\n\n这是大多数 Agent 使用的标准格式，采用 YAML frontmatter 结合 Markdown 内容：\n\n```markdown\n---\nname: my-skill\ndescription: What this skill does\n---\n# My Skill\nInstructions...\n```\n\n资料来源：[packages/agents/README.md]()\n\n### MDC 格式（Cursor）\n\nCursor 平台专用的格式，支持 glob 模式匹配和 alwaysApply 配置：\n\n```markdown\n---\ndescription: What this skill does\nglobs: [\"**/*.tsx\"]\nalwaysApply: false\n---\nInstructions...\n```\n\n资料来源：[packages/agents/README.md]()\n\n### Markdown 格式\n\nWindsurf 和 Copilot 使用的纯 Markdown 格式：\n\n```markdown\n# Skill Name\nInstructions for the agent...\n```\n\n资料来源：[packages/agents/README.md]()\n\n## 技术架构\n\n### 模块化设计\n\nSkillKit 采用 Monorepo 结构组织代码，主要包含以下核心模块：\n\n```mermaid\ngraph TD\n A[SkillKit] --> B[CLI 模块]\n A --> C[Core 核心库]\n A --> D[TUI 终端界面]\n A --> E[Extension 扩展]\n A --> F[MCP Server]\n B --> C\n D --> C\n F --> C\n```\n\n资料来源：[packages/core/README.md]()\n\n### Core 核心库\n\n核心库提供以下关键功能：\n\n- **格式转换引擎**：支持 SKILL.md、MDC、Markdown 之间的相互转换\n- **项目分析器**：检测项目技术栈（语言、框架、库、数据库等）\n- **技能推荐系统**：基于检测到的技术栈提供相关技能建议\n- **格式渲染器**：支持 Markdown、HTML、XML 等多种输出格式\n\n资料来源：[packages/core/README.md]()\n资料来源：[packages/core/src/primer/generator.ts]()\n\n### CLI 命令行工具\n\n通过命令行界面提供完整的技能管理能力：\n\n```bash\n# 添加技能\nskillkit add claude:user/my-skill # Claude\nskillkit add github:owner/repo # GitHub\nskillkit add gitlab:team/skills # GitLab\nskillkit add ./my-local-skills # 本地路径\nskillkit add https://gist.github.com/... # Gist\n\n# 格式转换\nskillkit translate my-skill --to cursor\nskillkit translate --all --to windsurf,codex\nskillkit translate my-skill --to copilot --dry-run\n\n# 技能推荐\nskillkit recommend\n\n# 安全扫描\nskillkit scan \nskillkit scan --format json\n```\n\n资料来源：[README.md]()\n资料来源：[packages/cli/README.md]()\n\n### TUI 终端界面\n\n提供交互式的终端用户界面，包含以下功能模块：\n\n- **Browse（浏览）**：浏览和搜索技能市场\n- **Recommend（推荐）**：基于项目技术栈的智能推荐\n- **Translate（转换）**：技能格式转换\n- **Lineage（溯源）**：查看技能使用历史\n- **Context（上下文）**：分析当前项目的技术环境\n- **Methodology（方法论）**：管理和应用开发方法论\n- **Sync（同步）**：将技能同步到各 Agent 平台\n- **Plan（计划）**：执行和管理开发计划\n- **Handoff（交接）**：Agent 间的工作交接\n\n资料来源：[packages/tui/src/screens/Browse.tsx]()\n资料来源：[packages/tui/src/screens/Recommend.tsx]()\n资料来源：[packages/tui/src/screens/Translate.tsx]()\n\n### REST API 服务\n\nSkillKit 提供 REST API 服务，允许其他系统按需获取技能：\n\n```bash\nskillkit serve\n# http://localhost:3737\n\ncurl \"http://localhost:3737/search?q=react+performance\"\n```\n\n资料来源：[README.md]()\n\n### MCP 服务器支持\n\n支持通过 Model Context Protocol (MCP) 集成到开发环境：\n\n```json\n{\n \"mcpServers\": {\n \"skillkit\": { \"command\": \"npx\", \"args\": [\"@skillkit/mcp\"] }\n }\n}\n```\n\n资料来源：[README.md]()\n\n### Python 客户端\n\n提供 Python SDK 方便集成到现有 Python 项目：\n\n```python\nfrom skillkit import SkillKitClient\n\nasync with SkillKitClient() as client:\n results = await client.search(\"react performance\", limit=5)\n```\n\n资料来源：[README.md]()\n\n## 项目上下文分析\n\nSkillKit 能够自动分析项目特征，生成详细的技术栈报告：\n\n### 上下文数据类型\n\n```typescript\ninterface ProjectProfile {\n name: string;\n type: 'web-app' | 'api' | 'cli' | 'library' | 'unknown';\n stack: {\n languages: Detection[];\n frameworks: Detection[];\n libraries: Detection[];\n testing: Detection[];\n databases: Detection[];\n };\n}\n```\n\n资料来源：[packages/core/README.md]()\n\n### 检测能力\n\nSkillKit 可以检测项目的以下技术特征：\n\n- **编程语言**：检测项目使用的编程语言及其版本\n- **框架**：识别前端/后端框架（如 React、Next.js、Django 等）\n- **库依赖**：分析 package.json、requirements.txt 等依赖文件\n- **测试框架**：识别单元测试、集成测试工具\n- **数据库**：检测配置的数据库类型\n\n资料来源：[packages/tui/src/screens/Context.tsx]()\n\n## 技能推荐系统\n\n### 工作流程\n\n```mermaid\ngraph LR\n A[项目代码] --> B[上下文分析]\n B --> C[技术栈检测]\n C --> D[技能匹配]\n D --> E[推荐排序]\n E --> F[技能列表]\n```\n\n### 推荐输出示例\n\n```\n$ skillkit recommend\n\n 92% vercel-react-best-practices\n 87% tailwind-v4-patterns\n 85% nextjs-app-router\n 81% shadcn-ui-components\n```\n\n推荐系统会为每个技能计算匹配度分数，优先推荐与当前项目技术栈高度匹配的内容。\n\n资料来源：[README.md]()\n\n## 团队协作功能\n\n### Bundle 管理\n\n```bash\nskillkit team bundle-create # 创建 Bundle\nskillkit team bundle-export # 导出 Bundle\nskillkit team bundle-list # 列出所有 Bundle\n```\n\nBundle 允许团队将一组相关技能打包分发，便于统一管理和版本控制。\n\n资料来源：[packages/cli/README.md]()\n\n### 插件系统\n\n```bash\nskillkit plugin list # 列出已安装插件\nskillkit plugin install # 安装插件\nskillkit plugin uninstall # 卸载插件\nskillkit plugin enable # 启用插件\nskillkit plugin disable # 禁用插件\n```\n\n资料来源：[packages/cli/README.md]()\n\n### 钩子与自动化\n\n```bash\nskillkit hook list # 列出注册的钩子\nskillkit hook register # 注册新钩子\nskillkit hook trigger # 手动触发钩子\n```\n\n资料来源：[packages/cli/README.md]()\n\n## 扩展能力\n\n### 方法论管理\n\n```bash\nskillkit methodology list # 列出方法论\nskillkit methodology load # 加载方法论\nskillkit methodology apply # 应用到项目\n```\n\n内置多种开发方法论模板，包括任务分解、技术选型指南等最佳实践。\n\n资料来源：[packages/cli/README.md]()\n资料来源：[packages/core/src/methodology/packs/planning/task-decomposition/SKILL.md]()\n\n### 计划执行\n\n```bash\nskillkit plan parse # 解析计划文件\nskillkit plan validate # 验证计划\nskillkit plan execute # 执行计划\nskillkit plan status # 查看执行状态\n```\n\n资料来源：[packages/cli/README.md]()\n\n### 安全扫描\n\n```bash\nskillkit scan # 扫描技能漏洞\nskillkit scan --format json # JSON 格式输出\n```\n\n资料来源：[packages/cli/README.md]()\n\n## 安装与快速开始\n\n### 环境要求\n\n- Node.js 18.0 或更高版本\n- npm 或 yarn 包管理器\n\n### 安装方式\n\n```bash\n# 通过 npm 全局安装\nnpm install -g @skillkit/cli\n\n# 或使用 npx 直接运行\nnpx @skillkit/cli \n```\n\n### 基本使用流程\n\n1. **初始化项目**：在项目目录中运行 `skillkit` 启动 TUI\n2. **分析技术栈**：使用 `skillkit analyze` 检测项目环境\n3. **获取推荐**：`skillkit recommend` 查看推荐技能列表\n4. **安装技能**：选择并安装需要的技能\n5. **同步到 Agent**：使用 `skillkit sync` 同步到目标平台\n\n## 许可证\n\nSkillKit 采用 Apache-2.0 开源许可证，允许自由使用、修改和分发。\n\n资料来源：[README.md]()\n资料来源：[packages/agents/README.md]()\n\n---\n\n\n\n## 安装指南\n\n### 相关页面\n\n相关主题：[项目介绍](#project-overview), [快速入门](#quick-start-guide)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/rohitg00/skillkit/blob/main/README.md)\n- [packages/core/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/core/README.md)\n- [packages/agents/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/agents/README.md)\n- [packages/cli/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/cli/README.md)\n- [apps/skillkit/README.md](https://github.com/rohitg00/skillkit/blob/main/apps/skillkit/README.md)\n \n\n# 安装指南\n\nSkillKit 是一个跨平台 AI 技能管理系统，支持多种安装方式以满足不同用户的需求。本指南涵盖从快速启动到完整源码部署的全部安装方案。\n\n## 系统要求\n\nSkillKit 对运行环境有以下基本要求：\n\n| 要求项 | 最低版本 | 推荐版本 |\n|--------|----------|----------|\n| Node.js | 18.0.0 | 20.x LTS |\n| npm | 8.0.0 | 10.x |\n| Git | 2.30.0 | 最新版本 |\n| 操作系统 | macOS/Linux/Windows (WSL2) | - |\n\n## 安装方式\n\n### 方式一：全局安装（推荐）\n\n使用 npm 全局安装 SkillKit CLI 工具，这是最便捷的生产环境使用方式：\n\n```bash\nnpm install -g skillkit\n```\n\n安装完成后，直接在终端运行 `skillkit` 命令即可：\n\n```bash\nskillkit --help\n```\n\n资料来源：[README.md:1]()\n\n### 方式二：使用 npx 免安装运行\n\n如果仅需临时使用或进行快速演示，可以通过 npx 直接运行而无需全局安装：\n\n```bash\nnpx skillkit \n```\n\nnpx 会自动下载并执行指定版本的 SkillKit，每次运行时会检查更新。\n\n资料来源：[README.md:1]()\n\n### 方式三：Docker 部署\n\n对于需要隔离环境的场景，SkillKit 支持通过 Docker 运行：\n\n```bash\ndocker pull skillkit/skillkit:latest\ndocker run -it skillkit/skillkit \n```\n\nDocker 方式特别适合团队标准化环境配置和 CI/CD 集成场景。\n\n### 方式四：源码编译安装\n\n适用于需要自定义功能或参与项目开发的用户。\n\n#### 克隆仓库\n\n```bash\ngit clone https://github.com/rohitg00/skillkit.git\ncd skillkit\n```\n\n#### 安装依赖\n\nSkillKit 采用 monorepo 结构，主目录下使用 npm workspaces 管理多个子包：\n\n```bash\nnpm install\n```\n\n此命令会自动安装所有子包的依赖，包括核心包、CLI 包、TUI 包等。\n\n#### 编译构建\n\n```bash\nnpm run build\n```\n\n构建过程会生成各包的发布产物，包括：\n\n- `packages/core` - 核心功能库\n- `packages/cli` - 命令行工具\n- `packages/tui` - 终端用户界面\n- `packages/api` - REST API 服务\n- `packages/mesh` - 服务网格模块\n- `packages/messaging` - 消息传递模块\n\n资料来源：[package.json](https://github.com/rohitg00/skillkit/blob/main/package.json)\n\n## 项目架构概览\n\nSkillKit 的整体架构设计如下：\n\n```mermaid\ngraph TD\n A[用户终端] --> B[CLI 工具
skillkit 命令]\n A --> C[TUI 界面
交互式终端]\n A --> D[REST API
skillkit serve]\n \n B --> E[核心模块
packages/core]\n C --> E\n D --> E\n \n E --> F[技能存储]\n E --> G[翻译引擎]\n E --> H[推荐系统]\n \n F --> I[本地文件系统]\n F --> J[远程仓库]\n F --> K[团队 Bundle]\n \n L[Agent 集成] --> M[Claude
Cursor
Windsurf
Copilot]\n```\n\n## 包结构说明\n\nSkillKit 采用 monorepo 架构，主要包的功能如下：\n\n| 包名 | 功能描述 | 主要导出 |\n|------|----------|----------|\n| `@skillkit/core` | 核心功能，包含技能解析、翻译、推荐等核心算法 | `SkillKit`, `SkillTranslator` |\n| `@skillkit/cli` | 命令行工具，提供所有 `skillkit` 子命令 | CLI 可执行文件 |\n| `@skillkit/tui` | 终端用户界面，交互式操作界面 | 独立的 TUI 应用 |\n| `@skillkit/api` | REST API 服务，支持 HTTP 接口访问 | Express 服务 |\n| `@skillkit/mesh` | 服务网格模块，支持微服务架构集成 | 连接器和适配器 |\n| `@skillkit/messaging` | 消息传递系统，支持事件驱动通信 | 消息队列接口 |\n| `@skillkit/mcp` | MCP 协议集成，支持模型上下文协议 | MCP 服务器 |\n\n资料来源：[packages/core/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/core/README.md)\n\n## 验证安装\n\n安装完成后，可通过以下方式验证：\n\n### 检查 CLI 版本\n\n```bash\nskillkit --version\n```\n\n### 查看可用命令\n\n```bash\nskillkit --help\n```\n\n输出应包含以下主要功能模块：\n\n```bash\nskillkit add # 添加技能\nskillkit translate # 翻译技能格式\nskillkit recommend # 智能推荐\nskillkit serve # 启动 API 服务\nskillkit team # 团队协作\nskillkit plugin # 插件管理\nskillkit methodology # 方法论加载\nskillkit plan # 计划执行\nskillkit hook # 自动化钩子\nskillkit scan # 安全扫描\n```\n\n资料来源：[packages/cli/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/cli/README.md)\n\n## 快速开始\n\n安装完成后，按以下步骤创建第一个技能：\n\n### 初始化项目\n\n```bash\nskillkit init\n```\n\n### 添加技能\n\n```bash\nskillkit add \n```\n\n支持的来源格式：\n\n```bash\nskillkit add claude:username/skill # Claude\nskillkit add cursor:owner/skill # Cursor\nskillkit add windsurf:repo/skills # Windsurf\nskillkit add github:owner/repo # GitHub\nskillkit add gitlab:team/skills # GitLab\nskillkit add ./my-local-skills # 本地路径\nskillkit add https://gist.github.com/... # Gist\n```\n\n资料来源：[README.md:1]()\n\n### 启动交互界面\n\n```bash\nskillkit tui\n```\n\n### 启动 API 服务\n\n```bash\nskillkit serve\n# 服务地址: http://localhost:3737\n```\n\n## 团队安装配置\n\n对于团队环境，建议通过配置文件统一管理：\n\n```bash\nskillkit team init --name \"Engineering Team\"\nskillkit team sync\n```\n\n配置文件 `.skillkit.json` 可放在项目根目录，确保团队成员使用一致的技能配置。\n\n## 环境变量配置\n\nSkillKit 支持以下环境变量自定义行为：\n\n| 变量名 | 默认值 | 说明 |\n|--------|--------|------|\n| `SKILLKIT_DIR` | `~/.skillkit` | 技能存储目录 |\n| `SKILLKIT_API_PORT` | `3737` | API 服务端口 |\n| `SKILLKIT_LOG_LEVEL` | `info` | 日志级别 |\n| `SKILLKIT_CACHE_TTL` | `3600` | 缓存生存时间（秒） |\n\n## 常见问题\n\n### 全局安装后命令不可用\n\n确保 npm 全局 bin 目录在系统 PATH 中：\n\n```bash\nnpm config get prefix\n```\n\n如果路径不在 PATH 中，添加到 shell 配置文件（`.bashrc`、`.zshrc` 等）：\n\n```bash\nexport PATH=\"$(npm config get prefix)/bin:$PATH\"\n```\n\n### 权限错误（EACCES）\n\nLinux/macOS 上如遇权限问题，避免使用 sudo：\n\n```bash\nmkdir ~/.npm-global\nnpm config set prefix '~/.npm-global'\nexport PATH=~/.npm-global/bin:$PATH\n```\n\n### 源码安装构建失败\n\n确保 Node.js 版本符合要求，并清理缓存后重试：\n\n```bash\nrm -rf node_modules package-lock.json\nnpm cache clean --force\nnpm install\nnpm run build\n```\n\n## 下一步\n\n安装完成后，建议继续阅读以下文档：\n\n- [用户指南](https://github.com/rohitg00/skillkit#readme) - 完整功能说明\n- [技能格式规范](https://github.com/rohitg00/skillkit/blob/main/packages/agents/README.md) - SKILL.md、MDC 格式说明\n- [API 参考](https://github.com/rohitg00/skillkit/blob/main/apps/skillkit/README.md) - REST API 端点说明\n- [插件开发](https://github.com/rohitg00/skillkit/blob/main/packages/cli/README.md) - 扩展 SkillKit 功能\n\n---\n\n\n\n## 快速入门\n\n### 相关页面\n\n相关主题：[技能管理](#skill-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/rohitg00/skillkit/blob/main/README.md)\n- [packages/agents/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/agents/README.md)\n- [packages/core/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/core/README.md)\n- [packages/cli/src/commands/init.ts](https://github.com/rohitg00/skillkit/blob/main/packages/cli/src/commands/init.ts)\n- [packages/cli/src/commands/add.ts](https://github.com/rohitg00/skillkit/blob/main/packages/cli/src/commands/add.ts)\n- [packages/cli/src/commands/recommend.ts](https://github.com/rohitg00/skillkit/blob/main/packages/cli/src/commands/recommend.ts)\n- [packages/cli/src/commands/sync.ts](https://github.com/rohitg00/skillkit/blob/main/packages/cli/src/commands/sync.ts)\n \n\n# 快速入门\n\n本文档将帮助你快速上手 SkillKit，了解如何安装、配置以及使用核心功能来管理 AI Agent 技能。\n\n## 什么是 SkillKit\n\nSkillKit 是一个用于统一管理和分发 AI Agent 技能（Skills）的命令行工具。它允许开发者：\n\n- 为多个 AI Agent 平台（如 Cursor、Windsurf、Claude Code 等）编写一次技能\n- 自动将技能转换为不同 Agent 支持的格式\n- 订阅社区技能市场并同步到本地\n- 根据项目技术栈获取智能推荐\n\n\n\n## 系统要求\n\n| 要求 | 最低版本 |\n|------|----------|\n| Node.js | 18.0.0 |\n| npm/pnpm | 最新版本 |\n| 操作系统 | macOS、Linux、Windows |\n\n## 安装\n\n通过 npm 全局安装 SkillKit CLI：\n\n```bash\nnpm install -g @skillkit/cli\n```\n\n或使用 pnpm：\n\n```bash\npnpm add -g @skillkit/cli\n```\n\n安装完成后，验证安装：\n\n```bash\nskillkit --version\n```\n\n## 初始化项目\n\n在项目根目录运行初始化命令，创建 `.skillkit` 配置文件：\n\n```bash\nskillkit init\n```\n\n初始化过程会：\n1. 创建 `.skillkit` 目录\n2. 生成 `skillkit.yaml` 配置文件\n3. 检测项目技术栈（语言、框架、库）\n4. 配置支持的 AI Agent\n\n资料来源：[README.md](https://github.com/rohitg00/skillkit/blob/main/README.md)\n\n### 初始化配置\n\n初始化后生成的 `skillkit.yaml` 结构如下：\n\n```yaml\nagents:\n - cursor\n - windsurf\n - claude\n - copilot\nstack:\n languages: []\n frameworks: []\n libraries: []\nskills: []\n```\n\n## 核心命令\n\n### 添加技能\n\n使用 `add` 命令添加本地技能或远程技能源：\n\n```bash\n# 添加 GitHub 仓库\nskillkit add github:username/skills\n\n# 添加 GitLab 仓库\nskillkit add gitlab:team/skills\n\n# 添加本地路径\nskillkit add ./my-local-skills\n\n# 添加 Gist\nskillkit add https://gist.github.com/...\n```\n\n资料来源：[README.md](https://github.com/rohitg00/skillkit/blob/main/README.md)\n\n### 智能推荐\n\n根据项目技术栈获取推荐技能：\n\n```bash\nskillkit recommend\n```\n\n输出示例：\n\n```\n92% vercel-react-best-practices\n87% tailwind-v4-patterns\n85% nextjs-app-router\n81% shadcn-ui-components\n```\n\n推荐系统会分析项目中的：\n- 编程语言\n- 前端框架\n- UI 库\n- 测试框架\n- 数据库\n\n资料来源：[packages/cli/src/commands/recommend.ts](https://github.com/rohitg00/skillkit/blob/main/packages/cli/src/commands/recommend.ts)\n\n### 同步技能\n\n将技能同步到指定的 AI Agent：\n\n```bash\n# 同步所有技能\nskillkit sync\n\n# 同步到指定 Agent\nskillkit sync --to cursor\n\n# 同步指定技能\nskillkit sync my-skill --to windsurf\n```\n\n资料来源：[packages/cli/src/commands/sync.ts](https://github.com/rohitg00/skillkit/blob/main/packages/cli/src/commands/sync.ts)\n\n### 格式转换\n\nSkillKit 支持将技能转换为不同 Agent 专用的格式：\n\n```bash\n# 转换单个技能\nskillkit translate my-skill --to cursor\n\n# 转换所有技能\nskillkit translate --all --to windsurf,codex\n\n# 预览转换结果\nskillkit translate my-skill --to copilot --dry-run\n```\n\n## 技能格式\n\n### SKILL.md 格式\n\n大多数 Agent 使用的标准格式，采用 YAML frontmatter + Markdown 内容：\n\n```markdown\n---\nname: my-skill\ndescription: 技能描述\n---\n# My Skill\nInstructions...\n```\n\n### MDC 格式 (Cursor)\n\nCursor 专用的格式，支持 glob 模式和 alwaysApply 字段：\n\n```markdown\n---\ndescription: 技能描述\nglobs: [\"**/*.tsx\"]\nalwaysApply: false\n---\nInstructions...\n```\n\n### Markdown 格式\n\n用于 Windsurf 和 Copilot 的纯 Markdown 格式：\n\n```markdown\n# Skill Name\nInstructions for the agent...\n```\n\n资料来源：[packages/agents/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/agents/README.md)\n\n## 支持的 AI Agent\n\nSkillKit 支持以下 AI Agent 平台：\n\n| Agent | 格式支持 | 状态 |\n|-------|----------|------|\n| Claude | SKILL.md | 完整支持 |\n| Cursor | MDC | 完整支持 |\n| Windsurf | Markdown | 完整支持 |\n| Copilot | Markdown | 完整支持 |\n| Augment Code | SKILL.md | 完整支持 |\n| Bolt | SKILL.md | 完整支持 |\n| Lovable | SKILL.md | 完整支持 |\n| Replit Agent | SKILL.md | 完整支持 |\n| Sourcegraph Cody | SKILL.md | 完整支持 |\n| Tabby | SKILL.md | 完整支持 |\n| Tabnine | SKILL.md | 完整支持 |\n| Universal | SKILL.md | 完整支持 |\n\n资料来源：[packages/agents/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/agents/README.md)\n\n## 工作流程图\n\n```mermaid\ngraph TD\n A[开始] --> B[安装 SkillKit]\n B --> C[初始化项目 skillkit init]\n C --> D[添加技能 skillkit add]\n D --> E[推荐技能 skillkit recommend]\n E --> F[同步到 Agent skillkit sync]\n F --> G[在 Agent 中使用技能]\n```\n\n## 进阶功能\n\n### 运行本地服务\n\n启动 SkillKit REST API 服务，让 Agent 按需获取技能：\n\n```bash\nskillkit serve\n# http://localhost:3737\n\ncurl \"http://localhost:3737/search?q=react+performance\"\n```\n\n### MCP 集成\n\n将 SkillKit 集成到支持 MCP 的编辑器中：\n\n```json\n{\n \"mcpServers\": {\n \"skillkit\": { \n \"command\": \"npx\", \n \"args\": [\"@skillkit/mcp\"] \n }\n }\n}\n```\n\n### Python 客户端\n\n使用 Python SDK 与 SkillKit 服务交互：\n\n```python\nfrom skillkit import SkillKitClient\n\nasync with SkillKitClient() as client:\n results = await client.search(\"react performance\", limit=5)\n```\n\n资料来源：[README.md](https://github.com/rohitg00/skillkit/blob/main/README.md)\n\n## 常见问题\n\n### 初始化失败怎么办？\n\n确保：\n- 当前目录是 Git 仓库根目录\n- 有写入 `.skillkit` 目录的权限\n- Node.js 版本 >= 18.0.0\n\n### 如何查看已配置的 Agent？\n\n```bash\nskillkit config --list\n```\n\n### 技能同步失败？\n\n检查：\n1. Agent 是否已安装\n2. Agent 的技能目录路径是否正确\n3. 技能格式是否与目标 Agent 兼容\n\n## 下一步\n\n- 查看[完整文档](https://github.com/rohitg00/skillkit)\n- 浏览 [packages/core](https://github.com/rohitg00/skillkit/blob/main/packages/core/README.md) 了解核心 API\n- 探索[示例技能库](https://github.com/rohitg00/skillkit/tree/main/packages/core/src/methodology/packs)\n\n---\n\n\n\n## 包结构与依赖关系\n\n### 相关页面\n\n相关主题：[核心模块解析](#core-modules), [项目介绍](#project-overview)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [pnpm-workspace.yaml](https://github.com/rohitg00/skillkit/blob/main/pnpm-workspace.yaml)\n- [turbo.json](https://github.com/rohitg00/skillkit/blob/main/turbo.json)\n- [packages/core/src/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/index.ts)\n- [packages/cli/src/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/cli/src/index.ts)\n- [packages/agents/src/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/agents/src/index.ts)\n- [packages/tui/src/screens/Methodology.tsx](https://github.com/rohitg00/skillkit/blob/main/packages/tui/src/screens/Methodology.tsx)\n- [packages/core/src/primer/generator.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/primer/generator.ts)\n \n\n# 包结构与依赖关系\n\n## 项目概述\n\nSkillKit 是一个基于 pnpm monorepo 架构的多包项目，采用 pnpm workspaces 和 Turborepo 进行包管理和构建优化。项目设计围绕 AI 代理技能系统展开，提供了核心库、命令行工具、TUI 界面和浏览器扩展等多元化终端。\n\n资料来源：[pnpm-workspace.yaml](https://github.com/rohitg00/skillkit/blob/main/pnpm-workspace.yaml)\n\n## Monorepo 架构\n\nSkillKit 采用标准的 pnpm monorepo 结构，所有子包位于 `packages` 目录下，应用位于 `apps` 目录下。这种结构允许共享依赖、提升构建效率，并确保各模块间的版本一致性。\n\n资料来源：[pnpm-workspace.yaml](https://github.com/rohitg00/skillkit/blob/main/pnpm-workspace.yaml)\n\n## 包目录结构\n\n```\nskillkit/\n├── packages/ # 核心包集合\n│ ├── core/ # 核心业务逻辑库\n│ ├── cli/ # 命令行工具\n│ ├── agents/ # AI 代理集成包\n│ ├── tui/ # 终端用户界面\n│ └── extension/ # 浏览器扩展\n├── apps/ # 独立应用\n│ └── skillkit/ # 主应用程序\n├── pnpm-workspace.yaml # 工作空间配置\n└── turbo.json # 构建流水线配置\n```\n\n## 核心包详解\n\n### Core 包 (packages/core)\n\nCore 包是整个项目的基础，包含了技能系统的核心业务逻辑、翻译引擎、上下文分析等关键功能。\n\n```mermaid\ngraph TD\n A[Core 包] --> B[ai/]\n A --> C[skill-translator.ts]\n A --> D[methodology/]\n A --> E[primer/]\n \n B --> B1[providers/]\n B --> B2[wizard/]\n B --> B3[recommend/]\n \n C --> C1[SKILL.md 解析]\n C --> C2[MDC 转换]\n C --> C3[Agent Format]\n \n D --> D1[Packs 系统]\n D --> D2[Task 模板]\n \n E --> E1[ProjectAnalysis]\n E --> E2[ContextGenerator]\n```\n\n**主要子模块功能说明：**\n\n| 模块路径 | 功能描述 | 关键文件 |\n|---------|---------|----------|\n| `ai/providers/` | AI 能力提供者抽象 | mock.ts 等 |\n| `ai/wizard/` | 技能创建向导系统 | types.ts, 状态管理 |\n| `methodology/` | 开发方法论与任务分解 | packs/, task-decomposition/ |\n| `primer/` | 项目上下文生成器 | generator.ts |\n| `skill-translator/` | 技能格式翻译引擎 | 多格式转换支持 |\n\n资料来源：[packages/core/src/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/index.ts)\n\n### CLI 包 (packages/cli)\n\nCLI 包封装了 SkillKit 的命令行交互能力，提供技能安装、翻译、同步、团队协作等功能入口。\n\n```mermaid\ngraph LR\n subgraph CLI 功能模块\n A[skillkit install] --> B[core]\n C[skillkit translate] --> B\n D[skillkit sync] --> B\n E[skillkit team] --> B\n end\n \n B --> F[core 包 API]\n```\n\n**核心命令分类：**\n\n| 命令类别 | 子命令 | 功能说明 |\n|---------|-------|----------|\n| 基础操作 | `install`, `sync`, `list` | 技能生命周期管理 |\n| 翻译功能 | `translate --to ` | 技能格式转换 |\n| 团队协作 | `bundle-*`, `team share` | 团队技能包管理 |\n| 插件系统 | `plugin list/install` | 插件扩展管理 |\n| 方法论 | `methodology list/apply` | 开发方法论应用 |\n\n资料来源：[packages/cli/src/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/cli/src/index.ts)\n\n### Agents 包 (packages/agents)\n\nAgents 包定义了与各种 AI 代理（Claude Code、Cursor、Copilot 等）的集成规范和格式转换逻辑。\n\n```mermaid\ngraph TD\n A[Agents 包] --> B[SKILL.md 格式]\n A --> C[MDC 格式]\n A --> D[Markdown 格式]\n A --> E[通用 YAML 格式]\n \n B --> B1[Claude Code]\n B --> B2[Codex]\n B --> B3[Gemini CLI]\n \n D --> D1[Windsurf]\n D --> D2[Copilot]\n \n E --> E1[通用适配]\n```\n\n**支持的代理格式映射：**\n\n| 代理名称 | 格式类型 | 配置特征 |\n|---------|---------|----------|\n| Claude Code | SKILL.md | YAML frontmatter + Markdown |\n| Cursor | MDC | globs + alwaysApply |\n| Windsurf | Markdown | 纯 Markdown 指令 |\n| GitHub Copilot | Markdown | 纯 Markdown 指令 |\n| Replit Agent | SKILL.md | YAML frontmatter + Markdown |\n\n资料来源：[packages/agents/src/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/agents/src/index.ts)\n\n### TUI 包 (packages/tui)\n\nTUI 包提供了 SkillKit 的终端用户界面，使用 Ink（React for CLI）构建，支持交互式浏览、安装和管理技能。\n\n```mermaid\ngraph TD\n A[TUI 界面] --> B[Browse 屏幕]\n A --> C[Marketplace 屏幕]\n A --> D[Methodology 屏幕]\n A --> E[Translate 屏幕]\n A --> F[Recommend 屏幕]\n A --> G[Lineage 屏幕]\n A --> H[Handoff 屏幕]\n A --> I[Context 屏幕]\n \n B --> B1[技能市场浏览]\n C --> C1[分类树视图]\n D --> D1[方法论包安装]\n E --> E1[格式翻译]\n F --> F1[智能推荐]\n```\n\n**屏幕组件映射表：**\n\n| 屏幕组件 | 文件位置 | 功能描述 |\n|---------|---------|----------|\n| Browse | screens/Browse.tsx | 浏览远程技能仓库 |\n| Marketplace | screens/Marketplace.tsx | 技能分类与树形展示 |\n| Methodology | screens/Methodology.tsx | 方法论包管理与安装 |\n| Translate | screens/Translate.tsx | 技能格式翻译预览 |\n| Recommend | screens/Recommend.tsx | 基于项目的技能推荐 |\n| Lineage | screens/Lineage.tsx | 技能使用历史追踪 |\n| Handoff | screens/Handoff.tsx | 任务交接与状态展示 |\n| Context | screens/Context.tsx | 项目上下文信息展示 |\n\n资料来源：[packages/tui/src/screens/Methodology.tsx](https://github.com/rohitg00/skillkit/blob/main/packages/tui/src/screens/Methodology.tsx)\n\n### Extension 包 (packages/extension)\n\nExtension 包提供了浏览器扩展能力，支持用户在浏览器中直接浏览和管理技能。\n\n## 依赖关系图\n\n```mermaid\ngraph TD\n CLI[packages/cli] --> CORE[packages/core]\n TUI[packages/tui] --> CORE\n AGENTS[packages/agents] --> CORE\n EXTENSION[packages/extension] --> CORE\n \n APP[apps/skillkit] --> CLI\n APP --> TUI\n \n CLI --> AGENTS\n TUI --> AGENTS\n \n style CORE fill:#e1f5fe\n style CLI fill:#fff3e0\n style TUI fill:#e8f5e9\n```\n\n## 包间依赖规范\n\n### 核心依赖原则\n\n1. **单向依赖**：上层包可依赖下层包，禁止反向依赖\n2. **共享核心**：所有功能性包都应依赖 `packages/core`\n3. **接口稳定**：`packages/core` 导出稳定公开 API\n\n### 依赖层级说明\n\n| 层级 | 包名 | 说明 |\n|-----|------|-----|\n| 基础设施层 | packages/core | 核心业务逻辑与类型定义 |\n| 功能封装层 | packages/agents, packages/cli | 特定功能的封装 |\n| 表现层 | packages/tui, packages/extension | 用户交互界面 |\n| 应用层 | apps/skillkit | 组合各模块的完整应用 |\n\n## Turborepo 构建配置\n\nTurborepo 负责管理构建任务的依赖关系和增量构建优化。\n\n```json\n// turbo.json 核心配置结构\n{\n \"pipeline\": {\n \"build\": {\n \"dependsOn\": [\"^build\"],\n \"outputs\": [\"dist/**\", \".next/**\"]\n },\n \"test\": {\n \"dependsOn\": [\"build\"],\n \"outputs\": [\"coverage/**\"]\n },\n \"lint\": {\n \"outputs\": []\n }\n }\n}\n```\n\n**构建任务说明：**\n\n| 任务名称 | 依赖任务 | 输出目录 | 说明 |\n|---------|---------|---------|------|\n| build | ^build | dist/, .next/ | 增量构建 |\n| test | build | coverage/ | 测试与覆盖率 |\n| lint | - | - | 代码检查 |\n| dev | - | - | 开发模式 |\n\n资料来源：[turbo.json](https://github.com/rohitg00/skillkit/blob/main/turbo.json)\n\n## pnpm Workspace 配置\n\n```yaml\n# pnpm-workspace.yaml\npackages:\n - 'packages/*'\n - 'apps/*'\n```\n\n该配置声明了所有子包和应用的位置，pnpm 将自动管理这些包之间的符号链接和依赖解析。\n\n## 导出 API 结构\n\n### Core 包导出 (packages/core/src/index.ts)\n\nCore 包通过 index.ts 统一导出以下模块：\n\n| 导出类别 | 包含内容 | 使用场景 |\n|---------|---------|----------|\n| 技能管理 | Skill, SkillSet | 技能定义与集合操作 |\n| 翻译引擎 | translateSkill() | 格式转换 |\n| 项目分析 | ProjectAnalyzer | 上下文分析 |\n| 方法论 | Methodology, TaskTemplate | 开发流程模板 |\n| 推荐系统 | recommendSkills() | 智能推荐 |\n| 向导系统 | WizardState, WizardStep | 引导式创建 |\n\n### Agents 包导出 (packages/agents/src/index.ts)\n\nAgents 包定义了代理集成的核心接口：\n\n```typescript\n// 代理格式配置\ninterface AgentSkillFormat {\n name: string;\n extension: string;\n hasFrontmatter: boolean;\n invokeCommand: string;\n supportsGlobs: boolean;\n}\n\n// 支持的代理列表\nconst SUPPORTED_AGENTS = ['claude-code', 'cursor', 'copilot', ...] as const;\n```\n\n### CLI 包导出 (packages/cli/src/index.ts)\n\nCLI 包通过命令注册系统对外暴露命令行接口：\n\n```typescript\n// 核心命令注册\nexport async function cli(args: string[]): Promise;\nexport const installCommand: Command;\nexport const translateCommand: Command;\nexport const syncCommand: Command;\nexport const teamCommand: Command;\nexport const pluginCommand: Command;\nexport const methodologyCommand: Command;\n```\n\n## 版本与发布\n\n各包独立版本管理，通过 pnpm workspace 确保版本同步：\n\n```bash\n# 查看所有包版本\npnpm list --depth=-1\n\n# 批量更新依赖\npnpm up -r\n\n# 发布指定包\npnpm --filter @skillkit/core publish\n```\n\n## 总结\n\nSkillKit 的包结构设计遵循了现代 monorepo 最佳实践，通过清晰的层级划分和单向依赖关系，实现了高度的可维护性和可扩展性。核心业务逻辑集中于 `packages/core`，各类终端（CLI、TUI、Extension）依赖核心库构建独立功能，应用层则组合各模块提供完整解决方案。\n\n---\n\n\n\n## 核心模块解析\n\n### 相关页面\n\n相关主题：[包结构与依赖关系](#package-structure), [技能管理](#skill-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/src/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/index.ts)\n- [packages/core/src/agents/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/agents/index.ts)\n- [packages/core/src/memory/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/memory/index.ts)\n- [packages/core/src/learning/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/learning/index.ts)\n- [packages/core/src/eval/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/eval/index.ts)\n- [packages/core/src/recommend/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/recommend/index.ts)\n \n\n# 核心模块解析\n\n## 概述\n\nSkillKit 是一个统一管理 AI Agent 技能的 CLI 工具和运行时框架，旨在解决不同 AI Agent（如 Cursor、Windsurf、Copilot、Claude Code 等）之间技能格式不兼容的问题。通过核心模块的协同工作，SkillKit 实现了技能的创建、转换、推荐、执行和学习闭环。资料来源：[packages/core/README.md:1-20]()\n\n## 核心架构\n\nSkillKit 的核心模块采用分层架构设计，各模块职责明确，通过标准接口进行通信：\n\n```mermaid\ngraph TD\n A[CLI / TUI 入口] --> B[Core API 层]\n B --> C1[Agents 模块]\n B --> C2[Memory 模块]\n B --> C3[Learning 模块]\n B --> C4[Eval 模块]\n B --> C5[Recommend 模块]\n C1 --> D[技能存储]\n C2 --> D\n C3 --> D\n C4 --> D\n C5 --> D\n```\n\n资料来源：[packages/core/src/index.ts:1-30]()\n\n## 模块详解\n\n### 1. Agents 模块\n\nAgents 模块负责管理不同 AI Agent 的技能格式转换和适配工作。\n\n#### 支持的 Agent 类型\n\n| Agent 名称 | 标识符 | 格式类型 |\n|-----------|--------|---------|\n| GitHub Copilot | `copilot` | Markdown |\n| Cursor | `cursor` | MDC |\n| Windsurf | `windsurf` | Markdown |\n| Claude Code | `claude` | SKILL.md |\n| Augment Code | `augment-code` | SKILL.md |\n| Bolt | `bolt` | SKILL.md |\n| Lovable | `lovable` | SKILL.md |\n| Replit Agent | `replit-agent` | SKILL.md |\n| Sourcegraph Cody | `sourcegraph-cody` | SKILL.md |\n| Tabby | `tabby` | SKILL.md |\n| Tabnine | `tabnine` | SKILL.md |\n| Universal | `universal` | 通用格式 |\n\n资料来源：[packages/agents/README.md:1-15]()\n\n#### 技能格式对比\n\n| 格式 | 使用 Agent | 特点 |\n|------|-----------|------|\n| SKILL.md | Claude, Bolt, Lovable 等 | YAML frontmatter + Markdown 内容 |\n| MDC | Cursor | 支持 globs 和 alwaysApply 字段 |\n| Markdown | Windsurf, Copilot | 纯文本指令格式 |\n\n资料来源：[packages/core/src/agents/index.ts:1-50]()\n\n### 2. Memory 模块\n\nMemory 模块负责技能的持久化存储和检索管理。\n\n#### 核心功能\n\n- 技能元数据存储\n- 版本历史追踪\n- 技能依赖关系图谱\n- 全文检索索引\n\n资料来源：[packages/core/src/memory/index.ts:1-40]()\n\n### 3. Learning 模块\n\nLearning 模块实现技能的增量学习和优化机制。\n\n```mermaid\ngraph LR\n A[技能执行] --> B[结果收集]\n B --> C[模式分析]\n C --> D[规则提取]\n D --> E[技能优化]\n E --> A\n```\n\n#### 学习策略\n\n| 策略类型 | 触发条件 | 优化方式 |\n|---------|---------|---------|\n| 成功率优化 | 执行成功率 < 80% | 简化步骤 |\n| 性能优化 | 执行时间 > 阈值 | 减少冗余 |\n| 准确性优化 | 错误率上升 | 增强验证 |\n\n资料来源：[packages/core/src/learning/index.ts:1-60]()\n\n### 4. Eval 模块\n\nEval 模块提供技能质量评估和兼容性验证功能。\n\n#### 评估指标\n\n| 指标名称 | 说明 | 阈值 |\n|---------|------|------|\n| 兼容性 | 与目标 Agent 的格式兼容程度 | ≥ 80% |\n| 完整性 | 必需字段和内容的完整程度 | ≥ 90% |\n| 可执行性 | 技能指令的可执行性 | 布尔值 |\n\n资料来源：[packages/core/src/eval/index.ts:1-50]()\n\n### 5. Recommend 模块\n\nRecommend 模块基于项目上下文提供智能技能推荐服务。\n\n#### 推荐算法\n\n```mermaid\ngraph TD\n A[项目上下文] --> B[栈检测]\n B --> C[技能匹配]\n C --> D[评分排序]\n D --> E[推荐结果]\n \n B --> B1[语言检测]\n B --> B2[框架检测]\n B --> B3[库检测]\n \n D --> D1[匹配度分数]\n D --> D2[使用频率]\n D --> D3[社区评分]\n```\n\n#### 上下文类型\n\n```typescript\ninterface ProjectProfile {\n name: string;\n type: 'web-app' | 'api' | 'cli' | 'library' | 'unknown';\n stack: {\n languages: Detection[];\n frameworks: Detection[];\n libraries: Detection[];\n testing: Detection[];\n databases: Detection[];\n };\n}\n```\n\n资料来源：[packages/core/README.md:50-80]()\n\n## 工作流程\n\n### 技能翻译流程\n\n```mermaid\nsequenceDiagram\n participant User\n participant CLI\n participant Agents\n participant Core\n \n User->>CLI: skillkit translate --to \n CLI->>Core: 加载技能\n Core->>Agents: 格式检测\n Agents->>Agents: 格式转换\n Agents->>Core: 转换结果\n Core->>CLI: 输出/写入\n CLI->>User: 完成\n```\n\n资料来源：[packages/cli/README.md:1-30]()\n\n### 技能推荐流程\n\n```mermaid\ngraph TD\n A[skillkit recommend] --> B[项目扫描]\n B --> C[栈分析]\n C --> D[技能检索]\n D --> E[评分计算]\n E --> F[结果排序]\n F --> G[输出推荐]\n \n C --> C1[语言栈]\n C --> C2[框架栈]\n C --> C3[依赖库]\n```\n\n资料来源：[apps/skillkit/README.md:1-20]()\n\n## API 接口\n\n### Python 客户端\n\n```python\nfrom skillkit import SkillKitClient\n\nasync with SkillKitClient() as client:\n # 搜索技能\n results = await client.search(\"react performance\", limit=5)\n \n # 获取推荐\n recommendations = await client.recommend()\n```\n\n资料来源：[README.md:40-55]()\n\n### REST API\n\n```bash\n# 启动服务\nskillkit serve\n\n# 搜索接口\ncurl \"http://localhost:3737/search?q=react+performance\"\n```\n\n资料来源：[README.md:35-40]()\n\n## 数据模型\n\n### 技能元数据结构\n\n| 字段 | 类型 | 必填 | 说明 |\n|-----|------|-----|------|\n| name | string | 是 | 技能名称 |\n| description | string | 是 | 技能描述 |\n| format | string | 是 | 格式类型 |\n| content | string | 是 | 技能内容 |\n| metadata | object | 否 | 附加元数据 |\n\n### 翻译结果结构\n\n```typescript\ninterface TranslationResult {\n content: string;\n format: string;\n warnings?: string[];\n}\n```\n\n资料来源：[packages/core/README.md:30-45]()\n\n## 模块交互关系\n\n```mermaid\ngraph LR\n Agents -->|格式转换| Eval\n Recommend -->|上下文| Agents\n Memory -->|存储| Agents\n Learning -->|优化| Memory\n Eval -->|评估| Recommend\n```\n\n| 源模块 | 目标模块 | 交互内容 |\n|-------|---------|---------|\n| Agents | Eval | 转换兼容性验证 |\n| Recommend | Agents | 技能格式适配 |\n| Memory | 所有模块 | 数据持久化 |\n| Learning | Memory | 增量更新 |\n| Eval | Recommend | 质量评分 |\n\n资料来源：[packages/core/src/index.ts:20-60]()\n\n## 扩展机制\n\n### MCP 协议支持\n\n```json\n{\n \"mcpServers\": {\n \"skillkit\": { \n \"command\": \"npx\", \n \"args\": [\"@skillkit/mcp\"] \n }\n }\n}\n```\n\n资料来源：[README.md:45-52]()\n\n### 插件系统\n\n| 命令 | 功能 |\n|-----|------|\n| `skillkit plugin list` | 列出已安装插件 |\n| `skillkit plugin install ` | 安装插件 |\n| `skillkit plugin uninstall ` | 卸载插件 |\n\n资料来源：[packages/cli/README.md:30-45]()\n\n## 最佳实践\n\n### 技能开发建议\n\n1. **格式选择**：优先使用 SKILL.md 格式以获得最大兼容性\n2. **元数据完整**：确保 YAML frontmatter 包含所有必需字段\n3. **版本管理**：使用语义化版本号进行版本追踪\n4. **测试验证**：使用 `skillkit scan` 进行安全扫描\n\n### 性能优化\n\n- 技能缓存：合理使用 Memory 模块的缓存机制\n- 批量操作：使用 bundle 机制进行批量技能管理\n- 增量同步：仅同步变更的技能文件\n\n资料来源：[packages/core/src/learning/index.ts:30-50]()\n\n## 总结\n\nSkillKit 的核心模块通过清晰的职责划分和标准化的接口设计，实现了跨 Agent 的技能统一管理。Agents 模块处理格式转换，Memory 模块提供持久化支持，Learning 模块实现增量优化，Eval 模块保证质量标准，Recommend 模块提供智能推荐。这一架构使得开发者能够“编写一次，部署各处”，显著提升了 AI Agent 技能的开发效率和可移植性。\n\n---\n\n\n\n## 技能管理\n\n### 相关页面\n\n相关主题：[代理支持](#agent-support), [格式翻译](#translation-format)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/agents/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/agents/README.md)\n- [packages/core/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/core/README.md)\n- [packages/cli/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/cli/README.md)\n- [packages/tui/src/screens/Sync.tsx](https://github.com/rohitg00/skillkit/blob/main/packages/tui/src/screens/Sync.tsx)\n- [packages/tui/src/screens/Browse.tsx](https://github.com/rohitg00/skillkit/blob/main/packages/tui/src/screens/Browse.tsx)\n- [packages/tui/src/screens/Recommend.tsx](https://github.com/rohitg00/skillkit/blob/main/packages/tui/src/screens/Recommend.tsx)\n- [registry/README.md](https://github.com/rohitg00/skillkit/blob/main/registry/README.md)\n \n\n# 技能管理\n\n## 概述\n\n技能管理（Skill Management）是 SkillKit 项目的核心功能模块，负责技能的发现、安装、同步、翻译和生命周期管理。该系统使开发团队能够跨多个 AI Agent 平台（如 Claude Code、Cursor、Copilot 等）统一管理和分发开发技能（Skills），从而提升团队协作效率和代码一致性。\n\n技能是定义 AI Agent 行为的指令集，通常以 Markdown 格式存储，包含名称、描述、使用说明和示例等内容。SkillKit 通过技能管理系统将这些技能标准化，使其能够在不同 Agent 之间无缝迁移和适配。\n\n## 技能格式\n\nSkillKit 支持多种技能格式，以适配不同 AI Agent 的需求。系统内部会将技能转换为各平台所需的特定格式。\n\n### 支持的格式类型\n\n| 格式 | 适配 Agent | 说明 |\n|------|------------|------|\n| SKILL.md | Claude Code, Codex, Gemini CLI 等 | 标准 YAML frontmatter + Markdown 内容 |\n| MDC (.mdc) | Cursor | 包含 globs 和 alwaysApply 字段 |\n| Markdown | Windsurf, GitHub Copilot | 纯 Markdown 格式 |\n\n### SKILL.md 格式（标准格式）\n\n```markdown\n---\nname: my-skill\ndescription: 技能功能描述\n---\n# My Skill\n具体指令内容...\n```\n\n资料来源：[packages/agents/README.md:22-30]()\n\n### MDC 格式（Cursor 专用）\n\n```markdown\n---\ndescription: 技能功能描述\nglobs: [\"**/*.tsx\"]\nalwaysApply: false\n---\n指令内容...\n```\n\n资料来源：[packages/agents/README.md:33-40]()\n\n### Markdown 格式（Windsurf/Copilot）\n\n```markdown\n# Skill Name\nInstructions for the agent...\n```\n\n资料来源：[packages/agents/README.md:43-46]()\n\n## 技能生命周期\n\n技能从创建到最终使用的完整生命周期包含以下阶段：\n\n```mermaid\ngraph TD\n A[创建技能] --> B[本地开发测试]\n B --> C[安装到 SkillKit]\n C --> D{发布方式}\n D -->|社区注册| E[提交到 registry]\n D -->|私有发布| F[团队 bundle]\n E --> G[技能市场发现]\n F --> H[团队内部同步]\n G --> I[安装到项目]\n H --> I\n I --> J[翻译为目标格式]\n J --> K[同步到 Agent]\n K --> L[Agent 执行技能]\n```\n\n### 创建与开发\n\n技能开发者首先按照标准格式创建 SKILL.md 文件，定义技能的名称、描述和使用指令。开发阶段可以在本地进行测试和迭代。\n\n### 安装流程\n\n通过 `skillkit install` 命令将技能安装到本地环境：\n\n```bash\n# 安装社区技能\nskillkit install owner/skills --skills=lint,test --yes\n\n# 从市场浏览并安装\nskillkit browse\nskillkit install my-skill\n```\n\n资料来源：[packages/cli/README.md:88-93]()\n\n### 同步机制\n\n安装后的技能需要同步到各个 AI Agent。同步过程会根据目标 Agent 的格式要求进行转换：\n\n```bash\n# 同步已安装的技能到所有可用 Agent\nskillkit sync --yes\n\n# 同步特定 Agent 的技能\nskillkit sync --agent cursor\n```\n\n资料来源：[packages/cli/README.md:94-98]()\n\n## 技能市场\n\n技能市场是 SkillKit 提供的技能发现和分发平台，允许用户浏览、搜索和安装社区贡献的技能。\n\n### 市场功能\n\n| 功能 | 说明 |\n|------|------|\n| 浏览 | 按分类查看所有可用技能 |\n| 搜索 | 通过关键词搜索技能 |\n| 安装 | 一键安装技能到本地 |\n| 预览 | 查看技能详情和使用说明 |\n\n### 市场界面（TUI）\n\n在终端用户界面中，市场浏览功能显示技能仓库列表：\n\n```typescript\n// 显示仓库名称、技能数量和加载状态\n{repo.name}\n{repo.skills.length > 0 ? `${repo.skills.length} skills` : ''}\n```\n\n资料来源：[packages/tui/src/screens/Browse.tsx:35-43]()\n\n### 技能详情\n\n选中技能后可以查看详细信息：\n\n```typescript\nfields={repoDetailFields()}\nactions={[\n { key: 'Enter', label: 'Install' },\n { key: 'Esc', label: 'Close' },\n]}\n```\n\n资料来源：[packages/tui/src/screens/Browse.tsx:56-68]()\n\n## 技能同步管理\n\n同步功能确保已安装的技能以正确格式分发到各个 AI Agent。\n\n### 同步状态显示\n\nTUI 界面展示每个 Agent 的同步状态：\n\n| 符号 | 含义 |\n|------|------|\n| ✓ | 已同步 |\n| ○ | 可用但未同步 |\n| ✗ | 不可用 |\n\n资料来源：[packages/tui/src/screens/Sync.tsx:30-32]()\n\n### 同步命令\n\n```bash\nskillkit sync # 同步所有技能\nskillkit sync --agent claude # 同步到特定 Agent\nskillkit sync --yes # 自动确认\n```\n\n资料来源：[packages/cli/README.md:94-98]()\n\n### Agent 兼容性\n\n系统支持超过 39 种不同的 AI Agent，包括：\n\n- Claude Code\n- Cursor\n- Codex\n- Gemini CLI\n- Windsurf\n- GitHub Copilot\n- 以及其他主流 Agent\n\n资料来源：[packages/cli/README.md:71-80]()\n\n## 智能推荐\n\n技能推荐系统分析项目特征，为开发者提供最相关的技能建议。\n\n### 推荐算法\n\n系统通过分析项目的以下特征进行推荐：\n\n- 编程语言栈\n- 框架和库\n- 项目结构\n- 开发约定\n- 测试框架\n\n### 推荐界面\n\nTUI 中的推荐界面显示技能评分和推荐理由：\n\n```typescript\n// 显示推荐技能及其评分\nScore: ${selectedRec()!.score}%\n// 显示推荐原因\n{rec.reasons[0]}\n```\n\n资料来源：[packages/tui/src/screens/Recommend.tsx:35-41]()\n\n### 推荐命令\n\n```bash\n# 获取项目相关的推荐\nskillkit recommend\n\n# 按任务类型筛选\nskillkit recommend --search \"authentication\"\n\n# 设置质量阈值\nskillkit recommend --min-score 85\n```\n\n资料来源：[apps/skillkit/README.md:28-37]()\n\n## 团队协作\n\n### Bundle 系统\n\n团队可以创建技能包（Bundle）以便共享和分发：\n\n```bash\nskillkit team bundle-create # 创建新 bundle\nskillkit team bundle-export # 导出 bundle\nskillkit team bundle-list # 列出所有 bundle\nskillkit team share onboarding-bundle # 分享给团队\n```\n\n资料来源：[packages/cli/README.md:50-55]()\n\n### 团队同步\n\n```bash\n# 初始化团队\nskillkit team init --name \"Engineering Team\"\n\n# 同步远程注册表\nskillkit team sync\n```\n\n资料来源：[apps/skillkit/README.md:40-46]()\n\n## 插件系统\n\nSkillKit 支持通过插件扩展技能管理功能。\n\n### 插件命令\n\n```bash\nskillkit plugin list # 列出已安装插件\nskillkit plugin install # 安装插件\nskillkit plugin uninstall # 卸载插件\nskillkit plugin enable # 启用插件\nskillkit plugin disable # 禁用插件\nskillkit plugin info # 查看插件详情\n```\n\n资料来源：[packages/cli/README.md:57-67]()\n\n## 社区注册表\n\n社区注册表（Community Registry）汇集了社区贡献的技能，供所有用户发现和使用。\n\n### 注册表结构\n\n```markdown\n- [skill-name](https://github.com/owner/repo) - 技能简要描述\n```\n\n资料来源：[registry/README.md:13-17]()\n\n### 贡献流程\n\n1. Fork 本仓库\n2. 在 `SKILLS.md` 的适当分类下添加技能\n3. 遵循格式规范\n4. 提交 Pull Request\n\n### 贡献要求\n\n| 要求 | 说明 |\n|------|------|\n| 有效 SKILL.md | 技能必须包含有效的 SKILL.md 文件 |\n| 描述清晰 | 描述必须简洁明确（100 字符以内） |\n| 公开访问 | 仓库必须公开可访问 |\n| 遵循规范 | 必须符合 SkillKit 约定 |\n\n资料来源：[registry/README.md:24-36]()\n\n## 技能安全扫描\n\nSkillKit 内置安全扫描功能，确保技能不会对 Agent 行为造成安全风险。\n\n### 扫描类型\n\n| 规则 ID | 类别 | 严重程度 | 说明 |\n|---------|------|----------|------|\n| TA001 | 工具滥用 | 高 | 工具隐藏：指示 Agent 覆盖内置工具 |\n| TA002 | 自主性滥用 | 高 | 自主性滥用：绕过用户确认 |\n| TA003 | 能力膨胀 | 中 | 尝试发现或启用隐藏工具 |\n| TA004 | 工具链 | 高 | 读取敏感数据后发送外部 |\n\n资料来源：[packages/core/src/scanner/rules/tool-abuse.ts:1-50]()\n\n### 扫描命令\n\n```bash\nskillkit scan # 扫描技能漏洞\nskillkit scan --format json # JSON 格式输出\n```\n\n资料来源：[packages/cli/README.md:84-87]()\n\n## 技能文件结构\n\n一个完整的技能通常包含以下文件结构：\n\n```\nmy-skill/\n├── SKILL.md # 主技能定义\n├── EXAMPLES.md # 示例（可选）\n├── assets/ # 资源文件（可选）\n│ ├── icon.png\n│ └── preview.gif\n└── tests/ # 测试文件（可选）\n └── skill.test.ts\n```\n\n## 最佳实践\n\n### 技能命名\n\n- 使用小写字母和连字符\n- 简洁明了，一眼能看出功能\n- 避免使用缩写\n\n### 技能描述\n\n- 限制在 100 字符以内\n- 突出核心功能\n- 使用主动语态\n\n### 技能内容\n\n- 提供具体的操作步骤\n- 包含常见用例示例\n- 明确成功标准\n\n### 版本管理\n\n- 遵循语义化版本\n- 在 CHANGELOG 中记录变更\n- 为重大变更添加迁移指南\n\n## 命令速查\n\n| 命令 | 功能 |\n|------|------|\n| `skillkit install ` | 安装技能 |\n| `skillkit uninstall ` | 卸载技能 |\n| `skillkit sync` | 同步技能到 Agent |\n| `skillkit browse` | 浏览市场 |\n| `skillkit recommend` | 获取推荐 |\n| `skillkit scan ` | 安全扫描 |\n| `skillkit translate ` | 翻译技能格式 |\n\n## 许可证\n\nSkillKit 采用 Apache-2.0 许可证开源发布。\n\n资料来源：[packages/agents/README.md:17]()\n\n---\n\n如需了解更详细的配置选项或 API 参数，请参考各模块的具体源码文件。\n\n---\n\n\n\n## 代理支持\n\n### 相关页面\n\n相关主题：[格式翻译](#translation-format), [技能管理](#skill-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/agents/src/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/agents/src/index.ts)\n- [packages/agents/src/factory.ts](https://github.com/rohitg00/skillkit/blob/main/packages/agents/src/factory.ts)\n- [packages/agents/src/base.ts](https://github.com/rohitg00/skillkit/blob/main/packages/agents/src/base.ts)\n- [packages/core/src/agents/discovery.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/agents/discovery.ts)\n- [packages/core/src/agents/types.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/agents/types.ts)\n- [packages/agents/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/agents/README.md)\n \n\n# 代理支持\n\n## 概述\n\nSkillKit 的代理支持（Agent Support）模块是一个多代理集成框架，旨在实现\"一次编写，随处运行\"的技能（Skill）管理模式。该模块通过抽象层设计，支持市场上主流的 AI 编程代理，使开发者能够将技能无缝同步到不同的代理环境中。\n\n代理支持模块位于 `packages/agents` 目录下，提供了代理发现、工厂模式实例化、技能格式转换和代理同步等核心功能。通过统一的数据模型和类型定义，实现了不同代理之间的互操作性。\n\n## 支持的代理列表\n\nSkillKit 目前支持以下 AI 代理，覆盖主流的商业和开源解决方案：\n\n| 代理名称 | 类型 | 技能格式 | 同步支持 |\n|---------|------|---------|---------|\n| Claude | 商业 | SKILL.md | 完整 |\n| ChatGPT | 商业 | SKILL.md | 完整 |\n| Gemini | 商业 | SKILL.md | 完整 |\n| Copilot | 商业 | Markdown | 完整 |\n| Cursor | 商业 | MDC | 完整 |\n| Windsurf | 商业 | Markdown | 完整 |\n| Roo Jira AQ | 商业 | SKILL.md | 完整 |\n| Windsurf Pure | 商业 | SKILL.md | 完整 |\n| Junie | 商业 | SKILL.md | 完整 |\n| Forge | 商业 | SKILL.md | 完整 |\n| Bolt | 商业 | SKILL.md | 完整 |\n| Lovable | 商业 | SKILL.md | 完整 |\n| Replit Agent | 商业 | SKILL.md | 完整 |\n| Sourcegraph Cody | 开源 | SKILL.md | 完整 |\n| Tabby | 开源 | SKILL.md | 完整 |\n| Tabnine | 商业 | SKILL.md | 完整 |\n| Universal | 通用 | SKILL.md | 完整 |\n\n资料来源：[packages/agents/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/agents/README.md)\n\n## 代理架构\n\n### 核心模块结构\n\n```\npackages/agents/\n├── src/\n│ ├── index.ts # 导出入口\n│ ├── factory.ts # 代理工厂\n│ └── base.ts # 基类定义\npackages/core/src/agents/\n├── discovery.ts # 代理发现机制\n└── types.ts # 类型定义\n```\n\n代理系统采用分层架构设计：\n\n```mermaid\ngraph TD\n A[用户请求] --> B[代理工厂 Factory]\n B --> C{代理类型判断}\n C -->|Claude| D[ClaudeAgent]\n C -->|Cursor| E[CursorAgent]\n C -->|Copilot| F[CopilotAgent]\n C -->|Windsurf| G[WindsurfAgent]\n C -->|其他| H[通用代理]\n D --> I[技能同步器]\n E --> I\n F --> I\n G --> I\n H --> I\n I --> J[代理环境]\n```\n\n### 代理基类设计\n\n所有代理实现继承自 `BaseAgent` 基类，该基类定义了代理的标准接口：\n\n```typescript\ninterface AgentAdapter {\n readonly name: string;\n readonly supportedFormats: SkillFormat[];\n readonly installPath: string | null;\n \n install(skill: Skill): Promise;\n uninstall(skillId: string): Promise;\n sync(): Promise;\n list(): Promise;\n detect(): Promise;\n}\n```\n\n资料来源：[packages/agents/src/base.ts](https://github.com/rohitg00/skillkit/blob/main/packages/agents/src/base.ts)\n\n## 代理发现机制\n\n### 自动发现流程\n\n代理发现模块负责检测用户系统中已安装的 AI 代理。当用户首次运行 SkillKit 或执行同步操作时，系统会自动扫描常见安装位置：\n\n```mermaid\ngraph LR\n A[启动发现] --> B[扫描配置目录]\n B --> C{代理可执行?}\n C -->|是| D[标记为已安装]\n C -->|否| E[尝试常见路径]\n E --> C\n D --> F[更新代理状态]\n E --> F\n F --> G[返回发现结果]\n```\n\n### 发现配置\n\n发现机制支持以下配置参数：\n\n| 参数 | 类型 | 说明 | 默认值 |\n|-----|------|-----|-------|\n| scanPaths | string[] | 自定义扫描路径 | 常见代理路径列表 |\n| cacheResults | boolean | 缓存发现结果 | true |\n| timeout | number | 扫描超时时间(ms) | 5000 |\n\n资料来源：[packages/core/src/agents/discovery.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/agents/discovery.ts)\n\n## 代理工厂模式\n\n### 工厂设计\n\n代理工厂（Factory）负责根据代理标识符创建对应的代理实例。这种设计遵循了工厂模式的开闭原则，便于扩展新的代理支持：\n\n```typescript\nclass AgentFactory {\n private static agents: Map = new Map();\n \n static register(type: AgentType, adapter: AgentAdapter): void {\n this.agents.set(type, adapter);\n }\n \n static create(type: AgentType): AgentAdapter | null {\n const adapter = this.agents.get(type);\n return adapter ? Object.create(adapter) : null;\n }\n \n static getSupportedAgents(): AgentType[] {\n return Array.from(this.agents.keys());\n }\n}\n```\n\n资料来源：[packages/agents/src/factory.ts](https://github.com/rohitg00/skillkit/blob/main/packages/agents/src/factory.ts)\n\n### 实例化流程\n\n```mermaid\ngraph TD\n A[传入代理类型] --> B[工厂查询注册表]\n B --> C{类型已注册?}\n C -->|是| D[创建代理实例]\n C -->|否| E[返回null]\n D --> F[初始化代理配置]\n F --> G[返回代理适配器]\n```\n\n## 技能格式兼容性\n\n### 格式类型\n\nSkillKit 支持三种主要的技能格式，每种格式针对特定的代理优化：\n\n#### 1. SKILL.md 格式（通用）\n\n适用于 Claude、ChatGPT、Gemini 等大多数代理。包含 YAML frontmatter 和 Markdown 内容：\n\n```markdown\n---\nname: my-skill\ndescription: 技能描述\n---\n# My Skill\n技能说明和指令...\n```\n\n#### 2. MDC 格式（Cursor 专用）\n\nCursor 特有的格式，支持 globs 和 alwaysApply 字段：\n\n```markdown\n---\ndescription: 技能描述\nglobs: [\"**/*.tsx\"]\nalwaysApply: false\n---\n技能指令...\n```\n\n#### 3. Markdown 格式（Windsurf 和 Copilot）\n\n纯 Markdown 格式，用于 Windsurf 和 GitHub Copilot：\n\n```markdown\n# Skill Name\nAgent instructions here...\n```\n\n资料来源：[packages/agents/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/agents/README.md)\n\n### 格式转换\n\n在同步技能时，系统会根据目标代理自动转换格式：\n\n```mermaid\ngraph LR\n A[源技能] --> B{目标代理}\n B -->|Cursor| C[转换为MDC]\n B -->|Windsurf| D[转换为Markdown]\n B -->|Claude| E[保持SKILL.md]\n C --> F[写入目标目录]\n D --> F\n E --> F\n```\n\n## 代理同步机制\n\n### 同步状态管理\n\n每个代理在同步过程中维护以下状态：\n\n| 状态 | 说明 | 显示标识 |\n|-----|------|---------|\n| synced | 已同步 | ✓ |\n| available | 可用但未同步 | ○ |\n| unavailable | 不可用/未安装 | ✗ |\n\n资料来源：[packages/tui/src/screens/Sync.tsx](https://github.com/rohitg00/skillkit/blob/main/packages/tui/src/screens/Sync.tsx)\n\n### 同步操作\n\n同步功能支持以下操作：\n\n- **单个代理同步**：将技能同步到指定的代理\n- **批量同步**：将技能同步到所有已安装的代理\n- **强制刷新**：重新检测代理并更新同步状态\n\n```mermaid\ngraph TD\n A[用户触发同步] --> B{同步范围}\n B -->|单个| C[选择目标代理]\n B -->|全部| D[获取已安装代理列表]\n C --> E[读取技能配置]\n D --> E\n E --> F[格式转换]\n F --> G[写入代理目录]\n G --> H[更新同步状态]\n H --> I[返回同步结果]\n```\n\n### TUI 界面展示\n\n在 SkillKit 的 TUI 界面中，代理同步状态通过以下方式呈现：\n\n- 代理列表显示当前同步状态\n- 已同步代理显示技能数量\n- 未安装代理显示 \"(unavailable)\" 提示\n- 同步过程中显示加载指示器\n\n## 类型系统\n\n### 核心类型定义\n\n```typescript\ntype AgentType = \n | 'claude' \n | 'chatgpt' \n | 'gemini' \n | 'copilot' \n | 'cursor' \n | 'windsurf' \n | 'roo-jira-aq' \n | 'windsurf-pure' \n | 'junie' \n | 'forge' \n | 'bolt' \n | 'lovable' \n | 'replit-agent' \n | 'sourcegraph-cody' \n | 'tabby' \n | 'tabnine' \n | 'universal';\n\ntype SkillFormat = 'skill-md' | 'mdc' | 'markdown';\n\ninterface AgentSkill {\n id: string;\n name: string;\n version: string;\n path: string;\n installed: boolean;\n syncedAt?: Date;\n}\n```\n\n资料来源：[packages/core/src/agents/types.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/agents/types.ts)\n\n### 操作结果类型\n\n```typescript\ninterface InstallResult {\n success: boolean;\n path?: string;\n error?: string;\n}\n\ninterface UninstallResult {\n success: boolean;\n error?: string;\n}\n\ninterface SyncResult {\n success: boolean;\n agent: AgentType;\n syncedCount: number;\n failedCount: number;\n errors?: string[];\n}\n```\n\n## 使用示例\n\n### CLI 命令\n\n通过命令行与代理进行交互：\n\n```bash\n# 列出所有已安装的代理\nskillkit agent list\n\n# 将技能同步到特定代理\nskillkit sync --to claude,cursor\n\n# 同步所有已安装代理\nskillkit sync --all\n\n# 检查代理状态\nskillkit agent status\n```\n\n### API 调用\n\n在代码中使用代理功能：\n\n```typescript\nimport { AgentFactory, createAgent } from '@skillkit/agents';\nimport { discoverAgents } from '@skillkit/core/agents';\n\n// 发现已安装的代理\nconst agents = await discoverAgents();\n\n// 创建代理实例\nconst claude = AgentFactory.create('claude');\n\n// 安装技能\nconst result = await claude.install(skill);\n```\n\n## 配置管理\n\n### 代理配置存储\n\n代理配置存储在用户目录下的配置文件中：\n\n```\n~/.skillkit/\n├── agents.json # 代理配置\n├── skills/ # 技能存储\n└── cache/ # 缓存目录\n```\n\n### agents.json 结构\n\n```json\n{\n \"installed\": [\"claude\", \"cursor\", \"windsurf\"],\n \"syncPath\": {\n \"claude\": \"~/.claude/skills\",\n \"cursor\": \"~/.cursor/skills\",\n \"windsurf\": \"~/.windsurf/skills\"\n },\n \"lastSync\": \"2024-01-15T10:30:00Z\"\n}\n```\n\n## 最佳实践\n\n### 添加新代理支持\n\n如需添加新的代理支持，建议遵循以下步骤：\n\n1. 在 `AgentType` 中添加新的代理类型\n2. 创建新的代理适配器类，继承 `BaseAgent`\n3. 在工厂中注册新代理\n4. 实现格式转换逻辑（如需要）\n5. 添加相应的测试用例\n\n### 技能编写建议\n\n编写跨代理兼容的技能时：\n\n- 优先使用 SKILL.md 格式（兼容性最广）\n- 避免使用代理特定的功能\n- 为不同代理提供相同的功能描述\n- 测试在多个代理环境中的表现\n\n## 相关文档\n\n- [技能格式指南](./skill-formats.md)\n- [CLI 使用手册](./cli-usage.md)\n- [TUI 界面指南](./tui-guide.md)\n- [API 参考文档](./api-reference.md)\n\n---\n\n\n\n## 格式翻译\n\n### 相关页面\n\n相关主题：[代理支持](#agent-support), [技能管理](#skill-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/core/README.md)\n- [packages/agents/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/agents/README.md)\n- [apps/skillkit/README.md](https://github.com/rohitg00/skillkit/blob/main/apps/skillkit/README.md)\n- [packages/core/src/ai/providers/mock.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/ai/providers/mock.ts)\n- [packages/core/src/primer/generator.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/primer/generator.ts)\n- [packages/cli/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/cli/README.md)\n \n\n# 格式翻译\n\n## 概述\n\n格式翻译是 SkillKit 的核心功能之一，允许开发者编写一次技能定义，然后将其转换为不同 AI 代理（Agent）所支持的格式。通过格式翻译，SkillKit 实现了\"编写一次，部署到多处\"的开发体验。\n\n格式翻译系统支持多种主流 AI 代理，包括 Claude Code、Cursor、Codex、Windsurf、GitHub Copilot 等，共计支持超过 39 种代理格式。资料来源：[packages/cli/README.md]()\n\n## 支持的代理与格式\n\nSkillKit 支持三种主要的技能定义格式，每种格式针对特定的代理进行了优化：\n\n| 格式类型 | 适用代理 | 文件扩展名 | 特点 |\n|---------|---------|-----------|------|\n| SKILL.md | Claude Code、Codex、Gemini CLI 等 | `.md` | YAML 前置元数据 + Markdown 内容 |\n| MDC | Cursor | `.mdc` | 支持 glob 模式匹配和 alwaysApply 字段 |\n| Markdown | Windsurf、Copilot | `.md` | 纯 Markdown 格式 |\n\n资料来源：[packages/agents/README.md]()\n\n## SKILL.md 格式\n\nSKILL.md 是 SkillKit 的标准格式，采用 YAML 前置元数据（frontmatter）加上 Markdown 内容的形式：\n\n```markdown\n---\nname: my-skill\ndescription: What this skill does\n---\n# My Skill\nInstructions...\n```\n\n该格式被大多数代理所使用，具有良好的可读性和结构化表达能力。资料来源：[packages/agents/README.md]()\n\n## MDC 格式（Cursor 专用）\n\nMDC 格式是 Cursor 代理特有的格式，支持更高级的配置选项：\n\n```markdown\n---\ndescription: What this skill does\nglobs: [\"**/*.tsx\"]\nalwaysApply: false\n---\nInstructions...\n```\n\n与 SKILL.md 相比，MDC 格式增加了 `globs` 字段用于文件匹配，以及 `alwaysApply` 字段控制技能的应用范围。资料来源：[packages/agents/README.md]()\n\n## 纯 Markdown 格式\n\n部分代理（如 Windsurf 和 GitHub Copilot）使用纯 Markdown 格式，不包含前置元数据：\n\n```markdown\n# Skill Name\nInstructions for the agent...\n```\n\n这种格式简单直接，适合不需要复杂配置的技能定义场景。资料来源：[packages/agents/README.md]()\n\n## 翻译工作流程\n\n格式翻译的典型工作流程如下：\n\n```mermaid\ngraph TD\n A[编写 SKILL.md 技能] --> B[执行 translate 命令]\n B --> C{目标代理格式}\n C -->|Cursor| D[转换为 MDC 格式]\n C -->|Windsurf/Copilot| E[转换为纯 Markdown]\n C -->|Claude Code| F[保持 SKILL.md]\n D --> G[生成 .mdc 文件]\n E --> H[生成 .md 文件]\n F --> I[输出到目标目录]\n G --> I\n H --> I\n```\n\n## 命令行使用方式\n\n### 基本翻译命令\n\n使用 CLI 进行技能格式翻译是最常见的使用方式：\n\n```bash\n# 翻译单个技能到指定格式\nskillkit translate my-skill --to cursor\n\n# 翻译单个技能到多个格式\nskillkit translate my-skill --to windsurf,codex\n\n# 预览翻译结果（不写入文件）\nskillkit translate my-skill --to copilot --dry-run\n\n# 翻译所有技能\nskillkit translate --all --to windsurf,codex\n```\n\n资料来源：[apps/skillkit/README.md]()\n\n### 预览翻译\n\n翻译预览功能允许在提交变更之前检查翻译结果的兼容性：\n\n```bash\nskillkit translate my-skill --to copilot --dry-run\n```\n\n预览模式会显示目标格式的兼容性问题，帮助用户在应用变更前进行修正。资料来源：[apps/skillkit/README.md]()\n\n## TUI 交互界面\n\nSkillKit 提供了终端用户界面（TUI）进行可视化翻译操作：\n\n### 翻译屏幕组件\n\n翻译界面 (`Translate.tsx`) 提供了交互式的翻译体验，支持选择源技能和目标代理格式。界面会显示：\n\n- 可用的代理列表及其兼容状态\n- 技能信息（名称、路径等）\n- 翻译进度指示器\n- 预览窗口显示翻译结果\n\n资料来源：[packages/tui/src/screens/Translate.tsx]()\n\n### 预览功能\n\nTUI 中的预览功能提供了翻译结果的实时预览，包括：\n\n| 状态 | 含义 | 显示样式 |\n|-----|------|---------|\n| 兼容 (Compatible) | 翻译成功，无问题 | ✓ 绿色 |\n| 有问题 (Has issues) | 存在兼容性问题 | ⚠ 黄色 |\n\n预览界面最多显示 2 个主要问题，便于用户快速了解翻译质量。资料来源：[packages/tui/src/screens/Translate.tsx]()\n\n## 格式检测与自动识别\n\nSkillKit 能够自动检测技能文件的格式类型，识别逻辑包括：\n\n1. **文件扩展名检测**：`.mdc` 文件自动识别为 Cursor MDC 格式\n2. **前置元数据解析**：检查 YAML frontmatter 的存在和结构\n3. **字段识别**：根据特定的字段（如 `globs`、`alwaysApply`）判断是否为 MDC 格式\n\n```mermaid\ngraph TD\n A[读取技能文件] --> B{文件扩展名}\n B -->|.mdc| C[识别为 MDC 格式]\n B -->|.md| D{检查前置元数据}\n D -->|存在 globs| C\n D -->|存在 YAML| E[识别为 SKILL.md]\n D -->|无元数据| F[识别为纯 Markdown]\n```\n\n## 格式转换器架构\n\n格式翻译系统采用了模块化的转换器架构，每个目标格式都有对应的转换器实现：\n\n### 核心转换器\n\n| 转换器 | 功能 | 输出格式 |\n|-------|------|---------|\n| `skill-md.ts` | SKILL.md 格式处理 | 标准 YAML + Markdown |\n| `cursor.ts` | Cursor MDC 格式处理 | MDC 格式（含 globs） |\n| `markdown.ts` | 纯 Markdown 处理 | 无元数据格式 |\n\n### 渲染器系统\n\n转换系统使用渲染器接口来生成不同格式的输出：\n\n```typescript\ninterface FormatRenderer {\n h1: (text) => string;\n h2: (text) => string;\n h3: (text) => string;\n bold: (text) => string;\n code: (text) => string;\n codeBlock: (code, lang?) => string;\n list: (items) => string;\n keyValue: (key, value) => string;\n paragraph: (text) => string;\n separator: () => string;\n wrap: (content, metadata?) => string;\n}\n```\n\n不同格式的渲染器实现会生成符合目标代理规范的输出内容。资料来源：[packages/core/src/primer/generator.ts]()\n\n## 注册表机制\n\n翻译系统使用注册表（Registry）模式管理支持的格式和转换器：\n\n```mermaid\ngraph LR\n A[注册表] --> B[格式 A 转换器]\n A --> C[格式 B 转换器]\n A --> D[格式 C 转换器]\n E[翻译请求] --> A\n A --> F[匹配转换器]\n F --> G[执行转换]\n```\n\n注册表机制允许动态注册新的格式转换器，便于扩展支持更多代理格式。资料来源：[packages/core/src/translator/registry.ts]()\n\n## 编程接口\n\n### Node.js API\n\n开发者可以通过编程方式使用翻译功能：\n\n```typescript\nimport { translateCommand } from '@skillkit/cli';\n\n// 翻译技能\nawait translateCommand('my-skill', {\n to: 'cursor',\n dryRun: false,\n});\n```\n\n### 返回值结构\n\n翻译操作返回包含以下信息的对象：\n\n| 字段 | 类型 | 描述 |\n|-----|------|------|\n| `content` | string | 翻译后的内容 |\n| `format` | string | 目标格式类型 |\n| `warnings` | string[] | 警告信息列表 |\n\n资料来源：[packages/core/README.md]()\n\n## 最佳实践\n\n### 格式选择建议\n\n| 使用场景 | 推荐格式 |\n|---------|---------|\n| 多代理通用技能 | SKILL.md |\n| 仅 Cursor 使用 | MDC |\n| Windsurf/Copilot 专用 | Markdown |\n| 复杂文件匹配需求 | MDC |\n\n### 翻译注意事项\n\n1. **兼容性检查**：翻译前使用 `--dry-run` 预览结果\n2. **格式特性保留**：注意 MDC 格式的 `globs` 字段在转换为其他格式时会被忽略\n3. **内容验证**：翻译后检查目标格式是否符合预期\n\n## 与 MCP 的集成\n\n格式翻译功能可以通过 MCP（Model Context Protocol）远程调用：\n\n```json\n{\n \"mcpServers\": {\n \"skillkit\": {\n \"command\": \"npx\",\n \"args\": [\"@skillkit/mcp\"]\n }\n }\n}\n```\n\nMCP 集成允许远程 AI 代理动态获取和翻译技能定义。资料来源：[README.md]()\n\n## 总结\n\n格式翻译是 SkillKit 实现跨代理兼容性的关键技术，通过统一的技能定义格式和灵活的转换机制，开发者可以专注于技能内容的编写，而将格式适配工作交给 SkillKit 自动完成。该系统支持超过 39 种 AI 代理格式，采用模块化的架构设计，便于扩展新的格式支持。\n\n---\n\n\n\n## AI 集成\n\n### 相关页面\n\n相关主题：[推荐引擎](#recommendation-engine)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/src/ai/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/ai/index.ts)\n- [packages/core/src/ai/providers/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/ai/providers/index.ts)\n- [packages/core/src/ai/providers/factory.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/ai/providers/factory.ts)\n- [packages/core/src/ai/providers/base.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/ai/providers/base.ts)\n- [packages/core/src/ai/security/injection-detect.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/ai/security/injection-detect.ts)\n- [packages/core/src/ai/security/trust-score.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/ai/security/trust-score.ts)\n- [packages/core/src/generator.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/generator.ts)\n \n\n# AI 集成\n\n## 概述\n\nAI 集成是 SkillKit 框架的核心子系统，负责管理与各种 AI 编码代理（Agent）的通信、格式转换和上下文生成。该系统通过统一抽象层，使 SkillKit 能够同时支持 Claude Code、Cursor、Windsurf、GitHub Copilot 等多种 AI 代理，同时保证技能（Skill）在不同代理间的无缝迁移和一致性执行。\n\nSkillKit 的 AI 集成架构采用模块化设计，核心组件包括：\n\n| 组件 | 功能 | 源码位置 |\n|------|------|----------|\n| Provider 工厂 | 创建和管理 AI 提供者实例 | `packages/core/src/ai/providers/factory.ts` |\n| 基础提供接口 | 定义统一的 AI 交互协议 | `packages/core/src/ai/providers/base.ts` |\n| 格式转换器 | 处理 SKILL.md、MDC、Markdown 等格式 | `packages/core/src/translator/formats/` |\n| 安全检测 | 防范提示词注入攻击 | `packages/core/src/ai/security/injection-detect.ts` |\n| 信任评分 | 评估技能内容的可信度 | `packages/core/src/ai/security/trust-score.ts` |\n\n## 架构设计\n\n### 系统分层\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ SkillKit CLI/TUI │\n├─────────────────────────────────────────────────────────────┤\n│ Generator (生成器) │\n│ packages/core/src/generator.ts │\n├─────────────────────────────────────────────────────────────┤\n│ AI Integration Layer │\n│ ┌──────────────┬────────────────┬────────────────┐ │\n│ │ Providers │ Security │ Translators │ │\n│ ├──────────────┼────────────────┼────────────────┤ │\n│ │ • factory │ • injection │ • skill-md │ │\n│ │ • base │ • trust-score │ • mdc │ │\n│ │ • mock │ │ • markdown │ │\n│ └──────────────┴────────────────┴────────────────┘ │\n├─────────────────────────────────────────────────────────────┤\n│ External Agents │\n│ Claude Code │ Cursor │ Windsurf │ Copilot │ Gemini │\n└─────────────────────────────────────────────────────────────┘\n```\n\n资料来源：[packages/core/src/ai/index.ts]()\n\n### Provider 工厂模式\n\nProvider 工厂负责实例化各种 AI 提供者，支持运行时动态切换不同的 AI 后端。工厂模式确保了系统的可扩展性，新增 AI 代理只需实现基础接口即可集成。\n\n```typescript\n// Provider 实例化流程\ncreateProvider(agent: AgentType, options?: ProviderOptions): AIProvider\n```\n\n支持的代理类型包括：claude-code、cursor、windsurf、copilot、gemini-cli、replit-agent、sourcegraph-cody、tabby、tabnine 等。\n\n资料来源：[packages/core/src/ai/providers/factory.ts]()\n\n### 基础提供接口\n\n所有 AI 提供者必须实现 `AIProvider` 接口，该接口定义了与 AI 代理交互的标准方法：\n\n| 方法 | 参数 | 返回值 | 说明 |\n|------|------|--------|------|\n| `generate` | `prompt: string, options?: GenerateOptions` | `Promise` | 生成内容 |\n| `complete` | `context: string, partial: string` | `Promise` | 代码补全 |\n| `chat` | `messages: Message[]` | `Promise` | 对话交互 |\n\n资料来源：[packages/core/src/ai/providers/base.ts]()\n\n## 格式转换系统\n\nSkillKit 支持多种代理特定的技能格式，系统会自动进行格式检测和转换。\n\n### 支持的格式类型\n\n| 格式 | 代理 | 特点 | 源码 |\n|------|------|------|------|\n| SKILL.md | Claude Code, Codex, Gemini CLI | YAML frontmatter + Markdown | `skill-md.ts` |\n| MDC | Cursor | 支持 globs 和 alwaysApply | `mdc.ts` |\n| Markdown | Windsurf, Copilot | 纯 Markdown 内容 | `markdown.ts` |\n\n### 翻译结果模型\n\n```typescript\ninterface TranslationResult {\n content: string; // 转换后的内容\n format: string; // 输出格式标识\n warnings?: string[]; // 潜在问题警告\n}\n```\n\n资料来源：[packages/core/README.md]()\n\n### SKILL.md 格式规范\n\nSKILL.md 是 SkillKit 的标准格式，使用 YAML frontmatter 定义元数据：\n\n```markdown\n---\nname: my-skill\ndescription: What this skill does\nversion: 1.0.0\ntags: [tag1, tag2]\n---\n# Instructions\nMarkdown content here...\n```\n\n解析流程：首先提取 YAML frontmatter，然后解析 body 内容，最后转换为目标格式。\n\n资料来源：[packages/core/src/translator/formats/skill-md.ts]()\n\n## 安全机制\n\n### 提示词注入检测\n\nAI 集成层内置多层安全检测，防范恶意的提示词注入攻击。系统定义了 15 种检测规则，覆盖常见注入模式。\n\n| 规则 ID | 严重程度 | 检测模式 | 说明 |\n|---------|----------|----------|------|\n| PI011 | HIGH | `user>`、`assistant>`、`[AI\\|claude]>` | 对话角色标记注入 |\n| PI012 | HIGH | `[INST]`、`<>` | 模型特定分隔符注入 |\n| PI013 | MEDIUM | `---$` (行尾) | YAML front-matter 注入 |\n| PI014 | MEDIUM | HTML 注释中的可疑内容 | 隐藏指令注入 |\n| PI015 | MEDIUM | `[comment]:` | Markdown 注释注入 |\n\n检测器使用正则表达式匹配和排除模式结合的方式，在保持高检测率的同时降低误报率。\n\n资料来源：[packages/core/src/scanner/rules/prompt-injection.ts]()\n\n### 信任评分系统\n\n每个技能内容都会经过信任评分计算，评分基于多个维度的加权综合：\n\n| 维度 | 权重 | 评估内容 |\n|------|------|----------|\n| 来源可靠性 | 0.3 | 技能来源仓库的信誉 |\n| 内容完整性 | 0.25 | 是否包含必要章节 |\n| 安全检测 | 0.25 | 注入风险评估 |\n| 格式规范 | 0.2 | 格式符合度 |\n\n信任评分结果会影响技能推荐排序和安装决策。\n\n资料来源：[packages/core/src/ai/security/trust-score.ts]()\n\n## 上下文生成器\n\n### 生成器架构\n\nGenerator 组件负责将项目分析和技能信息转换为 AI 代理可理解的上下文指令。\n\n```mermaid\ngraph TD\n A[Analysis Data] --> B[Generator]\n B --> C[Agent Instruction Template]\n C --> D[Section Renderer]\n D --> E[Markdown/MDC Output]\n \n F[Project Profile] --> G[Overview Section]\n H[Stack Info] --> I[Stack Section]\n I --> D\n \n J[Build Commands] --> K[Commands Section]\n K --> D\n \n L[Conventions] --> M[Conventions Section]\n M --> D\n```\n\n资料来源：[packages/core/src/generator.ts]()\n\n### 指令模板渲染\n\n系统支持生成多种格式的指令输出，包括纯 Markdown 和 MDC（Markdown + YAML frontmatter）格式。\n\n```typescript\nconst markdownRenderer: FormatRenderer = {\n h1: (text) => `# ${text}`,\n h2: (text) => `## ${text}`,\n code: (text) => `\\`${text}\\``,\n codeBlock: (code, lang = '') => `\\`\\`\\`${lang}\\n${code}\\n\\`\\`\\``,\n // ...\n};\n```\n\n格式渲染器抽象允许同一模板渲染为不同代理的特定格式。\n\n资料来源：[packages/core/src/primer/generator.ts]()\n\n### 生成区块\n\n上下文生成器支持生成以下区块：\n\n| 区块 | 说明 | 包含数据 |\n|------|------|----------|\n| overview | 项目概览 | 项目名称、类型、语言统计 |\n| stack | 技术栈 | 框架、库、测试工具、数据库 |\n| commands | 构建命令 | 安装、构建、测试命令 |\n| conventions | 代码规范 | 命名约定、提交规范 |\n| structure | 项目结构 | 目录树、重要文件 |\n| guidelines | 使用指南 | 技能适用场景、边界 |\n\n资料来源：[packages/core/src/primer/generator.ts]()\n\n## 技能翻译工作流\n\n### 翻译流程图\n\n```mermaid\ngraph LR\n A[Skill Content] --> B[Parse Source Format]\n B --> C[Validate Content]\n C --> D{Validation Pass?}\n D -->|No| E[Report Issues]\n D -->|Yes| F[Detect Target Agent]\n F --> G[Select Translator]\n G --> H[Transform Format]\n H --> I[Security Scan]\n I --> J{Security Pass?}\n J -->|No| K[Show Warnings]\n J -->|Yes| L[Translation Result]\n L --> M[Preview/Install]\n```\n\n### 翻译屏幕交互\n\nTUI 界面提供了交互式翻译功能，支持以下操作：\n\n- 源格式自动检测\n- 目标代理选择（支持多选批量转换）\n- 预览模式（dry-run）\n- 兼容性检查\n- 问题提示显示\n\n资料来源：[packages/tui/src/screens/Translate.tsx]()\n\n## 配置选项\n\n### Provider 配置\n\n```typescript\ninterface ProviderOptions {\n apiKey?: string; // API 密钥\n baseUrl?: string; // 自定义端点\n model?: string; // 指定模型\n temperature?: number; // 生成温度\n maxTokens?: number; // 最大 token 数\n timeout?: number; // 请求超时(ms)\n}\n```\n\n### Generator 配置\n\n```typescript\ninterface GeneratorOptions {\n format: 'markdown' | 'mdc';\n sections?: string[]; // 启用的区块\n customInstructions?: string; // 自定义指令\n template?: AgentInstructionTemplate;\n}\n```\n\n## 最佳实践\n\n### 1. 选择合适的技能格式\n\n根据目标代理选择对应的格式：\n\n| 目标代理 | 推荐格式 | 说明 |\n|----------|----------|------|\n| Claude Code | SKILL.md | 官方推荐标准格式 |\n| Cursor | MDC | 支持文件 glob 匹配 |\n| Windsurf/Copilot | Markdown | 简单纯文本格式 |\n| 多代理兼容 | SKILL.md | 通用的转换源格式 |\n\n### 2. 安全检查清单\n\n在发布技能前，确保通过以下检查：\n\n- ✅ 无提示词注入模式（PI011-PI015）\n- ✅ YAML frontmatter 格式正确\n- ✅ 不含隐藏指令（HTML 注释）\n- ✅ 信任评分达到阈值\n\n### 3. 格式转换注意事项\n\n- 转换前先验证源格式完整性\n- 使用 dry-run 模式预览转换结果\n- 检查转换后的兼容性警告\n- 多代理场景使用 SKILL.md 作为中间格式\n\n## 相关命令\n\n```bash\n# 翻译技能格式\nskillkit translate my-skill --to cursor\nskillkit translate --all --to windsurf,copilot\nskillkit translate my-skill --to copilot --dry-run\n\n# 扫描安全问题\nskillkit scan \nskillkit scan --format json\n\n# 生成上下文\nskillkit generate context --project . --format markdown\n```\n\n资料来源：[packages/cli/README.md]()\n\n## 扩展开发\n\n### 添加新代理支持\n\n1. 在 `packages/core/src/ai/providers/` 创建新 provider 文件\n2. 实现 `AIProvider` 接口的所有方法\n3. 在 `factory.ts` 中注册新代理类型\n4. 在 `packages/core/src/translator/formats/` 创建格式转换器\n5. 添加测试用例覆盖\n\n### 添加新格式支持\n\n1. 创建新的 translator 类实现 `FormatTranslator` 接口\n2. 实现 `parse()` 和 `generate()` 方法\n3. 在 translator 注册表中添加新格式\n4. 更新 README.md 文档\n\n## 总结\n\nSkillKit 的 AI 集成系统通过模块化架构实现了对多种 AI 编码代理的统一支持。核心设计包括 Provider 工厂模式、格式转换系统、安全检测机制和上下文生成器，确保技能在异构代理环境中的可移植性和安全性。开发者可以通过扩展 Provider 和 Translator 来支持新的代理类型和格式，无需修改核心逻辑。\n\n---\n\n\n\n## 推荐引擎\n\n### 相关页面\n\n相关主题：[AI 集成](#ai-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/tui/src/screens/Recommend.tsx](https://github.com/rohitg00/skillkit/blob/main/packages/tui/src/screens/Recommend.tsx)\n- [packages/cli/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/cli/README.md)\n- [packages/tui/src/screens/Handoff.tsx](https://github.com/rohitg00/skillkit/blob/main/packages/tui/src/screens/Handoff.tsx)\n- [README.md](https://github.com/rohitg00/skillkit/blob/main/README.md)\n- [packages/core/src/ai/providers/mock.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/ai/providers/mock.ts)\n \n\n# 推荐引擎\n\n## 概述\n\n推荐引擎（Recommendation Engine）是 SkillKit 项目中帮助用户发现适合其技术栈的技能的智能系统。该引擎通过分析用户项目的技术栈信息，为用户推荐最相关的技能，并按照匹配度评分进行排序展示。\n\nSkillKit 的推荐系统支持以下核心功能：\n\n| 功能 | 说明 |\n|------|------|\n| 栈感知推荐 | 基于项目技术栈（框架、语言、库）进行智能匹配 |\n| 评分排序 | 使用百分比评分（0-100%）衡量推荐准确度 |\n| 搜索过滤 | 支持通过关键词搜索筛选推荐结果 |\n| 质量阈值 | 可设置最低分数阈值过滤低质量推荐 |\n\n资料来源：[README.md]()\n\n## 核心架构\n\n推荐引擎采用分层架构设计，主要包含以下几个层次：\n\n```mermaid\ngraph TD\n A[用户项目] --> B[栈分析层]\n B --> C[推荐引擎核心]\n C --> D[混合搜索模块]\n C --> E[RRF 排序模块]\n D --> F[推荐结果]\n E --> F\n G[CLI 命令层] --> C\n H[TUI 界面层] --> C\n```\n\n### 各层职责\n\n| 层级 | 职责 | 源码位置 |\n|------|------|----------|\n| CLI 命令层 | 提供 `skillkit recommend` 命令入口 | `packages/cli/src/commands/recommend.ts` |\n| TUI 界面层 | 渲染推荐列表和详情面板 | `packages/tui/src/screens/Recommend.tsx` |\n| 推荐引擎核心 | 协调搜索和排序流程 | `packages/core/src/recommend/engine.ts` |\n| 混合搜索模块 | 执行多维度搜索 | `packages/core/src/search/hybrid.ts` |\n| RRF 排序模块 | 应用 Reciprocal Rank Fusion 算法 | `packages/core/src/search/rrf.ts` |\n| 栈分析层 | 分析项目技术栈 | `packages/core/src/primer/generator.ts` |\n\n资料来源：[packages/tui/src/screens/Recommend.tsx]()\n资料来源：[packages/core/src/search/rrf.ts]()\n\n## 推荐数据模型\n\n### 推荐结果结构\n\n```typescript\ninterface Recommendation {\n name: string; // 技能名称\n score: number; // 匹配度评分（0-100）\n description?: string; // 技能描述\n reasons?: string[]; // 推荐理由列表\n path?: string; // 技能文件路径\n compatible?: boolean; // 与项目的兼容性\n issues?: string[]; // 兼容性问题列表\n}\n```\n\n资料来源：[packages/tui/src/screens/Recommend.tsx]()\n\n### 推荐理由显示\n\n推荐理由（reasons）字段用于向用户解释为什么推荐该技能。当存在推荐理由时，界面会优先显示理由而非描述：\n\n```tsx\n 0}>\n \n {' '}{rec.reasons[0]}\n \n\n\n \n {' '}{rec.description.slice(0, 50)}\n {rec.description.length > 50 ? '...' : ''}\n \n\n```\n\n资料来源：[packages/tui/src/screens/Recommend.tsx:1-15]()\n\n## 搜索与排序机制\n\n### 混合搜索（Hybrid Search）\n\n推荐引擎内部使用混合搜索策略，结合多种搜索维度：\n\n```mermaid\ngraph LR\n A[关键词搜索] --> D[结果合并]\n B[栈匹配搜索] --> D\n C[语义搜索] --> D\n D --> E[RRF 融合排序]\n E --> F[最终排名]\n```\n\n### RRF（Reciprocal Rank Fusion）\n\nRRF 算法用于融合多个搜索结果源的排名，通过倒数排名融合公式计算综合得分：\n\n```\nRRF_score = Σ (1 / (k + rank_i))\n```\n\n其中 `k` 是常数参数（通常为60），`rank_i` 是该技能在第 i 个搜索结果中的排名。\n\n资料来源：[packages/core/src/search/rrf.ts]()\n\n## 命令行接口\n\n### 基本用法\n\n```bash\n# 获取项目感知建议\nskillkit recommend\n\n# 按任务筛选\nskillkit recommend --search \"authentication\"\n\n# 质量阈值过滤\nskillkit recommend --min-score 85\n```\n\n资料来源：[packages/cli/README.md]()\n\n### 参数说明\n\n| 参数 | 说明 | 示例 |\n|------|------|------|\n| `--search` | 关键词搜索过滤 | `--search \"react\"` |\n| `--min-score` | 最低匹配分数阈值 | `--min-score 70` |\n| `--format` | 输出格式（默认表格） | `--format json` |\n\n资料来源：[README.md]()\n\n## TUI 界面交互\n\n### 主视图布局\n\n```\n┌─────────────────────────────────────────────┐\n│ 推荐技能 │\n│ ───────────────────────────────────────── │\n│ ▸ 92% vercel-react-best-practices │\n│ 87% tailwind-v4-patterns │\n│ 85% nextjs-app-router │\n│ 81% shadcn-ui-components │\n│ │\n│ ▼ 5 more │\n│ │\n│ Last analyzed: 14:32:05 │\n│ ─────────────────────────────────────────────│\n│ j/k 导航 Enter 详情 Esc 返回 │\n└─────────────────────────────────────────────┘\n```\n\n### 详情面板\n\n按 Enter 键可打开选中推荐的详情面板，显示以下信息：\n\n| 字段 | 说明 |\n|------|------|\n| Title | 技能名称 |\n| Subtitle | 匹配分数（Score: XX%） |\n| Fields | 详细信息字段列表 |\n| Actions | 操作提示（Install / Close） |\n\n资料来源：[packages/tui/src/screens/Recommend.tsx]()\n\n### 导航与操作\n\n| 按键 | 操作 |\n|------|------|\n| `j` / `k` | 上/下导航选择 |\n| `Enter` | 查看详情面板 |\n| `Esc` | 返回上一级 |\n| `r` | 刷新推荐列表 |\n\n## 评分机制\n\n### 分数计算因素\n\n推荐技能的评分基于以下因素综合计算：\n\n1. **技术栈匹配度**：技能与项目使用的框架、语言、库的匹配程度\n2. **依赖关联度**：技能所需依赖与项目现有依赖的重叠度\n3. **使用频率**：该技能在同类项目中的使用统计数据\n4. **更新时效性**：技能文档的新旧程度\n\n### 分数阈值建议\n\n| 阈值范围 | 建议用途 |\n|----------|----------|\n| 90-100% | 高置信度推荐，直接安装使用 |\n| 70-89% | 中等置信度，建议查看详情后再安装 |\n| 50-69% | 低置信度，仅供参考 |\n| < 50% | 通常不显示，除非关闭阈值过滤 |\n\n## 编程接口\n\n### 程序化调用\n\n```typescript\nimport { recommendCommand } from '@skillkit/cli';\n\n// 获取推荐\nconst recs = await recommendCommand({\n path: './my-project',\n minScore: 70,\n});\n\n// 遍历推荐结果\nfor (const rec of recs) {\n console.log(`${rec.score}% ${rec.name}`);\n console.log(` 原因: ${rec.reasons?.join(', ')}`);\n}\n```\n\n### 搜索集成\n\n推荐引擎可与搜索系统集成，支持更精细的查询：\n\n```typescript\nimport { searchSkills } from '@skillkit/core/search';\nimport { rankResults } from '@skillkit/core/ranking';\n\n// 执行混合搜索\nconst results = await searchSkills({\n query: 'react performance',\n stack: projectStack,\n hybrid: true\n});\n\n// 应用 RRF 排序\nconst ranked = rankResults(results, { k: 60 });\n```\n\n资料来源：[packages/core/src/search/hybrid.ts]()\n\n## 交接（Handoff）功能中的推荐\n\n在项目交接功能中，推荐系统提供额外的上下文感知建议：\n\n```tsx\n\n Recommendations\n \n {(rec) => (\n \n →\n {rec}\n \n )}\n \n\n```\n\n资料来源：[packages/tui/src/screens/Handoff.tsx]()\n\n## 性能优化\n\n### 分页加载\n\n当推荐结果较多时，TUI 界面采用分页显示策略：\n\n```tsx\n\n \n ▼ {state().recommendations.length - recsWindow().start - maxVisible()} more\n \n\n```\n\n默认每页显示固定数量的推荐项，通过 `maxVisible()` 配置。\n\n资料来源：[packages/tui/src/screens/Recommend.tsx]()\n\n### 增量分析\n\n推荐引擎支持增量分析模式，仅对变更的文件重新计算推荐，避免全量扫描：\n\n```mermaid\ngraph LR\n A[文件变更] --> B[增量分析]\n B --> C{变更类型}\n C -->|依赖文件| D[重新匹配依赖]\n C -->|代码文件| E[更新栈检测]\n C -->|配置| F[刷新配置分析]\n D --> G[更新推荐列表]\n E --> G\n F --> G\n```\n\n## 最佳实践\n\n### 1. 合理设置阈值\n\n- 新项目建议使用较低阈值（50-70%）以获取更多参考\n- 成熟项目可提高阈值（80%+）确保推荐质量\n\n### 2. 结合搜索使用\n\n```bash\n# 先获取所有推荐\nskillkit recommend\n\n# 再通过关键词精筛\nskillkit recommend --search \"authentication\" --min-score 75\n```\n\n### 3. 查看推荐理由\n\n始终查看推荐理由（reasons）以理解推荐依据，对于不符合预期的推荐可进一步分析项目栈检测是否准确。\n\n### 4. 定期刷新\n\n项目依赖变更后建议执行 `skillkit recommend --refresh` 重新生成推荐列表。\n\n## 配置选项\n\n### 引擎配置\n\n| 配置项 | 默认值 | 说明 |\n|--------|--------|------|\n| `minScore` | 0 | 最低推荐分数阈值 |\n| `maxResults` | 20 | 最大返回结果数 |\n| `includeReasons` | true | 是否包含推荐理由 |\n| `stackDepth` | 3 | 技术栈分析深度 |\n\n### 排序配置\n\n| 配置项 | 默认值 | 说明 |\n|--------|--------|------|\n| `rrf.k` | 60 | RRF 算法常数参数 |\n| `weights.keyword` | 0.4 | 关键词搜索权重 |\n| `weights.stack` | 0.6 | 栈匹配搜索权重 |\n\n## 故障排除\n\n### 推荐结果为空\n\n可能原因及解决方案：\n\n| 原因 | 解决方案 |\n|------|----------|\n| 项目栈检测失败 | 运行 `skillkit analyze` 检查项目分析结果 |\n| 阈值设置过高 | 降低 `--min-score` 参数值 |\n| 技能库未同步 | 运行 `skillkit sync` 同步技能库 |\n\n### 评分异常\n\n如果推荐分数明显不符合预期：\n\n1. 检查 `skillkit analyze` 输出确认栈检测准确性\n2. 确认技能库版本为最新\n3. 查看是否有缓存问题，尝试 `skillkit clean && skillkit recommend`\n\n## 相关文档\n\n- [搜索系统](../search/index.html)\n- [栈分析器](../primer/index.html)\n- [技能格式](../skill-format/index.html)\n- [CLI 命令参考](../cli/commands.html)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：rohitg00/skillkit\n\n摘要：发现 23 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Trust downgrade for skillkit@1.24.0: v1.0.3 had provenance attestation but this version has no trust evidence。\n\n## 1. 安装坑 · 来源证据：Trust downgrade for skillkit@1.24.0: v1.0.3 had provenance attestation but this version has no trust evidence\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Trust downgrade for skillkit@1.24.0: v1.0.3 had provenance attestation but this version has no trust evidence\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_54f25870d6d64729a96eb14e8e1ee72f | https://github.com/rohitg00/skillkit/issues/121 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 2. 安全/权限坑 · 来源证据：[Publish] CreatorCrawl — Social Media Data Skill\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Publish] CreatorCrawl — Social Media Data Skill\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d2c6e8b4d87e4786af49c7bc9ee2665d | https://github.com/rohitg00/skillkit/issues/123 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：Add source: jorgeferrando/sdd-skills — Spec-Driven Development workflow\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add source: jorgeferrando/sdd-skills — Spec-Driven Development workflow\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d1cb6475bbfe4122ab15817ca66e58b6 | https://github.com/rohitg00/skillkit/issues/112 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：[Publish] Rhf Autosave\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Publish] Rhf Autosave\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7f4a4b823d1a40918a48fb8aae0d74ac | https://github.com/rohitg00/skillkit/issues/111 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 安装坑 · 来源证据：v1.20.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.20.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_73d12f84f1644a3dbc3981274dfefa42 | https://github.com/rohitg00/skillkit/releases/tag/v1.20.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 安装坑 · 来源证据：v1.22.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.22.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a5339307b2d04e409858700fa8186f6c | https://github.com/rohitg00/skillkit/releases/tag/v1.22.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 安装坑 · 来源证据：v1.22.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.22.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2a197dc603b242bdaa32dd2c70d535c1 | https://github.com/rohitg00/skillkit/releases/tag/v1.22.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 安装坑 · 来源证据：v1.23.0 — Slim install, safer picker, brand tags\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.23.0 — Slim install, safer picker, brand tags\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9388696ec7584a6b8f5998d74f1c428e | https://github.com/rohitg00/skillkit/releases/tag/v1.23.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 9. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1138376193 | https://github.com/rohitg00/skillkit | host_targets=claude, claude_code, cursor\n\n## 10. 能力坑 · 能力判断依赖假设\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:1138376193 | https://github.com/rohitg00/skillkit | README/documentation is current enough for a first validation pass.\n\n## 11. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1138376193 | https://github.com/rohitg00/skillkit | last_activity_observed missing\n\n## 12. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1138376193 | https://github.com/rohitg00/skillkit | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1138376193 | https://github.com/rohitg00/skillkit | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 来源证据：[Audit] Add --json output to 28 commands for CI/CD usage\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Audit] Add --json output to 28 commands for CI/CD usage\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e28aa428237f4e6ba09f785dbf5e6978 | https://github.com/rohitg00/skillkit/issues/89 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 15. 安全/权限坑 · 来源证据：[Audit] Add loading spinners to 43 commands missing progress feedback\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Audit] Add loading spinners to 43 commands missing progress feedback\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9bba06e67cf944c28dcb33d8ed334975 | https://github.com/rohitg00/skillkit/issues/88 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 16. 安全/权限坑 · 来源证据：[Publish] AlphaEar System\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Publish] AlphaEar System\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_26d8102a08b8434cb7456fcd1554ce3a | https://github.com/rohitg00/skillkit/issues/126 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：[Publish] Computer Use Patterns\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Publish] Computer Use Patterns\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5f48d6d0c0c04492b897829190a0df3c | https://github.com/rohitg00/skillkit/issues/124 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 18. 安全/权限坑 · 来源证据：[Publish] SkillKit Integration\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Publish] SkillKit Integration\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2c9342c012d74dcfba1ba832a87724c3 | https://github.com/rohitg00/skillkit/issues/125 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 19. 安全/权限坑 · 来源证据：[Source] Add Xquik TweetClaw\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Source] Add Xquik TweetClaw\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f9e22dd824ca491e8bd861cac00a2203 | https://github.com/rohitg00/skillkit/issues/120 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 20. 安全/权限坑 · 来源证据：v1.21.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.21.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2989a360f78d46cfbba976f4932bff93 | https://github.com/rohitg00/skillkit/releases/tag/v1.21.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 21. 安全/权限坑 · 来源证据：v1.24.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.24.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8dbf39f6064042bbb250f034a824d7d3 | https://github.com/rohitg00/skillkit/releases/tag/v1.24.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 22. 维护坑 · 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:1138376193 | https://github.com/rohitg00/skillkit | issue_or_pr_quality=unknown\n\n## 23. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1138376193 | https://github.com/rohitg00/skillkit | 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项目：rohitg00/skillkit\n\n摘要：发现 23 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Trust downgrade for skillkit@1.24.0: v1.0.3 had provenance attestation but this version has no trust evidence。\n\n## 1. 安装坑 · 来源证据：Trust downgrade for skillkit@1.24.0: v1.0.3 had provenance attestation but this version has no trust evidence\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Trust downgrade for skillkit@1.24.0: v1.0.3 had provenance attestation but this version has no trust evidence\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_54f25870d6d64729a96eb14e8e1ee72f | https://github.com/rohitg00/skillkit/issues/121 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 2. 安全/权限坑 · 来源证据：[Publish] CreatorCrawl — Social Media Data Skill\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Publish] CreatorCrawl — Social Media Data Skill\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d2c6e8b4d87e4786af49c7bc9ee2665d | https://github.com/rohitg00/skillkit/issues/123 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：Add source: jorgeferrando/sdd-skills — Spec-Driven Development workflow\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add source: jorgeferrando/sdd-skills — Spec-Driven Development workflow\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d1cb6475bbfe4122ab15817ca66e58b6 | https://github.com/rohitg00/skillkit/issues/112 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：[Publish] Rhf Autosave\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Publish] Rhf Autosave\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7f4a4b823d1a40918a48fb8aae0d74ac | https://github.com/rohitg00/skillkit/issues/111 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 安装坑 · 来源证据：v1.20.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.20.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_73d12f84f1644a3dbc3981274dfefa42 | https://github.com/rohitg00/skillkit/releases/tag/v1.20.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 安装坑 · 来源证据：v1.22.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.22.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a5339307b2d04e409858700fa8186f6c | https://github.com/rohitg00/skillkit/releases/tag/v1.22.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 安装坑 · 来源证据：v1.22.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.22.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2a197dc603b242bdaa32dd2c70d535c1 | https://github.com/rohitg00/skillkit/releases/tag/v1.22.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 安装坑 · 来源证据：v1.23.0 — Slim install, safer picker, brand tags\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.23.0 — Slim install, safer picker, brand tags\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9388696ec7584a6b8f5998d74f1c428e | https://github.com/rohitg00/skillkit/releases/tag/v1.23.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 9. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1138376193 | https://github.com/rohitg00/skillkit | host_targets=claude, claude_code, cursor\n\n## 10. 能力坑 · 能力判断依赖假设\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:1138376193 | https://github.com/rohitg00/skillkit | README/documentation is current enough for a first validation pass.\n\n## 11. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1138376193 | https://github.com/rohitg00/skillkit | last_activity_observed missing\n\n## 12. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1138376193 | https://github.com/rohitg00/skillkit | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1138376193 | https://github.com/rohitg00/skillkit | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 来源证据：[Audit] Add --json output to 28 commands for CI/CD usage\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Audit] Add --json output to 28 commands for CI/CD usage\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e28aa428237f4e6ba09f785dbf5e6978 | https://github.com/rohitg00/skillkit/issues/89 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 15. 安全/权限坑 · 来源证据：[Audit] Add loading spinners to 43 commands missing progress feedback\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Audit] Add loading spinners to 43 commands missing progress feedback\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9bba06e67cf944c28dcb33d8ed334975 | https://github.com/rohitg00/skillkit/issues/88 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 16. 安全/权限坑 · 来源证据：[Publish] AlphaEar System\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Publish] AlphaEar System\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_26d8102a08b8434cb7456fcd1554ce3a | https://github.com/rohitg00/skillkit/issues/126 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：[Publish] Computer Use Patterns\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Publish] Computer Use Patterns\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5f48d6d0c0c04492b897829190a0df3c | https://github.com/rohitg00/skillkit/issues/124 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 18. 安全/权限坑 · 来源证据：[Publish] SkillKit Integration\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Publish] SkillKit Integration\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2c9342c012d74dcfba1ba832a87724c3 | https://github.com/rohitg00/skillkit/issues/125 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 19. 安全/权限坑 · 来源证据：[Source] Add Xquik TweetClaw\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Source] Add Xquik TweetClaw\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f9e22dd824ca491e8bd861cac00a2203 | https://github.com/rohitg00/skillkit/issues/120 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 20. 安全/权限坑 · 来源证据：v1.21.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.21.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2989a360f78d46cfbba976f4932bff93 | https://github.com/rohitg00/skillkit/releases/tag/v1.21.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 21. 安全/权限坑 · 来源证据：v1.24.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.24.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8dbf39f6064042bbb250f034a824d7d3 | https://github.com/rohitg00/skillkit/releases/tag/v1.24.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 22. 维护坑 · 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:1138376193 | https://github.com/rohitg00/skillkit | issue_or_pr_quality=unknown\n\n## 23. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1138376193 | https://github.com/rohitg00/skillkit | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# skillkit - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 skillkit 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：claude / Claude Code / Cursor\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. project-overview：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. installation-guide：安装指南。围绕“安装指南”模拟一次用户任务，不展示安装或运行结果。\n3. quick-start-guide：快速入门。围绕“快速入门”模拟一次用户任务，不展示安装或运行结果。\n4. package-structure：包结构与依赖关系。围绕“包结构与依赖关系”模拟一次用户任务，不展示安装或运行结果。\n5. core-modules：核心模块解析。围绕“核心模块解析”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. project-overview\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. installation-guide\n输入：用户提供的“安装指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. quick-start-guide\n输入：用户提供的“快速入门”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. package-structure\n输入：用户提供的“包结构与依赖关系”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. core-modules\n输入：用户提供的“核心模块解析”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / project-overview：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / installation-guide：Step 2 必须围绕“安装指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / quick-start-guide：Step 3 必须围绕“快速入门”形成一个小中间产物，并等待用户确认。\n- Step 4 / package-structure：Step 4 必须围绕“包结构与依赖关系”形成一个小中间产物，并等待用户确认。\n- Step 5 / core-modules：Step 5 必须围绕“核心模块解析”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/rohitg00/skillkit\n- https://github.com/rohitg00/skillkit#readme\n- packages/core/src/eval/__tests__/fixtures/bad-skill/SKILL.md\n- packages/core/src/eval/__tests__/fixtures/eval-injection-skill/SKILL.md\n- packages/core/src/eval/__tests__/fixtures/good-skill/SKILL.md\n- packages/core/src/methodology/packs/collaboration/handoff-protocols/SKILL.md\n- packages/core/src/methodology/packs/collaboration/parallel-investigation/SKILL.md\n- packages/core/src/methodology/packs/collaboration/structured-review/SKILL.md\n- packages/core/src/methodology/packs/debugging/hypothesis-testing/SKILL.md\n- packages/core/src/methodology/packs/debugging/root-cause-analysis/SKILL.md\n- packages/core/src/methodology/packs/debugging/trace-and-isolate/SKILL.md\n- packages/core/src/methodology/packs/meta/skill-authoring/SKILL.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 skillkit 的核心服务。\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项目：rohitg00/skillkit\n\n## 官方安装入口\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx skillkit\n```\n\n来源：https://github.com/rohitg00/skillkit#readme\n\n## 来源\n\n- repo: https://github.com/rohitg00/skillkit\n- docs: https://github.com/rohitg00/skillkit#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_536fb43ab7c74f9eb46c79b5ed419828"
}