技术概念速查表

Skill 从小白到高手系列课

附录 C：技术概念速查表

遇到不懂的名词，在这里查。每个概念都有"为什么重要"和具体例子。

核心概念

Agent Skill（AI 能力扩展包）

一个文件夹形式的能力扩展包，包含指令、脚本和资源文件，AI 按需自动加载。

为什么重要：没有 Skill 的 AI 就像一个没有装 App 的手机——什么都能做一点，但什么都不精。装了 Skill 之后，AI 就有了专门的能力，比如"小红书文案专家""代码审查助手"。

什么场景用到：当你发现 AI 总是做不好某类任务时，就该写一个 Skill 了。比如每次让它写 commit message 格式都不对，那就写一个 commit-helper Skill。

具体例子：你创建了一个文件夹 xiaohongshu-writer/，里面放着 SKILL.md。当你在 Claude Code 里说"帮我写一篇小红书笔记"时，AI 会自动加载这个 Skill，按照你预设的格式和风格来写。

SKILL.md

每个 Skill 必需的核心文件，包含两部分：YAML 前言（元数据）+ Markdown 正文（操作指令）。

为什么重要：这是 AI 唯一必须读取的文件。你把所有"教 AI 怎么做"的信息都写在里面。写得越好，AI 表现越好。

什么场景用到：创建任何 Skill 的第一步就是创建 SKILL.md。它是整个 Skill 的"大脑"。

具体例子：

---
name: my-skill
description: "做什么。什么时候用。"
---

## 操作步骤
1. 第一步
2. 第二步

YAML 前言（--- 之间的部分）是元数据，正文是操作指令。AI 先读元数据决定要不要加载，加载后再读正文来执行。

渐进式披露（Progressive Disclosure）

信息分三层按需加载：L1 元数据（~100 tokens）→ L2 正文（~5000 tokens）→ L3 资源（按需）。

为什么重要：AI 上下文窗口是有限的公共资源。渐进式披露让 AI 启动时只加载"封面"（name + description），匹配后才加载"正文"，执行中才加载"附录"。50 个 Skill 启动消耗仅 5000 tokens，vs MCP 的 20000+ tokens。

三层架构：

具体例子：数据分析 Skill 启动时只加载"分析 MySQL 数据库"（100 tokens）。用户问"查薪资最高的员工"时加载正文（3000 tokens）。执行到"生成图表"时才读 scripts/chart.py。

上下文窗口（Context Window）

AI 一次能处理的最大文本长度，所有对话内容、系统提示、Skill 内容都共享这个空间。

为什么重要：你的 Skill 不是唯一占用上下文窗口的东西。用户的对话历史、系统提示、其他被加载的 Skill 都在争抢这个空间。如果 Skill 太臃肿，可能挤占其他重要信息，导致 AI 表现下降。

什么场景用到：当你发现加载了某个 Skill 后 AI 变"笨"了，可能就是这个 Skill 太长，占用了太多上下文。

具体例子：假设上下文窗口是 200K tokens。用户对话历史占了 50K，系统提示占了 10K，你加载了 3 个 Skill 各占 5K，总共就用掉了 75K。留给 AI "思考"的空间就少了。所以 Skill 要精简，能用 100 字说清的不要写 500 字。

Skill 触发（Skill Activation）

AI 根据 description 判断是否加载某个 Skill 的过程。

为什么重要：触发机制决定了你的 Skill 能不能被用上。description 写得好，该触发时触发，不该触发时不触发。写得差，要么用不上（under-trigger），要么乱用（over-trigger）。

什么场景用到：写 description 的时候。每个字都要考虑"用户会怎么描述这个需求"。

具体例子：用户说"帮我写一篇文章"。如果你的 description 只写了"生成小红书笔记"，AI 可能不会触发（因为用户没说"小红书"）。如果你写了"生成文章、笔记、文案"，AI 就更容易匹配上。

Skill 发现（Skill Discovery）

AI 启动时扫描 Skill 目录，获取所有 Skill 的 name 和 description，建立"能力目录"的过程。

为什么重要：发现阶段决定了 AI 知道哪些 Skill 可用。如果你的 Skill 放错了目录、name 不合规，AI 就发现不了它。

什么场景用到：调试 Skill 不生效的问题时。先确认 AI 是否发现了你的 Skill（看启动日志），再检查 description 是否匹配。

