名称: 技能开发者描述: 创建和管理 Claude Code 技能，遵循 Anthropic 最佳实践。用于创建新技能、修改 skill-rules.json、理解触发模式、处理钩子、调试技能激活或实施渐进式披露。涵盖技能结构、YAML frontmatter、触发类型（关键词、意图模式、文件路径、内容模式）、执行级别（阻止、建议、警告）、钩子机制（UserPromptSubmit、PreToolUse）、会话跟踪和 500 行规则。

技能开发者指南

目的

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

何时使用此技能

自动激活当您提到：

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

系统概述

双钩架构

1. UserPromptSubmit 钩子（主动建议）

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

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

文件: .claude/hooks/error-handling-reminder.ts
触发: 在 Claude 完成响应后
目的: 温和提醒自我评估编写的代码中的错误处理
方法: 分析编辑的文件以查找风险模式，如有需要则显示提醒
用例: 错误处理意识，无阻塞摩擦

理念变化（2025-10-27）: 我们不再使用 PreToolUse 阻止 Sentry/错误处理。相反，使用温和的后响应提醒，不阻塞工作流，但保持代码质量意识。

配置文件

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

定义：

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

技能类型

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.md

模板:

---
名称: 我的新技能
描述: 简要描述包括触发此技能的关键词。提及主题、文件类型和用例。明确触发术语。
---

# 我的新技能

## 目的
此技能帮助的内容

## 何时使用
具体场景和条件

## 关键信息
实际指导、文档、模式、示例

最佳实践:

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

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

参见 SKILL_RULES_REFERENCE.md 获取完整模式。

基本模板:

{
  "我的新技能": {
    "type": "domain",
    "enforcement": "suggest",
    "priority": "medium",
    "promptTriggers": {
      "keywords": ["关键词1", "关键词2"],
      "intentPatterns": ["(创建|添加).*?某物"]
    }
  }
}

步骤 3：测试触发

测试 UserPromptSubmit:

echo '{"session_id":"测试","prompt":"您的测试提示"}' | \
  npx tsx .claude/hooks/skill-activation-prompt.ts

测试 PreToolUse:

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

步骤 4：优化模式

基于测试：

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

步骤 5：遵循 Anthropic 最佳实践

✅ 保持 SKILL.md 少于 500 行 ✅ 使用渐进式披露与参考文件 ✅ 为参考文件添加目录，如果超过 100 行 ✅ 编写包含触发关键词的详细描述 ✅ 在文档前测试 3+ 真实场景 ✅ 基于实际使用迭代

执行级别

阻止（关键护栏）

物理阻止编辑/写入工具执行
钩子退出代码 2，stderr → Claude
Claude 看到消息，必须使用技能以继续
用于: 关键错误、数据完整性、安全问题

示例: 数据库列名验证

建议（推荐）

提醒在 Claude 看到提示前注入
Claude 知道相关技能
非强制执行，仅建议
用于: 领域指导、最佳实践、操作指南

示例: 前端开发指南

警告（可选）

低优先级建议
仅建议，最小执行
用于: 可有可无的建议、信息性提醒

很少使用 - 大多数技能要么阻止，要么建议。

跳过条件与用户控制

1. 会话跟踪

目的: 在同一会话中不重复提醒

工作原理:

首次编辑 → 钩子阻止，更新会话状态
第二次编辑（同一会话） → 钩子允许
不同会话 → 再次阻止

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

2. 文件标记

目的: 永久跳过已验证文件

标记: // @skip-validation

用法:

// @skip-validation
import { PrismaService } from './prisma';
// 此文件已手动验证

注意: 谨慎使用 - 如果过度使用则失去目的

3. 环境变量

目的: 紧急禁用、临时覆盖

全局禁用:

export SKIP_SKILL_GUARDRAILS=true  # 禁用所有 PreToolUse 阻止

技能特定:

export SKIP_DB_VERIFICATION=true
export SKIP_ERROR_REMINDER=true

测试清单

创建新技能时，验证：

[ ] 技能文件在 .claude/skills/{名称}/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）
内容模式库（正则表达式）
按用例组织
可复制粘贴

快速参考摘要

创建新技能（5 步骤）

使用 frontmatter 创建 .claude/skills/{名称}/SKILL.md
添加条目到 .claude/skills/skill-rules.json
使用 npx tsx 命令测试
基于测试优化模式
保持 SKILL.md 少于 500 行

触发类型

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

参见 TRIGGER_TYPES.md 获取完整详情。

执行

阻止: 退出代码 2，仅关键时使用
建议: 注入上下文，最常见
警告: 建议性，很少使用

跳过条件

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

Anthropic 最佳实践

✅ 500 行规则: 保持 SKILL.md 少于 500 行 ✅ 渐进式披露: 使用参考文件获取详细信息 ✅ 目录: 为参考文件添加目录，如果超过 100 行 ✅ 一级深度: 不深度嵌套参考 ✅ 丰富描述: 包括所有触发关键词（最多 1024 字符） ✅ 先测试: 在广泛文档前构建 3+ 评估 ✅ 动名词命名: 优选动词 + -ing（例如，“processing-pdfs”）

故障排除

手动测试钩子：

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

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

参见 TROUBLESHOOTING.md 获取完整调试指南。

技能开发者Skill skill-developer