Week 1 · D1About 3 hours

What Skills Are: the SKILL.md Spec, Directory Layout, and Three-Stage Progressive Disclosure

A skill is just a folder containing a SKILL.md; get clear on its directory layout, its two required fields, and why the three stages of discovery, activation, and execution save so much context.

Today's goals 0/3

能说清一个 skill 的最小构成，并解释 scripts、references、assets 三个可选目录各放什么
能背下 SKILL.md frontmatter 的两个必填字段与它们的硬性约束
能用自己的话讲清三阶段渐进式加载，并算出它相对全量加载省了多少上下文

今日目标

能说清一个 skill 的最小构成，并解释 scripts、references、assets 三个可选目录各放什么
能背下 SKILL.md frontmatter 的两个必填字段与它们的硬性约束
能用自己的话讲清三阶段渐进式加载，并算出它相对全量加载省了多少上下文

这门课的一句话定位是：MCP 管接线，Skills 管经验，上下文工程管取舍。 今天先把「经验」这一半的地基打好——一个 skill 到底是什么，它凭什么能在该出现的时候自己出现。读完正文、做完实验之后，回到页面顶部把三条目标勾掉。

小白版讲解

档案柜里的作业指导书

想象你入职一家做了十年的公司。同事领你到走廊尽头一排铁皮档案柜前，说：「以后要干什么，先来这儿翻一下。」柜子里是几十个文件夹，每个封面上写着一句话——「客户投诉超过两天没回复时，翻开我」「季度报表要交给财务前，翻开我」。你不需要背下所有文件夹的内容，只需要记住那几十句封面语；真到了那个场景，才把对应的那本抽出来读。

这就是 Agent Skills 的全部直觉。大模型本身聪明得很，但它不知道你们这儿是怎么干这件事的：提交信息用什么格式、报表哪几栏必须对齐、哪个接口的返回值有个众所周知的坑。这些东西不在它的训练数据里，只在你脑子里和你团队的默契里。

这里要先分清一件常被混为一谈的事。工具（tool）解决的是「能不能做」——模型本来读不到你的数据库，给它一个查询工具它就能读了。而技能（skill）解决的是「该怎么做」——模型本来就会写提交信息，但它写出来的不符合你们的规范。能力的缺口用工具补，经验的缺口用技能补，这是两件事。第六天我们会把函数调用、MCP 与 Skills 三者摆到一张表里逐格对比，今天先记住这个分工。

那为什么不干脆把所有经验都写进系统提示（system prompt）呢？因为你要为它付两次钱。第一次是真金白银：系统提示每一轮请求都会重新发送一遍，二十条团队规范假如写满六千个 token，一次五十轮的会话就要重复计费三十万个 token。第二次更贵——模型的注意力是有限的，一份塞了二十件不相干事情的系统提示，会让它在做第三件事的时候被第十七条规则干扰。档案柜的价值不在于装得多，而在于平时都关着。

一个 skill 就是一个文件夹

规范把这件事定义得极其朴素：一个 skill 就是一个包含 SKILL.md 文件的目录。除此之外没有任何必需品——不需要注册、不需要清单文件、不需要编译。

一个用满了全部约定的 skill 长这样：

TextText

commit-message/
├── SKILL.md          # 必需：元数据 + 指令正文
├── scripts/          # 可选：可执行代码
│   └── check_scope.py
├── references/       # 可选：按需查阅的文档
│   └── REFERENCE.md
└── assets/           # 可选：模板与静态资源
    └── template.md

三个可选目录不是随便起的名字，它们对应三种性质完全不同的东西，分清楚了才能用好明天要讲的分层。

scripts/ 放可执行代码。判据是「这段逻辑每次跑都应该给出一模一样的结果」——校验一份 JSON 的字段是否齐全、把一份表格转成另一种格式。这类事让模型每次现写一遍既慢又不稳，写成脚本调用一次就完了。第四天整天都在讲这个目录。

references/ 放按需查阅的文档。判据是「这份材料很长，但大多数时候用不上」——某个接口的完整错误码表、某个格式的字段字典。规范建议把每个引用文件切小、保持聚焦，因为模型是一份一份加载的，文件越小浪费越少。

