# https://github.com/rohitg00/skillkit 项目说明书 生成时间：2026-05-16 18:44:53 UTC ## 目录 - [项目介绍](#project-overview) - [安装指南](#installation-guide) - [快速入门](#quick-start-guide) - [包结构与依赖关系](#package-structure) - [核心模块解析](#core-modules) - [技能管理](#skill-management) - [代理支持](#agent-support) - [格式翻译](#translation-format) - [AI 集成](#ai-integration) - [推荐引擎](#recommendation-engine) ## 项目介绍 ### 相关页面 相关主题：[安装指南](#installation-guide), [快速入门](#quick-start-guide)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/rohitg00/skillkit/blob/main/README.md) - [packages/agents/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/agents/README.md) - [packages/cli/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/cli/README.md) - [packages/core/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/core/README.md) - [packages/core/src/ai/providers/mock.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/ai/providers/mock.ts)
# 项目介绍 ## 概述 SkillKit 是一个开源的 AI Agent 技能管理系统，旨在解决 AI 代码助手（Agent）在技能定义格式上互不兼容的问题。该项目允许开发者编写一次技能配置，即可将其转换并分发到多个 AI 平台使用，包括 Cursor、Copilot、Windsurf、Claude 等主流工具。 资料来源：[README.md]() ## 核心价值定位 当前 AI 代码助手生态中存在一个显著问题：每个平台都定义了各自独特的技能（Skill）格式规范。这种碎片化导致开发者需要为同一个技能编写多份配置，造成了重复劳动和维护负担。SkillKit 通过提供统一的技能格式和自动化转换机制，显著简化了这一工作流程。 资料来源：[README.md]() ## 支持的 AI Agent 平台 SkillKit 目前支持以下 AI Agent 平台的技能分发： | 平台名称 | 状态 | |---------|------| | augment-code | ✅ 支持 | | bolt | ✅ 支持 | | lovable | ✅ 支持 | | replit-agent | ✅ 支持 | | sourcegraph-cody | ✅ 支持 | | tabby | ✅ 支持 | | tabnine | ✅ 支持 | | universal | ✅ 支持 | 资料来源：[packages/agents/README.md]() ## 技能格式支持 ### SKILL.md 格式 这是大多数 Agent 使用的标准格式，采用 YAML frontmatter 结合 Markdown 内容： ```markdown --- name: my-skill description: What this skill does --- # My Skill Instructions... ``` 资料来源：[packages/agents/README.md]() ### MDC 格式（Cursor） Cursor 平台专用的格式，支持 glob 模式匹配和 alwaysApply 配置： ```markdown --- description: What this skill does globs: ["**/*.tsx"] alwaysApply: false --- Instructions... ``` 资料来源：[packages/agents/README.md]() ### Markdown 格式 Windsurf 和 Copilot 使用的纯 Markdown 格式： ```markdown # Skill Name Instructions for the agent... ``` 资料来源：[packages/agents/README.md]() ## 技术架构 ### 模块化设计 SkillKit 采用 Monorepo 结构组织代码，主要包含以下核心模块： ```mermaid graph TD A[SkillKit] --> B[CLI 模块] A --> C[Core 核心库] A --> D[TUI 终端界面] A --> E[Extension 扩展] A --> F[MCP Server] B --> C D --> C F --> C ``` 资料来源：[packages/core/README.md]() ### Core 核心库 核心库提供以下关键功能： - **格式转换引擎**：支持 SKILL.md、MDC、Markdown 之间的相互转换 - **项目分析器**：检测项目技术栈（语言、框架、库、数据库等） - **技能推荐系统**：基于检测到的技术栈提供相关技能建议 - **格式渲染器**：支持 Markdown、HTML、XML 等多种输出格式 资料来源：[packages/core/README.md]() 资料来源：[packages/core/src/primer/generator.ts]() ### CLI 命令行工具 通过命令行界面提供完整的技能管理能力： ```bash # 添加技能 skillkit add claude:user/my-skill # Claude skillkit add github:owner/repo # GitHub skillkit add gitlab:team/skills # GitLab skillkit add ./my-local-skills # 本地路径 skillkit add https://gist.github.com/... # Gist # 格式转换 skillkit translate my-skill --to cursor skillkit translate --all --to windsurf,codex skillkit translate my-skill --to copilot --dry-run # 技能推荐 skillkit recommend # 安全扫描 skillkit scan skillkit scan --format json ``` 资料来源：[README.md]() 资料来源：[packages/cli/README.md]() ### TUI 终端界面 提供交互式的终端用户界面，包含以下功能模块： - **Browse（浏览）**：浏览和搜索技能市场 - **Recommend（推荐）**：基于项目技术栈的智能推荐 - **Translate（转换）**：技能格式转换 - **Lineage（溯源）**：查看技能使用历史 - **Context（上下文）**：分析当前项目的技术环境 - **Methodology（方法论）**：管理和应用开发方法论 - **Sync（同步）**：将技能同步到各 Agent 平台 - **Plan（计划）**：执行和管理开发计划 - **Handoff（交接）**：Agent 间的工作交接 资料来源：[packages/tui/src/screens/Browse.tsx]() 资料来源：[packages/tui/src/screens/Recommend.tsx]() 资料来源：[packages/tui/src/screens/Translate.tsx]() ### REST API 服务 SkillKit 提供 REST API 服务，允许其他系统按需获取技能： ```bash skillkit serve # http://localhost:3737 curl "http://localhost:3737/search?q=react+performance" ``` 资料来源：[README.md]() ### MCP 服务器支持 支持通过 Model Context Protocol (MCP) 集成到开发环境： ```json { "mcpServers": { "skillkit": { "command": "npx", "args": ["@skillkit/mcp"] } } } ``` 资料来源：[README.md]() ### Python 客户端 提供 Python SDK 方便集成到现有 Python 项目： ```python from skillkit import SkillKitClient async with SkillKitClient() as client: results = await client.search("react performance", limit=5) ``` 资料来源：[README.md]() ## 项目上下文分析 SkillKit 能够自动分析项目特征，生成详细的技术栈报告： ### 上下文数据类型 ```typescript interface ProjectProfile { name: string; type: 'web-app' | 'api' | 'cli' | 'library' | 'unknown'; stack: { languages: Detection[]; frameworks: Detection[]; libraries: Detection[]; testing: Detection[]; databases: Detection[]; }; } ``` 资料来源：[packages/core/README.md]() ### 检测能力 SkillKit 可以检测项目的以下技术特征： - **编程语言**：检测项目使用的编程语言及其版本 - **框架**：识别前端/后端框架（如 React、Next.js、Django 等） - **库依赖**：分析 package.json、requirements.txt 等依赖文件 - **测试框架**：识别单元测试、集成测试工具 - **数据库**：检测配置的数据库类型 资料来源：[packages/tui/src/screens/Context.tsx]() ## 技能推荐系统 ### 工作流程 ```mermaid graph LR A[项目代码] --> B[上下文分析] B --> C[技术栈检测] C --> D[技能匹配] D --> E[推荐排序] E --> F[技能列表] ``` ### 推荐输出示例 ``` $ skillkit recommend 92% vercel-react-best-practices 87% tailwind-v4-patterns 85% nextjs-app-router 81% shadcn-ui-components ``` 推荐系统会为每个技能计算匹配度分数，优先推荐与当前项目技术栈高度匹配的内容。 资料来源：[README.md]() ## 团队协作功能 ### Bundle 管理 ```bash skillkit team bundle-create # 创建 Bundle skillkit team bundle-export # 导出 Bundle skillkit team bundle-list # 列出所有 Bundle ``` Bundle 允许团队将一组相关技能打包分发，便于统一管理和版本控制。 资料来源：[packages/cli/README.md]() ### 插件系统 ```bash skillkit plugin list # 列出已安装插件 skillkit plugin install # 安装插件 skillkit plugin uninstall # 卸载插件 skillkit plugin enable # 启用插件 skillkit plugin disable # 禁用插件 ``` 资料来源：[packages/cli/README.md]() ### 钩子与自动化 ```bash skillkit hook list # 列出注册的钩子 skillkit hook register # 注册新钩子 skillkit hook trigger # 手动触发钩子 ``` 资料来源：[packages/cli/README.md]() ## 扩展能力 ### 方法论管理 ```bash skillkit methodology list # 列出方法论 skillkit methodology load # 加载方法论 skillkit methodology apply # 应用到项目 ``` 内置多种开发方法论模板，包括任务分解、技术选型指南等最佳实践。 资料来源：[packages/cli/README.md]() 资料来源：[packages/core/src/methodology/packs/planning/task-decomposition/SKILL.md]() ### 计划执行 ```bash skillkit plan parse # 解析计划文件 skillkit plan validate # 验证计划 skillkit plan execute # 执行计划 skillkit plan status # 查看执行状态 ``` 资料来源：[packages/cli/README.md]() ### 安全扫描 ```bash skillkit scan # 扫描技能漏洞 skillkit scan --format json # JSON 格式输出 ``` 资料来源：[packages/cli/README.md]() ## 安装与快速开始 ### 环境要求 - Node.js 18.0 或更高版本 - npm 或 yarn 包管理器 ### 安装方式 ```bash # 通过 npm 全局安装 npm install -g @skillkit/cli # 或使用 npx 直接运行 npx @skillkit/cli ``` ### 基本使用流程 1. **初始化项目**：在项目目录中运行 `skillkit` 启动 TUI 2. **分析技术栈**：使用 `skillkit analyze` 检测项目环境 3. **获取推荐**：`skillkit recommend` 查看推荐技能列表 4. **安装技能**：选择并安装需要的技能 5. **同步到 Agent**：使用 `skillkit sync` 同步到目标平台 ## 许可证 SkillKit 采用 Apache-2.0 开源许可证，允许自由使用、修改和分发。 资料来源：[README.md]() 资料来源：[packages/agents/README.md]() --- ## 安装指南 ### 相关页面 相关主题：[项目介绍](#project-overview), [快速入门](#quick-start-guide)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/rohitg00/skillkit/blob/main/README.md) - [packages/core/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/core/README.md) - [packages/agents/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/agents/README.md) - [packages/cli/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/cli/README.md) - [apps/skillkit/README.md](https://github.com/rohitg00/skillkit/blob/main/apps/skillkit/README.md)
# 安装指南 SkillKit 是一个跨平台 AI 技能管理系统，支持多种安装方式以满足不同用户的需求。本指南涵盖从快速启动到完整源码部署的全部安装方案。 ## 系统要求 SkillKit 对运行环境有以下基本要求： | 要求项 | 最低版本 | 推荐版本 | |--------|----------|----------| | Node.js | 18.0.0 | 20.x LTS | | npm | 8.0.0 | 10.x | | Git | 2.30.0 | 最新版本 | | 操作系统 | macOS/Linux/Windows (WSL2) | - | ## 安装方式 ### 方式一：全局安装（推荐） 使用 npm 全局安装 SkillKit CLI 工具，这是最便捷的生产环境使用方式： ```bash npm install -g skillkit ``` 安装完成后，直接在终端运行 `skillkit` 命令即可： ```bash skillkit --help ``` 资料来源：[README.md:1]() ### 方式二：使用 npx 免安装运行 如果仅需临时使用或进行快速演示，可以通过 npx 直接运行而无需全局安装： ```bash npx skillkit ``` npx 会自动下载并执行指定版本的 SkillKit，每次运行时会检查更新。 资料来源：[README.md:1]() ### 方式三：Docker 部署 对于需要隔离环境的场景，SkillKit 支持通过 Docker 运行： ```bash docker pull skillkit/skillkit:latest docker run -it skillkit/skillkit ``` Docker 方式特别适合团队标准化环境配置和 CI/CD 集成场景。 ### 方式四：源码编译安装 适用于需要自定义功能或参与项目开发的用户。 #### 克隆仓库 ```bash git clone https://github.com/rohitg00/skillkit.git cd skillkit ``` #### 安装依赖 SkillKit 采用 monorepo 结构，主目录下使用 npm workspaces 管理多个子包： ```bash npm install ``` 此命令会自动安装所有子包的依赖，包括核心包、CLI 包、TUI 包等。 #### 编译构建 ```bash npm run build ``` 构建过程会生成各包的发布产物，包括： - `packages/core` - 核心功能库 - `packages/cli` - 命令行工具 - `packages/tui` - 终端用户界面 - `packages/api` - REST API 服务 - `packages/mesh` - 服务网格模块 - `packages/messaging` - 消息传递模块 资料来源：[package.json](https://github.com/rohitg00/skillkit/blob/main/package.json) ## 项目架构概览 SkillKit 的整体架构设计如下： ```mermaid graph TD A[用户终端] --> B[CLI 工具
skillkit 命令] A --> C[TUI 界面
交互式终端] A --> D[REST API
skillkit serve] B --> E[核心模块
packages/core] C --> E D --> E E --> F[技能存储] E --> G[翻译引擎] E --> H[推荐系统] F --> I[本地文件系统] F --> J[远程仓库] F --> K[团队 Bundle] L[Agent 集成] --> M[Claude
Cursor
Windsurf
Copilot] ``` ## 包结构说明 SkillKit 采用 monorepo 架构，主要包的功能如下： | 包名 | 功能描述 | 主要导出 | |------|----------|----------| | `@skillkit/core` | 核心功能，包含技能解析、翻译、推荐等核心算法 | `SkillKit`, `SkillTranslator` | | `@skillkit/cli` | 命令行工具，提供所有 `skillkit` 子命令 | CLI 可执行文件 | | `@skillkit/tui` | 终端用户界面，交互式操作界面 | 独立的 TUI 应用 | | `@skillkit/api` | REST API 服务，支持 HTTP 接口访问 | Express 服务 | | `@skillkit/mesh` | 服务网格模块，支持微服务架构集成 | 连接器和适配器 | | `@skillkit/messaging` | 消息传递系统，支持事件驱动通信 | 消息队列接口 | | `@skillkit/mcp` | MCP 协议集成，支持模型上下文协议 | MCP 服务器 | 资料来源：[packages/core/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/core/README.md) ## 验证安装 安装完成后，可通过以下方式验证： ### 检查 CLI 版本 ```bash skillkit --version ``` ### 查看可用命令 ```bash skillkit --help ``` 输出应包含以下主要功能模块： ```bash skillkit add # 添加技能 skillkit translate # 翻译技能格式 skillkit recommend # 智能推荐 skillkit serve # 启动 API 服务 skillkit team # 团队协作 skillkit plugin # 插件管理 skillkit methodology # 方法论加载 skillkit plan # 计划执行 skillkit hook # 自动化钩子 skillkit scan # 安全扫描 ``` 资料来源：[packages/cli/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/cli/README.md) ## 快速开始 安装完成后，按以下步骤创建第一个技能： ### 初始化项目 ```bash skillkit init ``` ### 添加技能 ```bash skillkit add ``` 支持的来源格式： ```bash skillkit add claude:username/skill # Claude skillkit add cursor:owner/skill # Cursor skillkit add windsurf:repo/skills # Windsurf skillkit add github:owner/repo # GitHub skillkit add gitlab:team/skills # GitLab skillkit add ./my-local-skills # 本地路径 skillkit add https://gist.github.com/... # Gist ``` 资料来源：[README.md:1]() ### 启动交互界面 ```bash skillkit tui ``` ### 启动 API 服务 ```bash skillkit serve # 服务地址: http://localhost:3737 ``` ## 团队安装配置 对于团队环境，建议通过配置文件统一管理： ```bash skillkit team init --name "Engineering Team" skillkit team sync ``` 配置文件 `.skillkit.json` 可放在项目根目录，确保团队成员使用一致的技能配置。 ## 环境变量配置 SkillKit 支持以下环境变量自定义行为： | 变量名 | 默认值 | 说明 | |--------|--------|------| | `SKILLKIT_DIR` | `~/.skillkit` | 技能存储目录 | | `SKILLKIT_API_PORT` | `3737` | API 服务端口 | | `SKILLKIT_LOG_LEVEL` | `info` | 日志级别 | | `SKILLKIT_CACHE_TTL` | `3600` | 缓存生存时间（秒） | ## 常见问题 ### 全局安装后命令不可用 确保 npm 全局 bin 目录在系统 PATH 中： ```bash npm config get prefix ``` 如果路径不在 PATH 中，添加到 shell 配置文件（`.bashrc`、`.zshrc` 等）： ```bash export PATH="$(npm config get prefix)/bin:$PATH" ``` ### 权限错误（EACCES） Linux/macOS 上如遇权限问题，避免使用 sudo： ```bash mkdir ~/.npm-global npm config set prefix '~/.npm-global' export PATH=~/.npm-global/bin:$PATH ``` ### 源码安装构建失败 确保 Node.js 版本符合要求，并清理缓存后重试： ```bash rm -rf node_modules package-lock.json npm cache clean --force npm install npm run build ``` ## 下一步 安装完成后，建议继续阅读以下文档： - [用户指南](https://github.com/rohitg00/skillkit#readme) - 完整功能说明 - [技能格式规范](https://github.com/rohitg00/skillkit/blob/main/packages/agents/README.md) - SKILL.md、MDC 格式说明 - [API 参考](https://github.com/rohitg00/skillkit/blob/main/apps/skillkit/README.md) - REST API 端点说明 - [插件开发](https://github.com/rohitg00/skillkit/blob/main/packages/cli/README.md) - 扩展 SkillKit 功能 --- ## 快速入门 ### 相关页面 相关主题：[技能管理](#skill-management)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/rohitg00/skillkit/blob/main/README.md) - [packages/agents/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/agents/README.md) - [packages/core/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/core/README.md) - [packages/cli/src/commands/init.ts](https://github.com/rohitg00/skillkit/blob/main/packages/cli/src/commands/init.ts) - [packages/cli/src/commands/add.ts](https://github.com/rohitg00/skillkit/blob/main/packages/cli/src/commands/add.ts) - [packages/cli/src/commands/recommend.ts](https://github.com/rohitg00/skillkit/blob/main/packages/cli/src/commands/recommend.ts) - [packages/cli/src/commands/sync.ts](https://github.com/rohitg00/skillkit/blob/main/packages/cli/src/commands/sync.ts)
# 快速入门 本文档将帮助你快速上手 SkillKit，了解如何安装、配置以及使用核心功能来管理 AI Agent 技能。 ## 什么是 SkillKit SkillKit 是一个用于统一管理和分发 AI Agent 技能（Skills）的命令行工具。它允许开发者： - 为多个 AI Agent 平台（如 Cursor、Windsurf、Claude Code 等）编写一次技能 - 自动将技能转换为不同 Agent 支持的格式 - 订阅社区技能市场并同步到本地 - 根据项目技术栈获取智能推荐 ![SkillKit 工作流程](https://img.shields.io/badge/workflow-添加--翻译--同步--使用-bule) ## 系统要求 | 要求 | 最低版本 | |------|----------| | Node.js | 18.0.0 | | npm/pnpm | 最新版本 | | 操作系统 | macOS、Linux、Windows | ## 安装 通过 npm 全局安装 SkillKit CLI： ```bash npm install -g @skillkit/cli ``` 或使用 pnpm： ```bash pnpm add -g @skillkit/cli ``` 安装完成后，验证安装： ```bash skillkit --version ``` ## 初始化项目 在项目根目录运行初始化命令，创建 `.skillkit` 配置文件： ```bash skillkit init ``` 初始化过程会： 1. 创建 `.skillkit` 目录 2. 生成 `skillkit.yaml` 配置文件 3. 检测项目技术栈（语言、框架、库） 4. 配置支持的 AI Agent 资料来源：[README.md](https://github.com/rohitg00/skillkit/blob/main/README.md) ### 初始化配置 初始化后生成的 `skillkit.yaml` 结构如下： ```yaml agents: - cursor - windsurf - claude - copilot stack: languages: [] frameworks: [] libraries: [] skills: [] ``` ## 核心命令 ### 添加技能 使用 `add` 命令添加本地技能或远程技能源： ```bash # 添加 GitHub 仓库 skillkit add github:username/skills # 添加 GitLab 仓库 skillkit add gitlab:team/skills # 添加本地路径 skillkit add ./my-local-skills # 添加 Gist skillkit add https://gist.github.com/... ``` 资料来源：[README.md](https://github.com/rohitg00/skillkit/blob/main/README.md) ### 智能推荐 根据项目技术栈获取推荐技能： ```bash skillkit recommend ``` 输出示例： ``` 92% vercel-react-best-practices 87% tailwind-v4-patterns 85% nextjs-app-router 81% shadcn-ui-components ``` 推荐系统会分析项目中的： - 编程语言 - 前端框架 - UI 库 - 测试框架 - 数据库 资料来源：[packages/cli/src/commands/recommend.ts](https://github.com/rohitg00/skillkit/blob/main/packages/cli/src/commands/recommend.ts) ### 同步技能 将技能同步到指定的 AI Agent： ```bash # 同步所有技能 skillkit sync # 同步到指定 Agent skillkit sync --to cursor # 同步指定技能 skillkit sync my-skill --to windsurf ``` 资料来源：[packages/cli/src/commands/sync.ts](https://github.com/rohitg00/skillkit/blob/main/packages/cli/src/commands/sync.ts) ### 格式转换 SkillKit 支持将技能转换为不同 Agent 专用的格式： ```bash # 转换单个技能 skillkit translate my-skill --to cursor # 转换所有技能 skillkit translate --all --to windsurf,codex # 预览转换结果 skillkit translate my-skill --to copilot --dry-run ``` ## 技能格式 ### SKILL.md 格式 大多数 Agent 使用的标准格式，采用 YAML frontmatter + Markdown 内容： ```markdown --- name: my-skill description: 技能描述 --- # My Skill Instructions... ``` ### MDC 格式 (Cursor) Cursor 专用的格式，支持 glob 模式和 alwaysApply 字段： ```markdown --- description: 技能描述 globs: ["**/*.tsx"] alwaysApply: false --- Instructions... ``` ### Markdown 格式 用于 Windsurf 和 Copilot 的纯 Markdown 格式： ```markdown # Skill Name Instructions for the agent... ``` 资料来源：[packages/agents/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/agents/README.md) ## 支持的 AI Agent SkillKit 支持以下 AI Agent 平台： | Agent | 格式支持 | 状态 | |-------|----------|------| | Claude | SKILL.md | 完整支持 | | Cursor | MDC | 完整支持 | | Windsurf | Markdown | 完整支持 | | Copilot | Markdown | 完整支持 | | Augment Code | SKILL.md | 完整支持 | | Bolt | SKILL.md | 完整支持 | | Lovable | SKILL.md | 完整支持 | | Replit Agent | SKILL.md | 完整支持 | | Sourcegraph Cody | SKILL.md | 完整支持 | | Tabby | SKILL.md | 完整支持 | | Tabnine | SKILL.md | 完整支持 | | Universal | SKILL.md | 完整支持 | 资料来源：[packages/agents/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/agents/README.md) ## 工作流程图 ```mermaid graph TD A[开始] --> B[安装 SkillKit] B --> C[初始化项目 skillkit init] C --> D[添加技能 skillkit add] D --> E[推荐技能 skillkit recommend] E --> F[同步到 Agent skillkit sync] F --> G[在 Agent 中使用技能] ``` ## 进阶功能 ### 运行本地服务 启动 SkillKit REST API 服务，让 Agent 按需获取技能： ```bash skillkit serve # http://localhost:3737 curl "http://localhost:3737/search?q=react+performance" ``` ### MCP 集成 将 SkillKit 集成到支持 MCP 的编辑器中： ```json { "mcpServers": { "skillkit": { "command": "npx", "args": ["@skillkit/mcp"] } } } ``` ### Python 客户端 使用 Python SDK 与 SkillKit 服务交互： ```python from skillkit import SkillKitClient async with SkillKitClient() as client: results = await client.search("react performance", limit=5) ``` 资料来源：[README.md](https://github.com/rohitg00/skillkit/blob/main/README.md) ## 常见问题 ### 初始化失败怎么办？ 确保： - 当前目录是 Git 仓库根目录 - 有写入 `.skillkit` 目录的权限 - Node.js 版本 >= 18.0.0 ### 如何查看已配置的 Agent？ ```bash skillkit config --list ``` ### 技能同步失败？ 检查： 1. Agent 是否已安装 2. Agent 的技能目录路径是否正确 3. 技能格式是否与目标 Agent 兼容 ## 下一步 - 查看[完整文档](https://github.com/rohitg00/skillkit) - 浏览 [packages/core](https://github.com/rohitg00/skillkit/blob/main/packages/core/README.md) 了解核心 API - 探索[示例技能库](https://github.com/rohitg00/skillkit/tree/main/packages/core/src/methodology/packs) --- ## 包结构与依赖关系 ### 相关页面 相关主题：[核心模块解析](#core-modules), [项目介绍](#project-overview)
相关源码文件 以下源码文件用于生成本页说明： - [pnpm-workspace.yaml](https://github.com/rohitg00/skillkit/blob/main/pnpm-workspace.yaml) - [turbo.json](https://github.com/rohitg00/skillkit/blob/main/turbo.json) - [packages/core/src/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/index.ts) - [packages/cli/src/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/cli/src/index.ts) - [packages/agents/src/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/agents/src/index.ts) - [packages/tui/src/screens/Methodology.tsx](https://github.com/rohitg00/skillkit/blob/main/packages/tui/src/screens/Methodology.tsx) - [packages/core/src/primer/generator.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/primer/generator.ts)
# 包结构与依赖关系 ## 项目概述 SkillKit 是一个基于 pnpm monorepo 架构的多包项目，采用 pnpm workspaces 和 Turborepo 进行包管理和构建优化。项目设计围绕 AI 代理技能系统展开，提供了核心库、命令行工具、TUI 界面和浏览器扩展等多元化终端。 资料来源：[pnpm-workspace.yaml](https://github.com/rohitg00/skillkit/blob/main/pnpm-workspace.yaml) ## Monorepo 架构 SkillKit 采用标准的 pnpm monorepo 结构，所有子包位于 `packages` 目录下，应用位于 `apps` 目录下。这种结构允许共享依赖、提升构建效率，并确保各模块间的版本一致性。 资料来源：[pnpm-workspace.yaml](https://github.com/rohitg00/skillkit/blob/main/pnpm-workspace.yaml) ## 包目录结构 ``` skillkit/ ├── packages/ # 核心包集合 │ ├── core/ # 核心业务逻辑库 │ ├── cli/ # 命令行工具 │ ├── agents/ # AI 代理集成包 │ ├── tui/ # 终端用户界面 │ └── extension/ # 浏览器扩展 ├── apps/ # 独立应用 │ └── skillkit/ # 主应用程序 ├── pnpm-workspace.yaml # 工作空间配置 └── turbo.json # 构建流水线配置 ``` ## 核心包详解 ### Core 包 (packages/core) Core 包是整个项目的基础，包含了技能系统的核心业务逻辑、翻译引擎、上下文分析等关键功能。 ```mermaid graph TD A[Core 包] --> B[ai/] A --> C[skill-translator.ts] A --> D[methodology/] A --> E[primer/] B --> B1[providers/] B --> B2[wizard/] B --> B3[recommend/] C --> C1[SKILL.md 解析] C --> C2[MDC 转换] C --> C3[Agent Format] D --> D1[Packs 系统] D --> D2[Task 模板] E --> E1[ProjectAnalysis] E --> E2[ContextGenerator] ``` **主要子模块功能说明：** | 模块路径 | 功能描述 | 关键文件 | |---------|---------|----------| | `ai/providers/` | AI 能力提供者抽象 | mock.ts 等 | | `ai/wizard/` | 技能创建向导系统 | types.ts, 状态管理 | | `methodology/` | 开发方法论与任务分解 | packs/, task-decomposition/ | | `primer/` | 项目上下文生成器 | generator.ts | | `skill-translator/` | 技能格式翻译引擎 | 多格式转换支持 | 资料来源：[packages/core/src/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/index.ts) ### CLI 包 (packages/cli) CLI 包封装了 SkillKit 的命令行交互能力，提供技能安装、翻译、同步、团队协作等功能入口。 ```mermaid graph LR subgraph CLI 功能模块 A[skillkit install] --> B[core] C[skillkit translate] --> B D[skillkit sync] --> B E[skillkit team] --> B end B --> F[core 包 API] ``` **核心命令分类：** | 命令类别 | 子命令 | 功能说明 | |---------|-------|----------| | 基础操作 | `install`, `sync`, `list` | 技能生命周期管理 | | 翻译功能 | `translate --to ` | 技能格式转换 | | 团队协作 | `bundle-*`, `team share` | 团队技能包管理 | | 插件系统 | `plugin list/install` | 插件扩展管理 | | 方法论 | `methodology list/apply` | 开发方法论应用 | 资料来源：[packages/cli/src/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/cli/src/index.ts) ### Agents 包 (packages/agents) Agents 包定义了与各种 AI 代理（Claude Code、Cursor、Copilot 等）的集成规范和格式转换逻辑。 ```mermaid graph TD A[Agents 包] --> B[SKILL.md 格式] A --> C[MDC 格式] A --> D[Markdown 格式] A --> E[通用 YAML 格式] B --> B1[Claude Code] B --> B2[Codex] B --> B3[Gemini CLI] D --> D1[Windsurf] D --> D2[Copilot] E --> E1[通用适配] ``` **支持的代理格式映射：** | 代理名称 | 格式类型 | 配置特征 | |---------|---------|----------| | Claude Code | SKILL.md | YAML frontmatter + Markdown | | Cursor | MDC | globs + alwaysApply | | Windsurf | Markdown | 纯 Markdown 指令 | | GitHub Copilot | Markdown | 纯 Markdown 指令 | | Replit Agent | SKILL.md | YAML frontmatter + Markdown | 资料来源：[packages/agents/src/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/agents/src/index.ts) ### TUI 包 (packages/tui) TUI 包提供了 SkillKit 的终端用户界面，使用 Ink（React for CLI）构建，支持交互式浏览、安装和管理技能。 ```mermaid graph TD A[TUI 界面] --> B[Browse 屏幕] A --> C[Marketplace 屏幕] A --> D[Methodology 屏幕] A --> E[Translate 屏幕] A --> F[Recommend 屏幕] A --> G[Lineage 屏幕] A --> H[Handoff 屏幕] A --> I[Context 屏幕] B --> B1[技能市场浏览] C --> C1[分类树视图] D --> D1[方法论包安装] E --> E1[格式翻译] F --> F1[智能推荐] ``` **屏幕组件映射表：** | 屏幕组件 | 文件位置 | 功能描述 | |---------|---------|----------| | Browse | screens/Browse.tsx | 浏览远程技能仓库 | | Marketplace | screens/Marketplace.tsx | 技能分类与树形展示 | | Methodology | screens/Methodology.tsx | 方法论包管理与安装 | | Translate | screens/Translate.tsx | 技能格式翻译预览 | | Recommend | screens/Recommend.tsx | 基于项目的技能推荐 | | Lineage | screens/Lineage.tsx | 技能使用历史追踪 | | Handoff | screens/Handoff.tsx | 任务交接与状态展示 | | Context | screens/Context.tsx | 项目上下文信息展示 | 资料来源：[packages/tui/src/screens/Methodology.tsx](https://github.com/rohitg00/skillkit/blob/main/packages/tui/src/screens/Methodology.tsx) ### Extension 包 (packages/extension) Extension 包提供了浏览器扩展能力，支持用户在浏览器中直接浏览和管理技能。 ## 依赖关系图 ```mermaid graph TD CLI[packages/cli] --> CORE[packages/core] TUI[packages/tui] --> CORE AGENTS[packages/agents] --> CORE EXTENSION[packages/extension] --> CORE APP[apps/skillkit] --> CLI APP --> TUI CLI --> AGENTS TUI --> AGENTS style CORE fill:#e1f5fe style CLI fill:#fff3e0 style TUI fill:#e8f5e9 ``` ## 包间依赖规范 ### 核心依赖原则 1. **单向依赖**：上层包可依赖下层包，禁止反向依赖 2. **共享核心**：所有功能性包都应依赖 `packages/core` 3. **接口稳定**：`packages/core` 导出稳定公开 API ### 依赖层级说明 | 层级 | 包名 | 说明 | |-----|------|-----| | 基础设施层 | packages/core | 核心业务逻辑与类型定义 | | 功能封装层 | packages/agents, packages/cli | 特定功能的封装 | | 表现层 | packages/tui, packages/extension | 用户交互界面 | | 应用层 | apps/skillkit | 组合各模块的完整应用 | ## Turborepo 构建配置 Turborepo 负责管理构建任务的依赖关系和增量构建优化。 ```json // turbo.json 核心配置结构 { "pipeline": { "build": { "dependsOn": ["^build"], "outputs": ["dist/**", ".next/**"] }, "test": { "dependsOn": ["build"], "outputs": ["coverage/**"] }, "lint": { "outputs": [] } } } ``` **构建任务说明：** | 任务名称 | 依赖任务 | 输出目录 | 说明 | |---------|---------|---------|------| | build | ^build | dist/, .next/ | 增量构建 | | test | build | coverage/ | 测试与覆盖率 | | lint | - | - | 代码检查 | | dev | - | - | 开发模式 | 资料来源：[turbo.json](https://github.com/rohitg00/skillkit/blob/main/turbo.json) ## pnpm Workspace 配置 ```yaml # pnpm-workspace.yaml packages: - 'packages/*' - 'apps/*' ``` 该配置声明了所有子包和应用的位置，pnpm 将自动管理这些包之间的符号链接和依赖解析。 ## 导出 API 结构 ### Core 包导出 (packages/core/src/index.ts) Core 包通过 index.ts 统一导出以下模块： | 导出类别 | 包含内容 | 使用场景 | |---------|---------|----------| | 技能管理 | Skill, SkillSet | 技能定义与集合操作 | | 翻译引擎 | translateSkill() | 格式转换 | | 项目分析 | ProjectAnalyzer | 上下文分析 | | 方法论 | Methodology, TaskTemplate | 开发流程模板 | | 推荐系统 | recommendSkills() | 智能推荐 | | 向导系统 | WizardState, WizardStep | 引导式创建 | ### Agents 包导出 (packages/agents/src/index.ts) Agents 包定义了代理集成的核心接口： ```typescript // 代理格式配置 interface AgentSkillFormat { name: string; extension: string; hasFrontmatter: boolean; invokeCommand: string; supportsGlobs: boolean; } // 支持的代理列表 const SUPPORTED_AGENTS = ['claude-code', 'cursor', 'copilot', ...] as const; ``` ### CLI 包导出 (packages/cli/src/index.ts) CLI 包通过命令注册系统对外暴露命令行接口： ```typescript // 核心命令注册 export async function cli(args: string[]): Promise; export const installCommand: Command; export const translateCommand: Command; export const syncCommand: Command; export const teamCommand: Command; export const pluginCommand: Command; export const methodologyCommand: Command; ``` ## 版本与发布 各包独立版本管理，通过 pnpm workspace 确保版本同步： ```bash # 查看所有包版本 pnpm list --depth=-1 # 批量更新依赖 pnpm up -r # 发布指定包 pnpm --filter @skillkit/core publish ``` ## 总结 SkillKit 的包结构设计遵循了现代 monorepo 最佳实践，通过清晰的层级划分和单向依赖关系，实现了高度的可维护性和可扩展性。核心业务逻辑集中于 `packages/core`，各类终端（CLI、TUI、Extension）依赖核心库构建独立功能，应用层则组合各模块提供完整解决方案。 --- ## 核心模块解析 ### 相关页面 相关主题：[包结构与依赖关系](#package-structure), [技能管理](#skill-management)
相关源码文件 以下源码文件用于生成本页说明： - [packages/core/src/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/index.ts) - [packages/core/src/agents/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/agents/index.ts) - [packages/core/src/memory/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/memory/index.ts) - [packages/core/src/learning/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/learning/index.ts) - [packages/core/src/eval/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/eval/index.ts) - [packages/core/src/recommend/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/recommend/index.ts)
# 核心模块解析 ## 概述 SkillKit 是一个统一管理 AI Agent 技能的 CLI 工具和运行时框架，旨在解决不同 AI Agent（如 Cursor、Windsurf、Copilot、Claude Code 等）之间技能格式不兼容的问题。通过核心模块的协同工作，SkillKit 实现了技能的创建、转换、推荐、执行和学习闭环。资料来源：[packages/core/README.md:1-20]() ## 核心架构 SkillKit 的核心模块采用分层架构设计，各模块职责明确，通过标准接口进行通信： ```mermaid graph TD A[CLI / TUI 入口] --> B[Core API 层] B --> C1[Agents 模块] B --> C2[Memory 模块] B --> C3[Learning 模块] B --> C4[Eval 模块] B --> C5[Recommend 模块] C1 --> D[技能存储] C2 --> D C3 --> D C4 --> D C5 --> D ``` 资料来源：[packages/core/src/index.ts:1-30]() ## 模块详解 ### 1. Agents 模块 Agents 模块负责管理不同 AI Agent 的技能格式转换和适配工作。 #### 支持的 Agent 类型 | Agent 名称 | 标识符 | 格式类型 | |-----------|--------|---------| | GitHub Copilot | `copilot` | Markdown | | Cursor | `cursor` | MDC | | Windsurf | `windsurf` | Markdown | | Claude Code | `claude` | SKILL.md | | Augment Code | `augment-code` | SKILL.md | | Bolt | `bolt` | SKILL.md | | Lovable | `lovable` | SKILL.md | | Replit Agent | `replit-agent` | SKILL.md | | Sourcegraph Cody | `sourcegraph-cody` | SKILL.md | | Tabby | `tabby` | SKILL.md | | Tabnine | `tabnine` | SKILL.md | | Universal | `universal` | 通用格式 | 资料来源：[packages/agents/README.md:1-15]() #### 技能格式对比 | 格式 | 使用 Agent | 特点 | |------|-----------|------| | SKILL.md | Claude, Bolt, Lovable 等 | YAML frontmatter + Markdown 内容 | | MDC | Cursor | 支持 globs 和 alwaysApply 字段 | | Markdown | Windsurf, Copilot | 纯文本指令格式 | 资料来源：[packages/core/src/agents/index.ts:1-50]() ### 2. Memory 模块 Memory 模块负责技能的持久化存储和检索管理。 #### 核心功能 - 技能元数据存储 - 版本历史追踪 - 技能依赖关系图谱 - 全文检索索引 资料来源：[packages/core/src/memory/index.ts:1-40]() ### 3. Learning 模块 Learning 模块实现技能的增量学习和优化机制。 ```mermaid graph LR A[技能执行] --> B[结果收集] B --> C[模式分析] C --> D[规则提取] D --> E[技能优化] E --> A ``` #### 学习策略 | 策略类型 | 触发条件 | 优化方式 | |---------|---------|---------| | 成功率优化 | 执行成功率 < 80% | 简化步骤 | | 性能优化 | 执行时间 > 阈值 | 减少冗余 | | 准确性优化 | 错误率上升 | 增强验证 | 资料来源：[packages/core/src/learning/index.ts:1-60]() ### 4. Eval 模块 Eval 模块提供技能质量评估和兼容性验证功能。 #### 评估指标 | 指标名称 | 说明 | 阈值 | |---------|------|------| | 兼容性 | 与目标 Agent 的格式兼容程度 | ≥ 80% | | 完整性 | 必需字段和内容的完整程度 | ≥ 90% | | 可执行性 | 技能指令的可执行性 | 布尔值 | 资料来源：[packages/core/src/eval/index.ts:1-50]() ### 5. Recommend 模块 Recommend 模块基于项目上下文提供智能技能推荐服务。 #### 推荐算法 ```mermaid graph TD A[项目上下文] --> B[栈检测] B --> C[技能匹配] C --> D[评分排序] D --> E[推荐结果] B --> B1[语言检测] B --> B2[框架检测] B --> B3[库检测] D --> D1[匹配度分数] D --> D2[使用频率] D --> D3[社区评分] ``` #### 上下文类型 ```typescript interface ProjectProfile { name: string; type: 'web-app' | 'api' | 'cli' | 'library' | 'unknown'; stack: { languages: Detection[]; frameworks: Detection[]; libraries: Detection[]; testing: Detection[]; databases: Detection[]; }; } ``` 资料来源：[packages/core/README.md:50-80]() ## 工作流程 ### 技能翻译流程 ```mermaid sequenceDiagram participant User participant CLI participant Agents participant Core User->>CLI: skillkit translate --to CLI->>Core: 加载技能 Core->>Agents: 格式检测 Agents->>Agents: 格式转换 Agents->>Core: 转换结果 Core->>CLI: 输出/写入 CLI->>User: 完成 ``` 资料来源：[packages/cli/README.md:1-30]() ### 技能推荐流程 ```mermaid graph TD A[skillkit recommend] --> B[项目扫描] B --> C[栈分析] C --> D[技能检索] D --> E[评分计算] E --> F[结果排序] F --> G[输出推荐] C --> C1[语言栈] C --> C2[框架栈] C --> C3[依赖库] ``` 资料来源：[apps/skillkit/README.md:1-20]() ## API 接口 ### Python 客户端 ```python from skillkit import SkillKitClient async with SkillKitClient() as client: # 搜索技能 results = await client.search("react performance", limit=5) # 获取推荐 recommendations = await client.recommend() ``` 资料来源：[README.md:40-55]() ### REST API ```bash # 启动服务 skillkit serve # 搜索接口 curl "http://localhost:3737/search?q=react+performance" ``` 资料来源：[README.md:35-40]() ## 数据模型 ### 技能元数据结构 | 字段 | 类型 | 必填 | 说明 | |-----|------|-----|------| | name | string | 是 | 技能名称 | | description | string | 是 | 技能描述 | | format | string | 是 | 格式类型 | | content | string | 是 | 技能内容 | | metadata | object | 否 | 附加元数据 | ### 翻译结果结构 ```typescript interface TranslationResult { content: string; format: string; warnings?: string[]; } ``` 资料来源：[packages/core/README.md:30-45]() ## 模块交互关系 ```mermaid graph LR Agents -->|格式转换| Eval Recommend -->|上下文| Agents Memory -->|存储| Agents Learning -->|优化| Memory Eval -->|评估| Recommend ``` | 源模块 | 目标模块 | 交互内容 | |-------|---------|---------| | Agents | Eval | 转换兼容性验证 | | Recommend | Agents | 技能格式适配 | | Memory | 所有模块 | 数据持久化 | | Learning | Memory | 增量更新 | | Eval | Recommend | 质量评分 | 资料来源：[packages/core/src/index.ts:20-60]() ## 扩展机制 ### MCP 协议支持 ```json { "mcpServers": { "skillkit": { "command": "npx", "args": ["@skillkit/mcp"] } } } ``` 资料来源：[README.md:45-52]() ### 插件系统 | 命令 | 功能 | |-----|------| | `skillkit plugin list` | 列出已安装插件 | | `skillkit plugin install ` | 安装插件 | | `skillkit plugin uninstall ` | 卸载插件 | 资料来源：[packages/cli/README.md:30-45]() ## 最佳实践 ### 技能开发建议 1. **格式选择**：优先使用 SKILL.md 格式以获得最大兼容性 2. **元数据完整**：确保 YAML frontmatter 包含所有必需字段 3. **版本管理**：使用语义化版本号进行版本追踪 4. **测试验证**：使用 `skillkit scan` 进行安全扫描 ### 性能优化 - 技能缓存：合理使用 Memory 模块的缓存机制 - 批量操作：使用 bundle 机制进行批量技能管理 - 增量同步：仅同步变更的技能文件 资料来源：[packages/core/src/learning/index.ts:30-50]() ## 总结 SkillKit 的核心模块通过清晰的职责划分和标准化的接口设计，实现了跨 Agent 的技能统一管理。Agents 模块处理格式转换，Memory 模块提供持久化支持，Learning 模块实现增量优化，Eval 模块保证质量标准，Recommend 模块提供智能推荐。这一架构使得开发者能够“编写一次，部署各处”，显著提升了 AI Agent 技能的开发效率和可移植性。 --- ## 技能管理 ### 相关页面 相关主题：[代理支持](#agent-support), [格式翻译](#translation-format)
相关源码文件 以下源码文件用于生成本页说明： - [packages/agents/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/agents/README.md) - [packages/core/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/core/README.md) - [packages/cli/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/cli/README.md) - [packages/tui/src/screens/Sync.tsx](https://github.com/rohitg00/skillkit/blob/main/packages/tui/src/screens/Sync.tsx) - [packages/tui/src/screens/Browse.tsx](https://github.com/rohitg00/skillkit/blob/main/packages/tui/src/screens/Browse.tsx) - [packages/tui/src/screens/Recommend.tsx](https://github.com/rohitg00/skillkit/blob/main/packages/tui/src/screens/Recommend.tsx) - [registry/README.md](https://github.com/rohitg00/skillkit/blob/main/registry/README.md)
# 技能管理 ## 概述 技能管理（Skill Management）是 SkillKit 项目的核心功能模块，负责技能的发现、安装、同步、翻译和生命周期管理。该系统使开发团队能够跨多个 AI Agent 平台（如 Claude Code、Cursor、Copilot 等）统一管理和分发开发技能（Skills），从而提升团队协作效率和代码一致性。 技能是定义 AI Agent 行为的指令集，通常以 Markdown 格式存储，包含名称、描述、使用说明和示例等内容。SkillKit 通过技能管理系统将这些技能标准化，使其能够在不同 Agent 之间无缝迁移和适配。 ## 技能格式 SkillKit 支持多种技能格式，以适配不同 AI Agent 的需求。系统内部会将技能转换为各平台所需的特定格式。 ### 支持的格式类型 | 格式 | 适配 Agent | 说明 | |------|------------|------| | SKILL.md | Claude Code, Codex, Gemini CLI 等 | 标准 YAML frontmatter + Markdown 内容 | | MDC (.mdc) | Cursor | 包含 globs 和 alwaysApply 字段 | | Markdown | Windsurf, GitHub Copilot | 纯 Markdown 格式 | ### SKILL.md 格式（标准格式） ```markdown --- name: my-skill description: 技能功能描述 --- # My Skill 具体指令内容... ``` 资料来源：[packages/agents/README.md:22-30]() ### MDC 格式（Cursor 专用） ```markdown --- description: 技能功能描述 globs: ["**/*.tsx"] alwaysApply: false --- 指令内容... ``` 资料来源：[packages/agents/README.md:33-40]() ### Markdown 格式（Windsurf/Copilot） ```markdown # Skill Name Instructions for the agent... ``` 资料来源：[packages/agents/README.md:43-46]() ## 技能生命周期 技能从创建到最终使用的完整生命周期包含以下阶段： ```mermaid graph TD A[创建技能] --> B[本地开发测试] B --> C[安装到 SkillKit] C --> D{发布方式} D -->|社区注册| E[提交到 registry] D -->|私有发布| F[团队 bundle] E --> G[技能市场发现] F --> H[团队内部同步] G --> I[安装到项目] H --> I I --> J[翻译为目标格式] J --> K[同步到 Agent] K --> L[Agent 执行技能] ``` ### 创建与开发 技能开发者首先按照标准格式创建 SKILL.md 文件，定义技能的名称、描述和使用指令。开发阶段可以在本地进行测试和迭代。 ### 安装流程 通过 `skillkit install` 命令将技能安装到本地环境： ```bash # 安装社区技能 skillkit install owner/skills --skills=lint,test --yes # 从市场浏览并安装 skillkit browse skillkit install my-skill ``` 资料来源：[packages/cli/README.md:88-93]() ### 同步机制 安装后的技能需要同步到各个 AI Agent。同步过程会根据目标 Agent 的格式要求进行转换： ```bash # 同步已安装的技能到所有可用 Agent skillkit sync --yes # 同步特定 Agent 的技能 skillkit sync --agent cursor ``` 资料来源：[packages/cli/README.md:94-98]() ## 技能市场 技能市场是 SkillKit 提供的技能发现和分发平台，允许用户浏览、搜索和安装社区贡献的技能。 ### 市场功能 | 功能 | 说明 | |------|------| | 浏览 | 按分类查看所有可用技能 | | 搜索 | 通过关键词搜索技能 | | 安装 | 一键安装技能到本地 | | 预览 | 查看技能详情和使用说明 | ### 市场界面（TUI） 在终端用户界面中，市场浏览功能显示技能仓库列表： ```typescript // 显示仓库名称、技能数量和加载状态 {repo.name} {repo.skills.length > 0 ? `${repo.skills.length} skills` : ''} ``` 资料来源：[packages/tui/src/screens/Browse.tsx:35-43]() ### 技能详情 选中技能后可以查看详细信息： ```typescript fields={repoDetailFields()} actions={[ { key: 'Enter', label: 'Install' }, { key: 'Esc', label: 'Close' }, ]} ``` 资料来源：[packages/tui/src/screens/Browse.tsx:56-68]() ## 技能同步管理 同步功能确保已安装的技能以正确格式分发到各个 AI Agent。 ### 同步状态显示 TUI 界面展示每个 Agent 的同步状态： | 符号 | 含义 | |------|------| | ✓ | 已同步 | | ○ | 可用但未同步 | | ✗ | 不可用 | 资料来源：[packages/tui/src/screens/Sync.tsx:30-32]() ### 同步命令 ```bash skillkit sync # 同步所有技能 skillkit sync --agent claude # 同步到特定 Agent skillkit sync --yes # 自动确认 ``` 资料来源：[packages/cli/README.md:94-98]() ### Agent 兼容性 系统支持超过 39 种不同的 AI Agent，包括： - Claude Code - Cursor - Codex - Gemini CLI - Windsurf - GitHub Copilot - 以及其他主流 Agent 资料来源：[packages/cli/README.md:71-80]() ## 智能推荐 技能推荐系统分析项目特征，为开发者提供最相关的技能建议。 ### 推荐算法 系统通过分析项目的以下特征进行推荐： - 编程语言栈 - 框架和库 - 项目结构 - 开发约定 - 测试框架 ### 推荐界面 TUI 中的推荐界面显示技能评分和推荐理由： ```typescript // 显示推荐技能及其评分 Score: ${selectedRec()!.score}% // 显示推荐原因 {rec.reasons[0]} ``` 资料来源：[packages/tui/src/screens/Recommend.tsx:35-41]() ### 推荐命令 ```bash # 获取项目相关的推荐 skillkit recommend # 按任务类型筛选 skillkit recommend --search "authentication" # 设置质量阈值 skillkit recommend --min-score 85 ``` 资料来源：[apps/skillkit/README.md:28-37]() ## 团队协作 ### Bundle 系统 团队可以创建技能包（Bundle）以便共享和分发： ```bash skillkit team bundle-create # 创建新 bundle skillkit team bundle-export # 导出 bundle skillkit team bundle-list # 列出所有 bundle skillkit team share onboarding-bundle # 分享给团队 ``` 资料来源：[packages/cli/README.md:50-55]() ### 团队同步 ```bash # 初始化团队 skillkit team init --name "Engineering Team" # 同步远程注册表 skillkit team sync ``` 资料来源：[apps/skillkit/README.md:40-46]() ## 插件系统 SkillKit 支持通过插件扩展技能管理功能。 ### 插件命令 ```bash skillkit plugin list # 列出已安装插件 skillkit plugin install # 安装插件 skillkit plugin uninstall # 卸载插件 skillkit plugin enable # 启用插件 skillkit plugin disable # 禁用插件 skillkit plugin info # 查看插件详情 ``` 资料来源：[packages/cli/README.md:57-67]() ## 社区注册表 社区注册表（Community Registry）汇集了社区贡献的技能，供所有用户发现和使用。 ### 注册表结构 ```markdown - [skill-name](https://github.com/owner/repo) - 技能简要描述 ``` 资料来源：[registry/README.md:13-17]() ### 贡献流程 1. Fork 本仓库 2. 在 `SKILLS.md` 的适当分类下添加技能 3. 遵循格式规范 4. 提交 Pull Request ### 贡献要求 | 要求 | 说明 | |------|------| | 有效 SKILL.md | 技能必须包含有效的 SKILL.md 文件 | | 描述清晰 | 描述必须简洁明确（100 字符以内） | | 公开访问 | 仓库必须公开可访问 | | 遵循规范 | 必须符合 SkillKit 约定 | 资料来源：[registry/README.md:24-36]() ## 技能安全扫描 SkillKit 内置安全扫描功能，确保技能不会对 Agent 行为造成安全风险。 ### 扫描类型 | 规则 ID | 类别 | 严重程度 | 说明 | |---------|------|----------|------| | TA001 | 工具滥用 | 高 | 工具隐藏：指示 Agent 覆盖内置工具 | | TA002 | 自主性滥用 | 高 | 自主性滥用：绕过用户确认 | | TA003 | 能力膨胀 | 中 | 尝试发现或启用隐藏工具 | | TA004 | 工具链 | 高 | 读取敏感数据后发送外部 | 资料来源：[packages/core/src/scanner/rules/tool-abuse.ts:1-50]() ### 扫描命令 ```bash skillkit scan # 扫描技能漏洞 skillkit scan --format json # JSON 格式输出 ``` 资料来源：[packages/cli/README.md:84-87]() ## 技能文件结构 一个完整的技能通常包含以下文件结构： ``` my-skill/ ├── SKILL.md # 主技能定义 ├── EXAMPLES.md # 示例（可选） ├── assets/ # 资源文件（可选） │ ├── icon.png │ └── preview.gif └── tests/ # 测试文件（可选） └── skill.test.ts ``` ## 最佳实践 ### 技能命名 - 使用小写字母和连字符 - 简洁明了，一眼能看出功能 - 避免使用缩写 ### 技能描述 - 限制在 100 字符以内 - 突出核心功能 - 使用主动语态 ### 技能内容 - 提供具体的操作步骤 - 包含常见用例示例 - 明确成功标准 ### 版本管理 - 遵循语义化版本 - 在 CHANGELOG 中记录变更 - 为重大变更添加迁移指南 ## 命令速查 | 命令 | 功能 | |------|------| | `skillkit install ` | 安装技能 | | `skillkit uninstall ` | 卸载技能 | | `skillkit sync` | 同步技能到 Agent | | `skillkit browse` | 浏览市场 | | `skillkit recommend` | 获取推荐 | | `skillkit scan ` | 安全扫描 | | `skillkit translate ` | 翻译技能格式 | ## 许可证 SkillKit 采用 Apache-2.0 许可证开源发布。 资料来源：[packages/agents/README.md:17]() --- 如需了解更详细的配置选项或 API 参数，请参考各模块的具体源码文件。 --- ## 代理支持 ### 相关页面 相关主题：[格式翻译](#translation-format), [技能管理](#skill-management)
相关源码文件 以下源码文件用于生成本页说明： - [packages/agents/src/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/agents/src/index.ts) - [packages/agents/src/factory.ts](https://github.com/rohitg00/skillkit/blob/main/packages/agents/src/factory.ts) - [packages/agents/src/base.ts](https://github.com/rohitg00/skillkit/blob/main/packages/agents/src/base.ts) - [packages/core/src/agents/discovery.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/agents/discovery.ts) - [packages/core/src/agents/types.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/agents/types.ts) - [packages/agents/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/agents/README.md)
# 代理支持 ## 概述 SkillKit 的代理支持（Agent Support）模块是一个多代理集成框架，旨在实现"一次编写，随处运行"的技能（Skill）管理模式。该模块通过抽象层设计，支持市场上主流的 AI 编程代理，使开发者能够将技能无缝同步到不同的代理环境中。 代理支持模块位于 `packages/agents` 目录下，提供了代理发现、工厂模式实例化、技能格式转换和代理同步等核心功能。通过统一的数据模型和类型定义，实现了不同代理之间的互操作性。 ## 支持的代理列表 SkillKit 目前支持以下 AI 代理，覆盖主流的商业和开源解决方案： | 代理名称 | 类型 | 技能格式 | 同步支持 | |---------|------|---------|---------| | Claude | 商业 | SKILL.md | 完整 | | ChatGPT | 商业 | SKILL.md | 完整 | | Gemini | 商业 | SKILL.md | 完整 | | Copilot | 商业 | Markdown | 完整 | | Cursor | 商业 | MDC | 完整 | | Windsurf | 商业 | Markdown | 完整 | | Roo Jira AQ | 商业 | SKILL.md | 完整 | | Windsurf Pure | 商业 | SKILL.md | 完整 | | Junie | 商业 | SKILL.md | 完整 | | Forge | 商业 | SKILL.md | 完整 | | Bolt | 商业 | SKILL.md | 完整 | | Lovable | 商业 | SKILL.md | 完整 | | Replit Agent | 商业 | SKILL.md | 完整 | | Sourcegraph Cody | 开源 | SKILL.md | 完整 | | Tabby | 开源 | SKILL.md | 完整 | | Tabnine | 商业 | SKILL.md | 完整 | | Universal | 通用 | SKILL.md | 完整 | 资料来源：[packages/agents/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/agents/README.md) ## 代理架构 ### 核心模块结构 ``` packages/agents/ ├── src/ │ ├── index.ts # 导出入口 │ ├── factory.ts # 代理工厂 │ └── base.ts # 基类定义 packages/core/src/agents/ ├── discovery.ts # 代理发现机制 └── types.ts # 类型定义 ``` 代理系统采用分层架构设计： ```mermaid graph TD A[用户请求] --> B[代理工厂 Factory] B --> C{代理类型判断} C -->|Claude| D[ClaudeAgent] C -->|Cursor| E[CursorAgent] C -->|Copilot| F[CopilotAgent] C -->|Windsurf| G[WindsurfAgent] C -->|其他| H[通用代理] D --> I[技能同步器] E --> I F --> I G --> I H --> I I --> J[代理环境] ``` ### 代理基类设计 所有代理实现继承自 `BaseAgent` 基类，该基类定义了代理的标准接口： ```typescript interface AgentAdapter { readonly name: string; readonly supportedFormats: SkillFormat[]; readonly installPath: string | null; install(skill: Skill): Promise; uninstall(skillId: string): Promise; sync(): Promise; list(): Promise; detect(): Promise; } ``` 资料来源：[packages/agents/src/base.ts](https://github.com/rohitg00/skillkit/blob/main/packages/agents/src/base.ts) ## 代理发现机制 ### 自动发现流程 代理发现模块负责检测用户系统中已安装的 AI 代理。当用户首次运行 SkillKit 或执行同步操作时，系统会自动扫描常见安装位置： ```mermaid graph LR A[启动发现] --> B[扫描配置目录] B --> C{代理可执行?} C -->|是| D[标记为已安装] C -->|否| E[尝试常见路径] E --> C D --> F[更新代理状态] E --> F F --> G[返回发现结果] ``` ### 发现配置 发现机制支持以下配置参数： | 参数 | 类型 | 说明 | 默认值 | |-----|------|-----|-------| | scanPaths | string[] | 自定义扫描路径 | 常见代理路径列表 | | cacheResults | boolean | 缓存发现结果 | true | | timeout | number | 扫描超时时间(ms) | 5000 | 资料来源：[packages/core/src/agents/discovery.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/agents/discovery.ts) ## 代理工厂模式 ### 工厂设计 代理工厂（Factory）负责根据代理标识符创建对应的代理实例。这种设计遵循了工厂模式的开闭原则，便于扩展新的代理支持： ```typescript class AgentFactory { private static agents: Map = new Map(); static register(type: AgentType, adapter: AgentAdapter): void { this.agents.set(type, adapter); } static create(type: AgentType): AgentAdapter | null { const adapter = this.agents.get(type); return adapter ? Object.create(adapter) : null; } static getSupportedAgents(): AgentType[] { return Array.from(this.agents.keys()); } } ``` 资料来源：[packages/agents/src/factory.ts](https://github.com/rohitg00/skillkit/blob/main/packages/agents/src/factory.ts) ### 实例化流程 ```mermaid graph TD A[传入代理类型] --> B[工厂查询注册表] B --> C{类型已注册?} C -->|是| D[创建代理实例] C -->|否| E[返回null] D --> F[初始化代理配置] F --> G[返回代理适配器] ``` ## 技能格式兼容性 ### 格式类型 SkillKit 支持三种主要的技能格式，每种格式针对特定的代理优化： #### 1. SKILL.md 格式（通用） 适用于 Claude、ChatGPT、Gemini 等大多数代理。包含 YAML frontmatter 和 Markdown 内容： ```markdown --- name: my-skill description: 技能描述 --- # My Skill 技能说明和指令... ``` #### 2. MDC 格式（Cursor 专用） Cursor 特有的格式，支持 globs 和 alwaysApply 字段： ```markdown --- description: 技能描述 globs: ["**/*.tsx"] alwaysApply: false --- 技能指令... ``` #### 3. Markdown 格式（Windsurf 和 Copilot） 纯 Markdown 格式，用于 Windsurf 和 GitHub Copilot： ```markdown # Skill Name Agent instructions here... ``` 资料来源：[packages/agents/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/agents/README.md) ### 格式转换 在同步技能时，系统会根据目标代理自动转换格式： ```mermaid graph LR A[源技能] --> B{目标代理} B -->|Cursor| C[转换为MDC] B -->|Windsurf| D[转换为Markdown] B -->|Claude| E[保持SKILL.md] C --> F[写入目标目录] D --> F E --> F ``` ## 代理同步机制 ### 同步状态管理 每个代理在同步过程中维护以下状态： | 状态 | 说明 | 显示标识 | |-----|------|---------| | synced | 已同步 | ✓ | | available | 可用但未同步 | ○ | | unavailable | 不可用/未安装 | ✗ | 资料来源：[packages/tui/src/screens/Sync.tsx](https://github.com/rohitg00/skillkit/blob/main/packages/tui/src/screens/Sync.tsx) ### 同步操作 同步功能支持以下操作： - **单个代理同步**：将技能同步到指定的代理 - **批量同步**：将技能同步到所有已安装的代理 - **强制刷新**：重新检测代理并更新同步状态 ```mermaid graph TD A[用户触发同步] --> B{同步范围} B -->|单个| C[选择目标代理] B -->|全部| D[获取已安装代理列表] C --> E[读取技能配置] D --> E E --> F[格式转换] F --> G[写入代理目录] G --> H[更新同步状态] H --> I[返回同步结果] ``` ### TUI 界面展示 在 SkillKit 的 TUI 界面中，代理同步状态通过以下方式呈现： - 代理列表显示当前同步状态 - 已同步代理显示技能数量 - 未安装代理显示 "(unavailable)" 提示 - 同步过程中显示加载指示器 ## 类型系统 ### 核心类型定义 ```typescript type AgentType = | 'claude' | 'chatgpt' | 'gemini' | 'copilot' | 'cursor' | 'windsurf' | 'roo-jira-aq' | 'windsurf-pure' | 'junie' | 'forge' | 'bolt' | 'lovable' | 'replit-agent' | 'sourcegraph-cody' | 'tabby' | 'tabnine' | 'universal'; type SkillFormat = 'skill-md' | 'mdc' | 'markdown'; interface AgentSkill { id: string; name: string; version: string; path: string; installed: boolean; syncedAt?: Date; } ``` 资料来源：[packages/core/src/agents/types.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/agents/types.ts) ### 操作结果类型 ```typescript interface InstallResult { success: boolean; path?: string; error?: string; } interface UninstallResult { success: boolean; error?: string; } interface SyncResult { success: boolean; agent: AgentType; syncedCount: number; failedCount: number; errors?: string[]; } ``` ## 使用示例 ### CLI 命令 通过命令行与代理进行交互： ```bash # 列出所有已安装的代理 skillkit agent list # 将技能同步到特定代理 skillkit sync --to claude,cursor # 同步所有已安装代理 skillkit sync --all # 检查代理状态 skillkit agent status ``` ### API 调用 在代码中使用代理功能： ```typescript import { AgentFactory, createAgent } from '@skillkit/agents'; import { discoverAgents } from '@skillkit/core/agents'; // 发现已安装的代理 const agents = await discoverAgents(); // 创建代理实例 const claude = AgentFactory.create('claude'); // 安装技能 const result = await claude.install(skill); ``` ## 配置管理 ### 代理配置存储 代理配置存储在用户目录下的配置文件中： ``` ~/.skillkit/ ├── agents.json # 代理配置 ├── skills/ # 技能存储 └── cache/ # 缓存目录 ``` ### agents.json 结构 ```json { "installed": ["claude", "cursor", "windsurf"], "syncPath": { "claude": "~/.claude/skills", "cursor": "~/.cursor/skills", "windsurf": "~/.windsurf/skills" }, "lastSync": "2024-01-15T10:30:00Z" } ``` ## 最佳实践 ### 添加新代理支持 如需添加新的代理支持，建议遵循以下步骤： 1. 在 `AgentType` 中添加新的代理类型 2. 创建新的代理适配器类，继承 `BaseAgent` 3. 在工厂中注册新代理 4. 实现格式转换逻辑（如需要） 5. 添加相应的测试用例 ### 技能编写建议 编写跨代理兼容的技能时： - 优先使用 SKILL.md 格式（兼容性最广） - 避免使用代理特定的功能 - 为不同代理提供相同的功能描述 - 测试在多个代理环境中的表现 ## 相关文档 - [技能格式指南](./skill-formats.md) - [CLI 使用手册](./cli-usage.md) - [TUI 界面指南](./tui-guide.md) - [API 参考文档](./api-reference.md) --- ## 格式翻译 ### 相关页面 相关主题：[代理支持](#agent-support), [技能管理](#skill-management)
相关源码文件 以下源码文件用于生成本页说明： - [packages/core/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/core/README.md) - [packages/agents/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/agents/README.md) - [apps/skillkit/README.md](https://github.com/rohitg00/skillkit/blob/main/apps/skillkit/README.md) - [packages/core/src/ai/providers/mock.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/ai/providers/mock.ts) - [packages/core/src/primer/generator.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/primer/generator.ts) - [packages/cli/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/cli/README.md)
# 格式翻译 ## 概述 格式翻译是 SkillKit 的核心功能之一，允许开发者编写一次技能定义，然后将其转换为不同 AI 代理（Agent）所支持的格式。通过格式翻译，SkillKit 实现了"编写一次，部署到多处"的开发体验。 格式翻译系统支持多种主流 AI 代理，包括 Claude Code、Cursor、Codex、Windsurf、GitHub Copilot 等，共计支持超过 39 种代理格式。资料来源：[packages/cli/README.md]() ## 支持的代理与格式 SkillKit 支持三种主要的技能定义格式，每种格式针对特定的代理进行了优化： | 格式类型 | 适用代理 | 文件扩展名 | 特点 | |---------|---------|-----------|------| | SKILL.md | Claude Code、Codex、Gemini CLI 等 | `.md` | YAML 前置元数据 + Markdown 内容 | | MDC | Cursor | `.mdc` | 支持 glob 模式匹配和 alwaysApply 字段 | | Markdown | Windsurf、Copilot | `.md` | 纯 Markdown 格式 | 资料来源：[packages/agents/README.md]() ## SKILL.md 格式 SKILL.md 是 SkillKit 的标准格式，采用 YAML 前置元数据（frontmatter）加上 Markdown 内容的形式： ```markdown --- name: my-skill description: What this skill does --- # My Skill Instructions... ``` 该格式被大多数代理所使用，具有良好的可读性和结构化表达能力。资料来源：[packages/agents/README.md]() ## MDC 格式（Cursor 专用） MDC 格式是 Cursor 代理特有的格式，支持更高级的配置选项： ```markdown --- description: What this skill does globs: ["**/*.tsx"] alwaysApply: false --- Instructions... ``` 与 SKILL.md 相比，MDC 格式增加了 `globs` 字段用于文件匹配，以及 `alwaysApply` 字段控制技能的应用范围。资料来源：[packages/agents/README.md]() ## 纯 Markdown 格式 部分代理（如 Windsurf 和 GitHub Copilot）使用纯 Markdown 格式，不包含前置元数据： ```markdown # Skill Name Instructions for the agent... ``` 这种格式简单直接，适合不需要复杂配置的技能定义场景。资料来源：[packages/agents/README.md]() ## 翻译工作流程 格式翻译的典型工作流程如下： ```mermaid graph TD A[编写 SKILL.md 技能] --> B[执行 translate 命令] B --> C{目标代理格式} C -->|Cursor| D[转换为 MDC 格式] C -->|Windsurf/Copilot| E[转换为纯 Markdown] C -->|Claude Code| F[保持 SKILL.md] D --> G[生成 .mdc 文件] E --> H[生成 .md 文件] F --> I[输出到目标目录] G --> I H --> I ``` ## 命令行使用方式 ### 基本翻译命令 使用 CLI 进行技能格式翻译是最常见的使用方式： ```bash # 翻译单个技能到指定格式 skillkit translate my-skill --to cursor # 翻译单个技能到多个格式 skillkit translate my-skill --to windsurf,codex # 预览翻译结果（不写入文件） skillkit translate my-skill --to copilot --dry-run # 翻译所有技能 skillkit translate --all --to windsurf,codex ``` 资料来源：[apps/skillkit/README.md]() ### 预览翻译 翻译预览功能允许在提交变更之前检查翻译结果的兼容性： ```bash skillkit translate my-skill --to copilot --dry-run ``` 预览模式会显示目标格式的兼容性问题，帮助用户在应用变更前进行修正。资料来源：[apps/skillkit/README.md]() ## TUI 交互界面 SkillKit 提供了终端用户界面（TUI）进行可视化翻译操作： ### 翻译屏幕组件 翻译界面 (`Translate.tsx`) 提供了交互式的翻译体验，支持选择源技能和目标代理格式。界面会显示： - 可用的代理列表及其兼容状态 - 技能信息（名称、路径等） - 翻译进度指示器 - 预览窗口显示翻译结果 资料来源：[packages/tui/src/screens/Translate.tsx]() ### 预览功能 TUI 中的预览功能提供了翻译结果的实时预览，包括： | 状态 | 含义 | 显示样式 | |-----|------|---------| | 兼容 (Compatible) | 翻译成功，无问题 | ✓ 绿色 | | 有问题 (Has issues) | 存在兼容性问题 | ⚠ 黄色 | 预览界面最多显示 2 个主要问题，便于用户快速了解翻译质量。资料来源：[packages/tui/src/screens/Translate.tsx]() ## 格式检测与自动识别 SkillKit 能够自动检测技能文件的格式类型，识别逻辑包括： 1. **文件扩展名检测**：`.mdc` 文件自动识别为 Cursor MDC 格式 2. **前置元数据解析**：检查 YAML frontmatter 的存在和结构 3. **字段识别**：根据特定的字段（如 `globs`、`alwaysApply`）判断是否为 MDC 格式 ```mermaid graph TD A[读取技能文件] --> B{文件扩展名} B -->|.mdc| C[识别为 MDC 格式] B -->|.md| D{检查前置元数据} D -->|存在 globs| C D -->|存在 YAML| E[识别为 SKILL.md] D -->|无元数据| F[识别为纯 Markdown] ``` ## 格式转换器架构 格式翻译系统采用了模块化的转换器架构，每个目标格式都有对应的转换器实现： ### 核心转换器 | 转换器 | 功能 | 输出格式 | |-------|------|---------| | `skill-md.ts` | SKILL.md 格式处理 | 标准 YAML + Markdown | | `cursor.ts` | Cursor MDC 格式处理 | MDC 格式（含 globs） | | `markdown.ts` | 纯 Markdown 处理 | 无元数据格式 | ### 渲染器系统 转换系统使用渲染器接口来生成不同格式的输出： ```typescript interface FormatRenderer { h1: (text) => string; h2: (text) => string; h3: (text) => string; bold: (text) => string; code: (text) => string; codeBlock: (code, lang?) => string; list: (items) => string; keyValue: (key, value) => string; paragraph: (text) => string; separator: () => string; wrap: (content, metadata?) => string; } ``` 不同格式的渲染器实现会生成符合目标代理规范的输出内容。资料来源：[packages/core/src/primer/generator.ts]() ## 注册表机制 翻译系统使用注册表（Registry）模式管理支持的格式和转换器： ```mermaid graph LR A[注册表] --> B[格式 A 转换器] A --> C[格式 B 转换器] A --> D[格式 C 转换器] E[翻译请求] --> A A --> F[匹配转换器] F --> G[执行转换] ``` 注册表机制允许动态注册新的格式转换器，便于扩展支持更多代理格式。资料来源：[packages/core/src/translator/registry.ts]() ## 编程接口 ### Node.js API 开发者可以通过编程方式使用翻译功能： ```typescript import { translateCommand } from '@skillkit/cli'; // 翻译技能 await translateCommand('my-skill', { to: 'cursor', dryRun: false, }); ``` ### 返回值结构 翻译操作返回包含以下信息的对象： | 字段 | 类型 | 描述 | |-----|------|------| | `content` | string | 翻译后的内容 | | `format` | string | 目标格式类型 | | `warnings` | string[] | 警告信息列表 | 资料来源：[packages/core/README.md]() ## 最佳实践 ### 格式选择建议 | 使用场景 | 推荐格式 | |---------|---------| | 多代理通用技能 | SKILL.md | | 仅 Cursor 使用 | MDC | | Windsurf/Copilot 专用 | Markdown | | 复杂文件匹配需求 | MDC | ### 翻译注意事项 1. **兼容性检查**：翻译前使用 `--dry-run` 预览结果 2. **格式特性保留**：注意 MDC 格式的 `globs` 字段在转换为其他格式时会被忽略 3. **内容验证**：翻译后检查目标格式是否符合预期 ## 与 MCP 的集成 格式翻译功能可以通过 MCP（Model Context Protocol）远程调用： ```json { "mcpServers": { "skillkit": { "command": "npx", "args": ["@skillkit/mcp"] } } } ``` MCP 集成允许远程 AI 代理动态获取和翻译技能定义。资料来源：[README.md]() ## 总结 格式翻译是 SkillKit 实现跨代理兼容性的关键技术，通过统一的技能定义格式和灵活的转换机制，开发者可以专注于技能内容的编写，而将格式适配工作交给 SkillKit 自动完成。该系统支持超过 39 种 AI 代理格式，采用模块化的架构设计，便于扩展新的格式支持。 --- ## AI 集成 ### 相关页面 相关主题：[推荐引擎](#recommendation-engine)
相关源码文件 以下源码文件用于生成本页说明： - [packages/core/src/ai/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/ai/index.ts) - [packages/core/src/ai/providers/index.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/ai/providers/index.ts) - [packages/core/src/ai/providers/factory.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/ai/providers/factory.ts) - [packages/core/src/ai/providers/base.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/ai/providers/base.ts) - [packages/core/src/ai/security/injection-detect.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/ai/security/injection-detect.ts) - [packages/core/src/ai/security/trust-score.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/ai/security/trust-score.ts) - [packages/core/src/generator.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/generator.ts)
# AI 集成 ## 概述 AI 集成是 SkillKit 框架的核心子系统，负责管理与各种 AI 编码代理（Agent）的通信、格式转换和上下文生成。该系统通过统一抽象层，使 SkillKit 能够同时支持 Claude Code、Cursor、Windsurf、GitHub Copilot 等多种 AI 代理，同时保证技能（Skill）在不同代理间的无缝迁移和一致性执行。 SkillKit 的 AI 集成架构采用模块化设计，核心组件包括： | 组件 | 功能 | 源码位置 | |------|------|----------| | Provider 工厂 | 创建和管理 AI 提供者实例 | `packages/core/src/ai/providers/factory.ts` | | 基础提供接口 | 定义统一的 AI 交互协议 | `packages/core/src/ai/providers/base.ts` | | 格式转换器 | 处理 SKILL.md、MDC、Markdown 等格式 | `packages/core/src/translator/formats/` | | 安全检测 | 防范提示词注入攻击 | `packages/core/src/ai/security/injection-detect.ts` | | 信任评分 | 评估技能内容的可信度 | `packages/core/src/ai/security/trust-score.ts` | ## 架构设计 ### 系统分层 ``` ┌─────────────────────────────────────────────────────────────┐ │ SkillKit CLI/TUI │ ├─────────────────────────────────────────────────────────────┤ │ Generator (生成器) │ │ packages/core/src/generator.ts │ ├─────────────────────────────────────────────────────────────┤ │ AI Integration Layer │ │ ┌──────────────┬────────────────┬────────────────┐ │ │ │ Providers │ Security │ Translators │ │ │ ├──────────────┼────────────────┼────────────────┤ │ │ │ • factory │ • injection │ • skill-md │ │ │ │ • base │ • trust-score │ • mdc │ │ │ │ • mock │ │ • markdown │ │ │ └──────────────┴────────────────┴────────────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ External Agents │ │ Claude Code │ Cursor │ Windsurf │ Copilot │ Gemini │ └─────────────────────────────────────────────────────────────┘ ``` 资料来源：[packages/core/src/ai/index.ts]() ### Provider 工厂模式 Provider 工厂负责实例化各种 AI 提供者，支持运行时动态切换不同的 AI 后端。工厂模式确保了系统的可扩展性，新增 AI 代理只需实现基础接口即可集成。 ```typescript // Provider 实例化流程 createProvider(agent: AgentType, options?: ProviderOptions): AIProvider ``` 支持的代理类型包括：claude-code、cursor、windsurf、copilot、gemini-cli、replit-agent、sourcegraph-cody、tabby、tabnine 等。 资料来源：[packages/core/src/ai/providers/factory.ts]() ### 基础提供接口 所有 AI 提供者必须实现 `AIProvider` 接口，该接口定义了与 AI 代理交互的标准方法： | 方法 | 参数 | 返回值 | 说明 | |------|------|--------|------| | `generate` | `prompt: string, options?: GenerateOptions` | `Promise` | 生成内容 | | `complete` | `context: string, partial: string` | `Promise` | 代码补全 | | `chat` | `messages: Message[]` | `Promise` | 对话交互 | 资料来源：[packages/core/src/ai/providers/base.ts]() ## 格式转换系统 SkillKit 支持多种代理特定的技能格式，系统会自动进行格式检测和转换。 ### 支持的格式类型 | 格式 | 代理 | 特点 | 源码 | |------|------|------|------| | SKILL.md | Claude Code, Codex, Gemini CLI | YAML frontmatter + Markdown | `skill-md.ts` | | MDC | Cursor | 支持 globs 和 alwaysApply | `mdc.ts` | | Markdown | Windsurf, Copilot | 纯 Markdown 内容 | `markdown.ts` | ### 翻译结果模型 ```typescript interface TranslationResult { content: string; // 转换后的内容 format: string; // 输出格式标识 warnings?: string[]; // 潜在问题警告 } ``` 资料来源：[packages/core/README.md]() ### SKILL.md 格式规范 SKILL.md 是 SkillKit 的标准格式，使用 YAML frontmatter 定义元数据： ```markdown --- name: my-skill description: What this skill does version: 1.0.0 tags: [tag1, tag2] --- # Instructions Markdown content here... ``` 解析流程：首先提取 YAML frontmatter，然后解析 body 内容，最后转换为目标格式。 资料来源：[packages/core/src/translator/formats/skill-md.ts]() ## 安全机制 ### 提示词注入检测 AI 集成层内置多层安全检测，防范恶意的提示词注入攻击。系统定义了 15 种检测规则，覆盖常见注入模式。 | 规则 ID | 严重程度 | 检测模式 | 说明 | |---------|----------|----------|------| | PI011 | HIGH | `user>`、`assistant>`、`[AI\|claude]>` | 对话角色标记注入 | | PI012 | HIGH | `[INST]`、`<>` | 模型特定分隔符注入 | | PI013 | MEDIUM | `---$` (行尾) | YAML front-matter 注入 | | PI014 | MEDIUM | HTML 注释中的可疑内容 | 隐藏指令注入 | | PI015 | MEDIUM | `[comment]:` | Markdown 注释注入 | 检测器使用正则表达式匹配和排除模式结合的方式，在保持高检测率的同时降低误报率。 资料来源：[packages/core/src/scanner/rules/prompt-injection.ts]() ### 信任评分系统 每个技能内容都会经过信任评分计算，评分基于多个维度的加权综合： | 维度 | 权重 | 评估内容 | |------|------|----------| | 来源可靠性 | 0.3 | 技能来源仓库的信誉 | | 内容完整性 | 0.25 | 是否包含必要章节 | | 安全检测 | 0.25 | 注入风险评估 | | 格式规范 | 0.2 | 格式符合度 | 信任评分结果会影响技能推荐排序和安装决策。 资料来源：[packages/core/src/ai/security/trust-score.ts]() ## 上下文生成器 ### 生成器架构 Generator 组件负责将项目分析和技能信息转换为 AI 代理可理解的上下文指令。 ```mermaid graph TD A[Analysis Data] --> B[Generator] B --> C[Agent Instruction Template] C --> D[Section Renderer] D --> E[Markdown/MDC Output] F[Project Profile] --> G[Overview Section] H[Stack Info] --> I[Stack Section] I --> D J[Build Commands] --> K[Commands Section] K --> D L[Conventions] --> M[Conventions Section] M --> D ``` 资料来源：[packages/core/src/generator.ts]() ### 指令模板渲染 系统支持生成多种格式的指令输出，包括纯 Markdown 和 MDC（Markdown + YAML frontmatter）格式。 ```typescript const markdownRenderer: FormatRenderer = { h1: (text) => `# ${text}`, h2: (text) => `## ${text}`, code: (text) => `\`${text}\``, codeBlock: (code, lang = '') => `\`\`\`${lang}\n${code}\n\`\`\``, // ... }; ``` 格式渲染器抽象允许同一模板渲染为不同代理的特定格式。 资料来源：[packages/core/src/primer/generator.ts]() ### 生成区块 上下文生成器支持生成以下区块： | 区块 | 说明 | 包含数据 | |------|------|----------| | overview | 项目概览 | 项目名称、类型、语言统计 | | stack | 技术栈 | 框架、库、测试工具、数据库 | | commands | 构建命令 | 安装、构建、测试命令 | | conventions | 代码规范 | 命名约定、提交规范 | | structure | 项目结构 | 目录树、重要文件 | | guidelines | 使用指南 | 技能适用场景、边界 | 资料来源：[packages/core/src/primer/generator.ts]() ## 技能翻译工作流 ### 翻译流程图 ```mermaid graph LR A[Skill Content] --> B[Parse Source Format] B --> C[Validate Content] C --> D{Validation Pass?} D -->|No| E[Report Issues] D -->|Yes| F[Detect Target Agent] F --> G[Select Translator] G --> H[Transform Format] H --> I[Security Scan] I --> J{Security Pass?} J -->|No| K[Show Warnings] J -->|Yes| L[Translation Result] L --> M[Preview/Install] ``` ### 翻译屏幕交互 TUI 界面提供了交互式翻译功能，支持以下操作： - 源格式自动检测 - 目标代理选择（支持多选批量转换） - 预览模式（dry-run） - 兼容性检查 - 问题提示显示 资料来源：[packages/tui/src/screens/Translate.tsx]() ## 配置选项 ### Provider 配置 ```typescript interface ProviderOptions { apiKey?: string; // API 密钥 baseUrl?: string; // 自定义端点 model?: string; // 指定模型 temperature?: number; // 生成温度 maxTokens?: number; // 最大 token 数 timeout?: number; // 请求超时(ms) } ``` ### Generator 配置 ```typescript interface GeneratorOptions { format: 'markdown' | 'mdc'; sections?: string[]; // 启用的区块 customInstructions?: string; // 自定义指令 template?: AgentInstructionTemplate; } ``` ## 最佳实践 ### 1. 选择合适的技能格式 根据目标代理选择对应的格式： | 目标代理 | 推荐格式 | 说明 | |----------|----------|------| | Claude Code | SKILL.md | 官方推荐标准格式 | | Cursor | MDC | 支持文件 glob 匹配 | | Windsurf/Copilot | Markdown | 简单纯文本格式 | | 多代理兼容 | SKILL.md | 通用的转换源格式 | ### 2. 安全检查清单 在发布技能前，确保通过以下检查： - ✅ 无提示词注入模式（PI011-PI015） - ✅ YAML frontmatter 格式正确 - ✅ 不含隐藏指令（HTML 注释） - ✅ 信任评分达到阈值 ### 3. 格式转换注意事项 - 转换前先验证源格式完整性 - 使用 dry-run 模式预览转换结果 - 检查转换后的兼容性警告 - 多代理场景使用 SKILL.md 作为中间格式 ## 相关命令 ```bash # 翻译技能格式 skillkit translate my-skill --to cursor skillkit translate --all --to windsurf,copilot skillkit translate my-skill --to copilot --dry-run # 扫描安全问题 skillkit scan skillkit scan --format json # 生成上下文 skillkit generate context --project . --format markdown ``` 资料来源：[packages/cli/README.md]() ## 扩展开发 ### 添加新代理支持 1. 在 `packages/core/src/ai/providers/` 创建新 provider 文件 2. 实现 `AIProvider` 接口的所有方法 3. 在 `factory.ts` 中注册新代理类型 4. 在 `packages/core/src/translator/formats/` 创建格式转换器 5. 添加测试用例覆盖 ### 添加新格式支持 1. 创建新的 translator 类实现 `FormatTranslator` 接口 2. 实现 `parse()` 和 `generate()` 方法 3. 在 translator 注册表中添加新格式 4. 更新 README.md 文档 ## 总结 SkillKit 的 AI 集成系统通过模块化架构实现了对多种 AI 编码代理的统一支持。核心设计包括 Provider 工厂模式、格式转换系统、安全检测机制和上下文生成器，确保技能在异构代理环境中的可移植性和安全性。开发者可以通过扩展 Provider 和 Translator 来支持新的代理类型和格式，无需修改核心逻辑。 --- ## 推荐引擎 ### 相关页面 相关主题：[AI 集成](#ai-integration)
相关源码文件 以下源码文件用于生成本页说明： - [packages/tui/src/screens/Recommend.tsx](https://github.com/rohitg00/skillkit/blob/main/packages/tui/src/screens/Recommend.tsx) - [packages/cli/README.md](https://github.com/rohitg00/skillkit/blob/main/packages/cli/README.md) - [packages/tui/src/screens/Handoff.tsx](https://github.com/rohitg00/skillkit/blob/main/packages/tui/src/screens/Handoff.tsx) - [README.md](https://github.com/rohitg00/skillkit/blob/main/README.md) - [packages/core/src/ai/providers/mock.ts](https://github.com/rohitg00/skillkit/blob/main/packages/core/src/ai/providers/mock.ts)
# 推荐引擎 ## 概述 推荐引擎（Recommendation Engine）是 SkillKit 项目中帮助用户发现适合其技术栈的技能的智能系统。该引擎通过分析用户项目的技术栈信息，为用户推荐最相关的技能，并按照匹配度评分进行排序展示。 SkillKit 的推荐系统支持以下核心功能： | 功能 | 说明 | |------|------| | 栈感知推荐 | 基于项目技术栈（框架、语言、库）进行智能匹配 | | 评分排序 | 使用百分比评分（0-100%）衡量推荐准确度 | | 搜索过滤 | 支持通过关键词搜索筛选推荐结果 | | 质量阈值 | 可设置最低分数阈值过滤低质量推荐 | 资料来源：[README.md]() ## 核心架构 推荐引擎采用分层架构设计，主要包含以下几个层次： ```mermaid graph TD A[用户项目] --> B[栈分析层] B --> C[推荐引擎核心] C --> D[混合搜索模块] C --> E[RRF 排序模块] D --> F[推荐结果] E --> F G[CLI 命令层] --> C H[TUI 界面层] --> C ``` ### 各层职责 | 层级 | 职责 | 源码位置 | |------|------|----------| | CLI 命令层 | 提供 `skillkit recommend` 命令入口 | `packages/cli/src/commands/recommend.ts` | | TUI 界面层 | 渲染推荐列表和详情面板 | `packages/tui/src/screens/Recommend.tsx` | | 推荐引擎核心 | 协调搜索和排序流程 | `packages/core/src/recommend/engine.ts` | | 混合搜索模块 | 执行多维度搜索 | `packages/core/src/search/hybrid.ts` | | RRF 排序模块 | 应用 Reciprocal Rank Fusion 算法 | `packages/core/src/search/rrf.ts` | | 栈分析层 | 分析项目技术栈 | `packages/core/src/primer/generator.ts` | 资料来源：[packages/tui/src/screens/Recommend.tsx]() 资料来源：[packages/core/src/search/rrf.ts]() ## 推荐数据模型 ### 推荐结果结构 ```typescript interface Recommendation { name: string; // 技能名称 score: number; // 匹配度评分（0-100） description?: string; // 技能描述 reasons?: string[]; // 推荐理由列表 path?: string; // 技能文件路径 compatible?: boolean; // 与项目的兼容性 issues?: string[]; // 兼容性问题列表 } ``` 资料来源：[packages/tui/src/screens/Recommend.tsx]() ### 推荐理由显示 推荐理由（reasons）字段用于向用户解释为什么推荐该技能。当存在推荐理由时，界面会优先显示理由而非描述： ```tsx 0}> {' '}{rec.reasons[0]} {' '}{rec.description.slice(0, 50)} {rec.description.length > 50 ? '...' : ''} ``` 资料来源：[packages/tui/src/screens/Recommend.tsx:1-15]() ## 搜索与排序机制 ### 混合搜索（Hybrid Search） 推荐引擎内部使用混合搜索策略，结合多种搜索维度： ```mermaid graph LR A[关键词搜索] --> D[结果合并] B[栈匹配搜索] --> D C[语义搜索] --> D D --> E[RRF 融合排序] E --> F[最终排名] ``` ### RRF（Reciprocal Rank Fusion） RRF 算法用于融合多个搜索结果源的排名，通过倒数排名融合公式计算综合得分： ``` RRF_score = Σ (1 / (k + rank_i)) ``` 其中 `k` 是常数参数（通常为60），`rank_i` 是该技能在第 i 个搜索结果中的排名。 资料来源：[packages/core/src/search/rrf.ts]() ## 命令行接口 ### 基本用法 ```bash # 获取项目感知建议 skillkit recommend # 按任务筛选 skillkit recommend --search "authentication" # 质量阈值过滤 skillkit recommend --min-score 85 ``` 资料来源：[packages/cli/README.md]() ### 参数说明 | 参数 | 说明 | 示例 | |------|------|------| | `--search` | 关键词搜索过滤 | `--search "react"` | | `--min-score` | 最低匹配分数阈值 | `--min-score 70` | | `--format` | 输出格式（默认表格） | `--format json` | 资料来源：[README.md]() ## TUI 界面交互 ### 主视图布局 ``` ┌─────────────────────────────────────────────┐ │ 推荐技能 │ │ ───────────────────────────────────────── │ │ ▸ 92% vercel-react-best-practices │ │ 87% tailwind-v4-patterns │ │ 85% nextjs-app-router │ │ 81% shadcn-ui-components │ │ │ │ ▼ 5 more │ │ │ │ Last analyzed: 14:32:05 │ │ ─────────────────────────────────────────────│ │ j/k 导航 Enter 详情 Esc 返回 │ └─────────────────────────────────────────────┘ ``` ### 详情面板 按 Enter 键可打开选中推荐的详情面板，显示以下信息： | 字段 | 说明 | |------|------| | Title | 技能名称 | | Subtitle | 匹配分数（Score: XX%） | | Fields | 详细信息字段列表 | | Actions | 操作提示（Install / Close） | 资料来源：[packages/tui/src/screens/Recommend.tsx]() ### 导航与操作 | 按键 | 操作 | |------|------| | `j` / `k` | 上/下导航选择 | | `Enter` | 查看详情面板 | | `Esc` | 返回上一级 | | `r` | 刷新推荐列表 | ## 评分机制 ### 分数计算因素 推荐技能的评分基于以下因素综合计算： 1. **技术栈匹配度**：技能与项目使用的框架、语言、库的匹配程度 2. **依赖关联度**：技能所需依赖与项目现有依赖的重叠度 3. **使用频率**：该技能在同类项目中的使用统计数据 4. **更新时效性**：技能文档的新旧程度 ### 分数阈值建议 | 阈值范围 | 建议用途 | |----------|----------| | 90-100% | 高置信度推荐，直接安装使用 | | 70-89% | 中等置信度，建议查看详情后再安装 | | 50-69% | 低置信度，仅供参考 | | < 50% | 通常不显示，除非关闭阈值过滤 | ## 编程接口 ### 程序化调用 ```typescript import { recommendCommand } from '@skillkit/cli'; // 获取推荐 const recs = await recommendCommand({ path: './my-project', minScore: 70, }); // 遍历推荐结果 for (const rec of recs) { console.log(`${rec.score}% ${rec.name}`); console.log(` 原因: ${rec.reasons?.join(', ')}`); } ``` ### 搜索集成 推荐引擎可与搜索系统集成，支持更精细的查询： ```typescript import { searchSkills } from '@skillkit/core/search'; import { rankResults } from '@skillkit/core/ranking'; // 执行混合搜索 const results = await searchSkills({ query: 'react performance', stack: projectStack, hybrid: true }); // 应用 RRF 排序 const ranked = rankResults(results, { k: 60 }); ``` 资料来源：[packages/core/src/search/hybrid.ts]() ## 交接（Handoff）功能中的推荐 在项目交接功能中，推荐系统提供额外的上下文感知建议： ```tsx Recommendations {(rec) => ( → {rec} )} ``` 资料来源：[packages/tui/src/screens/Handoff.tsx]() ## 性能优化 ### 分页加载 当推荐结果较多时，TUI 界面采用分页显示策略： ```tsx ▼ {state().recommendations.length - recsWindow().start - maxVisible()} more ``` 默认每页显示固定数量的推荐项，通过 `maxVisible()` 配置。 资料来源：[packages/tui/src/screens/Recommend.tsx]() ### 增量分析 推荐引擎支持增量分析模式，仅对变更的文件重新计算推荐，避免全量扫描： ```mermaid graph LR A[文件变更] --> B[增量分析] B --> C{变更类型} C -->|依赖文件| D[重新匹配依赖] C -->|代码文件| E[更新栈检测] C -->|配置| F[刷新配置分析] D --> G[更新推荐列表] E --> G F --> G ``` ## 最佳实践 ### 1. 合理设置阈值 - 新项目建议使用较低阈值（50-70%）以获取更多参考 - 成熟项目可提高阈值（80%+）确保推荐质量 ### 2. 结合搜索使用 ```bash # 先获取所有推荐 skillkit recommend # 再通过关键词精筛 skillkit recommend --search "authentication" --min-score 75 ``` ### 3. 查看推荐理由 始终查看推荐理由（reasons）以理解推荐依据，对于不符合预期的推荐可进一步分析项目栈检测是否准确。 ### 4. 定期刷新 项目依赖变更后建议执行 `skillkit recommend --refresh` 重新生成推荐列表。 ## 配置选项 ### 引擎配置 | 配置项 | 默认值 | 说明 | |--------|--------|------| | `minScore` | 0 | 最低推荐分数阈值 | | `maxResults` | 20 | 最大返回结果数 | | `includeReasons` | true | 是否包含推荐理由 | | `stackDepth` | 3 | 技术栈分析深度 | ### 排序配置 | 配置项 | 默认值 | 说明 | |--------|--------|------| | `rrf.k` | 60 | RRF 算法常数参数 | | `weights.keyword` | 0.4 | 关键词搜索权重 | | `weights.stack` | 0.6 | 栈匹配搜索权重 | ## 故障排除 ### 推荐结果为空 可能原因及解决方案： | 原因 | 解决方案 | |------|----------| | 项目栈检测失败 | 运行 `skillkit analyze` 检查项目分析结果 | | 阈值设置过高 | 降低 `--min-score` 参数值 | | 技能库未同步 | 运行 `skillkit sync` 同步技能库 | ### 评分异常 如果推荐分数明显不符合预期： 1. 检查 `skillkit analyze` 输出确认栈检测准确性 2. 确认技能库版本为最新 3. 查看是否有缓存问题，尝试 `skillkit clean && skillkit recommend` ## 相关文档 - [搜索系统](../search/index.html) - [栈分析器](../primer/index.html) - [技能格式](../skill-format/index.html) - [CLI 命令参考](../cli/commands.html) --- --- ## Doramagic 踩坑日志 项目：rohitg00/skillkit 摘要：发现 23 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Trust downgrade for skillkit@1.24.0: v1.0.3 had provenance attestation but this version has no trust evidence。 ## 1. 安装坑 · 来源证据：Trust downgrade for skillkit@1.24.0: v1.0.3 had provenance attestation but this version has no trust evidence - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Trust downgrade for skillkit@1.24.0: v1.0.3 had provenance attestation but this version has no trust evidence - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_54f25870d6d64729a96eb14e8e1ee72f | https://github.com/rohitg00/skillkit/issues/121 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。 ## 2. 安全/权限坑 · 来源证据：[Publish] CreatorCrawl — Social Media Data Skill - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Publish] CreatorCrawl — Social Media Data Skill - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_d2c6e8b4d87e4786af49c7bc9ee2665d | https://github.com/rohitg00/skillkit/issues/123 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。 ## 3. 安装坑 · 来源证据：Add source: jorgeferrando/sdd-skills — Spec-Driven Development workflow - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add source: jorgeferrando/sdd-skills — Spec-Driven Development workflow - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_d1cb6475bbfe4122ab15817ca66e58b6 | https://github.com/rohitg00/skillkit/issues/112 | 来源类型 github_issue 暴露的待验证使用条件。 ## 4. 安装坑 · 来源证据：[Publish] Rhf Autosave - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Publish] Rhf Autosave - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_7f4a4b823d1a40918a48fb8aae0d74ac | https://github.com/rohitg00/skillkit/issues/111 | 来源类型 github_issue 暴露的待验证使用条件。 ## 5. 安装坑 · 来源证据：v1.20.0 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.20.0 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_73d12f84f1644a3dbc3981274dfefa42 | https://github.com/rohitg00/skillkit/releases/tag/v1.20.0 | 来源类型 github_release 暴露的待验证使用条件。 ## 6. 安装坑 · 来源证据：v1.22.0 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.22.0 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_a5339307b2d04e409858700fa8186f6c | https://github.com/rohitg00/skillkit/releases/tag/v1.22.0 | 来源类型 github_release 暴露的待验证使用条件。 ## 7. 安装坑 · 来源证据：v1.22.1 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.22.1 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_2a197dc603b242bdaa32dd2c70d535c1 | https://github.com/rohitg00/skillkit/releases/tag/v1.22.1 | 来源类型 github_release 暴露的待验证使用条件。 ## 8. 安装坑 · 来源证据：v1.23.0 — Slim install, safer picker, brand tags - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.23.0 — Slim install, safer picker, brand tags - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_9388696ec7584a6b8f5998d74f1c428e | https://github.com/rohitg00/skillkit/releases/tag/v1.23.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。 ## 9. 配置坑 · 可能修改宿主 AI 配置 - 严重度：medium - 证据强度：source_linked - 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。 - 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 - 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。 - 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。 - 证据：capability.host_targets | github_repo:1138376193 | https://github.com/rohitg00/skillkit | host_targets=claude, claude_code, cursor ## 10. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 建议检查：将假设转成下游验证清单。 - 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。 - 证据：capability.assumptions | github_repo:1138376193 | https://github.com/rohitg00/skillkit | README/documentation is current enough for a first validation pass. ## 11. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。 - 防护动作：维护活跃度未知时，推荐强度不能标为高信任。 - 证据：evidence.maintainer_signals | github_repo:1138376193 | https://github.com/rohitg00/skillkit | last_activity_observed missing ## 12. 安全/权限坑 · 下游验证发现风险项 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：下游已经要求复核，不能在页面中弱化。 - 建议检查：进入安全/权限治理复核队列。 - 防护动作：下游风险存在时必须保持 review/recommendation 降级。 - 证据：downstream_validation.risk_items | github_repo:1138376193 | https://github.com/rohitg00/skillkit | no_demo; severity=medium ## 13. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 建议检查：把风险写入边界卡，并确认是否需要人工复核。 - 防护动作：评分风险必须进入边界卡，不能只作为内部分数。 - 证据：risks.scoring_risks | github_repo:1138376193 | https://github.com/rohitg00/skillkit | no_demo; severity=medium ## 14. 安全/权限坑 · 来源证据：[Audit] Add --json output to 28 commands for CI/CD usage - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Audit] Add --json output to 28 commands for CI/CD usage - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_e28aa428237f4e6ba09f785dbf5e6978 | https://github.com/rohitg00/skillkit/issues/89 | 来源类型 github_issue 暴露的待验证使用条件。 ## 15. 安全/权限坑 · 来源证据：[Audit] Add loading spinners to 43 commands missing progress feedback - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Audit] Add loading spinners to 43 commands missing progress feedback - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_9bba06e67cf944c28dcb33d8ed334975 | https://github.com/rohitg00/skillkit/issues/88 | 来源类型 github_issue 暴露的待验证使用条件。 ## 16. 安全/权限坑 · 来源证据：[Publish] AlphaEar System - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Publish] AlphaEar System - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_26d8102a08b8434cb7456fcd1554ce3a | https://github.com/rohitg00/skillkit/issues/126 | 来源类型 github_issue 暴露的待验证使用条件。 ## 17. 安全/权限坑 · 来源证据：[Publish] Computer Use Patterns - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Publish] Computer Use Patterns - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_5f48d6d0c0c04492b897829190a0df3c | https://github.com/rohitg00/skillkit/issues/124 | 来源类型 github_issue 暴露的待验证使用条件。 ## 18. 安全/权限坑 · 来源证据：[Publish] SkillKit Integration - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Publish] SkillKit Integration - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_2c9342c012d74dcfba1ba832a87724c3 | https://github.com/rohitg00/skillkit/issues/125 | 来源类型 github_issue 暴露的待验证使用条件。 ## 19. 安全/权限坑 · 来源证据：[Source] Add Xquik TweetClaw - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Source] Add Xquik TweetClaw - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_f9e22dd824ca491e8bd861cac00a2203 | https://github.com/rohitg00/skillkit/issues/120 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。 ## 20. 安全/权限坑 · 来源证据：v1.21.0 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.21.0 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_2989a360f78d46cfbba976f4932bff93 | https://github.com/rohitg00/skillkit/releases/tag/v1.21.0 | 来源类型 github_release 暴露的待验证使用条件。 ## 21. 安全/权限坑 · 来源证据：v1.24.0 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.24.0 - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_8dbf39f6064042bbb250f034a824d7d3 | https://github.com/rohitg00/skillkit/releases/tag/v1.24.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。 ## 22. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 建议检查：抽样最近 issue/PR，判断是否长期无人处理。 - 防护动作：issue/PR 响应未知时，必须提示维护风险。 - 证据：evidence.maintainer_signals | github_repo:1138376193 | https://github.com/rohitg00/skillkit | issue_or_pr_quality=unknown ## 23. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 建议检查：确认最近 release/tag 和 README 安装命令是否一致。 - 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。 - 证据：evidence.maintainer_signals | github_repo:1138376193 | https://github.com/rohitg00/skillkit | release_recency=unknown