Week 1 · D6About 5 hours

Organizing and Distributing: Plugins and Marketplaces, Versioning and Team Sharing, and the Division of Labor Between Function Calling, MCP, and Skills

Go from one person's folder to a team's capability pack: how to organize a plugin, how to publish to a marketplace, how to version it, and exactly what function calling, MCP, and Skills each handle and when to reach for which.

Today's goals 0/3

能把一组 skill 打成一个带清单与版本的插件包并在本地加载验证
能说清团队共享 skill 的三条路径与各自的适用场景
能用一张对比表讲清函数调用、MCP 与 Skills 的分工，并给出选型判据

今日目标

能把一组 skill 打成一个带清单与版本的插件包并在本地加载验证
能说清团队共享 skill 的三条路径与各自的适用场景
能用一张对比表讲清函数调用、MCP 与 Skills 的分工，并给出选型判据

前五天你做出来的东西，都还只在你自己那台机器上。今天把它交出去：一组 skill 怎么打成一个包、怎么发布、怎么升版本、团队十几个人怎么共用一套。最后再还上这门课从第一天就欠你的那笔账——函数调用、MCP 与 Skills 三者到底各管什么。读完正文、做完实验之后，回到页面顶部把三条目标勾掉。

小白版讲解

从一个文件夹到一个包

回到档案柜。你手上现在有五六本作业指导书，散着放也不是不能用。但你要把它们交给隔壁部门的时候，问题立刻冒出来：他们那儿也有一本叫「季度报表」的，撞名了；你后来改了其中两页，他们不知道该不该更新；他们只想要其中三本，另外两本跟他们无关。

这三个问题——命名空间、版本、边界——就是打包要解决的全部。 一个包不是一堆文件夹的压缩，它是一次「这几本是一套，一起给，一起升」的声明。

什么时候该合并成一个包？判据是它们是否一起被采纳、一起被淘汰。三个都围着同一套团队规范转，谁装了都得装全套，那就是一个包。一个是团队规范、一个是你个人的调试习惯，凑在一起只会逼别人接受他不想要的那半边。

反过来，什么时候该把一个 skill 拆成两个？判据在第三天讲过，这里只提一句它的包级推论：如果两个部分的触发场景不重叠，它们就不该共用一条描述。 打包不能救一个边界模糊的 skill，只会把模糊放大到整个团队。

插件的目录结构与清单

规范本身只定义「一个 skill 是一个含 SKILL.md 的文件夹」，它不管分发。所以「包」这一层是各家客户端自己的机制，各家叫法与细节不同，得按你实际用的那家来。下面以 Claude Code 的插件为例，因为它是目前公开文档最完整的一套，读懂它再看别家会很快。

一个插件就是一个目录，根下放一份清单，各类组件按约定目录摆开：

TextText

team-conventions/
├── .claude-plugin/
│   └── plugin.json          # 清单：名字、描述、版本、作者
├── skills/
│   ├── commit-message/SKILL.md
│   ├── code-review/SKILL.md
│   └── release-report/SKILL.md
├── agents/                  # 可选：子代理定义
├── hooks/hooks.json         # 可选：事件钩子
├── .mcp.json                # 可选：随包带的 MCP server 配置
└── README.md

清单本身极短，四个字段：

JSONJSON

{
  "name": "team-conventions",
  "description": "某团队的提交、评审与发布规范，装上即生效",
  "version": "1.2.0",
  "author": { "name": "Platform Team" }
}

四个字段里有两条容易踩的规矩。

第一，name 就是命名空间。 包里的 skill 会被前缀成「包名冒号技能名」的形式，比如 team-conventions:commit-message。这就解决了开头那个撞名问题：两个包各带一个 commit-message，装在一起也不会打架。改包名等于改掉所有技能的调用名，所以名字要一次想好。

第二，组件目录必须在插件根下，不能塞进清单那个目录里。 skills/、agents/、hooks/ 全在根，.claude-plugin/ 里只放 plugin.json 一个文件。这是官方文档专门标出来的最常见错误，装不上时先查这一条。

这两条都是结构问题，而结构问题最适合用一段十几行的脚本挡在门口。下面这个自检做三件事：确认清单在专用目录里、确认没有把组件目录错放进去、确认每个 skill 都有描述。发包前跑一次，比装上之后再排查省事得多。