具体例子：AI 启动时扫描 ~/.claude/skills/ 和 .claude/skills/ 目录，读取每个子目录里的 SKILL.md 的 name 和 description。如果文件夹里没有 SKILL.md，或者 name 不符合规范，这个 Skill 就不会被纳入"能力目录"。

Skill 组合（Skill Composition）

多个 Skill 可以同时被 AI 加载和使用，协作完成复杂任务。

为什么重要：一个 Skill 不需要做所有事。把大任务拆成多个小 Skill，每个做好一件事，然后让 AI 按需组合。这比写一个"万能 Skill"更容易维护，效果也更好。

什么场景用到：当你发现一个 Skill 越来越臃肿，或者多个 Skill 有重叠功能时，考虑拆分和组合。

具体例子：你有一个 code-reviewer Skill 做代码审查，一个 security-scanner Skill 做安全扫描。当用户提交代码时，AI 可以同时加载两个 Skill，先用 code-reviewer 检查代码质量，再用 security-scanner 检查安全问题，最后综合输出。

可移植性（Portability）

Skill 是纯文本文件（Markdown + 脚本），不依赖特定平台或环境。

为什么重要：写好的 Skill 可以分享给任何人，也可以在不同项目之间复用。GitHub 上的 Skill 库之所以能繁荣，就是因为这个特性。

什么场景用到：当你想在多个项目中使用同一个 Skill，或者想分享给同事/社区时。

具体例子：你在公司项目里写了一个 api-doc-writer Skill，直接把整个文件夹复制到个人项目里就能用。或者上传到 GitHub，别人 clone 下来放到自己的 .claude/skills/ 目录就能用。不需要安装任何依赖（除了脚本里用到的库）。

allowed-tools

实验性功能，在 YAML 前言中声明 AI 可以不经用户确认直接使用的工具列表。

为什么重要：默认情况下，AI 使用某些工具（如写入文件、执行命令）需要用户确认。如果你信任某个 Skill，可以通过 allowed-tools 让它自动执行，提高效率。

什么场景用到：自动化工作流。比如你的 Skill 需要频繁执行脚本，每次都确认很麻烦，就把它加到 allowed-tools 里。

具体例子：

---
name: auto-test-runner
description: "自动运行测试。"
allowed-tools: ["Bash", "Write"]
---

这样 AI 在执行这个 Skill 时可以直接运行 Bash 命令和写入文件，不需要每次问你"允许吗？"

kebab-case

命名规范：只使用小写字母、数字和连字符，如 my-skill-name。

为什么重要：这不是建议，是强制要求。如果你的 name 用了大写字母或下划线，Skill 可能无法被正确识别。

什么场景用到：给 Skill 文件夹命名和填写 name 字段时。

具体例子：

• 正确：commit-helper、data-analyst-v2、pdf-to-markdown
• 错误：commitHelper（驼峰）、commit_helper（下划线）、Commit-Helper（大写）

为什么叫"kebab"：因为连字符看起来像烤肉串上的横杠。

Token

AI 处理文本的基本计量单位。大致换算：1 个中文字约等于 1-2 个 tokens，1 个英文单词约等于 1 个 token。

为什么重要：上下文窗口以 token 为单位计算。你的 Skill 越长，消耗的 token 越多，留给其他信息的空间就越少。优化 Skill 长度本质上就是优化 token 使用。

什么场景用到：控制 SKILL.md 的长度时。一般建议 SKILL.md 正文控制在 2000-5000 tokens 以内。

具体例子：一段 500 字的中文 description 大约消耗 500-1000 tokens。如果你的 description 超过 1024 字符（约 1024-2048 tokens），就超过了规范限制。

文件结构

SKILL.md（必需文件）

每个 Skill 的核心文件，包含 YAML 前言（元数据）和 Markdown 正文（操作指令）。

为什么重要：没有这个文件，AI 就不认为这个文件夹是一个 Skill。它是 Skill 的"入口文件"。

什么场景用到：创建 Skill 的第一步。所有指令和元数据都写在这里。

具体例子：如果你创建了文件夹 my-skill/ 但里面没有 SKILL.md，AI 启动时会直接跳过这个文件夹，不会报错也不会提醒。

scripts/（可选目录）

存放可执行脚本，如 Python、Shell 脚本等。AI 在执行 Skill 时可以调用这些脚本。

