Claude Code Skills: A Practical Guide for 2026

查看原文 / View Original

Claude Code Skills: A Practical Guide for 2026

Claude Code Skills：2026 年实用指南

If you have spent any real time with Claude Code, you have probably noticed the same problem I did. You write the same instructions in the prompt every other day. “Use four-space indentation here.” “Always run the linter after edits.” “Format commit messages this way.” After the third or fourth repeat, it stops feeling like a prompt and starts feeling like missing config. 如果你花过时间使用 Claude Code，你可能和我一样注意到了同一个问题：你每隔一天就要在提示词中重复相同的指令。“这里使用四空格缩进。”“编辑后务必运行 linter。”“按这种方式格式化提交信息。”在重复三四次之后，这就不再像是提示词，而更像是缺失的配置。

Skills are how Claude Code fixes that. A skill is a small folder, with one markdown file inside, that Claude pulls into the conversation only when your request actually needs it. No setup screen. No plugin manager. Just a file in a folder and a one-line description telling Claude what it is for. Skills（技能）正是 Claude Code 解决这一问题的方式。一个 Skill 是一个小文件夹，里面包含一个 Markdown 文件；只有当你的请求确实需要时，Claude 才会将其引入对话中。没有设置界面，没有插件管理器，只有一个文件夹里的文件，以及一行告诉 Claude 该文件用途的描述。

This post is a clean walkthrough for 2026. What a skill actually is, how to write your first one, where to put it, and how it compares to the two things people often confuse it with: slash commands and subagents. 本文是 2026 年的精简指南，将介绍 Skill 的本质、如何编写你的第一个 Skill、存放位置，以及它与人们常混淆的另外两个概念（斜杠命令和子代理）的区别。

What a Claude Code Skill actually is

什么是 Claude Code Skill

At the most basic level, a skill is a directory with a single file called SKILL.md inside it. The file has two parts. A short YAML frontmatter at the top, with a name and a description. A markdown body underneath, with the instructions Claude follows when the skill is triggered. That is the whole spec. Everything else, examples, supporting scripts, templates, helper files, is optional and lives in the same directory. 从最基础的层面来看，一个 Skill 就是一个包含名为 SKILL.md 文件的目录。该文件分为两部分：顶部是包含名称和描述的简短 YAML 元数据，下方是 Markdown 正文，包含触发 Skill 时 Claude 需要遵循的指令。这就是全部规范。其他所有内容（如示例、支持脚本、模板、辅助文件）都是可选的，且存放在同一目录下。

Here is the smallest valid skill you can write: 以下是你所能编写的最简有效 Skill：

.claude/skills/run-tests/
└── SKILL.md
---
name: run-tests
description: "Run the project's test suite using the Makefile target. Use this whenever the user asks to run tests, check tests, or verify the test suite is passing."
---
Run `make test` from the repo root. If the command fails, read the failing test output, point out the specific assertion that broke, and ask before changing anything in the source files.

That is a working skill. Drop it in .claude/skills/run-tests/, restart Claude Code, and the next time you say “run the tests” Claude will use this instead of guessing. 这就是一个可用的 Skill。将其放入 .claude/skills/run-tests/，重启 Claude Code，下次当你输入“run the tests”时，Claude 就会使用它，而不是盲目猜测。

How Claude actually picks up a skill

Claude 如何识别 Skill

This is the part that confuses people most. Skills are not always-on. They are auto-discovered. Here is what happens when you send a message: Claude reads the descriptions of every skill it can see. It compares your message to those descriptions. If one matches, it pulls that skill’s full content into the conversation. If nothing matches, no skill is loaded and you get the default behavior. 这是最让人困惑的部分。Skill 并非一直处于开启状态，而是自动发现的。当你发送消息时，过程如下：Claude 会读取它能看到的所有 Skill 的描述，并将你的消息与这些描述进行比对。如果匹配，它会将该 Skill 的全部内容引入对话；如果没有匹配，则不会加载任何 Skill，你将获得默认行为。

This is why the description does most of the heavy lifting in any skill. It is the only thing Claude has to decide whether the skill applies. A vague description (“Helps with tests”) will rarely fire. A specific one (“Runs the project’s pytest suite when the user asks to run, check, or verify tests”) will fire reliably. A simple test: read your description out loud. If it does not start with a clear verb and end with a clear trigger, rewrite it. 这就是为什么描述在 Skill 中起到了关键作用。它是 Claude 判断 Skill 是否适用的唯一依据。模糊的描述（如“Helps with tests”）很少会被触发，而具体的描述（如“Runs the project’s pytest suite when the user asks to run, check, or verify tests”）则能可靠触发。一个简单的测试方法：大声读出你的描述。如果它不是以清晰的动词开头，并以明确的触发条件结尾，那就重写它。

Where skills live

Skill 的存放位置

Skills sit in one of three places. The location decides who sees them. Skill 存放在以下三个位置之一，位置决定了谁能看到它们。