assets/ 放静态资源。输出模板、配置样板、查表用的数据文件、示意图。它和 references/ 的区别是：引用是给模型读的知识，资源是给模型用的素材。

除了这三个，你还可以放任何文件和目录，规范不管。但这三个名字是社区约定，别人打开你的 skill 时会按这个直觉找东西，最好别自创一套。

frontmatter 逐字段读规范

SKILL.md 的结构是「YAML frontmatter 加 Markdown 正文」，和这门课本身的章节文件是同一个套路。最小的一个 skill 只需要两个字段：

YAMLYAML

---
name: commit-message
description: 按团队规范写 Git 提交信息。当用户要提交代码、写 commit message、或者问这次改动该怎么描述时使用。
---

name 是必填，约束卡得很死，逐条记下来：长度 1 到 64 个字符；只能用小写字母、数字和连字符；不能以连字符开头或结尾；不能出现两个连着的连字符；并且必须与父目录名一致。所以 PDF-Processing、-pdf、pdf--processing 三个写法全都不合规。

为什么要卡得这么死？因为 name 是这个 skill 在整个生态里的唯一标识：它要拼进目录名、拼进命名空间、拼进用户敲的斜杠命令、还要在两个 skill 撞名时用来判优先级。任何一处大小写不一致，都会变成一个很难查的「明明装了却调不到」。

description 是另一个必填字段，长度 1 到 1024 个字符。它要同时回答两个问题：这个 skill 做什么，以及什么时候该用它。规范给的正反例对照极其直白——「Helps with PDFs」是坏例子，「提取 PDF 的文字与表格、填写表单、合并多个 PDF。当用户处理 PDF 文档，或者提到 PDF、表单、文档抽取时使用」是好例子。明天整整一天都在讲这一个字段怎么写，今天只要记住：它是这个 skill 唯一的触发面，写砸了后面的正文写得再好也没人翻开它。

四个可选字段各有用途，知道它们存在就行：license 写许可，建议就写个许可名或指向包里的许可文件；compatibility 写环境要求，最长 500 个字符，只有确实挑环境的 skill 才写，比如「需要 git、docker、jq 与联网」；metadata 是一个字符串到字符串的映射，客户端可以往里塞规范之外的属性，建议 key 起得独特一点免得撞车；allowed-tools 是一个空格分隔的字符串，列出预先批准的工具，这个字段还是实验性的，各家实现的支持程度不一样。

正文部分规范不做任何格式限制，写什么都行。它建议的结构是：分步骤的指令、输入输出示例、常见边界情况。第二天与第三天会把这三段展开讲。

三阶段渐进式加载

现在到了今天最重要的机制。渐进式加载（progressive disclosure）分三个阶段，各自加载的东西完全不同。

Mermaid source

mermaidmermaid

flowchart LR
  A[会话启动] --> B[阶段一 发现<br/>只读 name 与 description<br/>每个约 50 到 100 token]
  B --> C{任务命中<br/>某条描述?}
  C -- 否 --> B
  C -- 是 --> D[阶段二 激活<br/>读入完整 SKILL.md<br/>建议不超过 5000 token]
  D --> E{正文点名了<br/>某个附件?}
  E -- 否 --> F[按指令执行]
  E -- 是 --> G[阶段三 执行<br/>按需读脚本 引用 资源]
  G --> F

阶段一是发现。 会话一启动，客户端扫描各个 skill 目录，把每个 skill 的 name 与 description 抽出来，拼成一份目录塞进上下文。注意它只读这两个字段，正文一个字都不读。官方给的量级是每个 skill 大约 50 到 100 个 token。

阶段二是激活。 模型看着这份目录判断当前任务命中了哪一条，然后把那一个 skill 的完整正文读进上下文。规范建议正文控制在 5000 token 与 500 行以内，超过这个量就该往 references/ 里搬。

