skill-developer
遵循 Anthropic 最佳实践创建和管理 Claude 代码技能。适用于以下场景：创建新技能、修改 skill-rules.json 文件、理解触发模式、处理钩子机制、调试技能激活，或实施渐进式信息呈现。涵盖技能结构、YAML 前置元数据、触发类型（关键词、意图模式、文件路径、内容模式）、执行级别（阻止、建议、警告）、钩子机制（用户提示提交、工具使用前）、会话跟踪以及 500 行规则。
Skill Developer - Claude Code 技能开发完整指南
技能概述
Skill Developer 是创建和管理 Claude Code 自定义技能的权威指南，帮助开发者掌握 Anthropic 官方最佳实践，包括技能架构设计、触发器配置、Hook 机制和 500 行规则。
适用场景
-
创建新的 Claude Code 技能 当你需要为特定领域或任务创建自定义技能时，该指南提供从 SKILL.md 编写到 skill-rules.json 配置的完整流程，确保技能符合 Anthropic 官方规范。
-
调试技能激活问题 当你编写的技能没有被自动激活时，该指南提供了系统化的调试方法，包括触发器测试、Hook 验证和常见问题排查。
-
实现渐进式披露模式 当技能文档超过 500 行时，该指南教你如何使用参考文件和分层结构来保持核心 SKILL.md 的简洁性，同时提供详尽的参考文档。
核心功能
-
双 Hook 架构系统 详细讲解 UserPromptSubmit（主动建议）和 Stop Hook（温和提醒）两种 Hook 的工作机制，帮助开发者理解技能如何在合适的时机被激活和调用。
-
完整的触发器类型支持 涵盖关键词触发、意图模式（正则表达式）、文件路径（Glob）和内容检测四种触发方式，并提供实际场景的最佳模式配置示例。
-
灵活的执行级别控制 支持 BLOCK（强制阻止）、SUGGEST（建议提醒）和 WARN（警告）三种执行级别，让开发者根据技能的重要性选择合适的强制程度。
常见问题
如何创建一个 Claude Code 自定义技能？
创建技能分为五个步骤：
- 在
.claude/skills/{skill-name}/目录下创建 SKILL.md 文件，包含 YAML frontmatter（name 和 description）和技能内容 - 在
.claude/skills/skill-rules.json中添加技能配置，定义类型、执行级别和触发条件 - 使用命令行测试触发器是否正常工作
- 根据测试结果优化关键词和模式匹配
- 确保 SKILL.md 不超过 500 行，超过部分放入参考文件
为什么我的技能没有被激活？
技能不激活通常有以下原因：
- 关键词不匹配：检查 description 和 promptTriggers.keywords 是否包含用户可能输入的词汇
- 意图模式过于严格：复杂的正则表达式可能无法匹配用户的实际表达
- 文件路径错误：filePatterns 的 Glob 路径与实际文件位置不符
- Hook 未注册：确认
.claude/settings.json中正确注册了 Hook 文件 - 会话跳过：同一会话中已经触发过的技能不会重复提醒（这是正常行为）
建议使用 npx tsx .claude/hooks/skill-activation-prompt.ts 进行手动测试。
Guardrail 技能和 Domain 技能有什么区别？
两者主要区别在于用途和强制程度：
| 特性 | Guardrail 技能 | Domain 技能 |
|---|---|---|
| 类型 | guardrail | domain |
| 执行级别 | block | suggest |
| 优先级 | critical/high | high/medium |
| 用途 | 防止关键错误（如数据库列名错误） | 提供领域指导和最佳实践 |
| 行为 | 物理阻止编辑直到使用技能 | 在适当时机建议使用相关技能 |
| 典型场景 | database-verification | backend-dev-guidelines |
如果你的技能是为了防止运行时错误或数据安全问题，使用 Guardrail；如果是提供开发指导，使用 Domain。