《Claude Code 源码解析系列》第7章｜Skill

上一篇如果讲 MCP，我们会看到 Claude Code 怎么把外部工具、外部资源、外部服务接进自己的运行时。

但这时还有一个问题没解决：

比如使用者说的观点是，

帮我把这个 PR 做一次代码审查。按理说，

工具层能提供 ReadGrepBashGitHub MCP、浏览器、子 Agent。但“怎么审查一个 PR”本身不是一个工具调用。而是一套经验：

• 先看 diff 范围，不要被无关文件带偏。说起来，
• 再看行为变化。而不是只看代码风格，
• 优先找 bug、权限、数据一致性和测试缺口。
• 输出时先列问题，再给。
• 如果仓库有自己的 review 规范，要优先用本地规范。

使用者痛点：如果把这些经验全部写进程序提示，提示会膨胀； 每次都让使用者重复说明又体验差； 硬编码在源码里则无法灵活迭代。

Skill 正是为了解决这类痛点而生。

Skill 不是给 Claude Code 新增一个底层工具。而是把一类任务的做法、约束、示例、脚本和参考资料，封装成一个按需加载的能力包。

一、为什么不能只靠工具

在 Tools 那篇里我们说过工具程序解决的是“模型如何接触真实世界”。但工具只回答“能做什么”，不回答“应该怎么做”。其实，

• Read 能读文件。但不会告诉模型读哪些文件；说起来，
• Bash 能跑命令。但不会告诉模型先跑测试还是先看 diff；
• Grep 能搜索，但不会告诉模型审查 PR 时该搜权限判断还是数据写入。

If you compare tools to kitchen knives and pots。Skill is recipe.

使用者痛点：拥有大量工具后却不知道该怎样组合它们完成具体业务，导致模型经常走弯路或产生不一致的结果。

文件结构示例：

.claude/skills/
└── code-review/
├── SKILL.md
├── review-checklist.md
├── examples/
│ └── finding-format.md
└── scripts/
└── collect-diff.sh

SKILL.md 分为两部分：Frontmatter和正文。下面是一个最小示例：

---
name的观点是，code-review
description: Review code changes for bugs,regressions,security risks,and missing tests. Use when user asks to review a diff,PR,or current changes.
allowed-tools:
- Read
- Grep
- Bash
- Bash
---
# Code Review
## Instructions
- Review current change as a senior engineer.
- Inspect diff before reading unrelated files.
- Prioritize correctness。data integrity,security,and missing tests.
- Report findings first,ordered by severity.
- Keep summaries brief.
For detailed review criteria,read `review-checklist.md` only when needed.

User Pain Point: 很多团队把所有流程写进主提示，使得 prompt 超长且难以维护；而 Skill 的 Frontmatter 让程序只在必要时加载完整说明，从而保持上下文精简。

The most confusing part in many diagrams is last two branches.

• 普通 Skill: 渲染后的 S K I L L .md 直接作为一条消息注入当前会话。适合提供背景规则或参考信息。
• Fork Skill: 当 Frontmatter 中声明  时会创建子 Agent 来独立执行任务，再把结果返回主会话。适合耗时长或产生大量中间细节的任务，如深度代码研究。说起来，

User Pain Point: 没有区分 inline 与 fork 的概念。会导致大块文本污染主上下文或子 Agent 创建过度，影响性能与可读性。

来源	典型方法	适合放什么
E公司 / Managed 管理员下发目录	/etc/claude/managed/skills/…	公司统一规范、安全流程、合规检查
P个人	`~/.claude/skills//SKILL.md`	个人常用写作、调试、提交、流程
P项目	.claude/skills//SKILL.md	当前仓库特有规范、脚手架、架构约定
P插件	`/skills//SKILL.md` 插件随包分发的能力
N嵌套项目	`packages/foo/.claude/skills/…` Monorepo 中子项目专属能力

The function  collects all se sources in parallel,de‑duplicates by realpath and respects priority order .

If you run Claude Code with 。only explicitly added directories are considered – this is useful for debugging skill discovery problems.

If two skills share same name across layers,higher‑priority source wins;话说回来，plugin skills use a namespaced key .

