Agent Skills 概念解析以及使用方式

判断标准：

• 如果是"纯指令"且少于 100 行 → System Prompt
• 如果是"指令 + 大量参考资料" → Skill (Level 2 + Level 3)
• 如果需要"确定性执行"（如数据验证、格式转换） → Skill (Level 3 脚本)

2. 核心机制：三级加载（Progressive Disclosure）

Skills 的工程设计非常精妙：它承认 Context Window 依然是稀缺资源，所以采用"分级加载"策略。

关键理解：Level 1/2/3 不是指"内容类型"，而是指"加载时机"。

Level 1: Metadata（Always Loaded，启动时加载）

加载时机：Agent 启动时
Token 成本：~100 tokens/skill

yaml
---
name: postgres-schema-review
description: Review PostgreSQL schema designs for performance and best practices. Trigger when user asks about table design, indexing, normalization, or database optimization.
---

• 只有 name 和 description 进入 System Prompt
• 即使安装 100 个 Skills，也只占几千 Token
• Claude 只知道"这个 Skill 存在，什么时候用它"

Level 2: SKILL.md Body（Loaded When Triggered，触发时加载）

加载时机：用户请求匹配 description 时
Token 成本：通常 < 5000 tokens（建议 < 500 行）

关键机制：当用户请求匹配 description 时，Claude 读取 SKILL.md 文件：

bash
# Claude 自动执行
cat /path/to/skills/postgres-schema-review/SKILL.md

此时，SKILL.md 的主体内容（Level 1 之外的部分）才进入 Context Window。

示例内容：

markdown
# PostgreSQL Schema Review

## Quick Start

对于大多数 OLTP 场景，默认使用第三范式（3NF）：

```sql
-- ✅ 正确：拆分成关联表
CREATE TABLE orders (id BIGSERIAL PRIMARY KEY, user_id BIGINT);
CREATE TABLE order_items (id BIGSERIAL, order_id BIGINT, product_id BIGINT);
```

对于频繁 JOIN 的查询，参考 [references/denormalization.md](references/denormalization.md)。

Level 3: Bundled Resources（Loaded As Needed，按需加载）

加载时机：Claude 认为需要时
Token 成本：理论上无限（Scripts 可能被执行而不读取）

Skill 可以包含额外的资源文件，推荐按用途分类：

postgres-schema-review/
├── SKILL.md              # Level 2: 主指令
├── references/           # 文档和参考资料，会被读入 Context
│   ├── denormalization.md
│   └── indexing_guide.md
├── scripts/              # 可执行脚本，可能被执行而不读入 Context
│   ├── validate_schema.py
│   └── suggest_indexes.py
└── assets/               # 用于输出的文件，通常不读入 Context
    └── schema_template.sql

三种资源类型及加载方式：

1. References（参考文档，会被读入 Context）：

   bash
   # 当 SKILL.md 提到时，Claude 执行
   cat references/denormalization.md
   

   → 文件内容完整进入 Context

2. Scripts（可执行脚本，可能被读入 Context）：

   bash
   # Claude 执行脚本
   python scripts/validate_schema.py schema.sql
   

   → 通常只有输出进入 Context：

   ❌ Table 'users': Missing index on 'email' column
   ❌ Table 'orders': Foreign key 'user_id' has no index
   ✅ All primary keys are BIGSERIAL
   

   注意：Scripts 并非完全不进入 Context。当需要修补或环境调整时，Claude 可能需要读取脚本内容。

3. Assets（输出资源，通常不读入 Context）：

   bash
   # 当需要模板时，Claude 复制
   cp assets/schema_template.sql user_schema.sql
   

   → 文件被使用但不一定进入 Context

这个设计的关键洞察：

• References 适合"灵活指导"（需要 LLM 理解和推理）
• Scripts 适合"确定性操作"（Token 高效，执行可靠，结果可复现）
• Assets 适合"模板/资源"（被复制/修改，不占用 Context）

