教程2026-11-12 · 智涌AI

团队共享 Agent Skills:.well-known 与 Skills over MCP

团队共享 Agent Skills 教程头图:终端里 curl 读取 /.well-known/agent-skills/index.json 看到 0.2.0 schema 和 skill-md、archive 两类条目,再用 MCP skills/list 列出 skill://release-notes/SKILL.md 及校验通过的文件清单,最后 sync_skills 同步到本地 ~/.claude/skills;标注 Cloudflare 公开 22 个 Skill、单个 Skill 512 文件和 16 MiB 上限

团队里的 Agent Skills 多半散在每个人的 ~/.claude/skills 里,谁改了一版就在群里发个 zip。现在有两条官方路子能换掉这种同步方式:一条是把 Skill 发布在自家域名的 /.well-known/agent-skills/ 下,另一条是 MCP 的 Skills 扩展(Skills over MCP),由 MCP 服务器按身份把 Skill 发给 Agent。Tailscale 11 月 10 日(美国时间)更新的 Aperture 两条都接了。这篇按两份规范和 FastMCP 文档,讲清楚各自怎么搭、什么时候用哪条。

先分清两条路解决的问题

.well-known 发现规范由 Cloudflare 起草,仓库 Apache-2.0。它解决「对外公开」:任何人拿到你的域名,就能列出你发布了哪些 Skill。Skills over MCP 的标识是 io.modelcontextprotocol/skills,对应 SEP-2640,2026 年 9 月 13 日合并、状态 Final,目前处在扩展生命周期的 Beta 阶段。它解决「对内分发」:Skill 跟着 MCP 服务器走,服务器认得调用者是谁,可以只给某个团队看某些 Skill。

两者都不改 Skill 本身的格式,仍是一个目录加 SKILL.md,frontmatter 至少有 name 和 description。还没写过 Skill 的,先看站内 写你的第一个 Agent Skill。

方式适合权限更新
手工复制到本地目录个人、少量 Skill无靠人通知
Git 仓库 + npx skills add开源 Skill 包跟仓库权限走skills update
/.well-known/agent-skills/厂商对外发布公开比对 digest
Skills over MCP公司内部、多 Agent按身份服务器部署即生效

前置条件

第一条:在自家域名发布 index.json

规范要求发布方在 /.well-known/agent-skills/index.json 放一份索引,顶层是 $schema 和 skills 数组。当前 schema 是 https://schemas.agentskills.io/discovery/0.2.0/schema.json,每条 Skill 必须有五个字段:name、type、description、url、digest。

type 只有两种:只有一个 SKILL.md 的用 skill-md,带脚本、参考文档的打成 .tar.gz 或 .zip,用 archive。截至 11 月 12 日我们查阅的两份线上索引:developers.cloudflare.com 列了 22 个 Skill,全是 archive;vercel.com 列了 9 个,4 个 skill-md、5 个 archive,url 直接指向 GitHub Release 的下载地址。可见 url 不必放在 .well-known 目录下,放 CDN 也行。

下面这段脚本扫描 .well-known/agent-skills/*/SKILL.md,生成 skill-md 类型的索引(frontmatter 解析写得很简单,只认单行的 key: value):

import hashlib, json, pathlib
root = pathlib.Path(".well-known/agent-skills")
skills = []
for md in sorted(root.glob("*/SKILL.md")):
    raw = md.read_bytes()
    front = raw.decode().split("---")[1]
    meta = dict(l.split(":", 1) for l in front.strip().splitlines())
    skills.append({
        "name": meta["name"].strip(),
        "type": "skill-md",
        "description": meta["description"].strip(),
        "url": f"/.well-known/agent-skills/{md.parent.name}/SKILL.md",
        "digest": "sha256:" + hashlib.sha256(raw).hexdigest(),
    })
index = {"$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
         "skills": skills}
(root / "index.json").write_text(json.dumps(index, ensure_ascii=False, indent=2))

服务器那边规范也有硬要求:index.json 用 application/json,SKILL.md 用 text/markdown 或 text/plain,.tar.gz 用 application/gzip;支持 GET 和 HEAD,不存在的返回 404。想让浏览器里的客户端读,再加 CORS 头。

消费端最省事的是 skills CLI:它的文档写明,给 npx skills add 传一个网址时,先尝试 well-known 发现,失败了才当直接下载地址处理。Aperture 的「Use a URL」导入走的也是这份规范。