阶段三是执行。 正文里如果写了「校验失败时读 references/api-errors.md」，模型才会去读那个文件；写了「跑 scripts/validate.py」，才会去跑那个脚本。这一阶段是按文件粒度、按需触发的，不是把整个目录一股脑倒进来。

这里有一条最容易被忽略、也最能体现设计水平的经验：要在正文里明确写出「什么时候读哪个文件」。写「细节见 references 目录」几乎等于没写，模型不知道什么时候该去看；写「如果接口返回了非 200 状态码，读 references/api-errors.md」，才真正把加载时机交到了模型手里。

算一笔上下文账

光说「省」不够，把数算出来才有说服力。假设你装了 20 个 skill，每个 SKILL.md 正文按规范上限写到 3000 token，附带的引用文件平均 5000 token。

不做渐进式加载，全量塞进系统提示：20 乘以 3000 等于 60000 token，加上引用文件的 100000 token，一共 16 万个 token。这已经超过很多模型的窗口了，而且每一轮请求都要重发一遍。

做渐进式加载：阶段一按每个 80 token 算，20 个是 1600 token；一次会话平均命中 1 到 2 个 skill，阶段二花 3000 到 6000 token；阶段三读一两个引用文件，再花 5000 到 10000 token。总量落在 1 万到 1.8 万之间，是全量方案的十分之一左右。

省下来的不只是钱。窗口是有限的，你从 16 万降到 1.6 万，腾出来的位置可以装真正在做的这件事的代码和数据。什么该进窗口、什么不该进，本身就是一门手艺，我们的姊妹课 5 天上下文工程专门讲这个取舍。

这笔账里有一个可以自己动手核的部分：阶段一的成本是你唯一每次都要付的固定开销，所以值得实测一下你那几个 skill 的目录到底多大。下面这段代码扫描一个目录，把每个 skill 的 name 与 description 抽出来，估算这份目录的 token 开销。

catalog-cost.ts

import { readdir, readFile } from 'node:fs/promises'
import { join } from 'node:path'
 
// 粗略估算：中英混排大约 2.5 个字符一个 token。真要精确请用各家的分词器。
const estimateTokens = (text: string) => Math.ceil(text.length / 2.5)
 
async function catalogCost(skillsDir: string) {
  const entries = await readdir(skillsDir, { withFileTypes: true })
  let total = 0
  for (const entry of entries) {
    if (!entry.isDirectory()) continue
    const raw = await readFile(join(skillsDir, entry.name, 'SKILL.md'), 'utf8').catch(() => null)
    if (raw === null) continue // 没有 SKILL.md 的目录不是 skill，跳过
    const name = /^name:\s*(.+)$/m.exec(raw)?.[1]?.trim() ?? entry.name
    const description = /^description:\s*(.+)$/m.exec(raw)?.[1]?.trim() ?? ''
    const cost = estimateTokens(name + description)
    total += cost
    console.log(`${name.padEnd(24)} ${String(cost).padStart(4)} token`)
  }
  console.log(`目录总开销约 ${total} token，每一轮请求都要付一次`)
}
 
await catalogCost(process.argv[2] ?? '.agents/skills')

catalog_cost.py

import math
import re
import sys
from pathlib import Path
 
 
# 粗略估算：中英混排大约 2.5 个字符一个 token。真要精确请用各家的分词器。
def estimate_tokens(text: str) -> int:
    return math.ceil(len(text) / 2.5)
 
 
def catalog_cost(skills_dir: Path) -> None:
    total = 0
    for entry in sorted(p for p in skills_dir.iterdir() if p.is_dir()):
        skill_file = entry / "SKILL.md"
        if not skill_file.exists():  # 没有 SKILL.md 的目录不是 skill，跳过
            continue
        raw = skill_file.read_text(encoding="utf-8")
        name = m.group(1).strip() if (m := re.search(r"^name:\s*(.+)$", raw, re.M)) else entry.name
        desc = m.group(1).strip() if (m := re.search(r"^description:\s*(.+)$", raw, re.M)) else ""
        cost = estimate_tokens(name + desc)
        total += cost
        print(f"{name:<24} {cost:>4} token")
    print(f"目录总开销约 {total} token，每一轮请求都要付一次")
 
 
