Claude Code 的 Skills 是从 1.x 之后逐渐成型的能力扩展机制，本质是"把一段 markdown 提示词 + 一组 tool 调用约定打包，按需触发"。本文按我自己用了几个月的体感，讲透它的工作原理和写法。

Skill 是什么

最简形态就是一个 SKILL.md：

~/.claude/skills/my-skill/SKILL.md

文件头是 YAML frontmatter，正文是给 Claude 看的指令：

---
name: my-skill
description: 触发条件描述，Claude 看这段决定要不要用
allowed-tools: [Bash, Read, Edit]
---

当用户说 X 的时候，你应该 ...

触发方式有两种：

  1. 用户主动：/my-skill 显式调用
  2. 自动触发：Claude 看到对话内容匹配 description 就自动加载

一个真实例子：K8s 运维 skill

我团队有个内部 skill kubernetes-ops，触发条件写：

description: Kubernetes 集群智能运维 skill。用户描述目标、现象、资源名或业务问题时，
  Agent 自主完成资源识别、命名空间定位、健康排查、发布核查、故障诊断。

我说"看下 prod 集群里那个 cms 服务为啥 503"，Claude 自动加载这个 skill，里面有：

  • 集群连接信息（kubeconfig 路径）
  • 命名空间映射表（cms → prod-cms）
  • 排查 SOP（先看 endpoints → 再看 pod → 再看 ingress）
  • 变更前确认模板

不用我每次都给上下文。

写 skill 的几个原则

1. description 是命脉

Claude 不读 skill 正文，只读 description。description 写不清楚，再好的 skill 也不会被自动调用。

好的 description 包含：

  • 场景关键词（"K8s 集群"、"OpenStack 实例"）
  • 输入形式（"用户描述目标 / 资源名 / 现象"）
  • 不该触发的反例（"非运维场景不要触发"）

2. 正文按"决策树 + 模板"组织

别写成长篇大论。Claude 是按需读的，结构化更好命中：

## 触发后的第一步
立刻读 `cluster.yaml` 拿到 kubeconfig。

## 排查 SOP
1. ...
2. ...

## 变更前 checklist
- 是否生产环境？
- 是否有备份？

3. 用 allowed-tools 约束工具

不写 allowed-tools 时 skill 能用全部工具。生产 skill 一定要列白名单，避免误删：

allowed-tools: [Read, Bash(kubectl get *)]

Bash(kubectl get *) 是命令级 sandbox，只允许 kubectl get 开头的命令。

4. 引用外部文件用相对路径

具体集群信息见 `./clusters.json`。

skill 加载时 Claude 会读这个文件，相对路径基于 skill 目录。

init skill：怎么给一个新项目做上下文

内置的 /init 会扫描项目，生成 CLAUDE.md。我个人的最佳实践：

  1. /init 跑一遍生成草稿
  2. 手动补充：分支策略、测试命令、特殊约定
  3. 删掉所有"显而易见"的内容（"用 git 管理版本"这种没用）

CLAUDE.md 越短越好，每行都得是"不读会出问题"的信息。

全局 skill vs 项目 skill

  • ~/.claude/skills/：全局，所有项目可用
  • <project>/.claude/skills/：项目级，只在该项目目录下生效

我的习惯：

  • 全局：通用工具（k8s-ops、openstack-ops、git-flow）
  • 项目级：业务 SOP（"如何发布"、"如何回滚"）

别滥用 skill

skill 的"自动触发"特性意味着每次对话开始 Claude 都会扫 description 列表。100 个 skill 你 context 就废了。我自己的上限是 15 个，按季度清理一次。

教训一句话：skill 是"压缩的提示词 + 工具白名单"，把 description 写清楚比把正文写漂亮重要 10 倍。

标签: none

添加新评论