1. 项目概述当AI技能也需要一个“家”如果你最近在折腾AI Agent尤其是像Claude、Cursor这类能通过技能Skill扩展能力的智能体那你可能已经遇到了一个非常具体且恼人的问题技能管理太乱了。想象一下你从某个GitHub仓库下载了一个“代码审查”技能又从另一个地方找到了一个“数据库查询”技能。你把它们都扔进了某个文件夹然后手动修改Agent的配置文件告诉它“嘿去这里加载这些技能。” 这听起来还行对吧但问题很快就来了当技能A更新了你需要手动去覆盖当技能B依赖技能C的某个功能时你发现它们之间根本无法通信你想分享自己写的技能给同事结果发现需要附上一长串“安装说明”从复制文件到修改配置一步都不能错。这正是skillpm要解决的问题。它不是一个全新的、颠覆性的工具而是一个极其聪明的“粘合剂”。它的核心洞察非常直接既然Agent Skill本质上就是一堆文件指令、配置、脚本那为什么不直接用世界上最成熟、最强大的文件包管理器来管理它们呢这个管理器就是npm。skillpm 所做的就是在 Agent Skills 的开放标准之上构建了一个轻量级的编排层官方说只有约630行代码将技能的生命周期——发布、安装、版本管理、依赖解析——完全映射到 npm 的生态系统中。从此一个技能就是一个标准的 npm 包拥有自己的package.json可以声明依赖可以发布到 npm 仓库也可以通过一句简单的npx skillpm install命令连同它的所有依赖项被一键安装并自动配置到你的多个AI Agent如Claude Desktop、Cursor、VS Code Codex等中。简单来说skillpm 让 AI 技能的共享和复用变得像在 JavaScript 项目里安装一个lodash库一样简单、可靠。它填补了 Agent Skills 规范中“只定义了技能是什么没定义怎么管理”的巨大空白让开发者能从编写重复、臃肿的“单体技能”中解放出来转向开发小巧、可组合的模块化技能。2. 核心设计思路站在巨人的肩膀上skillpm 的设计哲学是“绝不重复造轮子”。它没有尝试去构建一个全新的注册中心、依赖解析器或版本控制系统而是巧妙地利用了现有、且已被验证了无数次的工具链。理解这个设计思路是高效使用它的关键。2.1 基石一npm 作为底层引擎npm 不仅仅是 Node.js 的包管理器它更是一套完整的、用于管理软件包依赖关系的工业标准。它解决了软件分发中最复杂的问题依赖解析与冲突处理自动计算并安装所有直接和间接依赖处理不同包对同一依赖不同版本的冲突。版本管理与语义化版本控制SemVer通过package.json中的版本范围声明实现灵活且可控的更新。锁文件保证一致性package-lock.json或yarn.lock确保了在任何地方、任何时间安装的依赖树都是完全一致的避免了“在我机器上能运行”的经典问题。庞大的公共仓库与成熟的发布流程npmjs.org 是全球最大的软件注册中心之一发布、搜索、安装的体验已经非常流畅。skillpm 将每个技能定义为一个标准的 npm 包。这意味着你的技能项目根目录必须有一个package.json文件其中必须包含agent-skill这个关键词keyword以便 skillpm 能够识别它。当执行skillpm install时它实际上是在后台调用了npm install。所有复杂的依赖拉取、节点模块组织工作都交给了 npm 去完成。实操心得利用 npm 的私有仓库由于底层是 npm这意味着 skillpm 天然支持私有 npm 仓库如 Verdaccio、GitHub Packages、公司内网的私有 registry。这对于企业内部分享敏感或定制化的 AI 技能至关重要。你只需要像配置普通 npm 项目一样设置好.npmrc文件中的 registry 地址skillpm publish和skillpm install就会自动使用私有仓库。2.2 基石二skillsCLI 负责 Agent 集成光把技能包下载到node_modules里是没用的AI Agent 并不知道去哪里找它们。这就是skillsCLI 工具的作用。它是一个由社区维护的工具专门负责扫描指定目录下的技能并将它们“链接”或“注册”到各个 AI Agent 的配置目录中。例如Claude Desktop 会在~/.config/claude/desktop-config.json中寻找技能路径Cursor 则有自己的一套机制。skills工具抽象了这些不同 Agent 的配置细节提供了一个统一的接口。skillpm 在 npm 安装完成后会自动调用skills工具将node_modules中所有识别出的技能即包含skills/*/SKILL.md文件的包链接到当前工作区workspace对应的 Agent 目录。这个过程对用户是完全透明的。2.3 基石三add-mcp处理 MCP 服务器配置模型上下文协议Model Context Protocol, MCP是另一个重要的开放标准它允许 AI 模型安全地访问外部工具和数据源如数据库、文件系统、API。许多高级技能会内置或依赖 MCP 服务器来提供这些能力。skillpm 通过整合add-mcp工具来处理这部分。它会扫描所有已安装技能包括它们的依赖的package.json收集其中定义的skillpm.mcpServers配置项然后自动为工作区内的 Agent 配置这些 MCP 服务器。这确保了技能所需的上下文访问能力在安装后立即可用。这三者的协作关系可以用一个简单的流水线来理解用户输入skillpm install awesome-skillnpm 工作解析awesome-skill及其依赖下载到node_modules。skillpm 扫描在node_modules里寻找所有带skills/子目录的包。skills 链接将找到的每个技能包通过skills工具注册到 Claude、Cursor 等 Agent。add-mcp 配置收集所有包的 MCP 配置并通过add-mcp工具写入 Agent 配置。结果用户打开 Claude 或 Cursorawesome-skill及其依赖的技能、相关的 MCP 服务器都已就绪可以直接使用。这个设计使得 skillpm 本身非常轻量且专注它只做“编排”这件事而把专业的事交给专业的工具。3. 从零开始安装、初始化与第一个技能理论讲完了我们上手操作。整个过程你会感到非常熟悉如果你用过 npm。3.1 安装 skillpm CLI你有两种方式使用 skillpm方式一使用npx推荐尤其适合尝鲜和单次操作npx是 npm 自带的工具允许你直接运行远程 npm 包中的命令而无需先全局安装。这是最干净、避免全局污染的方式。# 安装一个技能 npx skillpm install skill-name # 初始化一个新技能项目 npx skillpm init方式二全局安装如果你打算频繁创建或管理技能全局安装会更方便。npm install -g skillpm安装后你就可以在任何地方直接使用skillpm命令了。重要提示skillpm install -g这个命令不存在也不要这样用。skillpm本身是一个管理工具而“技能”本身是作为本地依赖被安装到你的项目node_modules里的。全局安装的只是skillpm这个 CLI 工具。3.2 探索与安装现有技能在创建自己的技能之前可以先看看社区里有什么。由于技能就是 npm 包你可以直接到 npmjs.com 上搜索关键词agent-skill。假设我们找到了一个很有用的技能包叫做skill-helper。在你的项目目录或者任何一个你希望启用技能的工作区下运行npx skillpm install skill-helper你会看到类似 npm 的输出显示依赖树被解析和下载。完成后运行npx skillpm list这个命令会列出当前工作区所有已安装的技能包包括它们的名称、版本和来源是来自 npm 还是本地工作区链接。3.3 创建你的第一个技能现在让我们创建一个属于自己的技能。这个过程和初始化一个 npm 包几乎一模一样。# 1. 创建一个新目录并进入 mkdir my-first-skill cd my-first-skill # 2. 使用 skillpm 初始化项目骨架 npx skillpm init执行init命令后它会交互式地询问你一些信息包名、版本、描述等并生成一个标准化的项目结构。一个最简化的技能包结构如下所示my-first-skill/ ├── package.json ├── skills/ │ └── my-first-skill/ # 技能目录名字通常与包名对应 │ └── SKILL.md # 技能的“说明书”这是核心文件 └── configs/ # 可选存放针对不同Agent的配置文件 ├── claude/ │ └── desktop-config.json └── cursor/ └── rules.md关键文件解析package.json这是技能的“身份证”和“清单”。除了常规的name,version,description有两个关键字段keywords: [agent-skill]必须包含。这是 skillpm 识别此包为技能的唯一标识。dependencies和devDependencies你可以在这里声明依赖的其他 npm 包包括其他技能包。skillpm 会通过 npm 自动处理这些依赖。skills/skill-name/SKILL.md这是技能的核心。它遵循 Agent Skills 规范 是一个 Markdown 文件其中定义了技能名称和描述告诉 AI 这个技能是干什么的。指令Instructions这是最重要的部分用自然语言详细描述该技能的功能、使用方式、输入输出示例、限制条件等。AI Agent 会读取这些指令来学习如何使用该技能。能力Capabilities声明技能提供的具体功能如文件读写、命令执行、API调用等。配置项定义技能所需的配置参数如 API 密钥、服务器地址等。configs/目录可选如果你需要为特定的 Agent 提供默认的配置文件、提示词模板或规则可以放在这里。例如configs/claude/desktop-config.json可以包含 Claude Desktop 特有的配置。当技能被安装时skillpm 会自动将这些配置文件并添加前缀以避免冲突复制到工作区根目录供 Agent 读取。4. 技能开发详解构建一个实用的代码审查技能让我们以一个更复杂的例子——“自动代码审查技能”为例深入讲解开发过程中的细节和最佳实践。4.1 项目初始化与元数据定义首先我们创建一个更专业的包名通常使用 scope 来分组。npx skillpm init # 包名输入my-org/code-review-skill # 描述An AI-powered skill to review pull requests and suggest improvements.生成的package.json雏形如下。我们需要手动完善它{ name: my-org/code-review-skill, version: 0.1.0, description: An AI-powered skill to review pull requests and suggest improvements., keywords: [agent-skill, code-review, pr, static-analysis], main: index.js, // 对于纯指令的技能这个可能用不到但保留无妨 scripts: { test: echo \Error: no test specified\ exit 1 }, dependencies: { // 假设我们的技能需要调用 GitHub API 和 ESLint octokit/rest: ^20.0.0, eslint: ^9.0.0 }, devDependencies: { // 开发依赖如TypeScript、测试框架 typescript: ^5.0.0, types/node: ^20.0.0 }, skillpm: { // skillpm 特有的配置项 mcpServers: { // 声明本技能提供或依赖的 MCP 服务器 github: ./mcp-servers/github-server.js, code-analyzer: ./mcp-servers/analyzer-server.js } }, author: Your Name, license: MIT }关键点skillpm.mcpServers字段是我们声明 MCP 服务器的地方。当这个技能被安装时skillpm 会读取这个配置并调用add-mcp工具将其注册到 Agent。这意味着即使技能包本身没有可执行的main入口它也能通过 MCP 为 AI 提供强大的后端服务。4.2 编写核心技能指令SKILL.mdskills/code-review-skill/SKILL.md文件是灵魂。它的质量直接决定了 AI 使用该技能的效果。# Code Review Assistant ## Description This skill enables the AI agent to perform automated code reviews on GitHub pull requests. It can fetch PR diff, run static analysis (ESLint), check for common security issues, and generate constructive review comments. ## Capabilities - **read:github_pr**: Read pull request details and diff from a specified GitHub repository. - **execute:eslint**: Run ESLint on provided code snippets or file paths to identify style and potential error issues. - **analyze:security**: Perform basic security pattern checks (e.g., hardcoded secrets, SQL injection patterns). - **write:github_comment**: Post review comments back to the GitHub pull request. ## Instructions ### For the AI Agent: You are now equipped with the Code Review Assistant skill. Use this skill when the user asks you to review code, especially code within a GitHub pull request context. #### How to use: 1. **Initialize Review**: - Ask the user for the GitHub repository URL and the pull request number. - Use the read:github_pr capability to fetch the PR title, description, and the unified diff. 2. **Analyze Changes**: - Parse the diff to identify added/modified files and code snippets. - For each JavaScript/TypeScript file changed, use the execute:eslint capability with appropriate rulesets (recommended: eslint:recommended and plugin:security/recommended). - Scan the diff lines for obvious security anti-patterns using analyze:security (look for patterns like eval(, localStorage with sensitive data, potential XSS strings). 3. **Generate Feedback**: - Categorize findings: - **Critical**: Security vulnerabilities, runtime errors. - **Warning**: Code style violations, potential performance issues, missing error handling. - **Suggestion**: Improvements for readability, better naming, or architectural hints. - For each finding, provide: - The file path and line number. - A concise description of the issue. - A suggested fix or code snippet. - A link to relevant documentation (if applicable). 4. **Deliver Results**: - Summarize the review at the top (e.g., “Found 2 critical issues, 5 warnings, and 3 suggestions”). - Ask the user if they would like you to post these comments directly to the GitHub PR using the write:github_comment capability. **Always get explicit user consent before posting.** ### Configuration This skill requires the following environment variables to be set in the agents workspace: - GITHUB_TOKEN: A Personal Access Token with repo scope to read PRs and post comments. - ESLINT_CONFIG_PATH: (Optional) Path to a custom ESLint configuration file. Defaults to built-in recommended rules. ### Examples **User**: Can you review PR #42 in https://github.com/my-org/my-app? **Agent (using this skill)**: 1. Sure, Ill review PR #42. Ill need a GitHub Personal Access Token with repo permissions. Do you have one set as GITHUB_TOKEN in this workspace, or shall I guide you to create one? 2. (After token is provided) Fetching PR details... Analyzing changes... Ive found 1 critical security issue regarding a potential SQL injection in api/db.js, and 3 style warnings in src/components/Button.js. Would you like me to post these as comments on the PR, or just present them here for you?这份指令写得非常详细它不仅仅是告诉 AI“你有这个能力”而是给出了一个完整的“工作流程”和“思维链”。它教 AI 如何一步步地使用各个子能力如何处理边界情况如获取用户授权以及如何组织输出。这是编写高质量技能的关键。4.3 实现 MCP 服务器进阶对于简单的技能可能只需要指令SKILL.md就够了。但对于我们这个代码审查技能我们需要真正的后端逻辑来调用 GitHub API 和运行 ESLint。这就是 MCP 服务器的用武之地。我们在package.json中声明了两个 MCP 服务器。现在我们需要创建它们。在项目根目录创建mcp-servers/目录。mcp-servers/github-server.js(简化示例):// 这是一个使用 Node.js 和 MCP 标准库的简单示例 const { McpServer } require(modelcontextprotocol/sdk/server); const { Octokit } require(octokit/rest); const server new McpServer({ name: github-code-review, version: 0.1.0, }); // 定义一个工具Tool对应技能指令中的 read:github_pr 能力 server.tool( read_github_pr, { repository: { type: string, description: Full repo name (e.g., octocat/Hello-World) }, pr_number: { type: number, description: Pull request number }, }, async ({ repository, pr_number }) { const token process.env.GITHUB_TOKEN; if (!token) { throw new Error(GITHUB_TOKEN environment variable is not set.); } const octokit new Octokit({ auth: token }); try { const { data: pr } await octokit.rest.pulls.get({ owner: repository.split(/)[0], repo: repository.split(/)[1], pull_number: pr_number, }); const { data: files } await octokit.rest.pulls.listFiles({ owner: repository.split(/)[0], repo: repository.split(/)[1], pull_number: pr_number, }); return { content: [ { type: text, text: # PR #${pr_number}: ${pr.title}\n\n${pr.body}\n\n## Files Changed:\n${files.map(f - ${f.filename} (${f.status}, ${f.additions}, -${f.deletions})).join(\n)}\n\n## Diff:\n\\\diff\n${files.map(f f.patch).join(\n---\n)}\n\\\, }, ], }; } catch (error) { return { content: [{ type: text, text: Error fetching PR: ${error.message} }], isError: true, }; } } ); // 同样可以定义 write_github_comment 工具 server.tool(write_github_comment, ...); // 启动服务器skillpm/add-mcp 会管理服务器进程 server.start();这个 MCP 服务器暴露了一个工具read_github_pr。当 AI Agent 需要执行代码审查时它会通过 MCP 协议调用这个工具并传入参数repository和pr_number。服务器执行实际的 GitHub API 调用并将结果格式化后返回给 AI。mcp-servers/analyzer-server.js则会类似地封装 ESLint 的调用。通过这种方式技能的逻辑被安全地封装在后端服务器中。AI 只需要知道“调用什么工具、传什么参数、怎么解释结果”而不需要直接处理 API 密钥或运行复杂的代码分析引擎。4.4 本地测试与调试在发布之前你需要在本地测试你的技能。由于 skillpm 支持 monorepo 工作区这是非常方便的。在技能目录下确保你的package.json和SKILL.md等文件都已就绪。在工作区根目录即你希望使用技能的项目将你的技能作为本地依赖链接。如果你的工作区根目录有package.json你可以使用 npm workspaces 或npm link。更简单的方式在工作区根目录运行skillpm sync。如果 skillpm 在node_modules中发现了通过 symlink 链接的本地技能包比如你用了npm link ../my-first-skill它会自动识别并处理它们输出类似Linking workspace package my-org/code-review-skill0.1.0的信息。启动你的 AI Agent如 Claude Desktop。在它的技能设置中你应该能看到你的技能被自动加载了。与 Agent 对话尝试触发你的技能指令。观察 AI 是否正确地理解了技能描述并尝试调用你定义的 MCP 工具。你需要在 MCP 服务器控制台查看日志以确认调用是否成功。避坑技巧MCP 服务器调试MCP 服务器是独立进程。在开发时建议先单独运行你的服务器脚本 (node mcp-servers/github-server.js)确保它能正常启动和响应。使用curl或 Postman 模拟 MCP 调用进行测试。然后再通过skillpm sync集成到 Agent 中。这样可以隔离问题确定是技能指令问题、MCP 协议问题还是 Agent 集成问题。5. 发布、共享与团队协作开发测试完成后是时候分享你的成果了。5.1 发布到 npm 仓库发布流程和发布普通 npm 包完全一致。# 1. 确保你已经登录 npm (如果没有运行 npm login) npm whoami # 2. 在技能项目根目录运行 skillpm publish # 它会做两件事a) 运行 npm publish b) 验证你的 package.json 包含 agent-skill 关键词。 skillpm publish发布成功后你的技能包就可以被全世界或你的组织内如果使用私有仓库通过skillpm install my-org/code-review-skill来安装了。5.2 管理技能依赖与版本技能包之间可以相互依赖这是 skillpm 带来的最大优势之一。例如你可以创建一个utility-helper-skill包里面包含一些通用的指令模板和工具函数。然后你的code-review-skill可以在package.json中依赖它{ name: my-org/code-review-skill, dependencies: { my-org/utility-helper-skill: ^1.0.0 } }当用户安装code-review-skill时utility-helper-skill会被自动安装。这促进了技能的模块化和复用。版本控制策略遵循语义化版本控制SemVer主版本号.次版本号.修订号。当技能指令SKILL.md有重大不兼容更新时升级主版本号。当新增功能但向下兼容时升级次版本号。当只修复问题或做微小改进时升级修订号。在package.json中为依赖指定合适的版本范围如^1.2.3以便用户能自动获得安全修复和兼容的功能更新。5.3 团队协作与 Monorepo 工作流对于团队开发多个相关技能skillpm 完美支持 npm workspaces monorepo。项目结构示例my-ai-skills-monorepo/ ├── package.json (workspaces: [packages/*]) ├── packages/ │ ├── utility-helpers/ (技能包) │ │ ├── package.json │ │ └── skills/... │ ├── code-review/ (技能包) │ │ ├── package.json (依赖 utility-helpers) │ │ └── skills/... │ └──>
skillpm：基于npm的AI技能包管理器，解决Agent技能管理难题
发布时间：2026/7/31 15:47:45
1. 项目概述当AI技能也需要一个“家”如果你最近在折腾AI Agent尤其是像Claude、Cursor这类能通过技能Skill扩展能力的智能体那你可能已经遇到了一个非常具体且恼人的问题技能管理太乱了。想象一下你从某个GitHub仓库下载了一个“代码审查”技能又从另一个地方找到了一个“数据库查询”技能。你把它们都扔进了某个文件夹然后手动修改Agent的配置文件告诉它“嘿去这里加载这些技能。” 这听起来还行对吧但问题很快就来了当技能A更新了你需要手动去覆盖当技能B依赖技能C的某个功能时你发现它们之间根本无法通信你想分享自己写的技能给同事结果发现需要附上一长串“安装说明”从复制文件到修改配置一步都不能错。这正是skillpm要解决的问题。它不是一个全新的、颠覆性的工具而是一个极其聪明的“粘合剂”。它的核心洞察非常直接既然Agent Skill本质上就是一堆文件指令、配置、脚本那为什么不直接用世界上最成熟、最强大的文件包管理器来管理它们呢这个管理器就是npm。skillpm 所做的就是在 Agent Skills 的开放标准之上构建了一个轻量级的编排层官方说只有约630行代码将技能的生命周期——发布、安装、版本管理、依赖解析——完全映射到 npm 的生态系统中。从此一个技能就是一个标准的 npm 包拥有自己的package.json可以声明依赖可以发布到 npm 仓库也可以通过一句简单的npx skillpm install命令连同它的所有依赖项被一键安装并自动配置到你的多个AI Agent如Claude Desktop、Cursor、VS Code Codex等中。简单来说skillpm 让 AI 技能的共享和复用变得像在 JavaScript 项目里安装一个lodash库一样简单、可靠。它填补了 Agent Skills 规范中“只定义了技能是什么没定义怎么管理”的巨大空白让开发者能从编写重复、臃肿的“单体技能”中解放出来转向开发小巧、可组合的模块化技能。2. 核心设计思路站在巨人的肩膀上skillpm 的设计哲学是“绝不重复造轮子”。它没有尝试去构建一个全新的注册中心、依赖解析器或版本控制系统而是巧妙地利用了现有、且已被验证了无数次的工具链。理解这个设计思路是高效使用它的关键。2.1 基石一npm 作为底层引擎npm 不仅仅是 Node.js 的包管理器它更是一套完整的、用于管理软件包依赖关系的工业标准。它解决了软件分发中最复杂的问题依赖解析与冲突处理自动计算并安装所有直接和间接依赖处理不同包对同一依赖不同版本的冲突。版本管理与语义化版本控制SemVer通过package.json中的版本范围声明实现灵活且可控的更新。锁文件保证一致性package-lock.json或yarn.lock确保了在任何地方、任何时间安装的依赖树都是完全一致的避免了“在我机器上能运行”的经典问题。庞大的公共仓库与成熟的发布流程npmjs.org 是全球最大的软件注册中心之一发布、搜索、安装的体验已经非常流畅。skillpm 将每个技能定义为一个标准的 npm 包。这意味着你的技能项目根目录必须有一个package.json文件其中必须包含agent-skill这个关键词keyword以便 skillpm 能够识别它。当执行skillpm install时它实际上是在后台调用了npm install。所有复杂的依赖拉取、节点模块组织工作都交给了 npm 去完成。实操心得利用 npm 的私有仓库由于底层是 npm这意味着 skillpm 天然支持私有 npm 仓库如 Verdaccio、GitHub Packages、公司内网的私有 registry。这对于企业内部分享敏感或定制化的 AI 技能至关重要。你只需要像配置普通 npm 项目一样设置好.npmrc文件中的 registry 地址skillpm publish和skillpm install就会自动使用私有仓库。2.2 基石二skillsCLI 负责 Agent 集成光把技能包下载到node_modules里是没用的AI Agent 并不知道去哪里找它们。这就是skillsCLI 工具的作用。它是一个由社区维护的工具专门负责扫描指定目录下的技能并将它们“链接”或“注册”到各个 AI Agent 的配置目录中。例如Claude Desktop 会在~/.config/claude/desktop-config.json中寻找技能路径Cursor 则有自己的一套机制。skills工具抽象了这些不同 Agent 的配置细节提供了一个统一的接口。skillpm 在 npm 安装完成后会自动调用skills工具将node_modules中所有识别出的技能即包含skills/*/SKILL.md文件的包链接到当前工作区workspace对应的 Agent 目录。这个过程对用户是完全透明的。2.3 基石三add-mcp处理 MCP 服务器配置模型上下文协议Model Context Protocol, MCP是另一个重要的开放标准它允许 AI 模型安全地访问外部工具和数据源如数据库、文件系统、API。许多高级技能会内置或依赖 MCP 服务器来提供这些能力。skillpm 通过整合add-mcp工具来处理这部分。它会扫描所有已安装技能包括它们的依赖的package.json收集其中定义的skillpm.mcpServers配置项然后自动为工作区内的 Agent 配置这些 MCP 服务器。这确保了技能所需的上下文访问能力在安装后立即可用。这三者的协作关系可以用一个简单的流水线来理解用户输入skillpm install awesome-skillnpm 工作解析awesome-skill及其依赖下载到node_modules。skillpm 扫描在node_modules里寻找所有带skills/子目录的包。skills 链接将找到的每个技能包通过skills工具注册到 Claude、Cursor 等 Agent。add-mcp 配置收集所有包的 MCP 配置并通过add-mcp工具写入 Agent 配置。结果用户打开 Claude 或 Cursorawesome-skill及其依赖的技能、相关的 MCP 服务器都已就绪可以直接使用。这个设计使得 skillpm 本身非常轻量且专注它只做“编排”这件事而把专业的事交给专业的工具。3. 从零开始安装、初始化与第一个技能理论讲完了我们上手操作。整个过程你会感到非常熟悉如果你用过 npm。3.1 安装 skillpm CLI你有两种方式使用 skillpm方式一使用npx推荐尤其适合尝鲜和单次操作npx是 npm 自带的工具允许你直接运行远程 npm 包中的命令而无需先全局安装。这是最干净、避免全局污染的方式。# 安装一个技能 npx skillpm install skill-name # 初始化一个新技能项目 npx skillpm init方式二全局安装如果你打算频繁创建或管理技能全局安装会更方便。npm install -g skillpm安装后你就可以在任何地方直接使用skillpm命令了。重要提示skillpm install -g这个命令不存在也不要这样用。skillpm本身是一个管理工具而“技能”本身是作为本地依赖被安装到你的项目node_modules里的。全局安装的只是skillpm这个 CLI 工具。3.2 探索与安装现有技能在创建自己的技能之前可以先看看社区里有什么。由于技能就是 npm 包你可以直接到 npmjs.com 上搜索关键词agent-skill。假设我们找到了一个很有用的技能包叫做skill-helper。在你的项目目录或者任何一个你希望启用技能的工作区下运行npx skillpm install skill-helper你会看到类似 npm 的输出显示依赖树被解析和下载。完成后运行npx skillpm list这个命令会列出当前工作区所有已安装的技能包包括它们的名称、版本和来源是来自 npm 还是本地工作区链接。3.3 创建你的第一个技能现在让我们创建一个属于自己的技能。这个过程和初始化一个 npm 包几乎一模一样。# 1. 创建一个新目录并进入 mkdir my-first-skill cd my-first-skill # 2. 使用 skillpm 初始化项目骨架 npx skillpm init执行init命令后它会交互式地询问你一些信息包名、版本、描述等并生成一个标准化的项目结构。一个最简化的技能包结构如下所示my-first-skill/ ├── package.json ├── skills/ │ └── my-first-skill/ # 技能目录名字通常与包名对应 │ └── SKILL.md # 技能的“说明书”这是核心文件 └── configs/ # 可选存放针对不同Agent的配置文件 ├── claude/ │ └── desktop-config.json └── cursor/ └── rules.md关键文件解析package.json这是技能的“身份证”和“清单”。除了常规的name,version,description有两个关键字段keywords: [agent-skill]必须包含。这是 skillpm 识别此包为技能的唯一标识。dependencies和devDependencies你可以在这里声明依赖的其他 npm 包包括其他技能包。skillpm 会通过 npm 自动处理这些依赖。skills/skill-name/SKILL.md这是技能的核心。它遵循 Agent Skills 规范 是一个 Markdown 文件其中定义了技能名称和描述告诉 AI 这个技能是干什么的。指令Instructions这是最重要的部分用自然语言详细描述该技能的功能、使用方式、输入输出示例、限制条件等。AI Agent 会读取这些指令来学习如何使用该技能。能力Capabilities声明技能提供的具体功能如文件读写、命令执行、API调用等。配置项定义技能所需的配置参数如 API 密钥、服务器地址等。configs/目录可选如果你需要为特定的 Agent 提供默认的配置文件、提示词模板或规则可以放在这里。例如configs/claude/desktop-config.json可以包含 Claude Desktop 特有的配置。当技能被安装时skillpm 会自动将这些配置文件并添加前缀以避免冲突复制到工作区根目录供 Agent 读取。4. 技能开发详解构建一个实用的代码审查技能让我们以一个更复杂的例子——“自动代码审查技能”为例深入讲解开发过程中的细节和最佳实践。4.1 项目初始化与元数据定义首先我们创建一个更专业的包名通常使用 scope 来分组。npx skillpm init # 包名输入my-org/code-review-skill # 描述An AI-powered skill to review pull requests and suggest improvements.生成的package.json雏形如下。我们需要手动完善它{ name: my-org/code-review-skill, version: 0.1.0, description: An AI-powered skill to review pull requests and suggest improvements., keywords: [agent-skill, code-review, pr, static-analysis], main: index.js, // 对于纯指令的技能这个可能用不到但保留无妨 scripts: { test: echo \Error: no test specified\ exit 1 }, dependencies: { // 假设我们的技能需要调用 GitHub API 和 ESLint octokit/rest: ^20.0.0, eslint: ^9.0.0 }, devDependencies: { // 开发依赖如TypeScript、测试框架 typescript: ^5.0.0, types/node: ^20.0.0 }, skillpm: { // skillpm 特有的配置项 mcpServers: { // 声明本技能提供或依赖的 MCP 服务器 github: ./mcp-servers/github-server.js, code-analyzer: ./mcp-servers/analyzer-server.js } }, author: Your Name, license: MIT }关键点skillpm.mcpServers字段是我们声明 MCP 服务器的地方。当这个技能被安装时skillpm 会读取这个配置并调用add-mcp工具将其注册到 Agent。这意味着即使技能包本身没有可执行的main入口它也能通过 MCP 为 AI 提供强大的后端服务。4.2 编写核心技能指令SKILL.mdskills/code-review-skill/SKILL.md文件是灵魂。它的质量直接决定了 AI 使用该技能的效果。# Code Review Assistant ## Description This skill enables the AI agent to perform automated code reviews on GitHub pull requests. It can fetch PR diff, run static analysis (ESLint), check for common security issues, and generate constructive review comments. ## Capabilities - **read:github_pr**: Read pull request details and diff from a specified GitHub repository. - **execute:eslint**: Run ESLint on provided code snippets or file paths to identify style and potential error issues. - **analyze:security**: Perform basic security pattern checks (e.g., hardcoded secrets, SQL injection patterns). - **write:github_comment**: Post review comments back to the GitHub pull request. ## Instructions ### For the AI Agent: You are now equipped with the Code Review Assistant skill. Use this skill when the user asks you to review code, especially code within a GitHub pull request context. #### How to use: 1. **Initialize Review**: - Ask the user for the GitHub repository URL and the pull request number. - Use the read:github_pr capability to fetch the PR title, description, and the unified diff. 2. **Analyze Changes**: - Parse the diff to identify added/modified files and code snippets. - For each JavaScript/TypeScript file changed, use the execute:eslint capability with appropriate rulesets (recommended: eslint:recommended and plugin:security/recommended). - Scan the diff lines for obvious security anti-patterns using analyze:security (look for patterns like eval(, localStorage with sensitive data, potential XSS strings). 3. **Generate Feedback**: - Categorize findings: - **Critical**: Security vulnerabilities, runtime errors. - **Warning**: Code style violations, potential performance issues, missing error handling. - **Suggestion**: Improvements for readability, better naming, or architectural hints. - For each finding, provide: - The file path and line number. - A concise description of the issue. - A suggested fix or code snippet. - A link to relevant documentation (if applicable). 4. **Deliver Results**: - Summarize the review at the top (e.g., “Found 2 critical issues, 5 warnings, and 3 suggestions”). - Ask the user if they would like you to post these comments directly to the GitHub PR using the write:github_comment capability. **Always get explicit user consent before posting.** ### Configuration This skill requires the following environment variables to be set in the agents workspace: - GITHUB_TOKEN: A Personal Access Token with repo scope to read PRs and post comments. - ESLINT_CONFIG_PATH: (Optional) Path to a custom ESLint configuration file. Defaults to built-in recommended rules. ### Examples **User**: Can you review PR #42 in https://github.com/my-org/my-app? **Agent (using this skill)**: 1. Sure, Ill review PR #42. Ill need a GitHub Personal Access Token with repo permissions. Do you have one set as GITHUB_TOKEN in this workspace, or shall I guide you to create one? 2. (After token is provided) Fetching PR details... Analyzing changes... Ive found 1 critical security issue regarding a potential SQL injection in api/db.js, and 3 style warnings in src/components/Button.js. Would you like me to post these as comments on the PR, or just present them here for you?这份指令写得非常详细它不仅仅是告诉 AI“你有这个能力”而是给出了一个完整的“工作流程”和“思维链”。它教 AI 如何一步步地使用各个子能力如何处理边界情况如获取用户授权以及如何组织输出。这是编写高质量技能的关键。4.3 实现 MCP 服务器进阶对于简单的技能可能只需要指令SKILL.md就够了。但对于我们这个代码审查技能我们需要真正的后端逻辑来调用 GitHub API 和运行 ESLint。这就是 MCP 服务器的用武之地。我们在package.json中声明了两个 MCP 服务器。现在我们需要创建它们。在项目根目录创建mcp-servers/目录。mcp-servers/github-server.js(简化示例):// 这是一个使用 Node.js 和 MCP 标准库的简单示例 const { McpServer } require(modelcontextprotocol/sdk/server); const { Octokit } require(octokit/rest); const server new McpServer({ name: github-code-review, version: 0.1.0, }); // 定义一个工具Tool对应技能指令中的 read:github_pr 能力 server.tool( read_github_pr, { repository: { type: string, description: Full repo name (e.g., octocat/Hello-World) }, pr_number: { type: number, description: Pull request number }, }, async ({ repository, pr_number }) { const token process.env.GITHUB_TOKEN; if (!token) { throw new Error(GITHUB_TOKEN environment variable is not set.); } const octokit new Octokit({ auth: token }); try { const { data: pr } await octokit.rest.pulls.get({ owner: repository.split(/)[0], repo: repository.split(/)[1], pull_number: pr_number, }); const { data: files } await octokit.rest.pulls.listFiles({ owner: repository.split(/)[0], repo: repository.split(/)[1], pull_number: pr_number, }); return { content: [ { type: text, text: # PR #${pr_number}: ${pr.title}\n\n${pr.body}\n\n## Files Changed:\n${files.map(f - ${f.filename} (${f.status}, ${f.additions}, -${f.deletions})).join(\n)}\n\n## Diff:\n\\\diff\n${files.map(f f.patch).join(\n---\n)}\n\\\, }, ], }; } catch (error) { return { content: [{ type: text, text: Error fetching PR: ${error.message} }], isError: true, }; } } ); // 同样可以定义 write_github_comment 工具 server.tool(write_github_comment, ...); // 启动服务器skillpm/add-mcp 会管理服务器进程 server.start();这个 MCP 服务器暴露了一个工具read_github_pr。当 AI Agent 需要执行代码审查时它会通过 MCP 协议调用这个工具并传入参数repository和pr_number。服务器执行实际的 GitHub API 调用并将结果格式化后返回给 AI。mcp-servers/analyzer-server.js则会类似地封装 ESLint 的调用。通过这种方式技能的逻辑被安全地封装在后端服务器中。AI 只需要知道“调用什么工具、传什么参数、怎么解释结果”而不需要直接处理 API 密钥或运行复杂的代码分析引擎。4.4 本地测试与调试在发布之前你需要在本地测试你的技能。由于 skillpm 支持 monorepo 工作区这是非常方便的。在技能目录下确保你的package.json和SKILL.md等文件都已就绪。在工作区根目录即你希望使用技能的项目将你的技能作为本地依赖链接。如果你的工作区根目录有package.json你可以使用 npm workspaces 或npm link。更简单的方式在工作区根目录运行skillpm sync。如果 skillpm 在node_modules中发现了通过 symlink 链接的本地技能包比如你用了npm link ../my-first-skill它会自动识别并处理它们输出类似Linking workspace package my-org/code-review-skill0.1.0的信息。启动你的 AI Agent如 Claude Desktop。在它的技能设置中你应该能看到你的技能被自动加载了。与 Agent 对话尝试触发你的技能指令。观察 AI 是否正确地理解了技能描述并尝试调用你定义的 MCP 工具。你需要在 MCP 服务器控制台查看日志以确认调用是否成功。避坑技巧MCP 服务器调试MCP 服务器是独立进程。在开发时建议先单独运行你的服务器脚本 (node mcp-servers/github-server.js)确保它能正常启动和响应。使用curl或 Postman 模拟 MCP 调用进行测试。然后再通过skillpm sync集成到 Agent 中。这样可以隔离问题确定是技能指令问题、MCP 协议问题还是 Agent 集成问题。5. 发布、共享与团队协作开发测试完成后是时候分享你的成果了。5.1 发布到 npm 仓库发布流程和发布普通 npm 包完全一致。# 1. 确保你已经登录 npm (如果没有运行 npm login) npm whoami # 2. 在技能项目根目录运行 skillpm publish # 它会做两件事a) 运行 npm publish b) 验证你的 package.json 包含 agent-skill 关键词。 skillpm publish发布成功后你的技能包就可以被全世界或你的组织内如果使用私有仓库通过skillpm install my-org/code-review-skill来安装了。5.2 管理技能依赖与版本技能包之间可以相互依赖这是 skillpm 带来的最大优势之一。例如你可以创建一个utility-helper-skill包里面包含一些通用的指令模板和工具函数。然后你的code-review-skill可以在package.json中依赖它{ name: my-org/code-review-skill, dependencies: { my-org/utility-helper-skill: ^1.0.0 } }当用户安装code-review-skill时utility-helper-skill会被自动安装。这促进了技能的模块化和复用。版本控制策略遵循语义化版本控制SemVer主版本号.次版本号.修订号。当技能指令SKILL.md有重大不兼容更新时升级主版本号。当新增功能但向下兼容时升级次版本号。当只修复问题或做微小改进时升级修订号。在package.json中为依赖指定合适的版本范围如^1.2.3以便用户能自动获得安全修复和兼容的功能更新。5.3 团队协作与 Monorepo 工作流对于团队开发多个相关技能skillpm 完美支持 npm workspaces monorepo。项目结构示例my-ai-skills-monorepo/ ├── package.json (workspaces: [packages/*]) ├── packages/ │ ├── utility-helpers/ (技能包) │ │ ├── package.json │ │ └── skills/... │ ├── code-review/ (技能包) │ │ ├── package.json (依赖 utility-helpers) │ │ └── skills/... │ └──>
