什么是 Skills?

在真实的工程团队里很少有人能够把所有规范背下来。代码风格教程十几页，Git 提交规范三四种类型。API 设计有版本约定，安全审查有检查清单，部署流程有风险控制条款…，

这些规则并不复杂。但数量一多，就不可能长期驻留在脑中。

人类工程师的做法很简单：需要时再查阅。

机器也是模拟人脑。

如果我们把 Claude 当作真正的工程助手，它也会面临一样的问题。

最直接的做法。是把所有团队规范写进 CLAUDE.md，让模型每次对话都读取这些内容。

短期看这是可行的。

但当知识规模扩大到几十页甚至上百页时问题就出现了：每一次对话都在为“可能用不到的知识”支付上下文成本。说起来，

这不仅消耗 tokens。它会稀释模型的注意力，真正需要用到的规则，反而淹没在冗余信息里。

这正是 Skills 出现的背景。

Skills 并不是简单的“能力 机制”，它本质上是一种按需加载的认知结构。与其把所有知识常驻在上下文中，不如把它们封装成可独立触发的能力单元。当模型判断当前任务涉及某个特定领域时再加载对应的知识与操作流程。

可以给 Skills 一个更精确的定义：Skills 是一种可被语义触发的能力包。它包含领域知识、执行步骤、输出规范与约束条件，并在需要时渐进式加载到主 Agent 的认知空间中。

如果我们把 Agent 环境整体展开来看，会发现 Skills 并不是孤立存在的。Agent 环境中有四大支柱，每个都解决了一个根本性问题。

• Tools 是行动原语. 它回答的是能做什么。读文件、改代码、执行 Bash 命令…，这些是操作层面的能力，类似人的双手。
• SubAgents 是执行分工. 它回答的是谁来做。当任务复杂到需要独立上下文时子代理承担专职职责，类似团队中的同事。
• 时候检查。按理说，它们在关键节点自动触发质量校验或合规约束，类似公司中的质检流程。
• Skill 是在正确时机可操作的知识. Skills 回答的是对了一个非常关键的问题：“怎么做。还有何时做”，它不是工具，也不是分工机制。怎么说呢，它是一种可操作知识结构。

Skills 解决的主要问题是在有限的中，让 Agent 在正确的时候拥有正确领域知识。说起来，

This is not a tool problem,nor a division-of-labour issue . It’s a cognition problem—Agent needs to know specific domain rules。processes,patterns to make correct decisions.

Skills 的主要环境位——可操作知识

很多人会把 Skills 理解成“结构化文档”。但可操作知识与被动文档之间，存在本质区别。一份 API 设计教程放在 Wiki 上，是静态文本。它不包含触发条件，不定义执行流程，不规定输出结构，也不会自动校验质量。不过，它等待人去阅读，而一个 Skill，则是一段具备语义入口 的标准操作程序。它逻辑，当我们把文档封装为 Skill。它就不再是参考资料，而成为一种可被调用行为模式。

• 使用者痛点：往往需要频繁阅读和引用多份规范，却无法快速定位最适用规则；导致代码质量不稳定、合规检查延迟。其实，
• 痛点之一：因为项目规模增长。可维护性下降，开发者花费大量时间寻找合适规范，而非专注编码工作。
• 痛点之二：传统手工编排方法无法覆盖所有场景。当新需求出现时需要重新编写 Prompt 或 Workflow，大幅增加迭代成本。

Skill 触发机制

使用者有时知道自己要什么有时只是描述需求。Skills 的双向触发机制让两种场景都能被满足，同时保持能力定义统一。两种方式调用的是同一个 Skill，执行的是一样指令。Status of skill triggers relies on LLM semantic inference rar than exact match.

• /skills//review-code : 直接指定技能名称，由程序立即激活；
• /prompt/"Please review this function": 程序通过对话意图匹配 description 激活对应技能；

Skill 加载权限管理

• If a skill has disable-model-invocation: true ,its description will not load into context;only /name can trigger it.
• You can control access via three methods:
  1. No global use: /permissions deny Skill;说起来，
  2. Tight tool control: Skill exact match;Skill prefix match;
  3. Selective disable per skill: add disable-model-invocation:true.

Skill 存放位置与优先级顺序

• The location determines who can use it and priority order. Same-name priority: Enterprise> Personal> Project.
• If you work in subdirectory,Claude Code automatically discovers .claude/skills/ in that folder. This monorepo discovery mechanism allows each package to have its own skills.

两大类型的 Skills：参考型和任务型

• influences “how to do”, determines “what to do”. The former is semantic environment,latter concrete action.

# Reference-type – Claude auto selects wher to use
从name来看，api-conventions
description: API design patterns for this codebase. Use when writing or reviewing API endpoints.
从name来看。deploy
description: Deploy application to production
disable-model-invocation: true

创建一个参考型 SKILL.md 文件：api-conventions


Create .claude/skills/api-conventions/ directory with SKILL.md file.
.claude/skills/api-conventions/
└── SKILL.md # main file
---name: api-conventions
description:
...
allowed-tools:
- Read
- Grep
- Glob

\endlist -->

No execution steps—just guidelines.

No output template—no fixed report format.

No disable-model-invocation—auto-trigger.

Only read tools allowed.\ n 
a\t\t\t\t\t\t\t\t\t\t"

Skills Frontmatter 字段详解

 
---name:my-skill-name # optional identifier description:What this does # recommended trigger phrase
warg‑hint:\"\" # optional autocomplete hint for args
disable-model-invocation:true # optional — disallow auto‑trigger by model
user-invocable:false # optional — hide from users unless explicitly called
allowed-tools: # optional — restrict tools available when skill active





Read




Grep




Glob




至于model，sonnet # optional — specify execution model

context:fork # optional — isolate execution in child agent

再看agent，Explore # optional — context fork's agent type

从hooks来看， # optional — hooks scoped within this skill

PreToolUse:
- matcher:warmup
再看hooks，- type:shell command:\"echo 'Write called in skill'\"``
 * name : max length?，must be lowercase letters digits hyphen;recommend gerund form code-reviewing etc.
* argument-hint : shows autocomplete when typing /skill-name.
* disable-model-invocation + user‑invocable controls who triggers.
* allowed‑tools : restrict which tools may be used by skill.
* context,agent,model define execution environment.
* hooks : define lifecycle-specific hooks for skill.


-->

再看示例测试，api-conventions 引导生成符合规范 API 接口代码







: Developers often waste time hunting down relevant guidelines across scattered docs。leading to inconsistent coding practices and increased defect rates.

: Skills are not just knowledge repositories but actionable modules that load on demand via semantic triggers,freeing developers from manual lookup overhead and reducing token waste during conversations.

: Separate small universal rules into CLAUDE.md so every session starts fresh;place scenario‑specific instructions and detailed knowledge into Skills for lazy loading when needed.