Skills

Skills

2026年9月5日

把可复用的 Claude Code 工作流、命令、指令、脚本和参考资料打包成按需加载的能力。

Skills 是什么

Skills 是模块化能力包。一个 skill 可以包含指令、命令式 prompt、脚本、参考资料、模板和其他辅助文件。Claude Code 会先发现 skill metadata，只有当前任务匹配 description 时才加载完整 skill。

可以把 skills 理解成“按需上下文”。它让 CLAUDE.md 保持短小，同时仍能在重复工作中给 Claude 很丰富的流程。

什么适合放进 Skill

适合用 skill 的场景：

跨项目重复出现的工作流。
太长、不适合塞进 CLAUDE.md 的领域 playbook。
带辅助上下文的自定义 slash command。
Review checklist、migration process、release process 或 debugging flow。
需要随指令一起携带的 templates、scripts、references。

一次性的项目事实不要放 skill。放 CLAUDE.md 或 .claude/rules/ 更合适。

Skill 结构

每个 skill 是一个目录，根目录放 SKILL.md：

skill layout

.claude/skills/
└── database-migration/
  ├── SKILL.md
  ├── references/
  │   └── migration-checklist.md
  └── scripts/
      └── verify-migration.sh

Frontmatter 是发现层：

SKILL.md

---
name: database-migration
description: Use when creating, reviewing, or verifying database migrations.
---

# Database Migration

1. Inspect the current schema and existing migrations.
2. Create the smallest incremental migration.
3. Regenerate types if the project requires it.
4. Run the migration verifier script.
5. Summarize data-loss risk and rollback notes.

description 要写成触发条件。Claude 会先读它，再判断是否加载完整 skill。

渐进式加载

Skills 的价值在于不把所有内容都放进启动上下文：

层	何时加载	内容
Metadata	启动时	`name`、`description`，以及判断是否适用所需的信息
Instructions	Skill 被触发时	`SKILL.md` 的操作正文
Resources	指令需要时	References、scripts、templates、examples、assets

Metadata 要短，正文要可执行。长背景材料放 references/，需要时再让正文指向它。

自定义命令现在更适合用 Skills

旧版 Claude Code 经常用 .claude/commands/ 写自定义 slash commands。当前 Claude Code 中，skills 是更完整的打包模型。一个 skill 可以表达 command-like workflow，同时携带 references、scripts 和 assets。

新建可复用命令时优先用 skills。只有仓库已经依赖旧 commands 且迁移收益不高时，才继续保留。

内置、项目与用户 Skills

Claude Code 可以从多处加载 skills：

Claude Code 自带 built-in skills。
.claude/skills/ 下的项目 skills。
~/.claude/skills/ 下的用户 skills。
Plugin 提供的 skills。
来自 marketplace 或团队分发源的 skills。

编码团队流程的 project skills 应该提交进 git。个人偏好更适合 user skills。

写好 Skill Description

不好的 description：

yaml

description: Helps with databases.

好的 description：

yaml

description: Use when adding or changing database migrations, reviewing schema diffs, or investigating migration failures.

好的 description 描述触发时机，而不只是主题。

Skills 与其他扩展点

需求	使用
持久项目事实	CLAUDE.md 或 `.claude/rules/`
可复用流程和 command-like workflows	Skills
为高噪声任务隔离上下文	Subagents
确定性强制规则	Hooks
外部系统和工具	MCP
可分享扩展包	Plugins

Skills 通常是最先创建的扩展，因为风险低、容易 review。

实用示例

text

Use the database-migration skill to review the migration I just wrote.
Focus on data loss, RLS policy dependencies, and generated TypeScript types.

Claude 应该加载 skill，只在需要时读取 referenced checklist 或 script，然后把流程应用到当前仓库。