上篇文章我讲了 fast-mirror-skill 解决什么问题——国内装包慢到想砸键盘。有读者问：这个 skill 本身是怎么设计的？SKILL.md 写了什么？为什么它能"自动触发"？

今天就来拆开看。不谈虚的，直接看代码、看结构、看决策逻辑。如果你也在琢磨怎么写一个 Claude Skill，这篇能帮你省掉踩坑的时间。

1. 先看全貌：项目结构
2. SKILL.md：一个 Skill 的灵魂
3. 触发机制：怎么让 AI 知道"什么时候该用我"
4. 镜像脚本：从配置到执行的完整链路
5. evals：怎么验证 Skill 真的好使
6. 几个关键设计决策
7. 如果你想写自己的 Skill

fast-mirror-skill 的 GitHub 仓库非常精简，一共就几个文件：

fast-mirror-skill/ ├── SKILL.md # Skill 定义文件（最核心） ├── README.md # 项目说明 ├── demo.jpg # 演示截图 ├── scripts/ │ └── mirror_config.sh # 镜像配置脚本 └── evals/ └── evals.json # 评测用例 

没有复杂的项目结构，没有 node_modules，没有构建流程。一个 Claude Skill 的核心就是 SKILL.md——它告诉 AI 这个 skill 做什么、什么时候该用、怎么执行。

这种极简设计不是偷懒，是有意为之。Claude Skill 的本质是一份结构化的指令文档，AI 读取它后就知道该怎么行动。你不需要写代码框架，你需要写的是一份精确、无歧义的操作手册。

SKILL.md 分三部分：frontmatter 元数据、触发条件、工作流程。

--- name: fast-mirror-skill description: Automatically configure and switch to domestic mirror sources... --- 

name 是 skill 的标识符，description 是给 AI 的"简历"——AI 会扫描所有已安装 skill 的 description 来决定当前任务要不要激活某个 skill。所以 description 写得好不好，直接决定你的 skill 能不能被正确触发。

fast-mirror-skill 的 description 写得很具体：列出了所有支持的包管理器名称（npm, pip, yarn, brew, apt, gem, cargo, go get, docker），还覆盖了"用户抱怨下载慢"、"用户想用国内镜像"这些自然语言场景。

SKILL.md 里有一个专门的 When to Use 章节：

 When to Use Trigger this skill when: - User runs or wants to run any package installation command - User complains about slow download speeds or installation timeouts - User explicitly mentions switching to Chinese/domestic mirror sources - User wants to accelerate package installations - User is setting up a new environment or installing project dependencies 

注意这里不是用正则匹配，而是用自然语言描述。因为 AI 的理解能力足够强，你只需要把意图讲清楚。

很多人第一次写 Skill 的时候，会纠结一个问题：AI 是怎么决定用不用我的 skill 的？

答案是两阶段匹配：

第一阶段：description 粗筛。 AI 拿到用户输入后，先扫描所有已安装 skill 的 description，找到可能相关的。这就是为什么 description 要包含关键词——不是给搜索引擎看的，是给 AI 的语义匹配看的。

第二阶段：When to Use 精筛。 AI 读取候选 skill 的 SKILL.md 全文，根据 When to Use 部分判断当前场景是否匹配。

所以写 Skill 的一个关键原则：description 覆盖广，When to Use 覆盖准。

fast-mirror-skill 在这一点上做得不错。它的 description 提到了所有包管理器名称，确保粗筛不会漏掉；When to Use 则精确描述了五类触发场景，避免误触发。

SKILL.md 里的 Workflow 部分定义了四步操作：

Step 1: 检测包管理器 → Step 2: 生成配置脚本 → Step 3: 加载脚本 → Step 4: 执行安装 

检测逻辑很简单——分析用户的命令和环境：

- Look for explicit commands (npm install, pip install, brew install, etc.) - Check for package.json, requirements.txt, Gemfile, go.mod, Cargo.toml - Ask the user if needed 

