skill-developer

技能开发指南

目的

全面介绍如何在 Claude Code 中创建和管理技能，遵循 Agent Skills Specification 以及 Anthropic 的最佳实践，包括 500 行规则和渐进式披露模式。

Agent Skills Specification (agentskills.io)

本项目中的技能遵循开放的 Agent Skills Specification。主要要求如下：

目录结构

skills/{skill-name}/
├── SKILL.md           # Required - main skill file
├── references/        # Optional - detailed documentation
├── scripts/           # Optional - executable code (Python, Bash, JS)
└── assets/            # Optional - templates, images, data files

SKILL.md Frontmatter 架构

必填字段：

字段	要求
name	1-64 个字符，仅限小写字母、数字和连字符，且必须与目录名称一致
description	1-1024 个字符，包含用于激活 Agent 的关键词

可选字段：

字段	用途
license	用于公开分享技能的许可证
compatibility	环境要求（软件包、网络访问）
metadata	用于自定义属性的键值对
allowed-tools	预先批准的工具列表（实验性）

渐进式披露模型

1. 元数据（约 100 个 token）——在启动时加载
2. 完整说明（建议少于 5000 个 token）——激活时加载
3. 支持文件——按需加载

验证

使用 skills-ref 工具或手动验证：

• 文件名必须为 SKILL.md（大写）
• Frontmatter 中的名称必须与上级目录一致
• 描述应包含触发关键词

何时使用此技能

提及以下内容时会自动激活：

• 创建或添加技能
• 修改技能触发条件或规则
• 了解技能激活的工作方式
• 调试技能激活问题
• Claude Code 最佳实践
• 渐进式披露
• YAML frontmatter
• 500 行规则

---

系统概览

技能激活方式

技能激活有多种方式，从简单到高级：

1. 基于描述的激活（默认）

• Claude 会在会话开始时读取 frontmatter 中的技能描述
• 当用户提示与描述关键词匹配时激活技能
• 无需额外配置
• 与 agentskills.io 规范开箱即用

2. 实现示例：基于 Hook 的激活

如需更复杂的激活方式，可以构建 Hook 系统。这是一种高级模式：

UserPromptSubmit Hook（主动建议）

• 触发时机：Claude 看到用户提示之前
• 用途：根据关键词和意图模式建议相关技能
• 方法：将格式化提醒作为上下文注入（通过 stdout 传递给 Claude 的输入）

Stop Hook（温和提醒）

• 触发时机：Claude 完成回复之后
• 用途：温和提醒 Claude 自行检查已编写代码中的模式
• 方法：分析已编辑文件中的模式，并在需要时显示提醒

Hook 系统的配置：

规则文件（例如 skill-rules.json）可以定义：

• 所有技能及其触发条件
• 强制级别（阻止、建议、警告）
• 文件路径模式（glob）
• 内容检测模式（regex）
• 跳过条件（会话跟踪、文件标记、环境变量）

---

技能类型

1. 护栏技能

用途： 强制执行可避免错误的关键最佳实践

特点：

• 类型："guardrail"
• 强制级别："block"
• 优先级："critical" 或 "high"
• 使用技能之前阻止编辑文件
• 防止常见错误
• 感知会话状态（同一会话中不重复提醒）

示例：

• database-verification - 查询前验证表名和列名
• frontend-dev-guidelines - 强制遵循 React/TypeScript 模式

适用场景：

• 会导致运行时错误的失误
• 数据完整性问题
• 关键兼容性问题

2. 领域技能

用途： 为特定领域提供全面指导

特点：

• 类型："domain"
• 强制级别："suggest"
• 优先级："high" 或 "medium"
• 提供建议，而非强制要求
• 针对特定主题或领域
• 提供全面的文档

示例：

• backend-dev-guidelines - Node.js/Express/TypeScript 模式
• frontend-dev-guidelines - React/TypeScript 最佳实践
• drupal-search-api - Search API 配置指南

适用场景：

• 需要深入了解的复杂系统
• 最佳实践文档
• 架构模式
• 操作指南

---

快速入门：创建新技能

步骤 1：创建技能文件

位置： skills/{skill-name}/SKILL.md

模板：

---
name: my-new-skill
description: Brief description including keywords that trigger this skill. Mention topics, file types, and use cases. Be explicit about trigger terms.
---

# My New Skill

## Purpose
What this skill helps with

## When to Use
Specific scenarios and conditions

## Key Information
The actual guidance, documentation, patterns, examples

最佳实践（依据 agentskills.io 规范）：

• 名称：1-64 个字符，使用小写字母、数字和连字符，且必须与目录名称一致
• 描述：1-1024 个字符，包含所有触发关键词/短语
• 内容：少于 500 行——详情请使用 references/ 目录
• 示例：真实代码示例
• 结构：使用清晰的标题、列表和代码块

步骤 2：（可选）添加触发规则

如果使用基于钩子的激活系统，请添加规则：

基本模板：

{
  "my-new-skill": {
    "type": "domain",
    "enforcement": "suggest",
    "priority": "medium",
    "promptTriggers": {
      "keywords": ["keyword1", "keyword2"],
      "intentPatterns": ["(create|add).*?something"]
    }
  }
}

步骤 3：测试激活

验证技能能否正确激活：

• 尝试应触发技能的提示词
• 尝试不应触发技能的提示词
• 根据结果优化描述中的关键词

步骤 4：遵循 Anthropic 最佳实践

