skill-developer

Name: skill-developer
Author: davila7

github.com/davila7Agent 工作流33.0k312 次安装今天更新

代码仓库

关于 skill-developer

面向 Claude Code 技能创建与维护的指南，涵盖自动激活、触发规则和钩子机制。适合构建、调试技能工作流的开发者。

主要功能

01技能文件结构与编写规范
02触发条件与规则配置
03钩子工作机制说明
04技能激活故障排查
05遵循 500 行与渐进披露

适用场景

01创建并注册新技能
02调整技能触发词与规则
03排查技能未激活问题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/davila7/claude-code-templates --skill skill-developer

安装后在 Claude Code 中输入/skill-developer确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

ADVANCED.md

HOOK_MECHANISMS.md

PATTERNS_LIBRARY.md

SKILL_RULES_REFERENCE.md

TRIGGER_TYPES.md

TROUBLESHOOTING.md

详细介绍

技能开发者指南

目的

在 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

测试清单

创建新技能时，验证：

引用文件

有关特定主题的详细信息，请参见：

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）
按使用场景组织
可复制粘贴直接使用

快速参考摘要

创建新技能（5 个步骤）

创建带 frontmatter 的 .claude/skills/{name}/SKILL.md
在 .claude/skills/skill-rules.json 中添加条目
使用 npx tsx 命令进行测试
根据测试结果优化模式
保持 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。

基本信息

作者: davila7
仓库: davila7/claude-code-templates
分类: Agent 工作流
安装次数: 312
GitHub Stars: 33,002

报告问题