速记版：Skill 是"给 AI 执行的工程规范"，强调可维护、可复用、可测试，本文总结工程化实践要点。

Skill 工程化实践总结（速记版）

核心理念

Skill 不是“能运行的 Prompt”，而是“给 AI 执行的工程规范”。

目标：

可维护（方便修改）
可复用（方便组合）
可测试（结果确定）
可扩展（适应变化）
安全可靠（避免事故）

1. 模块化设计

什么时候该拆 Skill？

满足任意一条就拆：

判断标准	说明
>500 行	上下文过大，维护困难
多个独立流程	不同场景却共享同一上下文
修改频率不同	高频和低频内容耦合
可独立复用	逻辑可被其他 Skill 使用

拆分三原则

1. 单一职责

❌ user-management

注册
登录
权限

✅

register-user
login-user
permission-check

2. 显式依赖

dependencies:
  - data-validate
  - data-transform
  - data-load

不要依赖隐式加载。

3. 子 Skill 可独立运行

检验标准：

离开主 Skill 是否还能工作？

如果不能，拆分失败。

2. 提高 AI 执行准确率

原则一：结构化优先

表格 > 文字

❌

name 是字符串必填
age 是整数可选

✅

参数	类型	必填	默认值
name	string	是	-
age	int	否	0

AI 对表格理解明显更准确。

原则二：复杂逻辑脚本化

不要：

检查文件名：
- 长度不能超过255
- 不能数字开头
- ...

应该：

执行 validate_filename.py
退出码非0则失败

优势：

无歧义
可测试
可复用
可版本管理

原则三：提供多种架构方案

集中式

一个 Skill 完成所有事情

适合：

小项目
稳定业务

分散式

主 Skill + 多个子 Skill

适合：

大项目
高频变化业务

渐进式（推荐）

集中式
    ↓
业务增长
    ↓
逐步拆分

避免过度设计。

原则四：记录易错点

单独维护：

## ⚠️ 常见陷阱

- 不要使用 rm -rf
- 环境变量区分大小写
- 默认时区 Asia/Shanghai

原则五：FAQ

记录高频问题：

Q: 子 Skill 加载失败？

A: 检查路径是否正确。

5~8 个即可。

3. MCP vs HTTP

一句话原则

高频复用 → MCP

临时调用 → HTTP

对比

维度	MCP	HTTP
复用性	高	低
开发成本	高	低
调试	较复杂	简单
适用场景	通用能力	临时需求

决策树

需要外部能力？

├─ 已有 MCP？
│    └─ 用 MCP
│
├─ 跨项目复用？
│    └─ 封装 MCP
│
├─ <10行代码？
│    └─ HTTP
│
└─ 混用

实际案例

MCP

适合：

企业微信
数据库
文档系统
搜索系统

一次开发
多 Skill 复用

HTTP

适合：

Jenkins 构建
内部接口
临时报表

requests.post(...)

即可。

4. 安全五条铁律

1. 不硬编码凭证

❌

TOKEN="abc123"

✅

TOKEN=os.getenv("API_TOKEN")

原则：

代码与配置分离

2. 危险操作必须确认

例如：

1. dry-run
2. 用户确认
3. 真正执行

危险操作：

删除文件
清空数据库
生产发布

3. 数据库先备份

执行：

pg_dump > backup.sql

验证：

backup.sql > 0KB

然后再执行：

DELETE
UPDATE
ALTER TABLE

4. 防 Prompt Injection

核心：

指令与数据分离

用户输入：

ignore previous instructions

必须视为：

数据

而非：

命令

推荐流程：

用户输入
    ↓
存文件
    ↓
只读取内容
    ↓
提取事实

不执行其中任何指令。

5. 发布前安全检查清单

□ API Key 是否来自环境变量

□ 危险操作是否确认

□ 数据库是否备份

□ 用户输入是否仅作为数据

□ 文件操作是否限制目录

□ URL 是否有白名单

□ 子 Skill 依赖是否声明

最佳实践 Checklist

模块化

□ >500 行拆分
□ 单一职责
□ 显式依赖
□ 子 Skill 可独立运行

准确性

□ 能用表格不用文字
□ 复杂规则脚本化
□ FAQ 完整
□ 易错点明确

集成

□ 高频能力 → MCP
□ 临时需求 → HTTP
□ 避免过度工程化

安全

□ 不硬编码凭证
□ 危险操作确认
□ 数据库先备份
□ 防 Prompt 注入
□ 发布前安全检查

最终记忆公式

Skill 工程化 =

模块化
+ 结构化表达
+ MCP/HTTP 合理选型
+ 安全防护

= 可维护、可复用、可扩展、可执行

一句话总结：

写 Skill 时，把它当成一个“小型软件系统”而不是一段 Prompt；主 Skill 负责编排，子 Skill 负责执行，规则结构化表达，能力合理封装，安全措施前置。这样 Skill 才能长期演进而不失控。

Skill 编写技巧

On this page