skill-developer

技能开发者指南

目的

在 Claude Code 中创建和管理技能的全面指南，包含自动激活系统，遵循 Anthropic 的官方最佳实践，包括 500 行规则和渐进式披露模式。

何时使用此技能

当您提到以下内容时自动激活：

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

---

系统概述

双 Hook 架构

1. UserPromptSubmit Hook（主动建议）

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

2. Stop Hook - 错误处理提醒（温和提醒）

• 文件：.claude/hooks/error-handling-reminder.ts
• 触发时机：在 Claude 完成响应之后
• 目的：温和提醒自我评估所写代码中的错误处理
• 方法：分析已编辑文件中的风险模式，如有需要则显示提醒
• 用例：在不产生阻塞摩擦的情况下提高错误处理意识

理念变化（2025-10-27）： 我们不再为 Sentry/错误处理使用阻塞式 PreToolUse。取而代之的是，使用温和的响应后提醒，既不阻塞工作流，又能保持代码质量意识。

配置文件

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

完整的 schema 请参见 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
• 具有包含 name 和 description 的正确 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

深入探讨 hook 内部机制：

• UserPromptSubmit 流程（详细）
• PreToolUse 流程（详细）
• 退出码行为表（关键）
• 会话状态管理
• 性能考量

TROUBLESHOOTING.md

全面的调试指南：

• 技能未触发（UserPromptSubmit）
• PreToolUse 未阻止
• 误报（触发过多）
• Hook 完全未执行
• 性能问题

PATTERNS_LIBRARY.md

开箱即用的模式集合：

• 意图模式库（regex）
• 文件路径模式库（glob）
• 内容模式库（regex）
• 按使用场景组织
• 可复制粘贴直接使用

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"）

故障排查

手动测试 hooks：

# 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 - Hook 注册

Hooks：

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

所有技能：

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

---

技能状态：COMPLETE - 已按照 Anthropic 最佳实践重构 ✅ 行数：< 500（遵循 500 行规则）✅ 渐进式披露：使用参考文件承载详细信息 ✅

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