catalog_cost(Path(sys.argv[1] if len(sys.argv) > 1 else ".agents/skills"))

跑一遍你就会发现，两三个 skill 的目录大概只有两三百个 token，几乎白送；但如果你的 description 全都写到 1024 个字符的上限，二十个 skill 的目录就要八千个 token——这时候该做的不是删 skill，是把描述写短。

它和你已经在用的指令文件差在哪

很多人第一反应是：这不就是把 AGENTS.md 或者项目根目录那份规范文件切成小块吗？形式上像，机制上是两件事。

常驻指令文件是「一直摊开在桌上的便签」。 它每次会话都全量进上下文，不管你今天干的活跟它有没有关系。所以它只适合放那种「无论做什么都成立」的东西：代码风格、语言偏好、绝对不能碰的目录。它一旦超过一两百行就会开始稀释注意力。

skill 是「关着的档案柜」。 平时只露一句封面语，命中才打开。所以它适合放那种「只在特定场景成立」的东西：某类任务的完整流程、某个格式的坑、某套报表的填法。

提示词模板是「你自己去柜子里拿的那一本」。 它也存在文件里，但是你在挑，不是模型在挑。skill 与它的关键差别就在这个「谁来挑」上：description 写好了，模型自己判断该翻哪本。这就是为什么明天要花一整天讲那一个字段。

判断口径可以简化成一句话：这条经验是不是每次都用得上？是就写进常驻指令文件，不是就做成 skill。

顺带把基础也补齐一下。skill 并不改变 Agent 的运行机制，它只是往「思考」这一步的上下文里多塞了一段材料——循环还是那个「思考、行动、观察」的循环。如果你对这个循环还没有手写过一遍的实感，去读 30 天课的第 2 天：工具调用原理与手写 Agent Loop，一个小时就能补上，之后第五天我们自己写 skill 运行时会用到它。

下面这段是最小示意：skill 的目录就是拼进系统提示的一段文本，激活就是把某个 skill 的正文追加成一条消息。 五十行就能看清全貌。

inject.ts

type Skill = { name: string; description: string; location: string; body: string }
 
function buildCatalog(skills: Skill[]): string {
  if (skills.length === 0) return '' // 一个都没有时整段省略，别给模型一个空清单
  const items = skills
    .map((s) => `  - name: ${s.name}\n    description: ${s.description}\n    location: ${s.location}`)
    .join('\n')
  return [
    '以下技能提供了特定任务的专门指令。',
    '当任务命中某条 description 时，先读取对应 location 的文件再继续。',
    'available_skills:',
    items,
  ].join('\n')
}
 
function activate(messages: Array<{ role: string; content: string }>, skill: Skill) {
  // 阶段二：整份正文作为一条消息进上下文，之后一直留着，别让压缩把它清掉
  messages.push({ role: 'user', content: `skill_content name=${skill.name}\n${skill.body}` })
}

inject.py

from dataclasses import dataclass
 
 
@dataclass
class Skill:
    name: str
    description: str
    location: str
    body: str
 
 
def build_catalog(skills: list[Skill]) -> str:
    if not skills:  # 一个都没有时整段省略，别给模型一个空清单
        return ""
    items = "\n".join(
        f"  - name: {s.name}\n    description: {s.description}\n    location: {s.location}"
        for s in skills
    )
    return "\n".join(
        [
            "以下技能提供了特定任务的专门指令。",
            "当任务命中某条 description 时，先读取对应 location 的文件再继续。",
            "available_skills:",
            items,
        ]
    )
 
 
def activate(messages: list[dict[str, str]], skill: Skill) -> None:
    # 阶段二：整份正文作为一条消息进上下文，之后一直留着，别让压缩把它清掉
    messages.append({"role": "user", "content": f"skill_content name={skill.name}\n{skill.body}"})

看懂这两个函数，你就已经理解了所有客户端在做的同一件事。第五天要做的就是把它补全成一个真能跑的运行时：加上扫描、加上宽松解析、加上同名冲突的优先级。