check-pack.ts

import { readFileSync, readdirSync, existsSync } from 'node:fs'
import { join } from 'node:path'
 
const COMPONENT_DIRS = ['skills', 'agents', 'hooks', 'commands']
 
export function checkPack(root: string): string[] {
  const errors: string[] = []
  const manifestPath = join(root, '.claude-plugin', 'plugin.json')
  if (!existsSync(manifestPath)) return [`清单不存在：${manifestPath}`]
 
  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as Record<string, unknown>
  for (const key of ['name', 'description', 'version']) {
    if (!manifest[key]) errors.push(`清单缺少 ${key}`)
  }
  // 最常见的错误：把组件目录塞进了清单所在的目录
  for (const dir of COMPONENT_DIRS) {
    if (existsSync(join(root, '.claude-plugin', dir))) {
      errors.push(`${dir}/ 必须放在插件根下，不能放进 .claude-plugin/`)
    }
  }
  const skillsDir = join(root, 'skills')
  if (!existsSync(skillsDir)) return [...errors, '没有 skills/ 目录']
 
  for (const name of readdirSync(skillsDir)) {
    const file = join(skillsDir, name, 'SKILL.md')
    if (!existsSync(file)) {
      errors.push(`${name}/ 里没有 SKILL.md，它不会被当成 skill`)
      continue
    }
    // 缺描述的 skill 永远不会被触发，发出去等于没发
    if (!/^description:\s*\S/m.test(readFileSync(file, 'utf8'))) {
      errors.push(`${name} 缺少 description`)
    }
  }
  return errors
}

check_pack.py

import json
import re
from pathlib import Path
 
COMPONENT_DIRS = ["skills", "agents", "hooks", "commands"]
 
 
def check_pack(root: Path) -> list[str]:
    errors: list[str] = []
    manifest_path = root / ".claude-plugin" / "plugin.json"
    if not manifest_path.exists():
        return [f"清单不存在：{manifest_path}"]
 
    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
    for key in ("name", "description", "version"):
        if not manifest.get(key):
            errors.append(f"清单缺少 {key}")
    # 最常见的错误：把组件目录塞进了清单所在的目录
    for name in COMPONENT_DIRS:
        if (root / ".claude-plugin" / name).exists():
            errors.append(f"{name}/ 必须放在插件根下，不能放进 .claude-plugin/")
 
    skills_dir = root / "skills"
    if not skills_dir.exists():
        return errors + ["没有 skills/ 目录"]
 
    for entry in sorted(skills_dir.iterdir()):
        skill_md = entry / "SKILL.md"
        if not skill_md.exists():
            errors.append(f"{entry.name}/ 里没有 SKILL.md，它不会被当成 skill")
            continue
        # 缺描述的 skill 永远不会被触发，发出去等于没发
        if not re.search(r"^description:\s*\S", skill_md.read_text(encoding="utf-8"), re.M):
            errors.append(f"{entry.name} 缺少 description")
    return errors

开发期不用发布也不用安装，用一个命令行参数直接把本地目录挂进去就能试；改完跑一次重载命令，不必重启。这个开发模式是今天实验的主线——包做出来第一件事就是本地加载，逐个触发一遍，确认命名空间对得上。

市场与版本

包做好了，别人怎么拿到？靠市场。市场听着像个商店，实际上朴素得多：一个仓库，根下放一份 marketplace.json，里面列出这个市场提供哪些包、每个包从哪儿取。

JSONJSON

{
  "name": "acme-tools",
  "owner": { "name": "Platform Team" },
  "plugins": [
    { "name": "team-conventions", "source": "./plugins/team-conventions", "version": "1.2.0" },
    { "name": "deploy-tools", "source": { "source": "github", "repo": "acme/deploy-plugin" } }
  ]
}

来源可以是市场仓库里的相对路径，也可以是另一个 Git 仓库、一个 npm 包、一个压缩包地址。这意味着市场是一层索引，不一定持有内容——你可以把一个只有清单文件的仓库当市场，包体各自躺在原来的地方。

用户那边只有两步：添加市场，然后按「包名 at 市场名」安装。

