---
title: "技术概念速查表"
wiki: skills
category: "基础概念"
slug: C-技术概念速查表
url: https://learnagent.wiki/skills/cards/C-技术概念速查表
tags: ["速查表", "技术概念", "Skill", "Agent"]
last_updated: 2026-04-11
reading_time: 19
---

> > 附录 C：技术概念速查表

# 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 的"大脑"。

**具体例子**：
```yaml
---
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。

**三层架构**：

| 层级 | 内容 | 何时加载 | Token 成本 | 作用 |
|------|------|----------|------------|------|
| L1 | frontmatter | 始终 | ~100 | 过滤器：AI 决定要不要用这个 Skill |
| L2 | SKILL.md body | 匹配后 | 1000-5000 | 操作手册：告诉 AI 怎么做 |
| L3 | references/ scripts/ assets/ | 执行中按需 | 无上限 | 工具箱：精确执行复杂任务 |

**具体例子**：数据分析 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 里。

**具体例子**：
```yaml
---
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 加标签、版本号、作者信息等。

**具体例子**：
```yaml
metadata:
  author: "zhangsan"
  version: "1.2.0"
  tags: "writing,marketing,xiaohongshu"
```

---

### allowed-tools（可选，实验性）

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

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

---

## 容易混淆的概念对比

### Skill vs 提示词（Prompt）

| 维度 | Skill | 提示词 |
|------|-------|--------|
| 形式 | 文件夹（SKILL.md + 脚本 + 资源） | 一段文字 |
| 复用性 | 写一次，反复用 | 每次要重写或粘贴 |
| 可维护性 | 改文件即更新 | 分散在各处，难以维护 |
| 可分享性 | 直接分享文件夹 | 复制粘贴，容易丢失 |
| 复杂度 | 支持脚本、参考文档 | 纯文本 |
| 触发方式 | AI 自动匹配 | 手动粘贴 |

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

---

### Skill vs MCP（Model Context Protocol）

| 维度 | Skill | MCP |
|------|-------|-----|
| 定位 | 教 AI "怎么做"（流程和步骤） | 给 AI "有什么工具"（接口和连接） |
| 类比 | 操作手册 | 工具箱 |
| 例子 | "先读数据，再分析，最后写报告" | "这里有个数据库连接，你可以查询" |
| 文件格式 | Markdown + 脚本 | JSON 配置 + 服务端 |
| 能否独立 | 能，纯文本指令即可 | 不能，需要 MCP 服务器运行 |

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

---

### Skill vs AGENTS.md

| 维度 | Skill | AGENTS.md |
|------|-------|-----------|
| 加载方式 | 按需加载，只有匹配时才读 | 始终加载，AI 每次都读 |
| 适用场景 | 特定任务（写文案、审代码） | 通用规则（项目规范、团队约定） |
| token 消耗 | 按需消耗 | 始终消耗 |
| 文件位置 | `.claude/skills/` 子目录 | 项目根目录或 `.claude/` |
| 数量 | 可以有很多个 | 通常只有一两个 |

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

---

### Skill vs Hook

| 维度 | Skill | Hook |
|------|-------|------|
| 定位 | 指令包（教 AI 怎么做） | 事件触发器（在特定时机自动执行） |
| 触发方式 | AI 判断是否需要 | 系统在特定事件发生时自动调用 |
| 例子 | "按这个格式写 commit message" | "每次提交前自动运行 lint" |
| 配置位置 | SKILL.md 文件 | `.claude/settings.json` |
| 能否修改文件 | 通过 AI 间接操作 | 通过脚本直接操作 |

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

---

### 项目级 Skill vs 用户级 Skill

| 维度 | 项目级 | 用户级 |
|------|--------|--------|
| 存放位置 | `.claude/skills/`（项目目录下） | `~/.claude/skills/`（用户主目录下） |
| 生效范围 | 仅当前项目 | 所有项目 |
| 适合场景 | 项目特定的 Skill（如项目代码规范） | 通用 Skill（如写作助手、翻译器） |
| 团队共享 | 提交到 Git，团队成员都能用 | 仅本地可用 |
| 优先级 | 项目级优先（同名时） | 被项目级覆盖 |

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

---

## 触发相关概念详解

