skill Plugin

skill 是 Agent 的本地技能目录。它负责发现当前可见的 Skill、读取 SKILL.md，并把可用 Skill 与扫描区域注入 system prompt。

find 和 install 是纯提示 action：它们根据输入和 SkillPlugin 的实际扫描配置返回 Shell 操作提示，但不会执行命令、访问网络或修改文件。Agent 再按提示使用 skills CLI。

注册

import { Agent, Workspace } from "@downcity/agent";
import { SkillPlugin } from "@downcity/plugins/skill";

const agent = new Agent({
  id: "skill-helper",
  workspace: new Workspace({ path: "/path/to/project" }),
  plugins: [new SkillPlugin()],
});

默认只扫描当前项目的 .agents/skills。

可以通过构造参数扩展扫描范围：

const skill_plugin = new SkillPlugin({
  use: ["project", "home"],
  paths: [".agents/shared-skills"],
  ignore: ["legacy-skill"],
});

• use: ["project"]：扫描 <project>/.agents/skills
• use: ["home"]：扫描 ~/.agents/skills
• paths：添加自定义扫描目录；相对路径基于项目根目录解析
• ignore：按 Skill ID、名称、正则或判断函数排除 Skill

发生同 ID 冲突时，优先级为 project > paths > home。

Actions

Skill Plugin 提供四个 action：

列出 Skill：

const result = await agent.plugins.run_action({
  plugin: "skill",
  action: "list",
  payload: {},
});

读取 Skill：

const result = await agent.plugins.run_action({
  plugin: "skill",
  action: "lookup",
  payload: {
    name: "web-access",
  },
});

模型在 Session 中使用相同协议：

plugin_call({
  plugin: "skill",
  action: "lookup",
  payload: {
    name: "web-access",
  },
});

查找和安装

调用 find 获取查找提示：

const find_instructions = await agent.plugins.run_action({
  plugin: "skill",
  action: "find",
  payload: {
    query: "web access",
  },
});

调用 install 获取安装提示：

const install_instructions = await agent.plugins.run_action({
  plugin: "skill",
  action: "install",
  payload: {
    spec: "owner/repository@web-access",
  },
});

两个 action 都只在返回结果的 data.prompt 中提供操作说明。system prompt 会列出实际扫描目录，并引导 Agent 调用这两个 action；install 提示再根据当前实例的 use / paths 动态列出：

• 实际扫描目录和扫描顺序
• 每类扫描目录对应的安装方式
• 安装后的验证要求

find 提示会引导 Agent 使用当前可用的 Web 或浏览器能力搜索以下 Skill 目录：

• skills.sh
• LobeHub Skill 社区

同时也会提供 npx skills find 命令，便于结合目录页面与 CLI 结果确定安装 spec。

查找缺失 Skill 使用 Shell：

npx -y skills find "<query>"

安装到项目扫描区域：

npx -y skills add "<spec>" -y

只有配置包含 use: ["home"] 时，才应选择全局安装：

npx -y skills add "<spec>" -g -y

自定义 paths 没有统一的 skills CLI 目标参数。安装或复制后，最终结构必须是：

<configured-root>/<skill-id>/SKILL.md

安装验证提示

install action 不会在代码层执行或验证安装。它返回的提示词会要求 Agent 在 Shell 命令完成后调用：

plugin_call({
  plugin: "skill",
  action: "list",
  payload: {},
});

如果新 Skill 出现在 list 结果中，提示词会继续引导 Agent 调用 lookup。整个流程由提示词驱动，不是 action 内部的强制状态机。

完整流程是：

1. 调用 list 确认本地是否已经存在。
2. 缺失时调用 find，再按返回提示通过 Shell 执行查找。
3. 选定 spec 后调用 install，再按返回提示选择扫描区域并执行安装。
4. 再次调用 list 验证是否可发现。
5. 调用 lookup 读取 SKILL.md。

System Prompt

每次构建 Session system prompt 时，Skill Plugin 会重新扫描配置的根目录，并注入：

• 当前可用 Skill 的名称与描述
• 当前扫描根及其解析后的真实路径
• 缺失 Skill 应调用 find/install action 的工作流

具体命令和安装后的 list 检查提示由 action 返回。install action 使用同一份扫描配置，不会把项目安装或全局安装写死。

相关文档

• 内建 Plugin 总览
• Plugin Actions
• Plugin System