The legacy .claude/commands/*.md files are now treated as Skills with lower priority.

User Pain Point:

• You often wonder *** a newly added skill isn’t recognized – it’s usually because it lives in a lower‑priority layer or was ignored due to

Description>

A common mistake is writing a long body but leaving a vague description such as “Helps with code.” This makes model routing fail.

description: Review code changes for correctness,regressions,security risks,and missing tests.
Use when user asks to review a diff,PR,branch,or current uncommitted changes.

The index built from all loaded skills looks like:

Available skills:
- code-review: Review code changes for bugs...
- write-blog: Write problem-driven technical concept blogs...
- debug: Systematically investigate and fix bugs...
...

The description acts as a routing hint under token budget constraints.

User Pain Point:

• If description is too short or generic。models rarely match skill even though it exists.
• If description is too long it gets truncated – important trigger words disappear.

参数替换 

You can call a skill via slash command with arguments:

/fix-issue #123  Add missing validation
... // arguments will replace $ARGUMENTS inside SKILL.md

Inside SKILL.md:

Fix GitHub issue $ARGUMENTS..
Read issue description..
Find affected code..
Implement fix..
Add tests.

Positional arguments syntax example:

Migrate $ARGUMENTS from $ARGUMENTS to $ARGUMENTS.

You can also declare named arguments in frontmatter:

arguments:
component
from
to

And n use m inside body:

Migrate $component from $from to $to.

环境变量替换 

Run helper script:
bash
python3 ${CLAUDE_SKILL_DIR}/scripts/collect_diff.py .

During rendering this becomes an absolute path pointing at skill’s folder.

动态上下文注入 

---name:summarize-changes
description: Summarize uncommitted git changes and flag risks.
allowed-tools:
Bash 

Bash

Current status

git status --short

Current diff

git diff HEAD

Instructions

Summarize change and list risks.

When Claude Code processes this skill it first runs both git commands,injects ir output into markdown,and n feeds that expanded text to LLM.

User Pain Point: Without this feature you’d have to ask model “should I run git status?” each time – adding latency and uncertainty.

• inline : background guidelines  – y enrich current context without spawning new agents.
• fork : heavy‑weight tasks  – y keep main conversation clean.

User Pain Point :Mis‑configuring context leads eir to noisy main sessions or useless forks .

---name : commit
description : Stage and commit current changes.
disable-model-invocation : true
allowed-tools :
- Bash 

- Bash

Now calling /commit will run those git commands without additional confirmations.

User Pain Point :Assuming allowed-tools alone protects from dangerous operations leads to accidental privilege escalation when or policies are permissive.

• MCP : How external capabilities are exposed as tools/resources/prompt fragments.
• Skill : How those exposed capabilities should be orchestrated into coherent task flows.

User Pain Point :Newcomers often try to encode entire workflows directly into MCP definitions – resulting in duplicated logic across projects. Skills provide reusable “orchestration bundles” that sit on top of MCP.

import fs from 'node:fs/promises';import path from 'node:path';import matter from 'gray-matter';

type Skill = { name这方面，string;description:string;dir:string，body:string;}，

export async function loadProjectSkills:Promise{ body:parsed.content.trim="" const="" description:.trim,="" dir="path.join;" dir,="" entries="await" file="path.join;" for{="" fs.readdir.catch=">);" fs.readfile.catch=">null);" if)continue;="" ifcontinue;="" name:parsed.data.name?，e.name,="" p="" parsed="matter;" raw="await" return="" root="path.join;" skills.push({="" skills:skill=";" skills，="" }="" });="" }<="">

export function buildAvailableSkillsPrompt:string{ return .join;}

export function renderSkill:string{ return skill.body .replaceAll .replaceAll .replaceAll;}

User Pain Point :Seeing only pseudo‑codes makes it hard to grasp where real Claude Code adds complexity – e.g.,live file watching,policy enforcement。nested discovery – which are all extensions of this skeleton.

1. Discovery ：scan all configured roots…<\/li>
2. Indexing ：extract frontmatter & lightweight description for routing<\/li>
3. Matching ：model decides wher description fits user intent<\/li>
4. Loading ：on match load full SKILL.md & supporting files<\/li>
5. Rendering ：substitute arguments/env vars/&bang commands<\/li>
6. Execution ：inline inject or fork sub‑agent based on context flag<\/ li>

User Pain Points Addressed :

• “Why do I need to restart after adding a new skill?” → because watch starts only on existing root directories.
• “Why isn’t my skill triggered?” → likely description too vague or not indexed yet.
• “Why do supporting files seem ignored?” → y’re lazily loaded on demand after skill activation.

• “把经验从 Prompt 抽出来”;<\/em>: 每种业务形成独立 SKILL.md，而不是堆进全局 system prompt.<\/ li>
• “按需展开上下文”;<\/em>: 模型先看到短描述。真正需要时才看到完整说明与脚本.<\/ li>
• “模糊判断交给模型，确定步骤沉淀为资产”;<\/em>: 路由由 LLM 完成，执行步骤通过 Skill 编码.<\/ li>

User Pain Point :/ Users often struggle with “prompt bloat” – Skills keep prompts lean while still providing rich procedural knowledge.

• “No large static data inside SKILL.md”;按理说，Use supporting files instead.<\/ li>
• “No high‑risk automation without explicit confirmation”;Set disable-model-invocation:true.<\/ li>
• “Avoid catch‑all Skills”;Keep each Skill focused on one clear goal.<\/ li>
• “Avoid overly broad allowed-tools like Bash unless absolutely trusted.”;<>/Strong><\/ li>

User Pain Point :/ Overly permissive Skills become security liabilities—especially when stored in version control and shared across teams.

---

©2026 Claude Code Community — All rights reserved. {>

---