版本是这里唯一需要动脑子的地方，规则要记准：

写了 version 就以它为准，用户只有在这个值变了的时候才会收到更新。 不写的话，Git 来源会拿解析出来的提交哈希当版本，你每推一次内容用户就更一次。前者可控，后者省事，团队内部用后者也行，对外发布必须写死版本。

版本别在两处都写。 包自己的清单优先级更高，两边不一致时你会得到一个自己都解释不清的状态。

什么改动要升版本？ 判据不是「改没改文件」，而是「用户的行为会不会因此变化」。描述改了、正文里的步骤改了、脚本的参数改了——升。修个错别字、补一段注释——不用。这跟你给库发版是一个道理，只不过这里的接口不是函数签名，是描述与正文。

团队共享的三条路径

十几个人要共用一套 skill，有三条路，按「谁装、谁管、谁能改」来选。

第一条，随仓库走。 直接把 skill 放进项目的 .agents/skills/，跟着代码提交。优点是零基础设施、拉下代码就有、评审走的还是那套 Pull Request 流程。缺点是只对这个仓库成立，五个仓库就要维护五份拷贝。只跟某一个代码库有关的规范，选它，不要犹豫。

第二条，走市场。 建一个市场仓库，团队成员各自添加一次，之后按需安装、自动收更新。优点是一处维护多处生效、有版本、有升级说明。缺点是多了一次「让每个人去添加市场」的推广成本。跨仓库的团队规范选它。

第三条，走组织托管。 由管理侧统一下发，成员不需要自己添加也不能随便关掉。优点是覆盖率有保证、合规能审计。缺点是流程重、迭代慢。只有必须强制、且不装就出事的规范才值得走这条路，比如涉及安全和合规的那几条。

三条路不互斥。常见的稳定组合是：安全合规那两条走组织托管，跨仓库的团队规范走市场，某个项目独有的怪癖随那个仓库走。

函数调用、MCP、Skills 三者完整对比

这门课从第一天就欠着这张表。先给一句能背下来的分工：MCP 管接线，Skills 管经验，上下文工程管取舍；而函数调用，是接线之前那根最短的线。

维度	函数调用	MCP	Skills
补的是什么缺口	能力：模型本来做不了	能力的接线方式：让工具与数据以统一协议接进任何 Agent	经验：模型做得了，但不知道你们这儿怎么做
具体形态	一段参数 schema 加你自己的一段代码	一个进程或一个 HTTP 端点，对外暴露工具、资源与提示模板	一个含 SKILL.md 的文件夹
谁真正执行	你的应用	服务端	模型按指令自己做，必要时跑包里的脚本
每轮固定开销	全部工具定义随每轮重发	同上，且多个服务端会叠加	只有名字与描述，正文按需加载
复用边界	绑死在你这一个应用里	跨 Agent、跨客户端，接一次多处可用	跨客户端，复制一个文件夹就行
谁来写、谁来维护	应用工程师	服务端作者	拥有这份经验的人，不一定会写代码
装不上时会怎样	功能直接缺失	功能直接缺失	退化成一份人能读的 Markdown
典型场景	只有这个应用要用、数量不多的几个动作	数据在别的系统里，或同一套能力要给多个 Agent 用	团队规范、多步流程、领域惯例

表里最值得单独拎出来的是最后两行。

「装不上时会怎样」这一行解释了 skill 为什么便宜。 工具与协议是二值的：接上了才有，接不上就没有。而一个 skill 装不上，它仍然是一份写得清清楚楚的 Markdown，人能读，另一个客户端也能读。这是它能在几十家客户端里横着铺开的根本原因——它不要求宿主实现任何协议，只要求宿主会读文件。

「谁来写」这一行决定了它们在组织里的位置。 函数和服务端只能由工程师产出，而 skill 可以由那个真正懂业务的人写，工程师最多帮忙审一遍。经验的持有者和代码的持有者本来就常常不是同一批人，skill 第一次让前者能直接交付。

最后要说清楚：三者不是替代关系，配合起来才是常态。 一个典型的组合是——MCP 服务端把公司的工单系统接进来，成了一个可调用的工具；一个 skill 的正文里写着「先用工单查询工具拉出本周所有工单，再按下面这份模板归类，注意状态为已合并的要排除」。工具给它手，skill 给它章法。 协议那一侧怎么设计、怎么防提示注入，姊妹课 7 天 MCP 从头讲了一遍。

