ARTICLE · 1393257
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 的子组件之一。先在本地技能目录散装试跑,稳定了再装进插件发出去。
03 · 边界问题:什么情况用哪个
记忆口诀:连不上→MCP,做不对→Skill,管不住→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
✂️ - - - - - 这张卡先记到这里,新资料后续分享 - - - - -















































































