一、本篇定位 & 学习目标

本篇定位

本节课将突破纯文本Skill的能力瓶颈，重点讲解**「Skill+本地脚本」联动核心方案**。仅依靠SKILL.md纯文本指令，只能完成简单代码修改、文本规整等基础操作。面对批量文件处理、终端命令执行、批量筛选校验、重复性运维操作等复杂场景，纯文本方案存在指令冗余、执行不稳定、无法循环处理、校验不精准等诸多短板。

而通过将复杂自动化逻辑下沉至本地脚本，让AI仅负责流程调度、步骤管控、结果校验，可极大拓展Skill能力边界，实现全场景高效自动化，彻底解放双手，适配日常开发与项目运维各类复杂需求。

学习目标

1. 熟练掌握Skill专属 scripts 目录规范、文件命名与编写标准；

2. 独立编写 Windows / Mac / Linux 跨系统适配脚本，精通各系统脚本权限配置实操；

3. 掌握 SKILL.md** 调用本地脚本的官方标准写法**，熟练搭建完整执行流程；

4. 落地2套高频商用自动化实战案例，全套代码与配置可直接复用落地；

5. 精准排查权限不足、系统不兼容、执行失效等脚本常见故障；

6. 搭建标准化**「AI调度+脚本执行」自动化工作流**，形成固定开发范式。

二、脚本联动核心认知：为什么必须搭配脚本？

1. 纯文本Skill的核心短板

仅依赖 SKILL.md 文字指令实现自动化，存在天然局限性，也是新手开发Skill频繁翻车、效果不达预期的核心原因：

- 指令冗余、Token消耗高：批量操作、循环处理、多步骤复杂逻辑需撰写大量文字描述，极易造成Token冗余，导致AI响应卡顿、执行精度大幅下降；

- 不支持复杂逻辑：纯文本指令无法实现循环遍历、批量筛选、条件分支、递归处理等进阶逻辑，适配场景极其有限；

-执行稳定性差：长流程文字指令易出现步骤遗漏、顺序错乱、自由发挥等问题，每次执行结果不一致，无法标准化落地；

- 结果校验薄弱：针对日志筛选、文件合规校验、批量结果比对等精细化场景，纯文本指令无法精准落地，难以保障执行质量。

2. 脚本联动核心优势（官方推荐最佳实践）

- 精简Skill主体，优化性能：将繁琐执行逻辑下沉至脚本，SKILL.md 仅保留流程调度、步骤规范与校验规则，大幅降低Token占用，提升AI响应速度；

- 执行稳定、标准化统一：脚本一次编写、永久复用，执行逻辑固定不变，彻底杜绝AI随机发挥、步骤遗漏问题，每次执行效果完全一致；

- 拓展能力边界：完美支持批量文件处理、日志分析筛选、环境校验、代码格式化、资源清理等高阶自动化场景；

- 易维护、可迭代：功能优化仅需更新对应脚本，无需改动Skill主体结构，适配个人长期迭代与团队协作场景。

3. 脚本适用场景（精准区分，避免滥用）

✅ 优先使用脚本的场景：批量循环操作、终端命令执行、批量文件读写、项目合规校验、环境检测、日志筛选清理、重复性运维操作

❌ 无需使用脚本的场景：简单文本修改、单行代码替换、基础格式标注、短文本规整（纯文本指令即可高效完成）

三、scripts 目录作用与文件规范（零基础强制执行标准）

scripts 是Skill专属的脚本存放目录，属于Skill进阶架构的核心目录，遵循Level3按需加载机制，全程不占用常驻Token，仅在技能触发、执行脚本步骤时临时调用，是优化Skill性能、实现复杂自动化的核心载体。

1. 标准目录结构

所有包含脚本的Skill，必须统一遵循以下固定目录结构，保证AI识别精准、规范统一、可直接复用：

1
2
3
4
5
6

你的技能文件夹/
├── SKILL.md        # 核心调度文件（负责调用脚本、流程管控、结果校验）
├── scripts/        # 脚本专属目录（固定命名，纯英文小写）
│   ├── 脚本文件1.sh # Linux/Mac 系统脚本
│   └── 脚本文件2.bat# Windows 系统脚本
└── references/     # 可选目录：存放脚本配套说明、规则文档、参考资料

