21 - Skills 高级模式
本节目标
-
理解渐进式信息披露（Progressive Disclosure）架构的设计理念
-
掌握条件 Skill 加载的三种策略（文件类型 / 任务类型 / 关键词触发）
-
学会 Skill Bundles 的组织方式（references / scripts / templates 子目录）
-
理解 Gotchas 章节作为最高信号密度的内容设计
-
掌握 Skill 测试、版本化和组合模式
核心知识点
1. 渐进式信息披露架构
传统的"全量加载"模式有一个致命缺陷：Skill 文件越长，模型越不认真看。渐进式信息披露（Progressive Disclosure）将 Skill 内容划分为多层，按需展开：
┌──────────────────────────────────────────┐ │ Layer 0: Skill 注册文件（metadata + 触发条件）│ │ 约 50-100 tokens，必定加载 │ │ 内容：名称、描述、触发词、简要说明 │ ├──────────────────────────────────────────┤ │ Layer 1: 核心指令（Core Instructions） │ │ 约 500-1500 tokens，触发时加载 │ │ 内容：核心流程、关键规则、输出格式 │ ├──────────────────────────────────────────┤ │ Layer 2: 详细参考（Detailed Reference） │ │ 约 2000-5000 tokens，按需引用 │ │ 内容：完整 API 文档、最佳实践、代码模板 │ ├──────────────────────────────────────────┤ │ Layer 3: 示例与模板（Examples & Templates） │ │ 不限长，仅在明确请求时加载 │ │ 内容：完整项目示例、视频脚本、模板文件 │ └──────────────────────────────────────────┘
设计原则：每一层都是独立的、自包含的文件。Agent 可以先读取 Layer 0-1 就开始工作，需要细节时再深入 Layer 2-3。这避免了"一本 50 页的手册塞进 prompt"的低效模式。
实际目录结构：
skills/ ├── python-patterns/ # Skill 名称 │ ├── SKILL.md # Layer 0-1：核心内容 │ ├── references/ # Layer 2：详细参考 │ │ ├── type-hints-guide.md │ │ ├── async-patterns.md │ │ └── dependency-injection.md │ ├── templates/ # Layer 3：模板 │ │ ├── fastapi-crud.py.tmpl │ │ └── service-layer.py.tmpl │ └── scripts/ # 辅助脚本 │ └── check-coverage.sh
2. 条件 Skill 加载
不是所有 Skill 每次对话都需要。条件加载机制让系统自动判断"这个 Skill 现在该不该加载"。
策略 1：文件类型触发
# 在 SKILL.md 的 frontmatter 中定义 --- triggers: file_patterns: - "*.py" # 编辑 Python 文件时加载 - "*.pyi" # Python stub 文件 - "pyproject.toml" # Python 项目配置 file_content_patterns: - "from fastapi" # 检测到 FastAPI 导入 - "@pytest.mark" # pytest 标记 - "async def" # 异步函数 ---
策略 2：任务类型触发
--- triggers: task_types: - "code_review" # 用户说"/review"或"审查代码" - "refactoring" # 用户说"重构" - "testing" # 用户说"写测试"或"运行测试" - "deployment" # 部署相关操作 ---
策略 3：关键词触发
--- triggers: keywords: # 精确匹配 exact: ["数据库迁移", "database migration", "Alembic"] # 模糊匹配（正则） regex: ["SQL\\s*Alchemy", "ORM\\s*(模型|映射)"] # 语义匹配（基于 embedding） semantic: ["数据库表结构变更", "schema 版本管理"] ---
策略 4：依赖触发
---
triggers:
depends_on:
- skill: "python-patterns" # 当 python-patterns 被加载时，自动加载本 Skill
reason: "Django 基于 Python 模式，需要先理解类型系统和异步机制"
- skill: "database-migrations"
condition: "task_contains('migration')"
---
3. Skill Bundles 设计
一个成熟的 Skill 应该是一个"Bundle"——不仅仅是 Markdown 文件，而是一个包含多种资源的目录：
skills/ └── django-security/ ├── SKILL.md # 入口文件（始终存在） │ # 包含： │ # - Frontmatter（触发条件、依赖、版本） │ # - 核心安全原则（5-7 条） │ # - 标准审查流程 │ # - 输出格式模板 │ # - Gotchas（常见陷阱） │ ├── references/ # 深度参考文档 │ ├── owasp-django.md # Django 特有的 OWASP 关注点 │ ├── csrf-patterns.md # CSRF 防护模式 │ ├── xss-prevention.md # XSS 防护（Django 模板引擎） │ └── middleware-guide.md # 安全中间件配置 │ ├── templates/ # 输出模板 │ ├── audit-report.md.tmpl # 安全审查报告模板 │ └── fix-script.py.tmpl # 常见修复脚本模板 │ └── scripts/ # 可执行脚本 ├── scan-secrets.sh # 密钥泄露扫描 └── check-headers.py # HTTP 安全头检查
入口文件 SKILL.md 的结构模板：
--- name: django-security version: 2.0.0 author: devsec-team description: Django 应用安全审查与加固 triggers: file_patterns: ["**/settings.py", "**/views.py", "**/urls.py"] keywords: ["安全审查", "security audit", "Django security"] task_types: ["code_review", "security_audit"] depends_on: - skill: "python-patterns" - skill: "web-security" --- # Django Security Skill ## 核心原则 1. 永远不要在 settings.py 中硬编码 SECRET_KEY 2. DEBUG=False 是生产环境的强制要求 3. 所有的用户输入都视为不可信的（包括 authenticated user） 4. CSRF 中间件不能禁用（除非有明确的 API-only 理由） 5. ORM 查询优先于原始 SQL ## 审查流程 1. 检查 settings.py 安全配置 2. 检查所有 View 中的用户输入处理 3. 检查模板中的 XSS 风险 4. 检查 URL 配置中的权限控制 5. 运行 `python manage.py check --deploy` ## Gotchas - **Django 默认的 CSRF 中间件不保护 GET 请求**——如果你的 GET 请求修改了数据，这是你的 Bug - **`mark_safe()` 是 XSS 的邀请函**——除非你 100% 确定内容是安全的 - **`raw()` 查询的参数化不会自动生效**——不同于 `filter()`，必须手动处理 ## 输出格式 安全审查报告必须包含： （见 references/audit-report.md.tmpl）
4. Gotchas 章节的设计哲学
Gotchas（常见陷阱）是一个 Skill 中信号密度最高的内容。它不是"一般性建议"，而是"实战中踩过的坑"。
Gotchas 的设计标准：
## Gotchas 一个好 Gotcha 的标准： 1. **具体**：精确到代码模式，而非泛泛而谈 2. **有原因**：解释为什么会掉进这个坑 3. **有解法**：给出具体的、可执行的修复方案 4. **有信号**：告诉 Agent 什么情况下需要警惕这个坑 # 示例：好的 Gotcha - Gotcha: Django REST Framework 的 `Serializer.save()` 在 `perform_create` 之前调用，导致 hook 中获取不到保存后的对象 ID。 触发信号：当代码同时使用 Serializer.save() 和 perform_create() 时。 解法：在 `perform_create()` 中手动保存，或在 `create()` 方法中统一处理。 # 示例：差的 Gotcha - 要注意 Django 的序列化器有一些陷阱。
5. Skill 测试与版本化
测试策略
# 1. 单元测试：验证 Skill 的 YAML 格式 /claude skill validate django-security # 2. 触发测试：验证条件加载是否生效 /claude skill test-trigger django-security \ --scenario "编辑 settings.py" \ --file-pattern "**/settings.py" # 3. 行为测试：用标准输入验证 Skill 输出 /claude skill test django-security \ --input "审查 src/views.py 的安全性" \ --expected-output-pattern "CRITICAL|HIGH|MEDIUM" \ --max-tokens 2000 # 4. 回归测试：每次修改 Skill 后运行 /claude skill test-all # 运行所有 Skill 的测试套件
版本化策略
# 语义化版本 version: "2.1.0" # │ │ └─ patch: 修复 Gotcha 中的描述错误 # │ └─── minor: 新增审查模式或输出格式 # └───── major: 重写核心流程（不向后兼容） # 变更日志 changelog: - version: "2.1.0" date: "2026-05-20" changes: - "新增：Django 5.0 异步 View 安全审查" - "更新：CSRF Gotcha 增加了 HTMX 场景" - version: "2.0.0" date: "2026-04-01" changes: - "重构：审查流程从 3 步扩展为 5 步" - "移除：不再建议使用 django-axes（维护已停止）"
6. Skill 组合模式
高阶用法是将多个 Skill 组合起来处理复杂任务：
# 组合模式 1：链式组合（Pipeline）
# 场景：完整的代码审查
review-pipeline:
steps:
- skill: "python-patterns" # 风格审查
- skill: "django-security" # 安全审查
- skill: "python-testing" # 测试质量审查
- skill: "performance-review" # 性能审查
merge_strategy: "union" # 合并所有产出
# 组合模式 2：条件组合（Conditional）
# 场景：根据项目类型自动选择审查 Skill
smart-review:
rules:
- if: "file_has('**/settings.py')"
skills: ["django-security", "python-patterns"]
- if: "file_has('**/router.tsx')"
skills: ["react-patterns", "typescript-review"]
- default:
skills: ["code-review-basics"]
# 组合模式 3：协同组合（Collaborative）
# 场景：多个 Skill 的产出相互补充
architecture-review:
skills:
- skill: "system-design-review"
role: "main" # 主导
- skill: "security-architecture"
role: "supplement" # 补充安全视角
- skill: "cost-optimization"
role: "supplement" # 补充成本视角
output: "merged_with_conflict_resolution"
实操步骤
步骤 1：评估现有 Skill 的信息层级
# 分析一个 Skill 的结构 /claude skill analyze python-patterns # 输出示例： # Skill: python-patterns # Layer 0 (metadata): 85 tokens ✓ # Layer 1 (core instructions): 1,200 tokens ✓ # Layer 2 (references): Not loaded (已分离到 references/) # Layer 3 (templates): Not loaded (已分离到 templates/) # 评分：EXCELLENT - 符合渐进式信息披露架构
步骤 2：将一个"大 Skill"拆分为 Bundle
# 假设你有一个 3000 行的 SKILL.md
# 步骤 1：提取核心流程到 SKILL.md（目标 500 行以内）
# 步骤 2：详细文档移到 references/
# 步骤 3：代码模板移到 templates/
# 步骤 4：脚本移到 scripts/
mkdir -p skills/my-skill/{references,templates,scripts}
# 编辑 SKILL.md，将所有 reference 链接改为相对路径引用
# 例如：见 [references/advanced-topics.md](references/advanced-topics.md)
步骤 3：添加条件触发配置
在 SKILL.md 的 frontmatter 中添加：
--- triggers: file_patterns: - "**/*.py" keywords: exact: ["Python", "async", "type hints"] regex: ["@dataclass", "async\\s+def", "Protocol"] task_types: - "code_review" - "refactoring" ---
验证触发条件：
/claude skill test-trigger my-skill --scenario "编辑 async_handler.py" # 输出：✓ 触发条件匹配
步骤 4：编写 Gotchas
基于你团队最近 3 个月的 Code Review 记录，提炼出 5-10 条 Gotchas：
## Gotchas 1. 异步生成器中的异常不会传播 触发：函数签名包含 `async def ... yield` 问题：`try-except` 在 `yield` 后可能不生效 解法：在 `yield` 前捕获，或使用 `contextlib.aclosing()` 2. `asyncio.gather()` 不是真正的并行 触发：在 gather 中混合 CPU 密集和 IO 密集任务 问题：CPU 密集任务会阻塞事件循环 解法：CPU 密集任务使用 `loop.run_in_executor()`
避坑指南
坑 1：Skill 写成"知识库"而非"行动指南"
现象：Skill 里全是概念解释和背景知识，Agent 读完还是不知道该怎么做。 解法：Skill 的核心是"how to do"，不是"what is"。每条知识后面必须跟一个可执行的动作。反面例子："Python 的类型系统很强大"；正面例子："所有函数参数必须标注类型，使用 -> ReturnType 标注返回值"。
坑 2：Frontmatter 中的触发词太宽泛
现象：设置了 keywords: ["code"]，结果每次对话都触发这个 Skill。 解法：触发词要精确到"只有这个场景才会匹配"。宁愿多设几个精确 trigger，也不要一个宽泛 trigger。测试方法：运行 10 次对话，看 Skill 的触发频次是否符合预期。
坑 3：忽略 Skill 之间的依赖关系
现象：Skill A 引用了 Skill B 中的概念，但 Skill B 没有被加载，导致 Agent 理解偏差。 解法：使用 depends_on 声明依赖关系。Agent 加载 Skill A 时会自动检查 Skill B 是否已加载。
坑 4：Gotchas 超过 10 条
现象：Gotchas 列表有 30 条，Agent 根本不可能全部记住和应用。 解法：Gotchas 严格控制在 10 条以内，按"出现频率 x 危害程度"排序。超出 10 条的部分，说明你的核心流程本身需要重构，而不是继续堆 Gotchas。
课后作业
-
基础练习：选择你团队中一个已有的 Skill（或创建一个新的），按渐进式信息披露架构重新组织：SKILL.md（<500 行）、references/（详细文档）、templates/（模板）、scripts/（脚本）。
-
进阶练习：收集团队过去 3 个月的 Code Review 记录，提炼出 5 条 Gotchas，写入对应的 Skill 文件中。每条 Gotchas 必须包含：触发条件 + 问题描述 + 根本原因 + 修复代码。
-
挑战练习：设计一套 Skill 自动化测试框架，包含：
-
格式验证（YAML frontmatter 完整性检查）
-
触发条件测试（用 mock 场景验证触发准确性）
-
行为测试（输入标准 prompt，验证输出是否包含必要元素）
-
回归测试（修改 Skill 后自动运行全套测试） 写出框架的核心代码。
-
总结
Skills 的质量不取决于"写了多少"，而取决于"Agent 能用上多少"。渐进式信息披露架构的核心思想是：让 Agent 先看到最重要的 20%，需要时再看到剩下的 80%。
四个高级原则：
-
分层设计：Layer 0-3 各有定位，不混不杂
-
精确触发：该加载时才加载，不该加载时别添乱
-
Gotchas 驱动：最具价值的不是"最佳实践"，而是"最常见的翻车现场"
-
可测试可版本化：Skill 也是代码，需要测试、需要版本管理、需要变更日志
当你开始用"工程化"的视角设计 Skills 时，你就从 AI 工具的消费者变成了 AI 能力的构建者。
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。
更多推荐
0
0- 0
已为社区贡献16条内容
所有评论(0)