为什么重要：有些任务超出了 AI 的文本处理能力，需要用脚本来处理。比如读取文件、调用 API、执行计算。

什么场景用到：当 Skill 需要处理数据、调用外部工具、或执行 AI 无法直接完成的操作时。

具体例子：一个数据分析 Skill 可能有 scripts/analyze.py 用来读取 CSV 文件并计算统计指标。SKILL.md 里的指令会让 AI 调用这个脚本，然后解读脚本的输出。

references/（可选目录）

存放参考文档，如模板、规范、示例库等。SKILL.md 中可以指引 AI 在需要时读取。

为什么重要：把大块参考信息从 SKILL.md 正文中分离出来，减少每次加载时的 token 消耗。AI 只在需要时才读取，实现渐进式披露。

什么场景用到：当你的 Skill 需要参考大量外部信息（如 API 文档、品牌规范、历史模板）时。

具体例子：一个公文写作 Skill 可能把各种公文模板放在 references/ 里。SKILL.md 只写"根据用户需求，选择 references/ 中对应的模板"，AI 按需读取，不浪费 token。

assets/（可选目录）

存放模板文件、图片、配置文件等静态资源。

什么场景用到：当 Skill 需要使用固定的模板文件（如 Excel 模板、HTML 模板）时。

YAML 前言字段详解

name（必填）

1-64 字符，kebab-case 格式，必须与所在文件夹名称完全一致。

为什么重要：这是 Skill 的唯一标识。AI 用 name 来索引和引用 Skill。如果不一致，AI 就找不到你的 Skill。

常见错误：文件夹叫 code-review/，但 name 写了 codereview（少了连字符）。结果：Skill 不生效。

description（必填）

1-1024 字符，必须说清"做什么 + 什么时候用 + 输出什么"。

为什么重要：这是 AI 判断是否加载 Skill 的唯一依据。写得好，触发精准；写得差，要么用不上要么乱触发。

最佳实践：包含 3 个以上触发词，50-150 字为佳。避免过度宽泛或过度狭窄。

license（可选）

声明 Skill 的开源许可证，如 MIT、Apache-2.0。

什么场景用到：公开发布 Skill 时。让使用者知道可以怎么使用你的 Skill。

compatibility（可选）

声明运行环境要求，如"需要 Python 3.8+"或"需要 Node.js"。

什么场景用到：Skill 包含脚本时，告诉使用者需要什么运行环境。

metadata（可选）

自定义键值对，用于存放任何额外信息。

什么场景用到：需要给 Skill 加标签、版本号、作者信息等。

具体例子：

metadata:
  author: "zhangsan"
  version: "1.2.0"
  tags: "writing,marketing,xiaohongshu"

allowed-tools（可选，实验性）

预批准的工具列表，AI 使用这些工具时不需要用户确认。

什么场景用到：自动化工作流，减少交互确认。但要谨慎使用，确保你信任这个 Skill。

容易混淆的概念对比

Skill vs 提示词（Prompt）

一句话区分：提示词是一次性的指令，Skill 是工程化的可复用解决方案。如果一段提示词你用了两次以上，就该升级成 Skill 了。

Skill vs MCP（Model Context Protocol）

一句话区分：MCP 提供"手"（工具），Skill 提供"脑子"（方法）。两者配合使用效果最好。

Skill vs AGENTS.md

一句话区分：AGENTS.md 是"家规"，Skill 是"专业技能"。家规时时遵守，专业技能按需使用。

Skill vs Hook

一句话区分：Skill 是 AI 主动使用的能力，Hook 是系统被动触发的自动化流程。

项目级 Skill vs 用户级 Skill

一句话区分：项目级是"这个项目专用"，用户级是"所有项目通用"。建议通用工具放用户级，项目定制放项目级。

触发相关概念详解

Under-trigger（应该触发但没触发）

表现：你写了一个 Skill，但 AI 什么时候都不用它。

原因：description 写得太窄、触发词太少、或用了 AI 不容易匹配的表达。

怎么修复：在 description 中增加更多用户可能使用的关键词。比如你的 Skill 是写小红书笔记的，不要只写"小红书"，还要加"种草笔记""好物推荐""产品测评"等。

Over-trigger（不该触发但也触发了）