选型判据：一张能当场用的流程

面试里被问到「什么时候用哪个」，最好的答法不是复述上面那张表，而是给一条能当场走的判定流程。

Mermaid source

mermaidmermaid

flowchart TB
  A[模型现在做不好这件事] --> B{它是缺能力<br/>还是缺做法}
  B -- 缺能力 做不了 --> C{这个能力只有<br/>这一个应用要用吗}
  C -- 是 --> D[写函数调用<br/>最短的路 不要过度设计]
  C -- 否 多个 Agent 都要 --> E[做成 MCP 服务端<br/>接一次 处处可用]
  B -- 缺做法 做得了但不合规矩 --> F{这份做法<br/>需要确定性执行吗}
  F -- 否 靠指令就够 --> G[写 skill<br/>正文讲清步骤与坑]
  F -- 是 结果必须逐字一致 --> H[写 skill 并配脚本<br/>确定性交给代码]

三个可以直接背的口径：

先分「能力」和「做法」。 这一刀切错，后面全错。判据很朴素：把这件事交给一个足够聪明但不熟悉你们公司的外包，他做不了，是缺能力；他能做但会做得不合你们的规矩，是缺做法。

能力这一侧，按复用面选。 只有这一个应用要用，写函数调用就完了，为它起一个服务端是过度设计；多个 Agent 或多个客户端都要用，才值得走协议。

做法这一侧，按确定性选。 靠指令说清楚就够的，写进正文；结果必须逐字一致的，第四天那三条判据一命中就配脚本。

源码导读

动手实验

🧪 D6 实验：一个含三个 skill 的插件包，清单、目录结构、版本策略与本地加载验证记录

Code location: labs/agent-skills-7days/day-06-skill-plugin-pack

验收标准：

插件目录结构正确：清单在专用目录里，三个 skill 在根下的 skills/ 里，没有把组件目录塞进清单目录。
三个 skill 各写清了边界与「不管什么」，任意两个的触发场景不重叠。
本地开发模式加载成功，三个 skill 各触发一次并记下了带命名空间的调用名。
升级说明区分了「要升版本」与「不用升」两类改动，并且把描述的改动明确归进要升的那一类。
交付文档里有一段「这个包不管什么」，写清了三个 skill 之外的诉求该去找谁。

今天是文档型实验：产出是一个插件包和一份交付文档，不是代码。最容易糊弄过去的是第 2 条和第 5 条——边界写不清楚，包发出去两周就会有人来问「为什么这个场景它不管」。写完之后把三条描述单独抽出来，用第三天那套正负例再跑一遍，确认它们互相不抢。

读 solution 的插件包，看三个 skill 是按什么标准划分边界的。
在 starter 里补全插件清单的名字、描述与版本三个字段。
把前几天写的三个 skill 按插件目录约定摆进去，并各写一句边界说明。
在本地以开发模式加载这个包，逐个触发三个 skill 并记录命名空间。
为这个包写一份升级说明，说清什么改动要升版本、什么改动不用。

面试题

今天 3 道题在下方题库区，侧重 skill 的组织与分发、版本与团队治理、以及三种扩展方式的选型。展开后先看「分析过程」再看要点——照着推导练，比背要点管用。标注「国内高频 / 海外高频」方便按目标市场取舍。

检查清单与明日预告

能把一组 skill 打成一个带清单与版本的插件包并在本地加载验证
能说清团队共享 skill 的三条路径与各自的适用场景
能用一张对比表讲清函数调用、MCP 与 Skills 的分工，并给出选型判据
能说出「描述的每一次改动都是行为变更」这条，并解释为什么它最容易被漏掉
实验的 5 条验收标准全部通过
3 道面试题不看要点也能答出至少 2 道

明天（D7）收口：把一份真实的团队规范文档拆成三个 skill，交给一个干净的子代理去执行一次真实任务，再用一组带断言的评估证明它确实比不带 skill 强——不是感觉更好，是通过率高了多少。最后把这次交付压缩成一条经得起追问的作品集条目。

Interview questions