### 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 不同自由度：高（创意）、中（报告）、低（脚本）。

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

| 自由度 | 实现方式 | 适用场景 | 例子 |
|--------|----------|---------|------|
| **高** | 文字指令 | 创意写作、头脑风暴 | "口语化，像跟朋友聊天" |
| **中** | 模板+参数 | 报告生成、代码审查 | "按以下格式输出：数据→分析→建议" |
| **低** | 具体脚本 | 部署、数据处理、格式控制 | `scripts/deploy.py` 精确执行 |

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

---

---

### 反模式（Anti-pattern）

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

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

**表格形式**：

| 不要这样做 | 症状 | 怎么改 |
|-----------|------|--------|
| 结构词堆砌 | 全文"首先""其次""最后" | 直接说事，不要过渡 |
| 程度副词滥用 | "非常""十分""极其" | 删掉，或用"挺""蛮" |
| 书面语腔调 | "笔者认为""综上所述" | 换成"我觉得""说白了" |
| 长段落 | 超过 3 行不换行 | 强制换行，一行一个意思 |
| 空洞修饰 | "优质的产品""很好的服务" | 用具体数据或场景替代 |

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

---

### 检查清单（Checklist）

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

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

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

---

### 模式模板（Pattern Template）

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

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

**具体例子**：
```markdown
## 报告模板
【标题】[产品名] + [核心卖点] + 评价
【评分】[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 前言 | Markdown 正文 |
|------|-----------|--------------|
| 位置 | 两个 `---` 之间 | 第二个 `---` 之后 |
| 格式 | YAML 键值对 | 自由格式 Markdown |
| 作用 | 元数据（name、description 等） | 操作指令（教 AI 怎么做） |
| 谁来读 | AI 的 Skill 发现系统 | AI 的执行引擎 |
| 何时读 | 启动时和匹配时 | Skill 被激活后才读 |
| Token 消耗 | 很小（只有几个字段） | 较大（包含所有指令） |

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

---

### scripts/ vs references/

| 维度 | scripts/ | references/ |
|------|----------|-------------|
| 内容 | 可执行代码（Python、Shell 等） | 纯文本文档（模板、规范等） |
| 用途 | 让 AI 调用执行具体操作 | 让 AI 读取参考信息 |
| AI 的角色 | 调用者，解读脚本输出 | 阅读者，按文档要求输出 |
| 适用场景 | 数据处理、API 调用、文件操作 | 模板参考、品牌规范、API 文档 |
| 是否必需 | 大多数 Skill 不需要 | 内容较长的 Skill 建议用 |

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

---

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

| 维度 | .claude/skills/ | ~/.claude/skills/ |
|------|-----------------|-------------------|
| 物理位置 | 当前项目根目录下 | 用户主目录下 |
| Git 管理 | 可以提交到仓库 | 不在项目仓库内 |
| 团队共享 | 团队成员 clone 后即可使用 | 仅自己可见 |
| 生效范围 | 仅当前项目 | 所有项目 |
| 典型内容 | 项目代码规范、特定工作流 | 通用写作助手、翻译工具 |

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

---

### Token vs 字符 vs 字数

| 维度 | Token | 字符 | 字数 |
|------|-------|------|------|
| 定义 | AI 处理文本的基本单位 | 每个字母/汉字/标点 | 每个词/汉字 |
| 换算（中文） | — | 1 汉字 ≈ 1-2 tokens | 1 字 ≈ 1-2 tokens |
| 换算（英文） | — | 1 字母 ≈ 0.25 tokens | 1 词 ≈ 1-1.5 tokens |
| 规范限制用哪个 | Token | 字符 | — |
| 为什么关心 | 决定上下文窗口消耗 | description 限制用字符（1024） | 容易直观感受 |

**实际换算经验**：
- 100 字中文 ≈ 150-200 tokens
- 100 词英文 ≈ 130-150 tokens
- 一页 A4 文档 ≈ 2000-3000 tokens
- 一个中等 Skill 的 SKILL.md ≈ 1000-3000 tokens

---
*Source: https://learnagent.wiki/skills/cards/C-技术概念速查表*
*Markdown mirror of https://learnagent.wiki, served as text/markdown for LLM ingestion.*