3. 实测数据：Skills 到底省多少？

测试场景：PostgreSQL Schema Review Agent

方案 A：全部塞进 System Prompt

System Prompt (8,500 tokens):
- PostgreSQL 最佳实践文档 (3,000 tokens)
- 常见反模式列表 (1,500 tokens)
- Schema 验证规则 (2,000 tokens)
- 示例 Schema (2,000 tokens)

问题：

• 每次对话都加载 8,500 tokens，即使用户只是问"怎么创建一个表"
• Schema 验证逻辑用自然语言描述，LLM 执行不稳定
• 成本：$3/1M tokens × 8.5k = $0.0255/次

方案 B：使用 Agent Skill

Level 1 (Always): 100 tokens
Level 2 (Triggered): SKILL.md (2,000 tokens)
Level 3 (As Needed):
  - references/denormalization.md (1,500 tokens) - 只在需要时读取
  - validate_schema.py - 通常只有输出进入 context (~50 tokens)
  - assets/*.sql - 只在需要时读取

场景 1：简单查询（70% 的对话）

• 用户："怎么创建一个索引？"
• 加载：Level 1 (100) + Level 2 (2,000) = 2,100 tokens
• 成本：$0.0063/次

场景 2：复杂审查（30% 的对话）

• 用户："帮我审查这个 Schema"
• 加载：Level 1 + Level 2 + validate_schema.py 输出 = 2,150 tokens
• 脚本执行：Schema 验证逻辑是确定性的 Python 代码，结果可靠
• 成本：$0.00645/次

平均成本对比：

• 方案 A：$0.0255/次
• 方案 B：$0.0063 × 0.7 + $0.00645 × 0.3 = $0.0063/次
• 节省 75%

更重要的收益：

• TTFT 从 2.3s 降到 0.9s（Context 减少）
• Schema 验证准确率从 85% 提升到 99%（确定性脚本）

4. 技术选型：Skill vs Prompt vs MCP

决策树

需要执行代码吗？
├─ 否 → 是简单规则（< 100 行）吗？
│       ├─ 是 → System Prompt
│       └─ 否 → Agent Skill (Level 2 Instructions)
└─ 是 → 需要访问外部系统（DB/API）吗？
        ├─ 是 → MCP Server
        └─ 否 → Agent Skill (Level 3 Code)

示例：

5. 反模式：不要滥用 Skills

❌ 错误 1：把所有东西都做成 Skill

错误示例：

yaml
---
name: encoding-rule
description: Enforce UTF-8 encoding
---
# Encoding Rule

All code must use UTF-8 encoding.

问题：这种 3 行的规则，直接写进 System Prompt 就行。创建 Skill 是过度工程。

判断标准：如果规则 < 50 行且每次都用到，别折腾 Skill。

❌ 错误 2：高频触发的 Skill

如果某个 Skill 在 80% 的对话中都会被触发，说明它应该直接进 System Prompt。

Skills 的价值在于"低频但重要"的知识。

❌ 错误 3：在 Skill 里存放动态数据

错误示例：

markdown
# User Database Skill

Current user's API key: sk-1234567890
Database connection: postgres://prod-db:5432

问题：Skills 是静态文件，不适合存放"当前用户的状态"或"实时数据"。

正确方案：用 MCP Server 提供实时数据访问。

❌ 错误 4：万能 Skill

不要搞一个 ultimate-backend-skill，里面塞满了从数据库到 API 到部署的所有内容。

正确做法：

✅ postgres-schema-review-skill  (只管数据库设计)
✅ api-design-principles-skill    (只管 API 规范)
✅ docker-deployment-skill        (只管容器部署)

让 Claude 自己决定组合使用哪几个 Skill。

6. 现成工具：如何使用这些 Skill 库

6.1 Anthropic 官方 Skills (anthropics/skills)

仓库地址：https://github.com/anthropics/skills
Stars：58.6k
定位：官方示例库 + 生产级文档处理 Skills

包含内容：

1. 文档处理 Skills（生产级，闭源但公开代码）：

   • docx - Word 文档创建和编辑
   • pptx - PowerPoint 幻灯片生成
   • xlsx - Excel 电子表格处理
   • pdf - PDF 文档生成

2. 示例 Skills（开源，Apache 2.0）：

   • 创意类：艺术、音乐、设计
   • 技术类：测试 Web 应用、MCP Server 生成
   • 企业类：沟通、品牌规范

安装方式：

bash
# Claude Code
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills

# Claude.ai
付费用户默认可用，无需安装

# Claude API
通过 Skills API 上传（需要 beta headers）

核心价值：这些是 Claude.ai 文档功能的底层实现，代表了 Skills 的生产级最佳实践。文档处理 Skills 包含复杂的 Python 脚本（Level 3 Code），用于确定性地生成 Office 文档，比让 LLM 直接生成 XML 可靠得多。

6.2 Vercel (vercel-labs/agent-skills)

仓库地址：https://github.com/vercel-labs/agent-skills
Stars：18k
定位：前端工程化专家

包含 Skills：

1. react-best-practices：

   • React 和 Next.js 性能优化指南（Vercel Engineering 出品）
   • 40+ 规则，8 个分类，按影响力优先级排序
   • 涵盖：消除 Waterfall、Bundle 优化、SSR 性能、Client-side Fetching、Re-render 优化

2. web-design-guidelines：

   • UI 代码审查工具，100+ 规则
   • 涵盖：Accessibility、Focus States、Forms、Animation、Typography、Images、Performance

3. react-native-guidelines：

   • React Native / Expo 最佳实践
   • 16 条规则，7 个分类
   • 涵盖：FlashList、Reanimated、Zustand、Platform API

4. composition-patterns：

   • React 组件组合模式
   • 避免 Boolean Prop 膨胀
   • Compound Components、State Lifting

5. vercel-deploy-claimable：

   • 一键部署到 Vercel
   • 自动检测 40+ 框架（Next.js、Vite、Astro 等）
   • 返回预览 URL 和认领 URL

安装方式：

bash
npx skills add vercel-labs/agent-skills

核心价值：这不是"React 入门教程"，而是 Vercel Engineering 的几百条生产级规范。由于 AI 比 ESLint 更懂语义，它能拦下架构级的 Bad Smell，比如"Client Component 滥用"或"Waterfall Fetching"。适合写 React/Next.js 代码时自动审查性能问题。

6.3 Supabase (supabase/agent-skills)

仓库地址：https://github.com/supabase/agent-skills
Stars：931
定位：PostgreSQL 架构师

包含 Skills：

1. supabase-postgres-best-practices：
   • PostgreSQL 性能优化指南（Supabase 出品）
   • 8 个分类，按影响力优先级排序
   • 涵盖：Query Performance、Connection Management、Schema Design、Concurrency、RLS、Monitoring

安装方式：

bash
# npm
npx skills add supabase/agent-skills

# Claude Code Plugin
/plugin marketplace add supabase/agent-skills
/plugin install postgres-best-practices@supabase-agent-skills

核心价值：这不是 SQL 语法纠错，而是高级 DBA 知识。包含 Schema 设计、索引策略、Row-Level Security、连接池配置等生产级最佳实践。它可以直接指出："你这个 JSONB 字段完全可以拆成关联表，因为你需要频繁 Update 它"。适合设计数据库表结构或优化 SQL 查询。

使用建议

安全提醒：这三个库都是官方或知名公司维护，相对安全。但使用任何第三方 Skill 前，务必审查代码（参见第 8 节）。

7. Skill 模板：标准结构

最小可用 Skill

postgres-schema-review/
└── SKILL.md

SKILL.md：

yaml
---
name: postgres-schema-review
description: Review PostgreSQL schema designs for performance and best practices. Trigger when user asks about table design, indexing, normalization, or database optimization.
---

# PostgreSQL Schema Review

你是 PostgreSQL 架构审查专家。当用户设计表结构时，按以下标准评审。

## 核心原则

1. **所有表必须有 PRIMARY KEY**
2. **所有 Foreign Keys 必须有索引**（PostgreSQL 不会自动创建）
3. **ID 字段默认使用 BIGSERIAL**（除非表永远 < 10K 行）

## 常见反模式

### ❌ VARCHAR 没有长度限制

```sql
CREATE TABLE users (email VARCHAR);  -- 错误

问题：存储膨胀，索引失效。

修复：

sql
CREATE TABLE users (email VARCHAR(255));

❌ 频繁更新的字段用 JSONB

sql
CREATE TABLE orders (items JSONB);  -- 如果 items 频繁更新，这是错误的

问题：JSONB 更新是整个字段重写，效率低。

修复：拆成关联表。

输出格式

发现问题时，按此格式输出：

❌ [表名].[字段名]: [问题]
建议: [修改方案]
理由: [原因]

完整 Skill（带脚本和资源）

postgres-schema-review/
├── SKILL.md                      # Level 2: 主指令
├── references/                   # 参考文档
│   ├── denormalization.md       # 反范式化指南
│   └── indexing_guide.md        # 索引策略指南
├── scripts/                      # 可执行脚本
│   ├── validate_schema.py       # Schema 验证
│   └── suggest_indexes.py       # 索引建议
└── assets/                       # 输出资源
    ├── ecommerce.sql            # 电商 Schema 示例
    └── saas_multi_tenant.sql    # SaaS 多租户示例

validate_schema.py 示例：

py
#!/usr/bin/env python3
import sys
import re

def validate_schema(sql_file):
    with open(sql_file) as f:
        content = f.read()

    issues = []

    # 检查：VARCHAR 是否有长度限制
    if re.search(r'VARCHAR\s*\)', content, re.IGNORECASE):
        issues.append("❌ Found VARCHAR without length limit")

    # 检查：是否所有表都有 PRIMARY KEY
    tables = re.findall(r'CREATE TABLE (\w+)', content, re.IGNORECASE)
    for table in tables:
        if not re.search(rf'{table}.*PRIMARY KEY', content, re.IGNORECASE):
            issues.append(f"❌ Table '{table}' missing PRIMARY KEY")

    if issues:
        for issue in issues:
            print(issue)
        sys.exit(1)
    else:
        print("✅ Schema validation passed")

if __name__ == '__main__':
    validate_schema(sys.argv[1])

在 SKILL.md 中引用脚本：

自动验证

要自动检查常见问题，执行：

bash
python scripts/validate_schema.py schema.sql

Claude 会自动执行脚本，代码不进入 Context，只有输出进入。

字段要求

name：

• 最大 64 字符
• 只能包含小写字母、数字、连字符
• 不能包含保留词（anthropic, claude）

description：

• 最大 1024 字符
• 必须说明"做什么"和"什么时候触发"

7.1 Skills 打包：从目录到 .skill 文件

创建完 Skill 后，需要将其打包成 .skill 文件用于分发和安装。.skill 文件本质上是一个 zip 压缩包，只是扩展名改为 .skill。

官方打包脚本：package_skill.py

Anthropic 提供了官方打包脚本 package_skill.py（在 anthropics/skills 仓库的 scripts/ 目录下），它会自动验证并打包你的 Skill。

基本用法：

bash
# 打包 Skill（输出到当前目录）
python scripts/package_skill.py path/to/skill-folder

# 指定输出目录
python scripts/package_skill.py path/to/skill-folder ./dist

打包流程：

1. 验证阶段（自动执行）：

   • 检查 YAML frontmatter 格式和必需字段（name, description）
   • 验证 Skill 命名规范（小写字母、数字、连字符）
   • 检查 description 完整性和质量
   • 验证文件组织和资源引用

2. 打包阶段（验证通过后）：

   • 创建 .skill 文件（例如 my-skill.skill）
   • 包含所有文件并保持目录结构
   • 输出到指定目录

如果验证失败，脚本会报告错误并退出（不创建包）。修复错误后重新运行。

手动打包（无需脚本）

如果本地环境没有 package_skill.py（例如缺少 Python 依赖），可以手动打包：

bash
# 进入 Skill 目录
cd path/to/skill-folder

# 使用 zip 创建 .skill 文件
zip -r ../my-skill.skill .

# 输出：../my-skill.skill

关键点：

• .skill 文件就是 zip 压缩包，扩展名改为 .skill
• 必须在 Skill 目录内部执行 zip，确保路径结构正确
• 包含所有文件：SKILL.md、scripts/、references/、assets/ 等

验证打包结果

解压 .skill 文件检查结构：

bash
# 解压查看
unzip -l my-skill.skill

# 预期输出：
# SKILL.md
# scripts/validate.py
# references/guide.md
# assets/template.sql

常见错误

分发和安装

打包后的 .skill 文件可以：

1. 分享给其他用户：

   bash
   # 用户安装
   /plugin install path/to/my-skill.skill
   

2. 发布到 GitHub：

   bash
   # 用户从 GitHub 安装
   /plugin marketplace add your-org/skills-repo
   /plugin install my-skill@your-org-skills-repo
   

3. 上传到 Anthropic Skills API（需要 beta headers）：

   python
   # 通过 API 上传
   client.beta.skills.upload("my-skill.skill")
   

8. 安全建议：只用可信来源的 Skills

关键警告：Skills 可以执行代码。恶意 Skill 可以：

• 窃取数据（读取文件系统、发送到外部服务器）
• 滥用工具（执行危险的 bash 命令）
• 伪装功能（声称是"代码审查"，实际偷偷植入后门）

安全检查清单

使用第三方 Skill 前，必须：

1. ✅ 审查所有文件：包括 SKILL.md、scripts、images
2. ✅ 检查网络调用：搜索 fetch, requests, curl, wget
3. ✅ 检查文件操作：搜索 open(), write(), rm, chmod
4. ✅ 检查外部 URL：Skill 如果从外部 URL 拉取内容，风险极高
5. ✅ 验证作者：只用 Anthropic 官方或你信任的组织的 Skills

只使用以下来源的 Skills：

• ✅ Anthropic 官方预置 Skills
• ✅ 你自己创建的 Skills
• ✅ 你公司/团队内部审查过的 Skills
• ❌ 随便从网上下载的 Skills

9. 从 Prompt 迁移到 Skill：3 步行动

Step 1: 识别候选内容（30 分钟）

检查你的 System Prompt，找出符合以下特征的部分：

Step 2: 拆分原子化 Skill（1-2 小时）

反例（错误）：

full-stack-best-practices/ # 太大了，什么都管

正例（正确）：

postgres-schema-review/ # 只管数据库设计
react-component-style/ # 只管 React 组件
api-design-principles/ # 只管 API 规范

迁移清单：

1. ✅ 创建 SKILL.md，把文档内容放进去
2. ✅ 识别"确定性逻辑"，改写成 Python/JS 脚本（放进 scripts/）
3. ✅ 把大量参考资料放进 references/ 或 assets/
4. ✅ 在 description 中明确触发条件
5. ✅ 使用 package_skill.py 打包（参见 7.1 节）

Step 3: 验证效果（1 周）

如果效果不明显：说明你的 System Prompt 本来就不长，无需优化。

10. 总结

核心观点

1. Agent Skills 不是"把 Prompt 拆分成文件"，而是"在 VM 中运行的能力包"
2. Skills 的杀手锏是 Scripts：确定性脚本通常只将输出（而非代码本身）加载到 Context，执行可靠且 Token 高效
3. Progressive Disclosure 是正确的工程权衡：三级加载机制（Metadata → SKILL.md → Bundled Resources）按需消耗 Token

使用场景