LocationScopeWhen to use
.claude/skills/<name>/ProjectWorkflows specific to one codebase
~/.claude/skills/<name>/PersonalWorkflows you want everywhere
Plugins or shared packagesTeamSkills you want to ship to others
位置范围使用场景
.claude/skills/<name>/项目针对特定代码库的工作流
~/.claude/skills/<name>/个人你希望在任何地方都能使用的通用工作流
插件或共享包团队你希望分发给其他人的 Skill

Project skills win when there is a conflict. So if your repo has a run-tests skill and your personal folder has one too, the project one is used while you are inside that repo. That is almost always what you want. 当发生冲突时，项目级 Skill 优先。因此，如果你的仓库有一个 run-tests 技能，而你的个人文件夹里也有一个，当你处于该仓库内时，会优先使用项目级的。这通常正是你所期望的。

A small but important detail: skills that live inside the repo are checked into git by default. That is fine. They are usually short, they help every collaborator, and they are easier to review than long CLAUDE.md files. 一个虽小但重要的细节：存放在仓库内的 Skill 默认会被提交到 Git 中。这没问题。它们通常很短，能帮助每一位协作者，而且比冗长的 CLAUDE.md 文件更容易审查。

A walkthrough: build a skill from scratch

实战演练：从零构建一个 Skill

Let us write something slightly more useful than run-tests. Say you have a personal habit of starting every commit message with a Conventional Commit type (feat:, fix:, chore:). You want Claude to do the same when it commits. 让我们写一个比 run-tests 更实用的 Skill。假设你有一个个人习惯：每个提交信息都以 Conventional Commit 类型（如 feat:, fix:, chore:）开头。你希望 Claude 在提交时也这样做。

Step 1: make the directory 第一步：创建目录 From the root of your project: 在项目根目录下执行： mkdir -p .claude/skills/conventional-commit

Step 2: write SKILL.md 第二步：编写 SKILL.md Open .claude/skills/conventional-commit/SKILL.md and put this inside: 打开 .claude/skills/conventional-commit/SKILL.md 并填入以下内容：

---
name: conventional-commit
description: Use this skill any time the user asks for a git commit, to commit changes, or to write a commit message. It writes the message in Conventional Commit format.
---
When you create a git commit, follow these rules.
1. Start the subject line with one of: feat, fix, chore, docs, refactor, test, perf.
2. Add a colon and a space, then a short imperative summary, no period.
3. Keep the subject under 70 characters.
4. If the change touches more than two files, add a one-line body that says why.
Example:
feat: add IndexNow ping to publish workflow
Auto-pings Bing on every push to main so new posts get indexed faster.

Step 3: try it 第三步：测试 Restart Claude Code (or just open a new conversation). Say “commit these changes”. Claude should pull in the skill, follow the format, and you should see a commit subject that matches the rules. If it does not fire, the description is the first thing to fix. Make the trigger words match what you actually say to Claude. 重启 Claude Code（或直接开启新对话）。输入“commit these changes”。Claude 应该会加载该 Skill，遵循格式，你应该能看到符合规则的提交主题。如果没触发，首先要修改的是描述。确保触发词与你实际对 Claude 说的话相匹配。

Skills vs slash commands vs subagents

Skill 与斜杠命令及子代理的区别

This is the question I get most often, and the line is genuinely fuzzy because the three features have grown closer over time. Here is how I think about them in practice. 这是我最常被问到的问题，由于这三个功能随着时间推移界限变得模糊，区分它们确实有些困难。以下是我在实践中的看法：

  • Skills: Auto-discovered. Claude decides when to use them based on your message. Live inside the main conversation, so the work stays visible and you can intervene. Best for: repeated workflows you do not want to type out, like commit formatting, test running, or PR conventions.
    • Skills：自动发现。Claude 根据你的消息决定何时使用。它们存在于主对话中，因此工作过程可见，你可以随时干预。最适合：你不想每次都手动输入的重复工作流，如提交格式化、运行测试或 PR 规范。
  • Slash commands: You invoke them by hand, with /command-name. Same file format as skills now, in fact a single skill file gives you both an auto-trigger and a /run-tests slash command for free. Best for: explicit triggers when you want full control over when something runs.
    • 斜杠命令：通过 /command-name 手动调用。现在与 Skill 使用相同的文件格式，事实上，一个 Skill 文件既能提供自动触发，也能免费提供一个 /run-tests 斜杠命令。最适合：当你想要完全控制某项任务何时运行时，使用显式触发。
  • Subagents: Spawned by Claude into a separate, fresh context with their own tools and memory. They do not see your conversation. They get a brief…
    • 子代理：由 Claude 生成，进入一个独立的、全新的上下文，拥有自己的工具和记忆。它们看不到你的对话。它们会收到一份简要的……
← 返回新闻列表 / Back to news list