skill-developer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Developer Guide

Claude Code技能开发者指南

Purpose

目的

Comprehensive guide for creating and managing skills in Claude Code with auto-activation system, following Anthropic's official best practices including the 500-line rule and progressive disclosure pattern.

本指南是遵循Anthropic官方最佳实践（包括500行规则和渐进式披露模式），在Claude Code中创建和管理具备自动激活系统的技能的综合指南。

When to Use This Skill

何时使用此技能

Automatically activates when you mention:

Creating or adding skills
Modifying skill triggers or rules
Understanding how skill activation works
Debugging skill activation issues
Working with skill-rules.json
Hook system mechanics
Claude Code best practices
Progressive disclosure
YAML frontmatter
500-line rule

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

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

System Overview

系统概述

Two-Hook Architecture

双钩子架构

1. UserPromptSubmit Hook (Proactive Suggestions)

File:

.claude/hooks/skill-activation-prompt.ts

Trigger: BEFORE Claude sees user's prompt
Purpose: Suggest relevant skills based on keywords + intent patterns
Method: Injects formatted reminder as context (stdout → Claude's input)
Use Cases: Topic-based skills, implicit work detection

2. Stop Hook - Error Handling Reminder (Gentle Reminders)

File:

.claude/hooks/error-handling-reminder.ts

Trigger: AFTER Claude finishes responding
Purpose: Gentle reminder to self-assess error handling in code written
Method: Analyzes edited files for risky patterns, displays reminder if needed
Use Cases: Error handling awareness without blocking friction

Philosophy Change (2025-10-27): We moved away from blocking PreToolUse for Sentry/error handling. Instead, use gentle post-response reminders that don't block workflow but maintain code quality awareness.

1. UserPromptSubmit Hook（主动建议）

文件路径：

.claude/hooks/skill-activation-prompt.ts

触发时机：Claude接收用户提示之前
用途：基于关键词+意图模式推荐相关技能
实现方式：将格式化的提醒作为上下文注入（标准输出 → Claude的输入）
适用场景：基于主题的技能、隐性工作场景检测

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

文件路径：

.claude/hooks/error-handling-reminder.ts

触发时机：Claude完成响应之后
用途：温和提醒用户自查编写代码中的错误处理情况
实现方式：分析已编辑文件中的风险模式，必要时显示提醒
适用场景：在不阻碍工作流的前提下提升代码质量意识

理念更新（2025-10-27）：我们不再使用PreToolUse钩子来拦截Sentry/错误处理相关操作，转而使用响应后的温和提示，既不阻碍工作流，又能维持代码质量意识。

Configuration File

配置文件

Location:

.claude/skills/skill-rules.json

Defines:

All skills and their trigger conditions
Enforcement levels (block, suggest, warn)
File path patterns (glob)
Content detection patterns (regex)
Skip conditions (session tracking, file markers, env vars)

位置：

.claude/skills/skill-rules.json

定义内容包括：

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

Skill Types

技能类型

1. Guardrail Skills

1. 防护型技能

Purpose: Enforce critical best practices that prevent errors

Characteristics:

Type:
```
"guardrail"
```
Enforcement:
```
"block"
```
Priority:
```
"critical"
```
or
```
"high"
```
Block file edits until skill used
Prevent common mistakes (column names, critical errors)
Session-aware (don't repeat nag in same session)

Examples:

```
database-verification
```
- Verify table/column names before Prisma queries
```
frontend-dev-guidelines
```
- Enforce React/TypeScript patterns

When to Use:

Mistakes that cause runtime errors
Data integrity concerns
Critical compatibility issues

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

特征：

类型：
```
"guardrail"
```
执行级别：
```
"block"
```
优先级：
```
"critical"
```
或
```
"high"
```
阻止文件编辑，直到使用对应技能
预防常见错误（如列名错误、严重逻辑错误）
支持会话跟踪（同一会话中不会重复提示）

示例：

```
database-verification
```
- 在执行Prisma查询前验证表/列名称
```
frontend-dev-guidelines
```
- 强制执行React/TypeScript编码模式

适用场景：

会导致运行时错误的常见失误
数据完整性相关场景
关键兼容性问题

2. Domain Skills

2. 领域型技能

Purpose: Provide comprehensive guidance for specific areas

Characteristics:

Type:
```
"domain"
```
Enforcement:
```
"suggest"
```
Priority:
```
"high"
```
or
```
"medium"
```
Advisory, not mandatory
Topic or domain-specific
Comprehensive documentation

Examples:

```
backend-dev-guidelines
```
- Node.js/Express/TypeScript patterns
```
frontend-dev-guidelines
```
- React/TypeScript best practices
```
error-tracking
```
- Sentry integration guidance

When to Use:

Complex systems requiring deep knowledge
Best practices documentation
Architectural patterns
How-to guides

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

特征：

类型：
```
"domain"
```
执行级别：
```
"suggest"
```
优先级：
```
"high"
```
或
```
"medium"
```
仅提供建议，不强制要求
针对特定主题或领域
包含全面的文档说明

示例：

```
backend-dev-guidelines
```
- Node.js/Express/TypeScript编码模式
```
frontend-dev-guidelines
```
- React/TypeScript最佳实践
```
error-tracking
```
- Sentry集成指导

适用场景：

需要深度知识的复杂系统
最佳实践文档
架构模式
操作指南

Quick Start: Creating a New Skill

快速入门：创建新技能

Step 1: Create Skill File

步骤1：创建技能文件

Location:

.claude/skills/{skill-name}/SKILL.md

Template:

markdown

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

位置：

.claude/skills/{skill-name}/SKILL.md

模板：

markdown

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


**Best Practices:**
- ✅ **Name**: Lowercase, hyphens, gerund form (verb + -ing) preferred
- ✅ **Description**: Include ALL trigger keywords/phrases (max 1024 chars)
- ✅ **Content**: Under 500 lines - use reference files for details
- ✅ **Examples**: Real code examples
- ✅ **Structure**: Clear headings, lists, code blocks

The actual guidance, documentation, patterns, examples


**最佳实践**：
- ✅ **命名**：小写、连字符连接，首选动名词形式（动词+ing）
- ✅ **描述**：包含所有触发关键词/短语（最多1024字符）
- ✅ **内容**：不超过500行 - 详情使用参考文件
- ✅ **示例**：真实代码示例
- ✅ **结构**：清晰的标题、列表、代码块

Step 2: Add to skill-rules.json

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

See SKILL_RULES_REFERENCE.md for complete schema.

Basic Template:

json

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

完整架构请参考SKILL_RULES_REFERENCE.md。

基础模板：

json

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

Step 3: Test Triggers

步骤3：测试触发器

Test UserPromptSubmit:

bash

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

Test PreToolUse:

bash

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

测试UserPromptSubmit：

bash

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

测试PreToolUse：

bash

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

Step 4: Refine Patterns

步骤4：优化模式

Based on testing:

Add missing keywords
Refine intent patterns to reduce false positives
Adjust file path patterns
Test content patterns against actual files

根据测试结果：

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

Step 5: Follow Anthropic Best Practices

步骤5：遵循Anthropic最佳实践

✅ Keep SKILL.md under 500 lines ✅ Use progressive disclosure with reference files ✅ Add table of contents to reference files > 100 lines ✅ Write detailed description with trigger keywords ✅ Test with 3+ real scenarios before documenting ✅ Iterate based on actual usage

✅ 保持SKILL.md不超过500行 ✅ 使用渐进式披露，通过参考文件提供详情 ✅ 为超过100行的参考文件添加目录 ✅ 编写包含触发关键词的详细描述 ✅ 正式文档前用3+真实场景测试 ✅ 根据实际使用情况迭代优化

Enforcement Levels

执行级别

BLOCK (Critical Guardrails)

BLOCK（关键防护）

Physically prevents Edit/Write tool execution
Exit code 2 from hook, stderr → Claude
Claude sees message and must use skill to proceed
Use For: Critical mistakes, data integrity, security issues

Example: Database column name verification

直接阻止Edit/Write工具执行
钩子返回退出码2，错误信息输出至stderr → Claude
Claude会收到提示，必须使用对应技能才能继续
适用场景：严重错误、数据完整性问题、安全相关问题

示例：数据库列名验证

SUGGEST (Recommended)

SUGGEST（推荐）

Reminder injected before Claude sees prompt
Claude is aware of relevant skills
Not enforced, just advisory
Use For: Domain guidance, best practices, how-to guides

Example: Frontend development guidelines

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

示例：前端开发指南

WARN (Optional)

WARN（可选）

Low priority suggestions
Advisory only, minimal enforcement
Use For: Nice-to-have suggestions, informational reminders

Rarely used - most skills are either BLOCK or SUGGEST.

低优先级建议
仅提供参考，几乎无强制约束
适用场景：锦上添花的建议、信息性提醒

极少使用 - 大多数技能要么是BLOCK要么是SUGGEST级别

Skip Conditions & User Control

跳过条件与用户控制

1. Session Tracking

1. 会话跟踪

Purpose: Don't nag repeatedly in same session

How it works:

First edit → Hook blocks, updates session state
Second edit (same session) → Hook allows
Different session → Blocks again

State File:

.claude/hooks/state/skills-used-{session_id}.json

目的：避免在同一会话中重复提示

工作原理：

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

状态文件：

.claude/hooks/state/skills-used-{session_id}.json

2. File Markers

2. 文件标记

Purpose: Permanent skip for verified files

Marker:

// @skip-validation

Usage:

typescript

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

NOTE: Use sparingly - defeats the purpose if overused

目的：为已验证的文件设置永久跳过

标记：

// @skip-validation

使用方式：

typescript

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

注意：谨慎使用 - 过度使用会失去防护意义

3. Environment Variables

3. 环境变量

Purpose: Emergency disable, temporary override

Global disable:

bash

export SKIP_SKILL_GUARDRAILS=true  # Disables ALL PreToolUse blocks

Skill-specific:

bash

export SKIP_DB_VERIFICATION=true
export SKIP_ERROR_REMINDER=true

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

全局禁用：

bash

export SKIP_SKILL_GUARDRAILS=true  # 禁用所有PreToolUse拦截

针对特定技能：

bash

export SKIP_DB_VERIFICATION=true
export SKIP_ERROR_REMINDER=true

Testing Checklist

测试清单

When creating a new skill, verify:

Skill file created in
```
.claude/skills/{name}/SKILL.md
```
Proper frontmatter with name and description
Entry added to
```
skill-rules.json
```
Keywords tested with real prompts
Intent patterns tested with variations
File path patterns tested with actual files
Content patterns tested against file contents
Block message is clear and actionable (if guardrail)
Skip conditions configured appropriately
Priority level matches importance
No false positives in testing
No false negatives in testing
Performance is acceptable (<100ms or <200ms)
JSON syntax validated:
```
jq . skill-rules.json
```
SKILL.md under 500 lines ⭐
Reference files created if needed
Table of contents added to files > 100 lines

创建新技能时，请验证以下内容：

技能文件已创建于
```
.claude/skills/{name}/SKILL.md
```
包含正确的前置内容（name和description）
已在
```
skill-rules.json
```
中添加条目
关键词已通过真实提示测试
意图模式已通过多种变体测试
文件路径模式已通过实际文件测试
内容模式已针对文件内容测试
阻止消息清晰且可操作（如果是防护型技能）
已正确配置跳过条件
优先级与重要性匹配
测试中无假阳性
测试中无假阴性
性能可接受（<100ms或<200ms）
JSON语法已验证：
```
jq . skill-rules.json
```
SKILL.md不超过500行 ⭐
已创建必要的参考文件
为超过100行的文件添加了目录

Reference Files

参考文件

For detailed information on specific topics, see:

如需特定主题的详细信息，请查看：

TRIGGER_TYPES.md

Complete guide to all trigger types:

Keyword triggers (explicit topic matching)
Intent patterns (implicit action detection)
File path triggers (glob patterns)
Content patterns (regex in files)
Best practices and examples for each
Common pitfalls and testing strategies

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

关键词触发（明确主题匹配）
意图模式（隐性动作检测）
文件路径触发（基于位置的激活）
内容模式（文件中的正则匹配）
每种类型的最佳实践和示例
常见陷阱和测试策略

SKILL_RULES_REFERENCE.md

Complete skill-rules.json schema:

Full TypeScript interface definitions
Field-by-field explanations
Complete guardrail skill example
Complete domain skill example
Validation guide and common errors

完整的skill-rules.json架构：

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

HOOK_MECHANISMS.md

Deep dive into hook internals:

UserPromptSubmit flow (detailed)
PreToolUse flow (detailed)
Exit code behavior table (CRITICAL)
Session state management
Performance considerations

钩子内部机制深度解析：

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

TROUBLESHOOTING.md

Comprehensive debugging guide:

Skill not triggering (UserPromptSubmit)
PreToolUse not blocking
False positives (too many triggers)
Hook not executing at all
Performance issues

综合调试指南：

技能未触发（UserPromptSubmit）
PreToolUse未拦截
误触发（触发过于频繁）
钩子完全未执行
性能问题

PATTERNS_LIBRARY.md

Ready-to-use pattern collection:

Intent pattern library (regex)
File path pattern library (glob)
Content pattern library (regex)
Organized by use case
Copy-paste ready

可直接使用的模式集合：

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

ADVANCED.md

Future enhancements and ideas:

Dynamic rule updates
Skill dependencies
Conditional enforcement
Skill analytics
Skill versioning

未来增强功能和思路：

动态规则更新
技能依赖
条件执行
技能分析
技能版本控制

Quick Reference Summary

快速参考摘要

Create New Skill (5 Steps)

创建新技能（5步骤）

Create
```
.claude/skills/{name}/SKILL.md
```
with frontmatter
Add entry to
```
.claude/skills/skill-rules.json
```
Test with
```
npx tsx
```
commands
Refine patterns based on testing
Keep SKILL.md under 500 lines

在
```
.claude/skills/{name}/SKILL.md
```
创建技能文件
在
```
.claude/skills/skill-rules.json
```
中添加条目
使用
```
npx tsx
```
命令测试
根据测试结果优化模式
保持SKILL.md不超过500行

Trigger Types

触发类型

Keywords: Explicit topic mentions
Intent: Implicit action detection
File Paths: Location-based activation
Content: Technology-specific detection

See TRIGGER_TYPES.md for complete details.

关键词：明确的主题提及
意图：隐性动作检测
文件路径：基于位置的激活
内容：基于技术的检测

详情请见TRIGGER_TYPES.md。

Enforcement

执行级别

BLOCK: Exit code 2, critical only
SUGGEST: Inject context, most common
WARN: Advisory, rarely used

BLOCK：退出码2，仅用于关键场景
SUGGEST：注入上下文，最常用
WARN：仅作参考，极少使用

Skip Conditions

跳过条件

Session tracking: Automatic (prevents repeated nags)
File markers:
```
// @skip-validation
```
(permanent skip)
Env vars:
```
SKIP_SKILL_GUARDRAILS
```
(emergency disable)

会话跟踪：自动（避免重复提示）
文件标记：
```
// @skip-validation
```
（永久跳过）
环境变量：
```
SKIP_SKILL_GUARDRAILS
```
（紧急禁用）

Anthropic Best Practices

Anthropic最佳实践

✅ 500-line rule: Keep SKILL.md under 500 lines ✅ Progressive disclosure: Use reference files for details ✅ Table of contents: Add to reference files > 100 lines ✅ One level deep: Don't nest references deeply ✅ Rich descriptions: Include all trigger keywords (max 1024 chars) ✅ Test first: Build 3+ evaluations before extensive documentation ✅ Gerund naming: Prefer verb + -ing (e.g., "processing-pdfs")

✅ 500行规则：SKILL.md不超过500行 ✅ 渐进式披露：使用参考文件提供详情 ✅ 目录：为超过100行的参考文件添加目录 ✅ 单层引用：不要深度嵌套参考文件 ✅ 详细描述：包含所有触发关键词（最多1024字符） ✅ 先测试后文档：在编写详细文档前完成3+场景测试 ✅ 动名词命名：首选动词+ing形式（如"processing-pdfs"）

Troubleshoot

故障排查

Test hooks manually:

bash

undefined

手动测试钩子：

bash

undefined

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


See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for complete debugging guide.

---

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


完整调试指南请见[TROUBLESHOOTING.md](TROUBLESHOOTING.md)。

---