源码导读

动手实验

🧪 D1 实验：一张读懂并触发三个现成 skill 的记录表，逐个标注它们的触发面与分层结构

Code location: labs/agent-skills-7days/day-01-skill-anatomy

验收标准：

记录表里三个 skill 各填满一行，每行都写出了它的 name、description 的触发面、正文分成了哪几段、带了哪些可选目录。
每个 skill 都写出了一句会触发它的话，和一句形似但不该触发它的话，并说明两者的差别在哪个词上。
三个 skill 的 description 字符数与 SKILL.md 行数都数出来了，并对照 1024 字符与 500 行两条线各给出了一个超标或不超标的判断。
表格末尾写了一段不超过五行的总结，指出这三个 skill 里你最想抄的一个写法是什么。

今天没有代码要写，产出是一张读懂现成 skill 的记录表——先学会读，明天才写得出来。动手前先把上面「frontmatter 逐字段读规范」那一节留在旁边的标签页里，填表时会反复回来对照。素材从示例仓库里挑，挑那种你一眼能看懂它在解决什么问题的，别挑最复杂的。

打开 solution 里已经填好的那一行，对着它引用的那个 skill 的 SKILL.md 看一遍，弄清每一栏的内容是从文件的哪个位置抄来的。
从示例仓库里挑三个 skill，在 starter 的表格里各填一行：名字、触发面、正文分层、附带目录。
为每个 skill 各写一句会触发的话，再写一句形似但不该触发的话，并标出差别在哪个词。
数出三个 skill 的 description 字符数与 SKILL.md 行数，对照规范的两条预算线逐个判断。
写完总结那一段，回到验收标准逐条自检，四条都过了才算完成。

面试题

今天 3 道题在下方题库区，侧重 skill 的构成与规范约束、渐进式加载三阶段、以及 skill 与提示词文件的边界。展开后先看「分析过程」再看要点——照着推导练，比背要点管用。标注「国内高频 / 海外高频」方便按目标市场取舍。

检查清单与明日预告

能说清一个 skill 的最小构成，并解释 scripts、references、assets 三个可选目录各放什么
能背下 SKILL.md frontmatter 的两个必填字段与它们的硬性约束
能用自己的话讲清三阶段渐进式加载，并算出它相对全量加载省了多少上下文
能说出「工具补能力、技能补经验」这个分工，并各举一个例子
实验的 4 条验收标准全部通过
3 道面试题不看要点也能答出至少 2 道

明天（D2）我们写第一个真正的 skill。顺序是有意的：今天你知道了 description 是唯一的触发面，明天就把整节课花在这一个字段上——触发词怎么选、边界怎么划、正文怎么分层、装进客户端之后怎么验证它真的被翻开了。先懂机制再动手，写出来的第一个 skill 才不会是一份「装了但从来没被触发过」的摆设。

Interview questions

