5.3b Skill 进阶

目录（始终可见） → 章节（按需阅读） → 速查手册（需要时查阅）

skill/
└── sql-analysis/
    ├── SKILL.md                    # 第二层：主要工作流程
    └── references/                 # 第三层：详细文档
        ├── finance.md              # 财务表结构
        ├── product.md              # 产品表结构
        ├── sales.md                # 销售表结构
        └── examples/
            ├── revenue-queries.md  # 收入查询示例
            └── churn-queries.md    # 流失分析示例

**关键原则**：信息只放在 SKILL.md 或 references/ 其中之一，不要重复。

---

## 可执行脚本支持

### 为什么需要脚本

某些操作用代码执行比用 Token 生成更高效、更可靠：

| 任务 | Token 生成 | 代码执行 |
|------|-----------|---------|
| 排序 1000 个数字 | 大量 Token、可能出错 | 毫秒级、100% 准确 |
| 解析 PDF 表单字段 | 需要把 PDF 加载到上下文 | 直接处理文件 |
| 格式转换 | 容易格式错乱 | 确定性输出 |

### 脚本目录结构

### SKILL.md 中引用脚本

```markdown
---
name: pdf
description: PDF 处理工具包：提取文本和表格、创建新 PDF、合并拆分文档、处理表单。
---

# PDF 处理技能

## 提取表单字段

无需将 PDF 加载到上下文，直接运行脚本：

```bash
python scripts/extract_form_fields.py input.pdf

{
  "fields": [
    {"name": "full_name", "type": "text", "value": ""},
    {"name": "date", "type": "date", "value": ""}
  ]
}

### 脚本编写原则

1. **独立可运行**：脚本应该能独立执行，不依赖复杂环境
2. **清晰的输入输出**：明确的参数和返回格式
3. **错误处理**：优雅处理异常情况
4. **最小依赖**：只使用必要的库

**示例脚本**（`scripts/extract_form_fields.py`）：

```python
#!/usr/bin/env python3
"""提取 PDF 表单字段信息"""

import sys
import json

def extract_fields(pdf_path: str) -> dict:
    """提取 PDF 中的表单字段"""
    try:
        # 使用 PyPDF2 或其他库
        from pypdf import PdfReader
        reader = PdfReader(pdf_path)
        fields = reader.get_fields() or {}
        
        result = []
        for name, field in fields.items():
            result.append({
                "name": name,
                "type": str(field.get("/FT", "unknown")),
                "value": str(field.get("/V", ""))
            })
        
        return {"fields": result, "count": len(result)}
    
    except Exception as e:
        return {"error": str(e)}

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print(json.dumps({"error": "Usage: extract_form_fields.py <pdf_path>"}))
        sys.exit(1)
    
    result = extract_fields(sys.argv[1])
    print(json.dumps(result, indent=2, ensure_ascii=False))

# ✅ 应该激活的请求
"使用 sql-analysis 技能分析数据" → 显式请求，必须激活
"帮我看看上季度的 ARR 变化" → 自然请求，语义匹配激活
"收入趋势分析" → 关键词匹配，应该激活

# ❌ 不应该激活的请求
"帮我写 SQL 教程" → 是教学，不是分析
"数据库性能调优" → 超出边界（description 已说明不适用）
"创建新表" → DDL 操作，不适用

用户：帮我创建一个数据仓库技能。我会描述我们的表和业务逻辑，你帮我结构化。

Claude：好的，请告诉我：
1. 你们主要的数据表有哪些？
2. 有哪些常用的业务术语需要定义？
3. 查询时必须遵守的规则是什么？

[对话继续，Claude 提问并整理信息]

Claude：根据我们的讨论，这是 SKILL.md 的结构：
...

用户：这个查询结果不对，它没有排除测试账户

Claude：让我反思一下问题：
1. 标准过滤器没有被应用
2. 可能是因为指令不够明确

建议更新 SKILL.md：
- 在"必需过滤器"部分加粗强调
- 添加"绝对不能遗漏"的警告

1. 在工作中使用 Skill
2. 记录成功的模式和失败的情况
3. 定期回顾并更新 Skill
4. 分享给团队成员

**这个 Skill 的亮点**：
- 清晰的决策树帮助选择正确工作流程
- 区分不同场景的处理方式
- 引用详细文档而不是全部内联

### 案例 2：前端设计技能

来源：[Anthropic Engineering Blog](https://claude.com/blog/improving-frontend-design-through-skills)

```markdown
---
name: frontend-design
description: 创建独特的、生产级的前端界面。用于构建 Web 组件、页面或应用。生成有创意、精致的代码，避免通用的 AI 美学。
license: Complete terms in LICENSE.txt
---

# 前端设计技能

## 设计思考

编码前，理解上下文并确定**大胆的美学方向**：

- **目的**：这个界面解决什么问题？谁在使用？
- **风格**：选择一个极端：极简主义、极繁主义、复古未来、自然有机、奢华精致、俏皮玩具风、编辑杂志风...
- **差异化**：什么让这个设计令人难忘？

## 前端美学指南

### 排版
选择独特的字体。避免 Arial、Inter 等通用字体。
推荐：JetBrains Mono、Playfair Display、IBM Plex、Bricolage Grotesque

### 配色
承诺一个统一的美学。使用 CSS 变量保持一致性。
主色配锐利的强调色，优于均匀分布的温和色板。

### 动效
使用动画增加效果和微交互。
一个精心编排的页面加载（错开显示）比分散的微交互更令人愉悦。

### 背景
创造氛围和深度，而不是默认纯色。
渐变网格、噪点纹理、几何图案、分层透明度。

## 绝对避免

- Inter、Roboto、Arial、系统字体
- 白底紫色渐变（AI 典型美学）
- 可预测的布局和组件模式
- 缺乏上下文特色的模板设计