• 将 SKILL.md 控制在 500 行以内
• 使用参考文件实现渐进式披露
• 为超过 100 行的参考文件添加目录
• 编写包含触发关键词的详细描述
• 编写文档前，使用至少 3 个真实场景进行测试
• 根据实际使用情况进行迭代

---

强制级别

BLOCK（关键防护措施）

• 从物理上阻止 Edit/Write 工具执行
• Claude 会看到消息，必须使用技能才能继续
• 适用场景： 关键错误、数据完整性、安全问题

示例： 验证数据库列名称

SUGGEST（建议）

• 在 Claude 查看提示词前注入提醒
• Claude 会知晓相关技能
• 不会强制执行，仅提供建议
• 适用场景： 领域指导、最佳实践、操作指南

示例： 前端开发指南

WARN（可选）

• 低优先级建议
• 仅提供建议，强制程度最低
• 适用场景： 锦上添花的建议、信息提示

很少使用——大多数技能属于 BLOCK 或 SUGGEST。

---

跳过条件与用户控制

1. 会话跟踪

用途： 避免在同一会话中反复提醒

工作方式：

• 首次编辑：钩子阻止操作并更新会话状态
• 第二次编辑（同一会话）：钩子放行
• 不同会话：再次阻止

2. 文件标记

用途： 永久跳过已验证文件的检查

标记： // @skip-validation

用法：

// @skip-validation
import { PrismaService } from './prisma';
// This file has been manually verified

注意： 请谨慎使用——过度使用会背离其初衷

3. 环境变量

用途： 紧急停用、临时覆盖

全局停用：

export SKIP_SKILL_GUARDRAILS=true  # Disables ALL blocks

针对特定技能：

export SKIP_DB_VERIFICATION=true

---

测试清单

创建新技能时，请验证：

• 已在 skills/{name}/SKILL.md 中创建技能文件
• frontmatter 中包含正确的名称和描述
• 已使用真实提示词测试关键词
• 测试中没有误报
• 测试中没有漏报
• SKILL.md 少于 500 行
• 已按需创建参考文件
• 已为超过 100 行的文件添加目录

---

高级主题

对于构建复杂激活系统的团队，请考虑：

• 触发类型：关键词、意图模式、文件路径 glob、内容正则表达式
• 钩子机制：UserPromptSubmit、PreToolUse、Stop 事件钩子
• 会话状态管理：跟踪已确认的技能
• 性能：将钩子执行时间控制在 200ms 以内
• 模式库：可重复使用的正则表达式和 glob 模式

这些主题记录在可选的参考文件中：

• TRIGGER_TYPES.md - 完整的触发类型指南
• SKILL_RULES_REFERENCE.md - 规则架构文档
• HOOK_MECHANISMS.md - 深入介绍钩子内部机制
• TROUBLESHOOTING.md - 激活问题调试
• PATTERNS_LIBRARY.md - 可直接使用的模式集合

---

快速参考摘要

创建新技能（4 个步骤）

1. 创建带有 frontmatter 的 skills/{name}/SKILL.md
2. 使用真实提示词测试激活效果
3. 根据测试结果优化描述中的关键词
4. 将 SKILL.md 控制在 500 行以内

触发类型

• 关键词：明确提及主题（在描述中）
• 意图：隐式检测操作（高级，通过钩子实现）
• 文件路径：基于位置的激活（高级，通过钩子实现）
• 内容：特定技术检测（高级，通过钩子实现）

强制执行

• BLOCK：仅用于关键情况，可阻止工具执行
• SUGGEST：最常用，用于注入建议性上下文
• WARN：提供建议，很少使用

跳过条件

• 会话跟踪：自动进行（防止重复提醒）
• 文件标记：// @skip-validation（永久跳过）
• 环境变量：SKIP_SKILL_GUARDRAILS（紧急禁用）

Anthropic 最佳实践与 agentskills.io 规范

• 500 行规则：将 SKILL.md 控制在 500 行以内
• 渐进式披露：使用 references/ 目录存放详细文档
• 目录：为超过 100 行的参考文件添加目录
• 仅深入一层：不要将参考内容嵌套得太深
• 丰富的描述：包含所有触发关键词（根据规范，最多 1024 个字符）
• 名称 = 目录：frontmatter 中的技能名称必须与父目录匹配
• 先测试：在编写大量文档之前，先构建 3 个或更多评估项
• 规范 URL：https://agentskills.io/specification

故障排除

尝试使用应该触发和不应该触发技能的提示词，测试技能激活效果。迭代优化描述中的关键词。

---

参考文件

以上介绍的基于钩子的激活模式的深入文档 （这种架构高级且可选；基于描述的激活无需使用这些内容）：

• references/TRIGGER_TYPES.md - 详细介绍关键词、意图、文件路径和内容触发类型
• references/SKILL_RULES_REFERENCE.md - 完整的 skill-rules.json 架构
• references/HOOK_MECHANISMS.md - UserPromptSubmit/Stop 钩子的工作方式
• references/TROUBLESHOOTING.md - 调试技能激活
• references/PATTERNS_LIBRARY.md - 可重复使用的触发器/规则模式
• references/ADVANCED.md - 高级主题

---

相关文件

配置：

• skills/*/SKILL.md - 技能内容文件

规范：

• https://agentskills.io/specification - Agent Skills 规范

---

致谢

上述基于钩子的激活架构和参考文件改编自 diet103/claude-code-infrastructure-showcase （MIT License）。