表现：用户明明在做别的事，AI 却加载了你的 Skill。

原因：description 写得太宽泛。比如"description: 帮助用户写作"，那用户写代码注释、写邮件、写任何文字都可能触发。

怎么修复：在 description 中明确限定范围。比如"生成小红书种草笔记"比"帮助写作"精确得多。加上输出类型描述也有帮助："输出包含标题+正文+标签的小红书笔记"。

触发词（Trigger Words）

description 中包含的、用户可能在对话中使用的关键词或短语。

选择技巧：

• 想想你的目标用户会用什么词来描述需求
• 包含专业术语和口语表达两种形式
• 包含中文和英文两种形式（如果你的用户群体两种都用）

例子：一个代码审查 Skill 的触发词可以是：code review、代码审查、检查代码、看下这段代码有什么问题、PR 审查。

进阶概念详解

自由度光谱（Freedom Spectrum）

根据任务特性给 AI 不同自由度：高（创意）、中（报告）、低（脚本）。

核心逻辑：任务越脆弱（容易出错）→ 自由度越低 → 用脚本锁死；任务越灵活（多种方案都对）→ 自由度越高 → 用文字引导。

一句话区分：高自由度给方向，中自由度给框架，低自由度给步骤。部署脚本不能自由发挥，创意写作不能死步骤。

反模式（Anti-pattern）

告诉 AI "不要做什么"的指令，用表格形式更精确。

核心原理：写"做什么"是描述一个无限大的可行域，AI 在里面随机游走；写"不做什么"是在可行域上画边界，AI 的行为空间被收窄到你想要的范围。

表格形式：

一句话区分：正模式定义"去哪"，反模式定义"不能去哪"。两者结合，AI 才知道边界在哪。

检查清单（Checklist）

让 AI 在生成输出后、返回给用户前，进行一次自检。

为什么重要：AI 有时候会遗漏要求。检查清单相当于给 AI 一个"提交前确认"步骤，能显著减少遗漏。

具体例子：

## 检查清单
- [ ] 字数是否在 300-500 字之间？
- [ ] 是否包含标题、正文、标签三部分？
- [ ] 标签数量是否为 5-8 个？
- [ ] emoji 使用是否自然（不超过 5 个）？
- [ ] 是否避免了夸张用语？

模式模板（Pattern Template）

给 AI 提供现成的操作模板，AI 只需要选择模板并填入参数。

为什么重要：对于结构化输出，模板比自由生成更稳定。AI 从模板出发，不容易遗漏结构要素。

具体例子：

## 报告模板
【标题】[产品名] + [核心卖点] + 评价
【评分】[X]/10
【优点】
- 优点1
- 优点2
- 优点3
【缺点】
- 缺点1
【总结】一句话推荐/不推荐

优先级分层（Priority Tagging）

用标签标注指令的重要性级别。

为什么重要：当 Skill 内容很多时，AI 可能分不清哪些指令是"必须遵守"的，哪些是"尽量遵守"的。优先级标签帮 AI 做取舍。

具体例子：

[CRITICAL] 所有输出必须经过事实核查，不得编造数据
[HIGH] 字数控制在 500-800 字之间
[MEDIUM] 优先使用主动语态
[LOW] 可以适当使用比喻和修辞

当上下文空间紧张、AI 需要精简时，会优先遵守 CRITICAL 和 HIGH 级别的指令，适当放宽 LOW 级别。

更多容易混淆的概念对比

YAML 前言 vs Markdown 正文

一句话区分：YAML 前言是"名片"，让 AI 知道你是谁；Markdown 正文是"操作手册"，告诉 AI 怎么做。

scripts/ vs references/

一句话区分：scripts/ 是 AI 的"工具箱"，references/ 是 AI 的"参考资料架"。

项目级目录 .claude/skills/ vs 用户级目录 ~/.claude/skills/

最佳实践：

• 团队协作的 Skill 放项目级，确保所有人使用统一的规范
• 个人效率工具放用户级，所有项目都能受益
• 如果同名，项目级优先级高于用户级

Token vs 字符 vs 字数

实际换算经验：

• 100 字中文 ≈ 150-200 tokens
• 100 词英文 ≈ 130-150 tokens
• 一页 A4 文档 ≈ 2000-3000 tokens
• 一个中等 Skill 的 SKILL.md ≈ 1000-3000 tokens