2. 核心目录 & 文件强制规范

1. 目录名固定唯一：必须为小写 scripts，禁止缩写、大写、自定义命名，否则AI无法识别并调用脚本；

2. 文件命名规范：采用「小写英文+连字符」格式，语义清晰、见名知意，例如 clean-log.sh、format-code.bat，禁止中文、空格、特殊符号；

3. 跨系统分类存放：Linux/Mac脚本统一使用 .sh 后缀，Windows脚本统一使用 .bat 后缀，禁止跨后缀混用；

4. 单一职责原则：一个脚本仅实现一个核心功能，禁止堆砌杂糅逻辑，方便独立调试、迭代、复用与替换；

5. 路径安全规范：脚本内禁止硬编码绝对路径、密钥、固定配置，统一使用相对路径，适配多设备、多项目环境。

3. Level3按需加载核心优势

scripts 目录下所有资源均属于Level3层级，遵循按需加载、不常驻上下文核心机制，不会占用AI常驻Token资源，仅在Skill触发、执行脚本步骤时临时读取加载，既能保障功能完整性，又能最大化优化Skill响应性能。

四、跨系统脚本编写、权限配置实操

零基础无需具备专业编程能力，掌握「通用模板复制+权限配置+规范调用」即可覆盖99%的项目自动化场景。本节手把手讲解 Windows / Mac / Linux 全系统脚本编写与落地实操。

1. Linux / Mac 系统（.sh 脚本）

（1）通用基础脚本模板

新建 scripts/clean-log.sh 日志清理脚本（高频通用场景），零基础可直接复制复用，无需修改核心逻辑：

1
2
3
4
5
6

#!/bin/bash
# 功能：批量清理项目所有.log临时日志文件
# 适用：Linux / Mac 系统
echo "===== 开始清理项目临时日志 ====="
find . -name "*.log" -delete
echo "✅ 日志文件清理完成，无残留临时文件"

（2）权限配置（核心必做步骤）

Linux/Mac系统默认开启脚本权限保护，未授权脚本无法执行。需打开终端，进入Skill根目录，执行chmod授权命令：

1
2
3
4
5

# 给单个脚本单独授权
chmod +x scripts/clean-log.sh