三层检测：直接从命令提取 → 从项目文件推断 → 实在判断不了就问用户。这种防御性的设计思路值得学习——先尝试自动推断，推断不了再问，而不是一上来就问。

scripts/mirror_config.sh 是整个 skill 的执行核心。它不是一个巨大的 if-else，而是把每个包管理器的配置封装成独立函数：

configure_nodejs() { ... } # npm, yarn, pnpm configure_python() { ... } # pip, pip3 configure_homebrew() { ... } # brew configure_apt() { ... } # apt configure_gem() { ... } # gem configure_cargo() { ... } # cargo configure_go() { ... } # go modules configure_docker() { ... } # docker registry 

然后一个统一的入口函数：

configure_mirrors() {  local package_managers=("$@")  for pm in "${package_managers[@]}"; do  case "$pm" in  npm|yarn|pnpm|node|nodejs) configure_nodejs ;;  pip|python) configure_python ;;  brew|homebrew) configure_homebrew ;;  # ... 其他包管理器  esac  done } 

这种设计有几个好处：

1. 只配置需要的：用户装 pip 包就只切 pip 镜像，不会动 npm
2. 安全检查：每个函数都先检查命令是否存在（command -v npm），不会在没装 npm 的机器上做无意义操作
3. 别名支持：npm|yarn|pnpm|node|nodejs 都映射到同一个函数，用户说"配置 node 镜像"也能正确处理
4. 可逆：脚本最后提醒用户哪些是临时生效、哪些是永久生效

看 Docker 那段代码：

configure_docker()  

它没有像 npm/pip 那样直接执行配置，而是只打印提示。原因是 Docker 配置需要 sudo 权限和重启守护进程，自动执行可能影响正在运行的容器。这个判断体现了安全意识——能自动的就自动，有风险的就提示。

evals/evals.json 定义了三个评测用例：

{  "id": 1,  "prompt": "I need to install a new Node.js project but npm install is extremely slow...",  "expected_output": "The skill should detect npm is being used, generate a mirror switch script..." } 

这三个 eval 分别覆盖了 npm、pip、Homebrew 三个最常见的场景。eval 的价值不在于数量多，而在于场景的代表性——这三个场景能验证核心流程：检测 → 配置 → 执行。

fast-mirror-skill 完全可以做成一个独立的命令行工具——fast-mirror npm、fast-mirror pip 之类的。但它选择了 Claude Skill 的形式，原因在于：

• 零安装成本：用户不需要额外安装任何东西，Skill 随 AI Agent 加载
• 自然语言交互：用户说"npm 太慢了"就行，不需要记命令
• 上下文感知：AI 知道用户在做什么项目，能主动判断是否需要配置镜像

选择标准就两条：同步延迟低 + 长期维护有保障。没有选阿里云镜像不是因为不好，而是同类型选一个就够了，减少用户的选择焦虑。

configure_apt() 只打印了提示链接，没有自动修改 /etc/apt/sources.list。原因很简单——改 sources.list 风险太高：

• 不同发行版（Ubuntu/Debian/Kali）路径和格式不同
• 改坏了系统更新直接挂掉
• 需要 sudo 权限

对于这种高风险操作，"告诉用户怎么做但让他自己来"是最负责任的方式。

fast-mirror-skill 的结构其实就是一个 Claude Skill 的标准模板。你要写自己的 Skill，照着这个结构来：

1. 创建 SKILL.md：frontmatter 写 name 和 description，正文写 When to Use 和 Workflow
2. description 要具体：列出关键词、列出触发场景，不要写泛泛的”帮助用户加速”
3. When to Use 要覆盖隐式意图：不只是”用户说 X”，还要包括”用户遇到 Y 问题”这种间接场景
4. 脚本要安全：先检查环境再操作，高风险操作只提示不自动执行
5. 写几个 evals：不需要多，但要有代表性

完整的项目代码在这里：github.com/itech001/fast-mirror-skill

作者: itech001
来源: 公众号：AI人工智能时代
主页: https://www.theaiera.cn，每日分享最前沿的AI新闻和技术。

本文首发于 AI人工智能时代，转载请注明出处。