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

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

配置层做了什么

skill 当前有 project 级配置。

这说明：

当前项目可以有自己的 skill plugin 配置
这份配置属于插件配置，而不是某个具体 skill 的内容

对于大多数用户来说，skill 的重点不在复杂配置，而在 action 工作流。

主要动作

Action	作用	推荐用法
`find`	查找未学会 skill，并给出下一步	先判断要不要 install
`install`	安装 skill	安装完后立刻接 `lookup`
`list`	列出本地已学会 skill	想先看当前能力目录
`lookup`	读取 skill 的 `SKILL.md`	真正使用 skill 前必做

场景化用法示例

先找 skill

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

这个动作的重要意义不是“帮你自动完成一切”，而是给出当前状态判断：

skill 是不是已经在本地
如果不在，下一步是不是该 install

安装 skill

const result = await agent.plugins.runAction({
  plugin: "skill",
  action: "install",
  payload: {
    spec: "web-access",
    global: true,
    yes: true,
    agent: "claude-code",
  },
});

安装成功后，返回结果会强调下一步应该 lookup。

列出已学会 skill

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

这个动作最适合：

做能力面板
调试当前环境到底学过什么
在真正执行任务前先看本地技能目录

读取 skill 内容

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

lookup 的关键价值是：

找到 skill 元信息
读取 SKILL.md
生成适合后续注入的 skill 内容消息

所以它是“真正开始使用 skill”之前最关键的一步。

`system` 在这里起什么作用

skill 不只是一组 action。

它还会把当前 skill 概览注入 system prompt，让 agent 在运行时知道：

当前环境有哪些 skills
哪些 skill 已经学会
应该如何把 skill 用作外部能力边界

这能显著降低“skill 已安装，但 agent 当前上下文不知道它存在”的问题。

它和 skill 本身的边界

最容易混淆的一点是：

skill plugin 不是 skill
skill plugin 管的是 skill 的发现、安装、读取与可见性

换句话说：

plugin 是“技能目录系统”
具体 skill 是“被目录管理的能力单元”

它的自然边界

skill 不需要长期持有后台实例。

它更像一个：

目录查询层
安装入口层
内容注入层

如果你要做的事情主要是“发现并引入外部能力说明”，那优先考虑这种 plugin 模式。

常见边界与误区

`install` 不等于“现在就能正确使用”

安装完成只是第一步。

如果 agent 没有读取 skill 内容，它仍然可能不会按正确方式使用这个 skill。

`lookup` 很重要

很多场景里，真正决定 agent 是否“已经学会”某个 skill 的，不只是本地文件是否存在，而是当前执行上下文有没有把 skill 说明读进来。

这个 plugin 更偏工作流编排

它的强项不是复杂运行时状态，而是把“找、装、读、用”变成清晰的步骤。

什么时候优先参考它

如果你要设计这些能力，优先参考 skill：

显式 action 驱动型 plugin
本地目录发现
安装后再读取内容
通过 system 暴露当前已学会能力