How do function calling, MCP and Agent Skills relate, and when do you use which?函数调用、MCP 和 Skills 三者的关系是什么？什么时候用哪个？
Common in ChinaCommon overseasIntermediate#agent-skills#mcp#tool-calling#architecture
How to reason about it · think before answering
The most common question in this course. The classic mistake is framing the three as competitors and saying skills are lighter than MCP, when they do not solve the same problem.
Lead with the one-line division: MCP handles wiring, Skills handle experience, and function calling is the shortest wire of all.
Then name the gaps. Function calling and MCP supply capability: the model cannot reach your database or file a ticket until you give it a tool. Skills supply experience: the model can already write a commit message, it just does not know your format.
Give the two most informative contrasts. Context cost: tool definitions are resent every turn, while a skill costs only its name and description per turn with the body loaded on demand. Degradation: tools and protocols are binary, but a skill that fails to install is still readable Markdown, which is exactly why the format spread across dozens of clients. It requires the host to read files, not to implement a protocol.
For selection give a runnable decision path. First separate missing capability from missing method. For capability, choose by reuse surface: one application means function calling, several agents justify an MCP server. For method, choose by determinism: instructions go in the skill body, byte-identical results go in a bundled script.
Close on composition. The normal case stacks them: an MCP server exposes the ticket system as a tool, and a skill body says to pull this week's tickets with that tool and then group them by a template. Tools give hands, skills give procedure.
Expected follow-up: when should you not use MCP? When only one application needs it and there are just two or three actions. Standing up a server is over-engineering.
分析过程 · 先想清楚再作答
这是本课最高频的一题。答错的典型是把三者摆成竞争关系，说「Skills 比 MCP 更轻量所以更好」——它们解决的根本不是同一个问题。
先给一句能背下来的分工：**MCP 管接线，Skills 管经验**，而函数调用是接线之前那根最短的线。
再落到缺口上。函数调用与 MCP 补的是**能力**：模型本来读不到你的数据库、发不出工单，给它工具它就能了。Skills 补的是**经验**：模型本来就会写提交信息，只是不知道你们这儿的格式。能力的缺口用工具补，经验的缺口用技能补。
然后给两条对比里最有信息量的差异。第一，上下文成本：工具定义每一轮都要重发，而 skill 每轮只有名字与描述，正文按需加载。第二，装不上时的降级：工具与协议是二值的，接不上就没有；**一个 skill 装不上仍然是一份人能读的 Markdown**，这正是它能在几十家客户端铺开的原因——它不要求宿主实现协议，只要求宿主会读文件。
选型给一条能当场走的流程：先分缺能力还是缺做法。缺能力时按复用面选，只有这一个应用要用就写函数调用，多个 Agent 都要用才值得做成 MCP 服务端。缺做法时按确定性选，靠指令说清楚就写进 skill 正文，结果必须逐字一致就配脚本。
最后一定要说配合。三者常态是叠着用：MCP 服务端把工单系统接进来成为工具，skill 的正文里写「先用工单查询工具拉出本周工单，再按这份模板归类」。**工具给它手，skill 给它章法。**
可预期的追问是「那什么时候不该用 MCP」。答案是只有一个应用要用、动作又只有两三个的时候——为它起一个服务端是过度设计，直接写函数调用更短。
Key points
MCP is wiring, Skills are experience, function calling is the shortest wire.
Capability gaps need tools or a protocol; experience gaps need skills. They do not compete.
Tool definitions cost every turn; a skill costs only name and description until activated.
A skill that fails to install is still readable Markdown, which is why it spread across clients.
Choose by capability versus method: capability by reuse surface, method by determinism, and expect to combine all three.
答题要点
分工是 MCP 管接线、Skills 管经验，函数调用是接线之前最短的线。
能力的缺口用工具或协议补，经验的缺口用技能补，三者不是竞争关系。
工具定义每轮重发，skill 每轮只有名字与描述，正文按需加载。
skill 装不上仍是一份人能读的 Markdown，这是它跨客户端铺开的根本原因。
选型先分缺能力还是缺做法：能力按复用面选，做法按确定性选；常态是三者叠着用。
A team needs to share more than a dozen skills. How would you organize and distribute them?一个团队要共享十几个 skill，你会怎么组织和分发？
Common in ChinaCommon overseasIntermediate#agent-skills#distribution#team-governance
How to reason about it · think before answering
This tests governance, not commands. The interviewer wants your criteria for splitting packages and choosing a distribution path.
Organization first. The criterion is whether they are adopted and retired together. Skills orbiting the same team convention belong in one package; a team convention and your personal habit do not, because bundling forces people to take the half they did not want. A dozen skills usually becomes three or four packages.
Name two hard rules. The package name is the namespace, so skills are prefixed as package colon skill, which is where collisions are resolved; pick the name once. And component directories must sit at the plugin root, never inside the manifest directory, which is the documented top mistake.
Then the three distribution paths with criteria. Ship with the repository: commit the skills alongside code, zero infrastructure, reviewed through the existing pull request flow, but scoped to that repository. Choose it for conventions tied to one codebase.
Use a marketplace: a repository plus a catalog JSON, added once per person, then installed on demand with automatic updates. One place to maintain, real versions and upgrade notes, at the cost of getting everyone to add it. Private simply means a private repository; there is no central server.
Organization-managed distribution: pushed centrally and not easily disabled, with guaranteed coverage and auditability, but heavy process and slow iteration. Reserve it for rules that must be enforced, such as security and compliance.
Close by noting the three combine: compliance centrally managed, cross-repository conventions via a marketplace, project quirks with the repository.
Expected follow-up: will a dozen skills blow up the catalog? Discovery cost scales with total description length, so governance means auditing description length and mutual exclusivity, not capping the count.
分析过程 · 先想清楚再作答
这题考工程治理，不是考命令。面试官想听的是你按什么切包、按什么选分发路径，而不是背几条安装命令。
先讲组织。判据是**它们是否一起被采纳、一起被淘汰**：都围着同一套团队规范转、谁装了都得装全套，那就是一个包；一个是团队规范一个是你的个人习惯，凑在一起只会逼别人接受不想要的那半边。十几个 skill 通常应该切成三四个包，不是一个巨包也不是十几个碎包。
包的两条硬规矩要点出来：**包名就是命名空间**，包里的技能会被前缀成「包名冒号技能名」，撞名问题在这一层解决，所以包名要一次想好；组件目录必须在插件根下，不能塞进放清单的那个目录里，这是官方标出来的最常见错误。
再讲分发，给三条路径和各自的判据。随仓库走：直接放进项目目录跟着代码提交，零基础设施、评审走原来的流程，但只对这个仓库成立——**只跟某一个代码库有关的规范就选它**。
走市场：一个仓库加一份清单 JSON，成员各自添加一次，之后按需安装并自动收更新。一处维护多处生效、有版本、有升级说明，代价是要推动每个人添加一次。跨仓库的团队规范选它。**私有就是把市场仓库设成私有，没有中心服务器这回事。**
走组织托管：管理侧统一下发，不能随便关掉，覆盖率有保证、可审计，但流程重迭代慢，只有必须强制且不装就出事的规范才值得，比如安全合规那几条。
最后说三条不互斥，稳定组合是安全合规走托管、跨仓库规范走市场、项目独有的怪癖随仓库走。
可预期的追问是「十几个 skill 会不会把目录撑爆」。答案是发现阶段的开销只和描述总长有关，所以治理重点是**审描述的长度与互斥性**，而不是限制数量。
Key points
Split by whether skills are adopted and retired together; a dozen usually becomes three or four packages.
The package name is the namespace where collisions are resolved, and component directories live at the plugin root.
Repository-scoped conventions ship with the repository: no infrastructure, no cross-repository reuse.
Cross-repository conventions go through a marketplace, which is just a repository plus a catalog JSON; private repo means private marketplace.
Mandatory compliance rules go through organization-managed distribution, and the three paths combine.
答题要点
切包的判据是它们是否一起被采纳、一起被淘汰，十几个通常切成三四个包。
包名就是命名空间，撞名在这一层解决；组件目录必须在插件根下。
只跟一个仓库有关的规范随仓库走，零基础设施但不跨仓库复用。
跨仓库的团队规范走市场，市场就是一个仓库加一份清单 JSON，私有仓库即私有市场。
必须强制的合规规范走组织托管，三条路径可以组合使用。
Should a skill package be versioned, and what goes wrong most often on upgrade?skill 包要不要做版本管理？升级时最容易出什么问题？
Common in ChinaCommon overseasDeep dive#agent-skills#versioning#distribution
How to reason about it · think before answering
It looks procedural but really asks what a skill's interface is. Answer that and the rest follows.
Should you version? Internally you can be loose; for public distribution you must pin a version. With a version, users update only when it changes. Without one, git sources use the resolved commit, so every push updates everyone, which is tolerable inside a team and out of control outside it.
Add an easily missed detail: do not set the version in both the plugin manifest and the marketplace catalog. The plugin manifest wins, and a mismatch leaves a state you cannot explain.
Then the criterion. What requires a bump is not whether a file changed but whether user-visible behavior changes. A changed description, changed body steps, or changed script flags all require a bump; typos and comments do not. It is the same as releasing a library, except the interface is not a function signature.
The scoring point: a skill's interface is its description and body. Everyone remembers to bump for script changes but treats a slightly sharper description as cosmetic. The description is the only trigger surface: widen it and the skill starts stealing tasks, narrow it and it silently stops firing. Every description change is a behavior change and belongs in the upgrade notes.
Give two concrete upgrade traps. Renaming the package changes the namespace, so every skill's invocation name changes and any hard-coded reference breaks. Moving a skill between packages looks to users like a capability disappearing, so the upgrade notes must spell out the migration.
Expected follow-up: how do you know an upgrade did not break things? Run the day-three trigger tests as a regression, comparing hit rates on the same labeled queries before and after.
分析过程 · 先想清楚再作答
这题看着像流程题，实际考的是「skill 的接口到底是什么」。想清楚这一点，答案自然出来。
先答要不要：对内可以宽松，**对外发布必须写死版本**。写了版本，用户只在这个值变化时才收到更新，这是可控的；不写的话 Git 来源会拿提交哈希当版本，你每推一次内容用户就更一次，团队内部尚可，对外就是失控。
补一条容易忽略的细节：版本不要在包清单和市场清单两处都写，包自己的清单优先级更高，两边不一致会得到一个你自己都解释不清的状态。
接着答判据。什么改动要升版本？不是「改没改文件」，而是「**用户的行为会不会因此变化**」。描述改了、正文步骤改了、脚本参数改了都要升；修错别字、补注释不用。这跟给库发版一个道理，只不过这里的接口不是函数签名。
本题的拿分点在这里：**skill 的接口是描述与正文**。大家都记得改脚本要升版本，却常觉得「我就是把描述改得更准了一点」不算变更。但描述是唯一的触发面，改宽了会开始抢别的任务，改窄了会突然不触发。**描述的每一次改动都是行为变更**，都要在升级说明里单独写一行。
再给两个升级期的具体坑。一是改包名：包名是命名空间，改名等于把包里所有技能的调用名全改了，用户那边所有写死调用名的地方一起断。二是拆包与合包：一个 skill 从 A 包挪到 B 包，对用户来说是「装了 A 的人突然少了一个能力」，必须在升级说明里显式写迁移步骤。
可预期的追问是「怎么知道升级没升坏」。答案是把第三天那套触发测试当回归跑：改描述前后各跑一次同一组正负例，比触发率而不是凭感觉。
Key points
Loose internally, pinned for public release; without a version, git sources update on every commit.
Never set the version in both the plugin manifest and the marketplace catalog; the plugin manifest wins.
Bump when user-visible behavior changes, not when a file changes.
A skill's interface is its description and body, and every description change is a behavior change.
Renaming the package rewrites every invocation name, moving a skill across packages needs migration notes, and trigger tests serve as upgrade regression.
答题要点
对内可宽松，对外发布必须写死版本；不写版本时 Git 来源按提交更新，等于失控。
版本不要在包清单与市场清单两处都写，包清单优先。
升不升版本看用户行为会不会变，不看改没改文件。
skill 的接口是描述与正文，描述的每一次改动都是行为变更，最容易被漏掉。
改包名会改掉全部调用名，跨包挪动 skill 要写迁移步骤；用触发测试做升级回归。

Comments

No comments yet — be the first.