What problem do Agent Skills solve, and how are they different from putting every convention into one big instruction file?Agent Skills 解决的是什么问题？它和把所有规范写进一个大的提示词文件有什么区别？
Common in ChinaCommon overseasBasic#agent-skills#context-engineering
How to reason about it · think before answering
The discriminator is whether you say on demand. Answering skills are reusable prompts says nothing, because that is equally true of a prompt template.
Start with the split: tools fill a capability gap the model cannot cross on its own; skills fill an experience gap where the model can do the task but not the way your team does it.
Then the mechanism: a persistent instruction file enters context in full every session, while a skill exposes only name and description until something matches and its body is loaded.
Quantify the cost: twenty conventions at six thousand tokens of system prompt bill three hundred thousand tokens over a fifty-turn session, and the attention dilution costs more than the money.
Close with the rule of thumb interviewers want: if the guidance applies every single time, it belongs in the persistent instruction file; otherwise make it a skill.
Expected follow-up: what about prompt templates? The difference is who chooses. You pick a template; the model picks a skill by reading descriptions.
分析过程 · 先想清楚再作答
这题的区分度在你有没有说出「按需」两个字。只答「skill 是可复用的提示词」的人，等于没答，因为那句话对提示词模板同样成立。
先给分工：工具补的是能力缺口，模型本来做不到的事；技能补的是经验缺口，模型做得到但不知道你们这儿怎么做。这一刀切下去，后面的论证才站得住。
再给机制差异：常驻指令文件每次会话全量进上下文，skill 平时只露 name 与 description，命中才展开正文。前者的成本是固定的，后者的成本是按需的。
接着算代价：二十条规范写满六千 token 的系统提示，五十轮会话要重复计费三十万 token；更贵的是注意力被不相干的规则稀释，做第三件事时被第十七条干扰。
最后给判据，这是面试官真正想听的一句：这条经验是不是每次都用得上？是就写进常驻指令文件，不是就做成 skill。
可预期的追问是「那提示词模板呢」。答案是谁来挑：模板是你手动选的，skill 是模型读着 description 自己选的，触发权在模型手里。
Key points
Tools close capability gaps, skills close experience gaps. Do not blur the two.
A persistent instruction file costs the same tokens every turn; a skill body only enters context when it matches.
Dumping unrelated conventions into the system prompt both costs money and dilutes attention.
The test is whether the guidance applies every time: if yes it stays resident, if no it becomes a skill.
Unlike a prompt template, a skill is selected by the model itself from its description.
答题要点
工具补能力缺口，技能补经验缺口，这是两件事，不要混着答。
常驻指令文件成本固定且每轮重发，skill 的正文只在命中时才进上下文。
把不相干的规范全塞进系统提示，除了花钱还会稀释注意力，让模型被无关规则干扰。
判据是「是不是每次都用得上」：是就常驻，不是就做成 skill。
和提示词模板的关键差别是触发权在模型手里，靠的是 description。
What does each of the three progressive disclosure stages load, and why not just load every skill up front?渐进式加载的三个阶段分别加载什么？为什么不能一次性把所有 skill 全加载进去？
Common in ChinaCommon overseasIntermediate#agent-skills#progressive-disclosure
How to reason about it · think before answering
This tests both recall precision and engineering sense. Naming the three stages is not enough; say which fields and which files each stage pulls in.
Order them by granularity: stage one loads only name and description, roughly fifty to a hundred tokens per skill; stage two loads the full SKILL.md body, recommended under five thousand tokens and five hundred lines; stage three loads individual scripts, references and assets.
Answer the why with a number: twenty skills at three thousand tokens of body plus reference files is well over a hundred thousand tokens, past many context windows, and resent every turn. Progressive loading lands around ten thousand.
Add the deeper reason: what you save is window space, not just money, and that space belongs to the actual task.
Expected follow-up: how does stage three fire? The body must state the loading condition. See the references folder is useless; read the error-code reference when the API returns a non-200 hands the timing to the model.
分析过程 · 先想清楚再作答
这题在考你对机制的记忆精度，同时也在考工程感。只背出三个阶段的名字拿不到分，要说出每一阶段加载的**是哪些字段、哪些文件**。
拆法很简单，按加载的粒度从粗到细数：阶段一只加载 name 与 description，量级是每个 skill 五十到一百个 token；阶段二加载整份 SKILL.md 正文，建议不超过五千 token 与五百行；阶段三按文件粒度加载脚本、引用与资源。
回答「为什么不全加载」时给一个具体的数：二十个 skill 各三千 token 的正文加上引用文件，全量是十几万 token，超过很多模型的窗口，而且每一轮都要重发。渐进式加载后总量落在一万上下。
补一条更本质的理由：省下来的不只是钱，是窗口位置。腾出来的空间要留给真正在做的这件事的代码和数据，这就是上下文工程的核心取舍。
可预期的追问是「阶段三怎么触发」。答案是正文里必须写明读取条件——写「细节见 references 目录」等于没写，写「接口返回非 200 时读 references 里的错误码文件」才真正把时机交给了模型。
Key points
Discovery: only name and description, about fifty to a hundred tokens per skill.
Activation: the full SKILL.md body, ideally under five thousand tokens and five hundred lines.
Execution: individual files from scripts, references or assets, loaded one at a time on demand.
Loading everything up front blows the window and is resent every turn; progressive loading cuts it to roughly a tenth.
Stage three only fires if the body spells out which file to read under which condition.
答题要点
阶段一发现：只加载 name 与 description，每个 skill 约五十到一百 token。
阶段二激活：读入完整 SKILL.md 正文，建议不超过五千 token 与五百行。
阶段三执行：按需读取 scripts、references、assets 里的单个文件，不是整目录倒进来。
全量加载会撑爆窗口且每轮重发，渐进式加载能把量级压到十分之一左右。
阶段三能不能被触发，取决于正文有没有写清「什么条件下读哪个文件」。
What hard constraints does the spec put on the name and description fields, and why is name so tightly constrained?SKILL.md 的 name 与 description 有哪些硬性约束？规范为什么要把 name 卡得这么死？
Common in ChinaCommon overseasIntermediate#agent-skills#spec
How to reason about it · think before answering
It looks like spec recall, but the real question is the why. Listing the constraints is a pass; explaining which engineering problem they prevent is the differentiator.
Name has five constraints: one to sixty-four characters, lowercase letters digits and hyphens only, no leading or trailing hyphen, no consecutive hyphens, and it must match the parent directory name.
Description has two: one to one thousand twenty-four characters, and it must convey both what the skill does and when to use it.
The reason name is strict: it is the skill's identity across the ecosystem, feeding directory lookup, namespacing, slash-command invocation and collision precedence. One casing mismatch becomes an installed but uncallable skill.
Mention the real-world wrinkle: many clients deliberately relax the name-matches-directory rule and only warn, so a skill can work locally and vanish under a stricter implementation.
Expected follow-up: what if the description runs to a thousand characters? You pay for it every session. Twenty maxed-out descriptions cost eight thousand tokens of catalog, so shorten the text rather than dropping skills.
分析过程 · 先想清楚再作答
这题看着像背规范，其实题眼在后半句「为什么」。能把约束背全只算及格，能说出这些约束是为了解决什么工程问题才是加分项。
先把 name 的五条约束数完：长度一到六十四个字符、只能用小写字母数字和连字符、不能以连字符开头或结尾、不能有连续两个连字符、必须与父目录名一致。
再给 description 的两条：长度一到一千零二十四个字符；内容上要同时说清做什么和什么时候用，而不是只说做什么。
解释「为什么卡这么死」：name 是这个 skill 在整个生态里的唯一标识，要拼进目录名、命名空间、斜杠命令，还要在两个 skill 撞名时用来判优先级。任何一处大小写或分隔符不一致，都会变成一个很难查的「装了却调不到」。
补一个真实的坑：很多客户端在实现时故意放宽了「name 等于目录名」这条，不一致只打警告仍然加载。于是你本地一切正常，换个严格实现就整个消失。
可预期的追问是「description 写到一千个字符会怎样」。答案是它每次会话都要付一遍，二十个 skill 都写满上限，光目录就要八千 token，这时候该做的是把描述写短而不是删 skill。
Key points
Name: one to sixty-four characters, lowercase alphanumerics and hyphens, no leading or trailing hyphen, no double hyphens, must equal the directory name.
Description: one to one thousand twenty-four characters, stating both what it does and when to use it.
Name is strict because it is the skill's identity for lookup, namespacing, invocation and collision precedence.
Many clients validate name leniently, so working locally does not guarantee working elsewhere.
The description is a fixed per-session cost, so keep it as short as it can be while still triggering.
答题要点
name：一到六十四字符、小写字母数字与连字符、首尾不能是连字符、不能有连续连字符、必须等于父目录名。
description：一到一千零二十四字符，必须同时说清做什么与什么时候用。
name 卡死是因为它是唯一标识，要参与目录查找、命名空间、命令调用与撞名优先级。
很多客户端对 name 做宽松校验，本地能跑不代表换个客户端也能跑。
description 是每次会话都要付的固定开销，能短则短。

Comments

No comments yet — be the first.