1. Skill的本质与设计哲学
Skill是什么?简单来说,它是一个能让AI获得特定能力的"能力包"。想象你给一位全能助手安装了一个PDF处理插件,它就能处理PDF文件;安装一个代码审查插件,它就能审查代码——Skill就是这样的插件。
1.1 Skill的两种形态
最小形态只需要一个SKILL.md文件:
code复制my-skill/
└── SKILL.md
这个文件分为两部分:
- 上半部分(frontmatter):告诉AI"什么时候用我"
- 下半部分(body):告诉AI"具体怎么做"
完整形态则是一个包含多种资源的目录:
code复制skill-name/
├── SKILL.md # 核心指令
├── agents/
│ └── openai.yaml # 技能名片
├── scripts/ # 可执行脚本
├── references/ # 参考文档
└── assets/ # 模板资源
1.2 写给AI vs 写给人
新手常犯的错误是把Skill写成人类文档。对比两种写法:
人类文档风格:
markdown复制# 代码审查技能
## 背景
基于团队多年经验总结...
## 审查原则
保持专业、建设性的语气...
AI指令风格:
markdown复制# 代码审查步骤
1. 检查函数长度是否超过50行
2. 验证错误处理是否覆盖所有异常
3. 确认变量命名符合camelCase规范
关键区别在于:人类文档强调"为什么",AI指令明确"怎么做"。
2. SKILL.md的黄金结构
2.1 Frontmatter:精准触发机制
Frontmatter是技能的"广告牌",决定AI是否激活这个技能。必须包含:
yaml复制---
name: pdf-editor
description: >-
处理PDF文件的创建、编辑和转换。当用户需要:
- 合并/拆分PDF
- 提取文本/图片
- 添加水印/页眉页脚
时使用本技能。
---
description写作技巧:
- 先说核心功能("处理PDF文件")
- 列举具体触发场景("当用户需要...")
- 使用动词开头("合并"、"提取")
- 限制在3-5个主要场景
2.2 Body:操作指令的编写艺术
2.2.1 指令分层设计
L1:核心流程(必须优先加载)
markdown复制# PDF合并步骤
1. 确认输入文件列表
2. 执行合并命令:
```bash
python scripts/merge_pdf.py input1.pdf input2.pdf
- 验证输出文件完整性
code复制
**L2:扩展参考**(按需加载)
```markdown
## 高级选项
- 自定义页码:见[references/pagination.md]
- 加密设置:见[references/encryption.md]
2.2.2 反模式清单
比起正面描述"应该怎么做",列出"不要怎么做"往往更有效:
markdown复制## 避免的常见错误
- 不要用`pdf2text`处理扫描件 → 用`scripts/ocr.py`
- 不要直接修改PDF二进制 → 用`references/pdf_edit_guide.md`方法
- 不要合并超过100页的文件 → 先拆分处理
2.3 资源目录的智能分工
| 目录 | 内容类型 | AI交互方式 | 示例 |
|---|---|---|---|
| scripts/ | 可执行代码 | 直接运行 | rotate_pdf.py |
| references/ | 参考文档 | 按需读取 | api_spec.md |
| assets/ | 模板资源 | 直接使用 | logo.png |
黄金法则:
- 确定性操作 → scripts/
- 辅助知识 → references/
- 产出素材 → assets/
3. 五个核心编写技巧
3.1 技巧一:用TODO标记填空位
在模板中预留TODO标记,引导AI补充内容:
markdown复制## [TODO]功能名称
用途:[TODO]描述使用场景
命令:[TODO]填写执行命令
参数:
- [TODO]参数1
- [TODO]参数2
3.2 技巧二:设计触发关键词
在description中埋入3-5个触发关键词:
yaml复制description: >-
当用户提到以下任一关键词时激活:
- "转换PDF"
- "合并文档"
- "提取图片"
- "添加水印"
3.3 技巧三:创建校验脚本
编写validate.py确保技能合规:
python复制# 校验frontmatter格式
def validate_frontmatter(text):
required_fields = ['name', 'description']
# ...校验逻辑...
# 校验目录结构
def validate_structure(dir_path):
required_dirs = ['scripts', 'references']
# ...校验逻辑...
3.4 技巧四:制作技能模板
标准模板应包含:
- 目录结构生成器(init_skill.py)
- SKILL.md骨架
- 示例脚本/参考文件
- 校验工具链
3.5 技巧五:设计渐进式披露
信息加载策略:
- 首次触发:只加载核心流程
- 遇到特定关键词:加载对应参考文件
- 复杂操作:调用专用脚本
示例:
markdown复制# 主流程
## 基础操作
[常规步骤...]
## 高级功能
- 加密:见references/encryption.md
- 批量处理:运行scripts/batch_process.py
4. 实战案例:构建PDF编辑器技能
4.1 步骤一:初始化结构
bash复制python init_skill.py pdf-editor \
--resources scripts,references,assets \
--examples
生成结构:
code复制pdf-editor/
├── SKILL.md
├── agents/
├── scripts/
│ └── example.py
├── references/
│ └── example.md
└── assets/
└── example.pdf
4.2 步骤二:编写核心指令
SKILL.md内容:
markdown复制---
name: pdf-editor
description: >-
处理PDF文件的创建、编辑和转换。支持:
- 页面操作(旋转/删除/重组)
- 内容提取(文本/图片)
- 文档转换(PDF↔Word/Excel)
---
# 基础命令
## 合并PDF
```bash
python scripts/merge.py 输入1.pdf 输入2.pdf 输出.pdf
提取文本
bash复制python scripts/extract_text.py 输入.pdf > 输出.txt
高级功能
- 批量处理:见references/batch_processing.md
- OCR识别:运行scripts/ocr.py
code复制
### 4.3 步骤三:添加实用脚本
scripts/merge.py示例:
```python
# 合并PDF的Python实现
from PyPDF2 import PdfMerger
def merge_pdfs(inputs, output):
merger = PdfMerger()
for pdf in inputs:
merger.append(pdf)
merger.write(output)
merger.close()
4.4 步骤四:创建参考文档
references/batch_processing.md:
markdown复制# 批量处理规范
1. 输入目录结构:
- /input/xxx.pdf
- /config/config.json
2. 配置文件格式:
```json
{"operation": "rotate", "degrees": 90}
- 执行命令:
bash复制
python scripts/batch.py /input /config
code复制
## 5. 常见问题与解决方案
### 5.1 问题一:技能不被触发
**可能原因**:
- description不够具体
- 触发场景太少
- 关键词与用户表述不匹配
**解决方案**:
1. 在description中添加更多场景示例
2. 包含同义词(如"PDF转换"和"文档格式转换")
3. 使用更通用的动词("处理"→"编辑/修改/调整")
### 5.2 问题二:AI错误理解指令
**典型案例**:
- 混淆相似操作(合并vs追加)
- 忽略关键参数
- 错误使用脚本
**解决方案**:
1. 在指令中添加边界条件:
```markdown
# 严格区分
## 合并:多个→单个新文件
## 追加:添加到现有文件末尾
- 为脚本添加参数校验:
python复制if not output.endswith('.pdf'): raise ValueError("输出必须是PDF文件")
5.3 问题三:技能响应缓慢
优化策略:
- 拆分大文件:
- 将references/拆分为多个小文件
- 按需加载替代全量加载
- 使用脚本替代复杂指令:
markdown复制# 优化前:10步文字说明 # 优化后: ```bash python scripts/process.py --autocode复制
5.4 问题四:跨平台兼容性
应对方案:
- 在scripts/中提供多平台版本:
code复制scripts/ ├── win/ │ └── merge.bat └── linux/ └── merge.sh - 添加环境检测逻辑:
python复制if sys.platform == 'win32': # Windows专用代码 else: # Linux/Mac代码
6. 高级技巧与最佳实践
6.1 动态指令生成
对于需要适配不同环境的技能,可以在scripts/中添加指令生成器:
python复制# scripts/generate_instructions.py
def generate_instructions(env):
return f"""## {env}专用步骤
1. 安装依赖:
```bash
{get_install_cmd(env)}
- 执行命令:
bash复制"""{get_run_cmd(env)}
code复制
### 6.2 技能组合模式
通过references/实现技能组合:
```markdown
# 在data-process技能中
## 导出PDF报告
1. 生成数据:使用data-analysis技能
2. 创建图表:使用chart-generator技能
3. 组合输出:运行scripts/make_report.py
6.3 版本兼容处理
在references/version.md中维护版本信息:
markdown复制# 版本适配
| 软件版本 | 适配脚本 |
|----------|----------|
| PDFtk 2.x | scripts/v2/merge.py |
| PDFtk 3.x | scripts/v3/merge.py |
6.4 自动化测试套件
创建test/目录包含:
code复制test/
├── test_scripts.py # 脚本单元测试
├── test_samples/ # 测试用例
└── validate.sh # 完整校验
测试脚本示例:
python复制# test_scripts.py
def test_merge_pdf():
output = run_script('merge.py', 'a.pdf', 'b.pdf')
assert os.path.exists(output)
assert is_valid_pdf(output)
7. 技能维护与迭代
7.1 变更日志规范
在SKILL.md末尾添加:
markdown复制## 更新记录
- 2024-03-20 v1.1
- 新增batch_process.py脚本
- 更新references/encryption.md
- 2024-02-15 v1.0
- 初始版本
7.2 废弃处理策略
对于不再维护的技能:
- 在description中添加[DEPRECATED]标记
- 提供迁移指引:
markdown复制# 此技能已弃用 请改用new-pdf-toolkit技能: ```bash python upgrade_tool.py --migratecode复制
7.3 用户反馈机制
在references/feedback.md中添加:
markdown复制# 反馈渠道
1. 常见问题:见faq.md
2. 提交issue:
```bash
python scripts/report_issue.py
- 紧急联系:support@example.com
code复制
## 8. 工具链推荐
### 8.1 开发辅助工具
| 工具 | 用途 | 安装命令 |
|------|------|----------|
| SkillLint | 语法检查 | `pip install skilllint` |
| SkillViz | 结构可视化 | `npm install -g skillviz` |
| MockAI | 测试环境 | `docker run mockai` |
### 8.2 必备脚本模板
init_skill.py基础结构:
```python
#!/usr/bin/env python3
import argparse
from pathlib import Path
def create_skill(name, path):
# 创建目录结构
Path(f"{path}/{name}").mkdir(parents=True)
# 写入SKILL.md模板
with open(f"{path}/{name}/SKILL.md", "w") as f:
f.write(DEFAULT_TEMPLATE)
# ...其他初始化逻辑...
if __name__ == "__main__":
parser = argparse.ArgumentParser()
parser.add_argument("name", help="Skill名称")
parser.add_argument("--path", help="输出路径")
args = parser.parse_args()
create_skill(args.name, args.path or ".")
8.3 校验规则示例
quick_validate.py核心校验:
python复制def validate_skill(dir_path):
errors = []
# 检查SKILL.md
if not Path(f"{dir_path}/SKILL.md").exists():
errors.append("缺少SKILL.md")
# 检查frontmatter
with open(f"{dir_path}/SKILL.md") as f:
content = f.read()
if "---" not in content:
errors.append("缺少frontmatter分隔符")
return errors
9. 行业应用案例
9.1 技术文档自动化
金融行业技能:
code复制fin-docs/
├── SKILL.md # 文档生成规范
├── scripts/
│ ├── render.py # 模板渲染
│ └── validate.py # 合规检查
└── assets/
└── templates/ # 标准模板
9.2 数据分析流水线
电商分析技能:
code复制ecom-analytics/
├── SKILL.md # 分析流程
├── references/
│ ├── metrics.md # 指标定义
│ └── segments.md # 用户分群
└── scripts/
├── etl.py # 数据清洗
└── report.py # 自动报告
9.3 客户支持系统
智能客服技能:
code复制support-agent/
├── SKILL.md # 对话流程
├── references/
│ ├── products/ # 产品知识库
│ └── policies/ # 退换货政策
└── scripts/
├── escalate.py # 工单升级
└── track.py # 问题追踪
10. 性能优化策略
10.1 上下文管理技巧
-
延迟加载:
markdown复制## 高级选项 [默认不加载] 需要时查看references/advanced.md -
条件分段:
markdown复制{% if needs_ocr %} ## OCR处理步骤 ```bash python scripts/ocr.pycode复制
10.2 脚本优化原则
-
模块化设计:
python复制# scripts/lib/pdf_utils.py class PDFProcessor: @staticmethod def merge(inputs, output): # 合并逻辑 -
缓存机制:
python复制from functools import lru_cache @lru_cache def load_config(path): # 缓存配置读取
10.3 资源压缩方案
-
文本压缩:
bash复制# 预处理references/ gzip -9 references/*.md -
二进制优化:
python复制# scripts/optimize.py def compress_images(dir_path): for img in Path(dir_path).glob("*.png"): subprocess.run(["optipng", "-o7", str(img)])
11. 安全规范
11.1 输入验证标准
所有脚本必须包含:
python复制def safe_path(input_path):
"""防止路径遍历攻击"""
if "../" in str(input_path):
raise ValueError("非法路径")
return Path(input_path).resolve()
11.2 权限控制策略
在references/security.md中定义:
markdown复制# 权限等级
| 操作类型 | 所需权限 |
|----------|----------|
| 文件读取 | basic |
| 文件写入 | elevated |
| 网络访问 | admin |
11.3 敏感数据处理
创建scripts/sanitize.py:
python复制def clean_output(text):
"""移除敏感信息"""
patterns = [
r"\d{4}-\d{4}-\d{4}-\d{4}", # 信用卡号
r"\b\d{3}-\d{2}-\d{4}\b" # SSN
]
for pat in patterns:
text = re.sub(pat, "[REDACTED]", text)
return text
12. 调试与排错
12.1 日志记录规范
在scripts/中添加:
python复制import logging
logging.basicConfig(
filename='skill.log',
level=logging.DEBUG,
format='%(asctime)s - %(levelname)s - %(message)s'
)
12.2 问题诊断流程
创建references/troubleshooting.md:
markdown复制# 常见错误代码
| 代码 | 含义 | 解决方案 |
|------|------|----------|
| E101 | 输入无效 | 检查文件格式 |
| E202 | 权限不足 | 使用sudo重试 |
| E303 | 资源不足 | 增加内存配置 |
12.3 交互式调试
添加scripts/debug.py:
python复制import pdb
def debug_skill():
pdb.set_trace()
# 交互式调试
13. 技能商店设计
13.1 元数据规范
agents/openai.yaml示例:
yaml复制display_name: PDF工具箱
short_description: "处理PDF文档的完整解决方案"
categories: ["document", "productivity"]
version: 1.2.0
13.2 技能打包标准
创建package.sh:
bash复制#!/bin/bash
# 生成技能包
zip -r pdf-editor-v1.0.0.zip \
SKILL.md \
scripts/ \
references/ \
assets/ \
LICENSE
13.3 依赖声明
在SKILL.md的frontmatter中添加:
yaml复制dependencies:
- python>=3.8
- pypdf2>=2.0
- pillow>=9.0
14. 跨技能协作
14.1 技能组合模式
在SKILL.md中引用其他技能:
markdown复制## 完整报告生成
1. 使用data-analysis技能处理原始数据
2. 使用chart-generator技能创建可视化
3. 使用本技能组合为PDF报告
14.2 通用接口设计
创建scripts/interface.py:
python复制class SkillInterface:
@staticmethod
def call_skill(skill_name, input_data):
"""统一调用接口"""
14.3 数据传递规范
在references/protocol.md中定义:
markdown复制# 跨技能数据格式
```json
{
"metadata": {...},
"payload": {...}
}
15. 未来演进方向
15.1 动态技能加载
实验性scripts/dynamic_load.py:
python复制def load_skill(url):
"""从URL动态加载技能"""
resp = requests.get(url)
return resp.content
15.2 AI辅助开发
集成AI生成功能:
python复制# scripts/generate_skill.py
def generate_from_prompt(prompt):
"""根据自然语言描述生成技能骨架"""
15.3 技能市场集成
添加scripts/publish.py:
python复制def publish_to_market(skill_path):
"""发布到技能市场"""
