skill-developer

技能开发指南

目的

全面介绍如何在 Claude Code 中创建和管理技能，并使用一个示例性的自定义钩子架构、简明的渐进式披露模式和渐进式披露模式实现自动激活系统。

何时使用此技能

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

• 创建或添加技能
• 修改技能触发条件或规则
• 了解技能激活的工作方式
• 调试技能激活问题
• 使用 skill-rules.json
• 钩子系统机制
• Claude Code 最佳实践
• 渐进式披露
• YAML frontmatter
• 500 行规则

---

适用范围和可用性

此处介绍的钩子、封装程序和 skill-rules.json 是自定义示例系统，不是 Claude Code 内置功能，也未随此代码树一同提供。在运行示例之前，请确认它们是否存在并审查其实现。使用固定版本的本地依赖，保留现有配置，并在注册任意代码钩子之前获得授权。钩子建议和每个会话一次的提醒并非安全防护，也不能证明技能已被调用。

系统概览

双钩子架构

1. UserPromptSubmit 钩子（主动建议）

• 文件：.claude/hooks/skill-activation-prompt.ts
• 触发时机：Claude 看到用户提示词之前
• 目的：根据关键词和意图模式建议相关技能
• 方式：将格式化的提醒作为上下文注入（stdout → Claude 的输入）
• 使用场景：基于主题的技能、隐式工作检测

2. Stop 钩子——错误处理提醒（温和提醒）

• 文件：.claude/hooks/error-handling-reminder.ts
• 触发时机：Claude 完成回复之后
• 目的：温和提醒 Claude 自行检查所写代码中的错误处理
• 方式：分析已编辑文件中的风险模式，如有需要则显示提醒
• 使用场景：提高错误处理意识，同时避免阻碍工作流

**理念转变（2025-10-27）：**我们不再使用会阻止操作的 PreToolUse 来处理 Sentry/错误处理。改为在回复后提供温和提醒，既不阻碍工作流，又能保持对代码质量的关注。

配置文件

位置：.claude/skills/skill-rules.json

定义：

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

---

技能类型

1. 护栏技能

目的： 强制执行可预防错误的关键最佳实践

特点：

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

示例：

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

适用场景：

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

2. 领域技能

目的： 为特定领域提供全面指导

特点：

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

示例：

• backend-dev-guidelines——Node.js/Express/TypeScript 模式
• frontend-dev-guidelines——React/TypeScript 最佳实践
• error-tracking——Sentry 集成指南

适用场景：

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

---

快速入门：创建新技能

步骤 1：创建技能文件

位置： .claude/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

最佳实践：

• ✅ 名称：使用小写字母和连字符；优先采用动名词形式（动词 + -ing）
• ✅ 描述：包含所有触发关键词/短语（最多 1024 个字符）
• ✅ 内容：少于 500 行；详细信息请使用参考文件
• ✅ 示例：使用真实代码示例
• ✅ 结构：使用清晰的标题、列表和代码块

步骤 2：添加到 skill-rules.json

完整的架构请参阅 SKILL_RULES_REFERENCE.md。

基本模板：

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

步骤 3：测试触发条件

测试 UserPromptSubmit：

echo '{"session_id":"test","prompt":"your test prompt"}' | \
  npx tsx .claude/hooks/skill-activation-prompt.ts

测试 PreToolUse：

cat <<'EOF' | npx tsx .claude/hooks/skill-verification-guard.ts
{"session_id":"test","tool_name":"Edit","tool_input":{"file_path":"test.ts"}}
EOF

步骤 4：完善模式

根据测试结果：

• 添加缺失的关键词
• 优化意图模式以减少误报
• 调整文件路径模式
• 使用实际文件测试内容模式

步骤 5：遵循 Anthropic 最佳实践

✅ 确保 SKILL.md 少于 500 行
✅ 使用参考文件实现渐进式披露
✅ 为超过 100 行的参考文件添加目录
✅ 编写包含触发关键词的详细描述
✅ 在编写文档前使用 3 个或更多真实场景进行测试
✅ 根据实际使用情况迭代改进

---

执行级别

BLOCK（关键防护措施）

• 从物理层面阻止 Edit/Write 工具执行
• Hook 返回退出代码 2，stderr 内容会发送给 Claude
• Claude 会看到消息，必须使用技能才能继续
• 适用场景：严重错误、数据完整性问题、安全问题

示例： 验证数据库列名

SUGGEST（建议）

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

示例： 前端开发指南

WARN（可选）

• 低优先级建议
• 仅提供建议，几乎不强制执行
• 适用场景：可有可无的建议、信息提醒

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

---

跳过条件与用户控制

1. 会话跟踪

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

工作方式：

• 第一次编辑 → Hook 阻止操作并更新会话状态
• 第二次编辑（同一会话）→ Hook 允许操作
• 不同会话 → 再次阻止操作

状态文件： .claude/hooks/state/skills-used-{session_id}.json

2. 文件标记

用途： 作为示例提供便利的跳过方式；文件标记不是验证证据

标记： // @skip-validation

用法：

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

