夜雨聆风学习资料网

ARTICLE · 1393257

AGENT 手账:插件 vs 技能 - Agent 扩展机制拆解

AGENT 手账:插件 vs 技能 - Agent 扩展机制拆解

AGENT 手账 · No.01

插件 vs 技能:Agent 扩展机制拆解

一张卡讲清 MCP / Skills / Hooks / Plugins 各是什么、什么时候用、怎么做

01 · 一页看懂:四层机制各管什么

以生态最完整的 Claude Code 扩展体系为骨架,Codex、Cursor、OpenCode 等主流 Agent 都在跟进类似分层。一句话总纲:MCP 装手脚,Skills 教方法,Hooks 立规矩,Plugins 打包快递。

🔌 MCP · 连接层

开放协议,像给模型加「USB-C 接口」:暴露 Tools / Resources / Prompts 三类能力,解决「连得上外部系统」,模型主动调用工具。

📘 Skills · 执行层

Markdown 写的「工作流说明书」:SKILL.md + 脚本 + 参考资料,解决「任务做得对、有套路」,按 description 自动触发或手动调用。

🪝 Hooks · 切面层

生命周期钩子脚本(官方 29 个事件):PreToolUse 可拦截危险命令,解决「动作前后自动做什么」。事件驱动,几乎不耗 token。

📦 Plugins · 分发层

把上面三样 + 命令 + 子代理打包:plugin.json 清单 + marketplace 市场元数据,解决「怎么分享给团队/市场」,安装即加载。

✏️ 批注:插件不是新功能,是「快递包裹」——里面装的商品才是 Skills / Hooks / MCP 配置。

02 · 插件 vs 技能:核心区别对照

维度
技能 Skill
插件 Plugin
本质
一份 SKILL.md 工作流指令 + 可选脚本/资料,教 Agent「怎么做某类事」
分发容器,打包 Skills、Commands、Agents、Hooks、MCP 配置
载体
目录:技能名/SKILL.md(YAML 头 + 正文)
目录:.claude-plugin/plugin.json 清单 + 功能子目录
触发
斜杠命令或按 description 自动匹配
安装即加载,内部组件按各自方式触发
命名空间
直接用技能名(/hello)
带插件前缀(/plugin-name:hello)防冲突
版本管理
无,手动维护文件
语义化版本,可 install / update / publish
token 成本
三级渐进披露:元数据常驻(约 100 token)→ 正文触发才载(建议 ≤5k)→ 脚本按需读
清单轻量;内部技能仍按三级披露计费
适合谁
个人、单项目、快速沉淀团队共享、跨项目复用、市场分发

✏️ 关系不是二选一:Skill 是 Plugin 的子组件之一。先在本地技能目录散装试跑,稳定了再装进插件发出去。

03 · 边界问题:什么情况用哪个

记忆口诀:连不上→MCP,做不对→Skill,管不住→Hook,传不开→Plugin。

要连外部系统?
GitHub / 数据库 / 网盘 / IM……核心是「取数据、调服务」→ MCP
要固化流程?
代码审查、周报、提交规范……同一套提示词写过 3 次以上 → Skill
要自动拦截/格式化?
写文件后自动 prettier、拦截 rm -rf → Hook
要分享给别人?
整套配置交付团队、跨项目复用、上市场 → Plugin

✅ 选 / 做 Skill 当你:同一套提示词反复手写 ≥3 次;有固定步骤和输出格式但不需要新工具;沉淀领域知识(项目规范、分析套路、写作模板);个人项目、快速实验。

✅ 选 / 做 Plugin 当你:要把「技能 + 命令 + 钩子 + MCP 配置」整套交付给团队;跨项目复用并需要版本号、更新、回滚;要发布到插件市场(官方市场已收录 300+ 插件);需要捆绑子代理定义。

04 · 怎么做技能:SKILL.md 六步法

① 明确用例(举 3 个例子)→ ② 规划内容(哪些写成脚本/参考)→ ③ 初始化骨架 → ④ 编写并实测脚本 → ⑤ 打包验证 → ⑥ 实用后迭代

# 一个技能 = 一个目录

docx-processor/

├── SKILL.md        # 必需:YAML头 + 正文

├── scripts/        # 可执行脚本

├── references/     # 详细参考文档

└── assets/         # 模板等静态资源

# SKILL.md 头部(只有这两项必需)

---

name: docx-processor

description: "处理 Word 文档……

  当用户需要创建报告/提取内容

  /转换格式时使用。"

---

⭐ 高质量技能七原则(源自官方 skill-creator):

  • 短
    :上下文窗口是公共资源,正文 ≤500 行,细节拆到 references/
  • 准
    :description 是写给 AI 的触发条件——「做什么 + 何时用」,正文里再写何时用是无效的
  • 分
    :三级渐进披露,信息只存一处不重复
  • 祈使句
    :「运行脚本检查」,不写「你应该…」
  • 按任务给自由度
    :发邮件→文字指令即可;导财务报表→写死脚本少留参数
  • 不放无关文件
    :README / CHANGELOG 对 AI 没用
  • 试
    :脚本必须实际跑通

📎 Agent Skills 已是开放规范(agentskills.io),Claude Code / Codex / Cursor / Copilot 等通用。

05 · 怎么做插件:从目录到市场

my-plugin/

├── .claude-plugin/# 必需!缺了不识别

│   ├── plugin.json# 清单(必需)

│   └── marketplace.json# 市场分发才需要

├── skills/<name>/SKILL.md

├── commands/review.md   # 文件名即命令

├── agents/reviewer.md   # 子代理定义

├── hooks/hooks.json     # 自动识别,无需声明

└── README.md

# plugin.json 关键字段

{

"name": "code-quality",   // kebab-case 唯一

"version": "1.2.0",       // 语义化版本

"skills": ["./skills/"],  // 目录自动加载

"commands": ["./commands/"],

"agents": ["./agents/"]   // 须显式路径

}

# 安装测试

claude plugin install ./

claude plugin list

claude plugin validate .claude-plugin/plugin.json

🍯 避坑便签(高频踩坑实录)

  • 技能不自动触发
     → 九成是 description 没写清「何时用」
  • 插件装不上
     → 检查 .claude-plugin/plugin.json 是否存在、JSON 是否合法
  • agents 字段
    要显式路径;hooks 目录别写进 plugin.json(会自动识别)
  • Hook 不拦截
     → 只有 exit 2 才真正阻止;输入经 stdin 传 JSON,用 jq 解析
  • 先散装迭代,稳定后再封装插件;命名统一 kebab-case
  • CLAUDE.md 管项目背景(始终生效),Skill 管任务流程(触发叠加)——别把背景知识写成技能

📚 摘录来源(2026-11 检索)

OSCHINA《MCP、Skills、Plugins、Hooks:Claude Code 四大扩展机制完整解析》 · fly63《如何写出高质量的 AI Skill:7 个原则》 · CSDN《从零开发 Claude Code 插件完整指南》 · 官方文档 code.claude.com/docs

✂️ - - - - - 这张卡先记到这里,新资料后续分享 - - - - -

回首页,搜索你想要的文档

在首页搜索框输入关键词,快速定位资料

文库首页搜索指引 立即搜索

相关学习资料