skill-developer

Name: skill-developer
Author: diet103

github.com/diet103Agent 工作流10.0k51 次安装16 周前更新

代码仓库

关于 skill-developer

面向 Claude Code 开发者的技能指南，涵盖技能创建、配置与故障排查，并说明自动激活、钩子约束及渐进式披露和 500 行规则等实践。

主要功能

01按关键词和意图激活
02基于钩子的技能约束
03技能规则与触发器配置
04基于会话的跳过条件
05测试与故障排查指南

适用场景

01创建 Claude Code 技能
02调整技能触发器和规则
03诊断激活或钩子问题

安装

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

$npx skills add https://github.com/diet103/claude-code-infrastructure-showcase --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 前置元数据
500 行规则

系统概览

Hook 架构（五个已接入的 Hook）

1. UserPromptSubmit Hook（主动建议）

文件：.claude/hooks/skill-activation-prompt.ts
触发时机：Claude 查看用户提示词之前
目的：根据关键词和意图模式（正则表达式或可选的 AI 分类）推荐相关技能
方式：将格式化的提醒作为上下文注入（stdout → Claude 的输入）
强制机制：只有 enforcement: "block" 的技能会被标记为强制要求；suggest/warn 技能始终作为建议显示

2. PreToolUse Hook - 技能验证守卫（强制执行）

文件：.claude/hooks/skill-verification-guard.ts
触发时机：Edit/MultiEdit/Write 执行之前
目的：强制激活必需技能（两次尝试模式），并防护文件/内容模式；可选进行 AI 编辑分析
方式：退出代码 2 + stderr 会阻止工具执行；只有 enforcement: "block" 的技能可以阻止执行

3. PostToolUse Hook - 编辑跟踪器

文件：.claude/hooks/post-tool-use-tracker.sh
触发时机：Edit/MultiEdit/Write 完成之后
目的：跟踪已编辑的文件和仓库（为构建检查和错误处理提醒提供数据）

4. PostToolUse Hook - 技能激活跟踪器

文件：.claude/hooks/skill-activation-tracker.ts
触发时机：Skill 工具运行之后
目的：从待处理列表中清除已激活的技能，使守卫停止阻止操作

5. Stop Hook - 会话文档更新器

文件：.claude/hooks/session-doc-updater.ts
触发时机：Claude 完成响应之后
目的：为向量搜索索引开发文档（会话智能）；清理过期的会话状态

可选（已提供但未接入）： error-handling-reminder.ts（Stop）——在响应后进行温和的自检，分析已编辑文件中的风险模式，而不是阻止编辑。

**理念变更（2025-10-27）：**我们不再使用 PreToolUse 来阻止 Sentry/错误处理操作。取而代之的是，在响应后进行温和提醒，不阻断工作流，同时保持对代码质量的关注。

配置文件

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

定义：

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

技能类型

1. 防护技能

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

特征：

类型："guardrail"
强制级别："block"
优先级："critical" 或 "high"
在使用技能前阻止文件编辑
防止常见错误（列名、关键错误）
感知会话状态（同一会话中不重复提醒）

示例：

frontend-dev-guidelines——强制执行 React/TypeScript 模式（随附的 block 防护技能）
一个用于在 Prisma 查询前验证表名/列名的 database-verification 技能（假设示例）

适用场景：

会导致运行时错误的问题
数据完整性问题
关键兼容性问题

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

完整的架构请参阅 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 个以上真实场景进行测试 ✅ 根据实际使用情况迭代优化

强制级别

阻止（关键防护栏）

从物理层面阻止 Edit/Write 工具执行
Hook 返回退出代码 2，stderr → Claude
Claude 会看到消息，并且必须使用技能才能继续
适用于：关键错误、数据完整性和安全问题
只有 enforcement: "block" 技能可以强制阻止——这同时适用于 UserPromptSubmit 强制列表和 PreToolUse 防护栏检查。suggest/warn 匹配始终仅提供建议。

示例： 验证数据库列名称

建议（推荐）

在 Claude 查看提示词前注入提醒
Claude 会知晓相关技能
不强制执行，仅提供建议
适用于：领域指导、最佳实践和操作指南

示例： 前端开发指南

警告（可选）

低优先级建议
仅提供建议，强制程度最低
适用于：锦上添花的建议、信息提示

很少使用——大多数技能要么是阻止级别，要么是建议级别。

跳过条件与用户控制

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_MANDATORY_SKILLS=true   # Disables mandatory-skill blocking
export SKIP_PRETOOLUSE_AI=true      # Disables AI edit analysis in the guard

针对特定技能（通过 skill-rules.json 中的 skipConditions.envOverride）：

export SKIP_FRONTEND_GUIDELINES=true
export SKIP_ERROR_REMINDER=true     # Optional Stop-hook reminder

测试清单

创建新技能时，请确认：

参考文件

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

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

可直接使用的模式集合：

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

快速参考摘要

创建新技能（5 步）

创建带有 frontmatter 的 .claude/skills/{name}/SKILL.md
在 .claude/skills/skill-rules.json 中添加条目
使用 npx tsx 命令进行测试
根据测试结果优化模式
确保 SKILL.md 不超过 500 行

触发类型

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

完整详情请参阅 TRIGGER_TYPES.md。

强制方式

阻止：退出代码 2，仅用于关键情况
建议：注入上下文，最常用
警告：提示性质，很少使用

跳过条件

会话跟踪：自动进行（防止反复提醒）
文件标记：// @skip-validation（永久跳过）
环境变量：SKIP_MANDATORY_SKILLS，以及每个技能的 envOverride（紧急禁用）

Anthropic 最佳实践

✅ 500 行规则：确保 SKILL.md 不超过 500 行 ✅ 渐进式披露：使用参考文件提供详细信息 ✅ 目录：为超过 100 行的参考文件添加目录 ✅ 仅嵌套一层：避免深层嵌套参考 ✅ 丰富的描述：包含所有触发关键词（最多 1024 个字符） ✅ 先测试：在编写大量文档前，先构建 3 个以上评估 ✅ 动名词命名：优先使用动词 + -ing（例如，“processing-pdfs”）

故障排查

手动测试 Hook：

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

基本信息

作者: diet103
仓库: diet103/claude-code-infrastructure-showcase
分类: Agent 工作流
安装次数: 51
GitHub Stars: 10,046

报告问题