注意： 不要使用可编辑标记或环境覆盖来绕过实际的安全/策略关卡。覆盖操作必须遵循由所有者控制的策略并获得明确授权。

3. 环境变量

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

全局禁用：

export SKIP_SKILL_GUARDRAILS=true  # Disables ALL PreToolUse blocks

针对特定技能：

export SKIP_DB_VERIFICATION=true
export SKIP_ERROR_REMINDER=true

---

测试清单

创建新技能时，请确认：

• 已在 .claude/skills/{name}/SKILL.md 中创建技能文件
• Frontmatter 中包含正确的名称和描述
• 已在 skill-rules.json 中添加条目
• 已使用真实提示词测试关键词
• 已使用不同变体测试意图模式
• 已使用实际文件测试文件路径模式
• 已根据文件内容测试内容模式
• 阻止操作的消息清晰且可执行（如适用防护措施）
• 已适当配置跳过条件
• 优先级与重要性匹配
• 测试中没有误报
• 测试中没有漏报
• 性能可接受（<100ms 或 <200ms）
• 已验证 JSON 语法：jq . skill-rules.json
• SKILL.md 少于 500 行 ⭐
• 按需创建了参考文件
• 为超过 100 行的文件添加了目录

---

参考文件

有关特定主题的详细信息，请参阅：

TRIGGER_TYPES.md

所有触发器类型的完整指南：

• 关键词触发器（显式主题匹配）
• 意图模式（隐式动作检测）
• 文件路径触发器（glob 模式）
• 内容模式（文件中的正则表达式）
• 每种类型的最佳实践和示例
• 常见问题和测试策略

SKILL_RULES_REFERENCE.md

完整的 skill-rules.json 架构：

• 完整的 TypeScript 接口定义
• 逐字段说明
• 完整的护栏技能示例
• 完整的领域技能示例
• 验证指南和常见错误

HOOK_MECHANISMS.md

深入剖析钩子内部机制：

• UserPromptSubmit 流程（详细说明）
• PreToolUse 流程（详细说明）
• 退出代码行为表（重要）
• 会话状态管理
• 性能注意事项

TROUBLESHOOTING.md

全面的调试指南：

• 技能未触发（UserPromptSubmit）
• PreToolUse 未拦截
• 误报（触发过多）
• 钩子完全未执行
• 性能问题

PATTERNS_LIBRARY.md

可直接使用的模式集合：

• 意图模式库（正则表达式）
• 文件路径模式库（glob）
• 内容模式库（正则表达式）
• 按使用场景分类
• 可直接复制粘贴

ADVANCED.md

未来的增强功能和想法：

• 动态规则更新
• 技能依赖
• 条件式强制执行
• 技能分析
• 技能版本管理

---

快速参考摘要

创建新技能（5 个步骤）

1. 创建带有 frontmatter 的 .claude/skills/{name}/SKILL.md
2. 在 .claude/skills/skill-rules.json 中添加条目
3. 使用 npx tsx 命令进行测试
4. 根据测试结果优化模式
5. 将 SKILL.md 控制在 500 行以内

触发器类型

• 关键词：显式提及主题
• 意图：隐式动作检测
• 文件路径：基于位置的激活
• 内容：特定技术检测

完整详情请参见 TRIGGER_TYPES.md。

强制执行

• BLOCK：退出代码为 2，仅用于关键情况
• SUGGEST：注入上下文，最常用
• WARN：提示性警告，较少使用

跳过条件

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

Anthropic 最佳实践

✅ 500 行规则：将 SKILL.md 控制在 500 行以内
✅ 渐进式披露：使用参考文件提供详细信息
✅ 目录：为超过 100 行的参考文件添加目录
✅ 只深入一层：不要深层嵌套引用
✅ 丰富的描述：包含所有触发关键词（最多 1024 个字符）
✅ 先测试：在编写大量文档前，先构建至少 3 项评估
✅ 动名词命名：优先采用动词 + -ing（例如，“processing-pdfs”）

故障排查

手动测试钩子：

# UserPromptSubmit
echo '{"prompt":"test"}' | npx tsx .claude/hooks/skill-activation-prompt.ts

# PreToolUse
cat <<'EOF' | npx tsx .claude/hooks/skill-verification-guard.ts
{"tool_name":"Edit","tool_input":{"file_path":"test.ts"}}
EOF

完整的调试指南请参见 TROUBLESHOOTING.md。

---

相关文件

配置：

• .claude/skills/skill-rules.json - 主配置
• .claude/hooks/state/ - 会话跟踪
• .claude/settings.json - 钩子注册

钩子：

• .claude/hooks/skill-activation-prompt.ts - UserPromptSubmit
• .claude/hooks/error-handling-reminder.ts - Stop 事件（温和提醒）

所有技能：

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

---

技能状态：已完成 - 已按照 Anthropic 最佳实践重新整理 ✅
行数：< 500（遵循 500 行规则）✅
渐进式披露：通过参考文件提供详细信息 ✅

下一步：创建更多技能，并根据使用情况优化模式

局限性

• 仅当任务明确符合上述范围时才使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必要的输入、权限、安全边界或成功标准，请暂停并请求澄清。