---

name: skill-developer description: "在 Claude Code 中创建和管理技能的综合指南，包含自动激活系统，遵循 Anthropic 官方最佳实践，包括 500 行规则和渐进式披露模式。" risk: unknown source: community date_added: "2026-02-27"

技能开发者指南

目的

在 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)： 我们不再使用阻塞式 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

完整 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