digest 一变,客户端就知道该重新下载;对不上就必须丢弃,不能「先用着」。

第二条:让 MCP 服务器分发 Skill

Skills over MCP 没有发明新的传输方式,每个 Skill 文件都是一个 MCP 资源,地址惯例写成 skill://<skill-path>/<file-path>,用原有的 resources/read 读取。扩展只加了三个方法:

服务器要在 server/discover 里同时声明 resources 能力和这个扩展。规范建议单个 Skill 不超过 512 个文件、16 MiB。

用 FastMCP 搭一个,官方文档的最小示例是这样:

from fastmcp import FastMCP, Skill
from fastmcp.skills.provider import SkillCatalogProvider

release_notes = Skill(
    name="release-notes",
    description="Write release notes from merged pull requests.",
    instructions="# Release notes\n\nGroup changes by theme. Follow template.md.\n",
    files={"template.md": "## Highlights\n\n## Fixes\n"},
)

mcp = FastMCP("Team Skills")
mcp.add_provider(SkillCatalogProvider([release_notes]))

已有的 Skill 目录用 Skill.from_directory("skills/deploy") 读进来;Skill 存在数据库或经常改的,继承 SkillCatalogProvider 重写 load_skills(),FastMCP 每个请求调用一次,改动下一个请求就能看到。fastmcp list server.py --skills 可以列出当前提供的 Skill。

权限这块,FastMCP 的规则是调用者读不到的 Skill 不会出现在 skills/list 里,任何一个文件被 AuthMiddleware 拒绝,整个 Skill 都会从列表里消失。按团队分 Skill,就在这一层做。

多数 Agent 目前还只从磁盘读 Skill。FastMCP 4.2 的做法是客户端逐个 read_skill()(先核对每个文件的大小和 SHA-256),再用 to_directory() 写进本地目录;4.1 的 sync_skills() 在 4.2 里还能用但会告警,4.3 移除:

from pathlib import Path
from fastmcp import Client
from fastmcp.skills import SkillsClientExtension

target = Path.home() / ".claude" / "skills"
client = Client("http://localhost:8000/mcp", extensions=[SkillsClientExtension()])
async with client:
    for entry in await client.list_skills():
        skill = await client.read_skill(entry.uri)
        skill.to_directory(target / skill.name, overwrite=True)

服务器没开 Skills 扩展(比如还在 4.1)时,把 list_skills() 换成 list_skill_resources(),再把每个 str(resource.uri) 交给 read_skill()。overwrite=True 会整夹替换本地同名目录,本地改动会丢。

现在哪些地方能用

按 ext-skills 仓库维护的实现清单:官方 TypeScript SDK 在 v2.4.0 以 ext/skills 发布;Python SDK、C# SDK 已合并、还没发版。服务器侧有 Hugging Face、Cloudflare API MCP、n8n、Outline 等。宿主侧 fast-agent 在清单里标为 v1,ChatGPT 插件是部分支持(提交插件时导入一次快照),VS Code 还只是 planned,Goose、opencode 有 PR 在审。FastMCP 文档把 SkillCatalogProvider 标为 4.2.0 新增,4.2.0 正式版已于 11 月 13 日(美国时间)发布,详见站内 FastMCP 4.2 快讯。

Aperture 的做法是把两条路合在一个网关里:可以上传 SKILL.md 或 zip、同步公开 GitHub 仓库、按 .well-known 网址导入,也可以让接入 Aperture MCP 的 Agent 直接添加;分发时按 Skills over MCP 规范,管理员决定哪些人或团队拿到哪些 Skill。Tailscale 自己也写明,不是所有 Agent 都支持这个扩展。事件本身见站内 Aperture 快讯。

常见坑

做到哪一步算完成

Skill 和 MCP 各管什么,可以对照站内 Skill 和 MCP 的区别。

最后

先挑团队里最常被转发的那一两个 Skill,按上面的 FastMCP 示例放到一台内部 MCP 服务器上,用上面的客户端脚本发给大家,跑一周再决定要不要上网关。

关注公众号「智涌AI速递」

每天的 AI 快讯、实用教程和 AI项目实测,也会同步发到微信公众号。在微信里搜索「智涌AI速递」就能关注;不用微信的话,可以用 RSS 订阅本站。