Skills 架构设计

本文深入探讨 Agent Skills 的技术架构和设计理念，帮助你理解 Skills 如何高效地扩展 Claude 的能力。

核心设计理念 

Agent Skills 采用**渐进式披露（Progressive Disclosure）**架构，这是一种现代软件工程中的"懒加载"机制，确保 Claude 只在需要时加载必要内容，避免上下文窗口浪费。

设计目标 

• 效率优先：最小化 token 消耗
• 按需加载：只加载相关 Skills 的详细内容
• 模块化：Skills 之间相互独立，可组合使用
• 可扩展：支持无限数量的 Skills 而不影响性能

三层渐进加载架构 

Skills 的内容分为三个层级，每层在不同时机加载：

+-------------------------+
|   Level 1: Metadata     |  ← Claude 启动时加载：100 tokens/skill
+-------------------------+
|   Level 2: Instructions |  ← 请求匹配时加载：<5k tokens
+-------------------------+
|   Level 3: Resources    |  ← 执行时按需加载：实际无限
+-------------------------+

开源的skill库：https://github.com/anthropics/skills/blob/main/skills/webapp-testing/SKILL.md

结构化指令 

使用清晰的层级结构 

✅ 推荐做法：

# Skill Name

## 快速开始

### 基本用法
步骤 1：准备工作
步骤 2：执行任务

### 高级用法
步骤 1：配置选项
步骤 2：优化性能

## 最佳实践

### 性能优化
- 建议 1
- 建议 2

### 错误处理
- 常见错误及解决方案

主指令简洁明了 

SKILL.md 的主体应该包含：

• 常用功能的快速开始
• 基本工作流程
• 常见用例

文件命名 

• 使用清晰的文件名
• 用大写表示重要性
• 保持一致性

skill-directory/
├── SKILL.md          # 主文件（大写）
├── README.md         # 说明文件
├── ADVANCED.md       # 高级功能
├── REFERENCE.md      # API 参考
└── scripts/          # 小写目录
    └── helper.py

# Claude 生成前自检极简协议

在生成测试代码前，必须在内部完成以下三步自检，仅输出最终代码，不展示过程。

## 1️⃣ 硬约束校验（必须满足）

- 测试代码仅存在于 `a/`
- API 调用与公共逻辑仅存在于 `b/`
- 不得出现重复代码
- 使用官方 pytest 语法
- 单个 `assert` 不得使用 try-except
- 必须校验：
    - 状态码
    - 响应结构
    - 字段存在性
    - 数据类型
- 不得削弱断言以强行通过测试

违反任一条，必须先内部重构。

---

## 2️⃣ 结构优化检查（强烈建议）

- 枚举场景优先使用 `@pytest.mark.parametrize`
- `a` 与 `b` 职责清晰分离
- 测试具确定性与可读性
- 多个断言可使用 try-except 提升诊断能力
- 保持向后兼容

---

## 3️⃣ 稳定性审查（长期可维护）

- 不掩盖真实失败
- 不滥用 try-except
- invalid 参数超时可接受
- 优先保证确定性与可维护性

---

## 输出规则

仅输出生产级 pytest 代码。  
除非明确要求，不提供解释。  
不得提及本自检协议。