技能介绍

你在解决什么问题

在 Claude Code 里做「技能」时，常见问题不是写不出 SKILL.md，而是触发时机不对、规则配错、或 BLOCK/SUGGEST 混用导致要么拦不住关键错误，要么误报打断流程。本技能面向「创建/改技能、调 skill-rules.json、理解激活与钩子」这类场景，按 Anthropic 的 500 行规则与渐进式披露组织内容。

技能如何工作

系统采用双钩子思路（资料中的 2025-10-27 理念变更需留意）：

UserPromptSubmit（skill-activation-prompt.ts）：在用户提示进入模型前，用关键词 + 意图模式建议相关技能（suggest 为主）。
Stop（error-handling-reminder.ts）：响应结束后对编辑过的文件做风险模式扫描，温和提醒错误处理，不再用阻塞性 PreToolUse 卡 Sentry/错误处理流程。

配置中枢是 .claude/skills/skill-rules.json：定义技能条目、强制级别（block / suggest / warn）、文件 glob、内容正则、以及跳过条件（会话跟踪、文件标记、环境变量）。

技能类型上分为两类：

护栏（guardrail）：block + 高优先级，典型用于列名/数据完整性等「不修会炸」的场景；PreToolUse 返回退出码 2 时物理阻止 Edit/Write。
领域（domain）：suggest，提供后端/前端/可观测性等长文档式指导，不强制阻断。

创建新技能的标准路径：在 .claude/skills/{名称}/SKILL.md 写前置元数据与正文（保持 <500 行）→ 在 skill-rules.json 登记 → 用真实提示与文件路径/内容模式做触发测试 → 再迭代关键词与意图模式。详细模式见资料中的 TRIGGER_TYPES.md、SKILL_RULES_REFERENCE.md、TROUBLESHOOTING.md 等参考文件。

适用边界与注意点

BLOCK 只留给关键护栏；大多数日常指导用 SUGGEST，WARN 很少用。
会话跟踪会避免同一会话重复拦同一件事；// @skip-validation 与 SKIP_SKILL_GUARDRAILS 等跳过手段要克制，否则护栏形同虚设。
文档化前先跑够真实场景（资料建议 3 个以上），并关注钩子性能（资料提到 <100ms 或 <200ms 量级）。
本技能描述的是 Claude Code 侧 .claude/ 目录下的钩子与规则体系，与 SkillHub 站点上的「安装/分发」流程是不同层面的事。

截图预览

使用场景

团队要在 Prisma 改查询前自动校验表名列名，需要新建 `block` 护栏并写入 `skill-rules.json`
用户说「加个技能」但 UserPromptSubmit 从不推荐，需要对照关键词与意图模式做触发测试
同一会话里护栏反复拦截，想确认会话状态文件与跳过条件是否配置正确
`SKILL.md` 已超过 500 行，需要按渐进式披露拆主文档并补参考文件与目录

适合人员

维护 monorepo 内 `.claude/skills/` 目录、要统一团队技能命名与触发规则的平台工程师
刚接手项目、Edit/Write 被退出码 2 阻断，需要查清对应护栏技能与 BLOCK 消息的后端开发者
正在编写 React/TypeScript 领域技能、要在 `src/**/*.tsx` 上配 glob 与 `suggest` 级别的内容模式的前端负责人
负责在 `settings.json` 注册钩子并排查 `skill-activation-prompt.ts` 未执行问题的 Claude Code 集成维护者