# 批量授权（推荐）：给scripts目录下所有脚本开启执行权限，后续新增脚本无需重复操作
chmod +x scripts/*

授权完成后，脚本可被AI正常调度调用，也可手动独立运行测试，验证功能有效性。

2. Windows 系统（.bat 脚本）

（1）通用基础脚本模板

新建对应功能脚本 scripts/clean-log.bat，完美适配Windows终端执行逻辑：

1
2
3
4
5
6
7

@echo off
:: 功能：批量清理项目所有.log临时日志文件
:: 适用：Windows 系统
echo ===== 开始清理项目临时日志 =====
del /s /q *.log
echo ✅ 日志文件清理完成，无残留临时文件
pause>nul

（2）权限与运行说明

Windows系统无需手动授权，保存脚本文件后即可直接运行。若出现权限不足、执行失败问题，以**「管理员身份运行终端」**后重试即可。

3. 跨系统兼容优化技巧

如需实现「一套Skill适配全系统、自动匹配脚本」，可结合后续高阶语法的系统条件判断功能，实现自动调度对应系统脚本。零基础新手可先分系统独立编写，熟练后再统一优化跨系统适配逻辑。

五、SKILL.md 调用脚本官方标准写法

脚本编写完成后，标准化调用是保障执行精准度的核心。所有脚本调用必须严格遵循步骤说明+脚本执行+检查点校验三段式官方规范，彻底杜绝AI执行偏差、步骤遗漏、执行失败无感知等问题。

1. 核心调用原则

1. 脚本执行步骤独立拆分，统一编号Step，逻辑层级清晰、流程有序；

2. 每一步明确标注脚本功能与执行目的，让AI精准理解执行意图；

3. 所有脚本执行后必须配置检查点，校验失败立即终止流程，避免无效执行；

4. 严格分离逻辑与调度：脚本存放执行逻辑，SKILL.md仅负责调度，禁止大段脚本代码嵌入Skill正文。

2. 通用标准调用模板（可直接复用）

1
2
3
4
5
6
7
8

### Step 1：执行【功能名称】自动化脚本
调用项目专属脚本，批量完成对应自动化操作：
```bash
# Linux/Mac 系统执行命令
./scripts/xxx.sh

# Windows 系统执行命令
./scripts/xxx.bat

检查点（强制校验）
执行结果校验命令，验证脚本执行有效性：

1

# 自定义校验命令，无报错、无残留文件即为执行成功

✅ 校验通过，进入下一流程；❌ 校验失败，立即终止执行并排查脚本问题。

1
2
3
4
5
6
7
8
9
10
11
12
13
14

## 六、实战案例：两套可直接落地的脚本联动Skill

结合前文所有规范与实操技巧，落地2套**高频商用自动化案例**，覆盖项目运维、代码规范两大核心场景，零基础可直接复制全套文件配置，开箱即用。

### 案例一：项目临时文件自动清理 Skill

#### 1\. 完整目录结构

```plain
project-clean/
├── SKILL.md
└── scripts/
    ├── clean-log.sh
    └── clean-log.bat

2. 完整 YAML 头部配置

1
2
3
4
5
6
7
8
9
10
11
12
13

---
name: project-clean
description: >
  自动清理项目临时日志、冗余缓存文件，精简项目体积、优化项目结构。
  触发指令：清理项目垃圾、删除日志、清理缓存、优化项目文件、规整项目目录。
  适配Windows、Mac、Linux全系统，仅清理临时冗余文件，不改动任何业务代码与核心配置。
metadata:
  version: "1.0"
  author: "零基础Skill教程"
permissions:
  allow_delete: true
  allow_network: false
---

3. SKILL.md 完整正文（含脚本调用+结果校验）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# 项目临时文件自动清理技能
## 一、概述
本技能通过本地专属脚本，批量自动化清理项目冗余日志、临时垃圾文件，快速规整项目目录、精简项目体积。全程不修改、不删除任何业务代码与核心配置，操作安全可控，适配全系统项目运维场景。

## 二、前置条件
1. 对应系统脚本已完成权限配置，可正常执行；
2. 脚本仅对当前项目目录生效，无系统级文件操作权限。

## 三、适用/不适用范围
✅ 适用：清理项目.log日志、临时冗余文件、无效缓存文件
❌ 不适用：删除业务代码、项目配置文件、核心资源文件、业务数据文件

## 四、执行步骤
### Step 1：执行跨系统清理脚本
根据当前运行系统自动匹配对应脚本，批量清理临时日志文件：
```bash
# Mac/Linux 系统执行
./scripts/clean-log.sh

# Windows 系统执行
./scripts/clean-log.bat

检查点校验
执行校验命令，确认项目无残留日志文件：

1
2
3
4
5

# Mac/Linux 校验命令
find . -name "*.log" | wc -l

# Windows 校验命令
dir /s /b *.log

预期结果：无输出或输出数值为0，代表清理任务完成。

六、安全说明

本脚本仅定向删除后缀为.log的临时日志文件，不会修改、篡改、删除项目任何业务代码与核心配置文件，操作安全无风险。

1
2
3
4
5
6
7
8
9
10
11
12

### 案例二：Python代码自动格式化 Skill（企业级通用）

#### 1\. 脚本文件 scripts/format\-python\.sh

```bash
#!/bin/bash
# 自动格式化Python代码，统一代码缩进、导入顺序、代码风格
# 依赖：提前安装 isort、black 格式化工具
echo "===== 开始格式化Python代码 ====="
isort .
black .
echo "✅ Python代码格式统一完成，风格规范化完毕"

2. 核心调用步骤（SKILL.md 标准节选）

1
2
3
4

### Step 1：执行Python代码格式化脚本
调用本地自动化脚本，批量规整项目Python代码，统一全局编码规范：
```bash
./scripts/format-python.sh

检查点校验
校验项目所有Python代码格式完全合规，无格式错误：

1
2

[black](https://black.readthedocs.io/) --check .
[isort](https://pycqa.github.io/isort/) --check .

终端无报错输出，代表代码格式化、规范化校验全部通过。

七、脚本高频报错排错手册（零基础全覆盖）

汇总新手开发、调用脚本过程中99%的常见问题，按**「故障现象-核心原因-解决方案」**标准化梳理，无需盲目排查，对症即可快速修复。

1. 故障：Permission denied（权限不足）

现象：终端执行脚本提示权限拒绝，脚本无法启动运行

核心原因：Linux/Mac系统脚本未开启执行权限，系统默认拦截未授权脚本

解决方案：在Skill根目录执行批量授权命令 chmod +x scripts/*，一次性永久解决所有脚本权限问题

2. 故障：脚本执行无反应、无任何输出

原因1：脚本文件名、调用路径书写错误，AI无法匹配目标文件；

原因2：Skill的YAML头部格式异常，技能未正常加载触发；

原因3：脚本编码不统一，Windows默认GBK、Linux/Mac默认UTF-8，编码冲突导致执行失效；

解决方案：核对脚本调用路径与文件名，统一文件编码为UTF-8，优先手动终端运行脚本，排查脚本本身可用性。

3. 故障：本地手动可运行，AI调用报错/失效

核心原因：AI运行工作目录与本地手动运行目录不一致，绝对路径适配异常

解决方案：脚本全程使用相对路径，严禁硬编码绝对路径，脚本操作范围严格限定在当前项目目录内。

4. 故障：脚本执行成功，但业务结果不符合预期

核心原因：脚本内部逻辑存在漏洞、缺少边界判断、适配场景不全

解决方案：遵循**「先本地调试、后AI调用」**原则，手动跑通并优化脚本逻辑后，再接入Skill调度，禁止在AI对话中调试脚本。

5. 故障：脚本执行卡顿、占用资源过高

解决方案：精简脚本循环逻辑，避免全盘无差别遍历，添加执行超时限制，降低资源占用，提升执行效率。

八、脚本联动最佳实践 & 避坑清单

✅ 强制遵守：最佳实践规范

1. 逻辑下沉原则：复杂循环、批量处理、终端命令、重复性操作全部写入脚本，SKILL.md仅负责流程调度与结果校验；

2. 分步校验原则：每一个脚本执行步骤必须搭配专属检查点，校验失败立即终止流程，避免无效执行与遗漏问题；

3.先测后用原则：所有脚本优先手动调试跑通，确认功能正常后，再接入Skill联动调用，大幅降低排错成本；

4. 权限最小化原则：严格限定脚本操作范围，仅允许操作当前项目目录文件，禁止访问、修改系统目录与核心文件；

5. 性能优化原则：脚本统一存放于Level3的scripts目录，不占用常驻Token，最大化提升Skill响应速度。

❌ 绝对禁止：错误开发写法

1. 禁止将大段脚本代码直接嵌入SKILL.md正文，造成Token冗余、Skill臃肿、响应卡顿；

2. 禁止在脚本中硬编码绝对路径、密钥、账号密码、固定配置等敏感信息，存在泄露与适配风险；

3. 禁止无校验执行删除、清空、覆盖等高危操作，避免误删项目核心文件，造成不可逆损失；

4. 禁止单脚本堆砌多个无关功能，逻辑杂糅不利于独立调试、迭代与复用，违背单一职责原则。

九、本篇课后实操练习（巩固落地）

1. 自主仿写「项目缓存清理Skill」，编写Windows/Linux/Mac跨系统脚本，实现批量删除项目 __pycache__ 缓存文件；

2. 完成脚本权限配置，参照教程搭建完整Skill结构，配置标准化检查点校验步骤；

3. 分别测试手动终端执行、AI自动触发两种模式，确保功能正常、无报错、执行结果精准。

十、本篇小结

脚本联动是Skill从「基础文本指令工具」升级为「工程化自动化工具」的核心转折点。通过将复杂、重复、高规整的自动化逻辑下沉至本地脚本，既能彻底解决AI随机发挥、步骤遗漏、执行不稳定等问题，又能精简Skill主体、降低Token消耗、优化响应性能，同时解锁批量处理、跨系统适配、精准校验等高阶能力。

掌握本篇内容后，你将彻底突破纯文本Skill的能力局限，具备开发项目运维、代码规整、批量处理等自动化Skill的能力，真正实现AI辅助开发、极简运维、效率翻倍的落地效果，为后续模块化、高阶语法、团队级Skill开发筑牢基础。