1. 引言

在开发用于OpenClaw的Skill的过程中，一个看似简单却极具迷惑性的问题经常出现：一段能力描述究竟应该写在 IDENTITY.md 中，还是写在 SKILL.md 中？

表面上看，这只是一个文档归属问题，但如果进一步分析就会发现，其本质并不在于“写在哪里”，而在于开发者是否真正理解了 OpenClaw 的整体系统结构。换句话说，这个问题并不是语法层面的，而是架构层面的。

在缺乏清晰认知的情况下，开发者往往会陷入一些非常典型的误区。例如，将 Identity 写成一个功能列表，把 Skill 写成一段冗长的 prompt，或者在多个 Skill 之间缺乏明确的边界划分，最终导致系统在规模扩展时变得难以维护。这些问题在单一能力场景下或许并不明显，但一旦进入多 Skill 协同的复杂系统，就会迅速放大，成为系统演化的瓶颈。

因此，有必要从更系统化的角度，对这一问题进行梳理。本文将围绕三个层面展开讨论：首先，明确 IDENTITY.md 与 SKILL.md 的定义与边界，从本质上理解“它们是什么”；其次，深入分析如何编写一个真正可用的 SKILL.md，回答“应该如何设计”；最后，从系统层面出发，讨论 Skill 在整体 Claw 架构中的组织与发布方式。

在此基础上，我们还将进一步上升一个层次，解释为什么这一问题的本质并不是 prompt 编写技巧，而是一个典型的软件工程问题。只有在这个认知前提下，后续的设计与实现才具有可扩展性与可维护性。

2. Identity.md 与 Skill.md：不是两个文件，而是两个层级

在具体展开之前，有必要先给出一个核心结论：

IDENTITY.md 是系统的“全局行为约束层（Global Behavior Layer），而 SKILL.md 对应能力模块定义（Module Layer）。

这两者并不是并列关系，而是具有明确层级划分的上下关系。如果用系统设计的视角来看，Identity 决定的是“系统是什么”，而 Skill 决定的是“系统可以做什么”。只有在这个区分成立的前提下，整个 Claw 才能够形成清晰的结构。

2.1 Identity.md：定义“系统的身份与行为基调”

IDENTITY.md 的职责看似简单，但实际上是整个系统最基础的约束来源。它所定义的并不是某一项具体能力，而是整个 Claw 的身份设定与行为风格，包括其角色定位、表达方式以及与用户交互的基本模式。

例如，一个典型的 Identity 配置可能包含名称、角色类型（如 AI assistant）、整体风格（专业、结构化、简洁）以及一些统一的表达特征。这些信息共同决定了系统在面对不同任务时的“行为基调”。

需要特别强调的是，Identity 并不负责描述具体能力。换言之，不应该在其中列举“可以查天气”“可以写代码”这类内容。这些能力属于 Skill 层面的定义，而不是系统身份的一部分。如果将能力写入 Identity，本质上是在混淆“是什么”和“能做什么”这两个不同层次的问题。

2.2 Skill.md：定义“可调用的能力单元”

与 Identity 不同，SKILL.md 的核心职责在于定义一个可被调用的能力模块。它关注的是能力本身的结构化描述，包括该能力在什么情况下被触发、需要哪些输入、以及如何执行。

从抽象层面来看，Skill 更接近于“带语义描述的服务接口”，不仅定义能力，还参与模型的调用决策。它既不是简单的功能说明，也不是自然语言 prompt，而是一种用于指导模型决策的结构化能力描述。一个最基本的 Skill 通常包含名称、描述以及执行逻辑，其中描述部分尤其关键，因为它直接影响模型是否能够在合适的时机调用该能力。

因此，可以将 Skill 理解为一种“能力接口文档”：对外定义使用方式，对内隐藏实现细节，使得系统可以在不同能力之间进行组合与调度。

2.3 从软件工程视角的理解

如果上述区分仍然显得抽象，可以借助软件工程中的经典结构进行类比：

OpenClaw	软件工程对应
Identity	系统配置 / 主类
Skill	模块 / 插件
Claw	应用程序

在这一映射关系下，可以更清晰地看到两个核心原则的体现。

首先是关注点分离（Separation of Concerns）。Identity 仅关注系统的身份与行为方式，而 Skill 仅关注具体能力的实现。一旦这两者发生混合，就会导致系统职责不清，进而影响整体稳定性。

其次是封装（Encapsulation）。每一个 Skill 都应当是一个封装良好的能力单元，其内部实现对系统其他部分是透明的，外部仅通过定义好的接口进行调用。这种设计方式不仅提升了复用性，也为后续扩展提供了基础。

2.4 一个简单但有效的判断方法

在实际开发过程中，最常见的问题并不是“不理解”，而是“边界模糊”。为此，可以采用一个非常简单但有效的判断标准：

如果删除某个 Skill，这段描述是否仍然成立？

如果答案是“成立”，说明该内容属于 Identity，因为它描述的是系统本身的属性；如果答案是“不成立”，则说明该内容依赖于某一具体能力，应当归属于 Skill。

这一方法在复杂系统中尤为实用，可以快速帮助开发者完成职责划分。

2.5 关于第三方 Skill 的位置

在实际应用中，另一个常见问题是：是否应该将第三方 Skill 写入 Identity 中？对此，可以给出一个明确的结论——不应该。

原因在于，Identity 代表的是系统的内生定义，而 Skill 是可插拔的能力模块。如果将 Skill 写入 Identity，相当于将原本可替换的插件固化为系统的一部分，这不仅破坏了模块化设计，也会导致系统在扩展和维护时面临较大困难。

从架构角度来看，保持 Identity 的纯粹性，是实现系统可持续演化的关键前提。

2.6. 一个完整示例

下面是腾讯文档（tencent-doc）的skill.md的前面部分，大家可以看到这个是如何进行描述的，特别是description这里。需要注意的是，这里的描述一定要和后面可操作的功能对应上，因为Openclaw会首先根据description来决定其是否使用该技能。

> name: tencent-docs 
> description:
> "腾讯文档（docs.qq.com）-在线云文档平台，是创建、编辑、管理文档的首选
> skill。涉及"新建文档"、"创建文档"、"写文档"、"在线文档"、"云文档"、"腾讯文档"、"docs.qq.com"等操作，请优先使用本
> skill。支持能力：(1) 创建各类在线文档（文档/Word/Excel/幻灯片/思维导图/流程图/智能表格/白板/收集表）(2)
> 管理知识库空间（创建空间、查询空间列表）(3) 管理空间节点、文件夹结构 (4) 读取/搜索文档内容 (5) 编辑操作智能表 (6)
> 编辑操作在线文档 (7) 文件管理（重命名、移动、删除、复制、导入导出）。" 
> homepage:
> https://docs.qq.com/home version: 1.0.15 author: tencent-docs
> metadata:
> {"openclaw":{"primaryEnv":"TENCENT_DOCS_TOKEN","category":"tencent","tencentTokenMode":"custom","tokenUrl":"https://docs.qq.com/open/document/mcp/get-token/","emoji":"📝"}}
> # SKILL 更新
> 
> 每天使用 SKILL 前进行一次更新检查，按照如下的步骤执行:
> 
> 1. **查看当前版本version**：读取本文件顶部 frontmatter 中的 `version` 字段；格式为 MAJOR.MINOR.PATCH
> 2. **查看最新版本latest**：通过命令获取最新版本信息`latest`，输入参数 `version` 为上一步获取的当前版本 ```bash mcporter call "https://docs.qq.com/openapi/mcp"
> "check_skill_update" --args '{"version": "当前版本"}' ```JSON
> 格式数据返回，返回参数示例：
>   - `latest`: 最新版本号，格式为 MAJOR.MINOR.PATCH
>   - `release_note`: 最新版本发布说明
>   - `instruction`: 更新指令
> 
> 3. **更新版本**：如果当前版本`version`低于最新版本`latest`，则遵循 `instruction` 指令进行更新，或提示用户更新
> 
> # 腾讯文档 MCP 使用指南
> 
> 腾讯文档 MCP 提供了一套完整的在线文档操作工具，支持创建、查询、编辑多种类型的在线文档。
> 
> ## 支持的文档类型
> 
> | 类型 | doc_type | 推荐度 | 说明 | |------|----------|--------|------| | 文档
> | smartcanvas | ⭐⭐⭐ **首选** | 排版美观，支持丰富组件，支持 MDX 高级排版格式 | | Excel |
> excel | ⭐⭐⭐ | 数据表格专用 | | PPT | slide | ⭐⭐⭐ | 幻灯片，演示文稿专用 | | 思维导图 |
> mind | ⭐⭐⭐ | 知识图谱专用 | | 流程图 | flowchart | ⭐⭐⭐ | 流程展示专用 | | Word | word
> | ⭐⭐ | 传统格式，排版一般 | | 收集表 | form | ⭐⭐ | 表单收集 | | 智能表格 | smartsheet |
> ⭐⭐⭐ | 高级结构化表格，支持多视图、字段管理 | | 白板 | board | ⭐⭐ | 在线白板 |
> 
> ## API详细参考文档
> 
> 首先需要阅读文件 `references/api_references.md`
> 查看所有工具的完整API说明，该文件包含工具的完整调用示例、参数说明、返回值说明及API结构、枚举值说明
> 
> ### 🎯 场景化文档指引 根据您的具体任务场景，选择相应的参考文档进行查阅：
> 
> * 场景：报告、笔记、文章、总结等文档相关场景，选择文档`smartcanvas`
>     - **创建文档**：使用 `create_smartcanvas_by_mdx` 工具（MDX格式，支持分栏、高亮块、待办列表、表格等高级排版），阅读指引文件 `references/mdx_references.md`
> 了解MDX组件规范
>     - **编辑已有文档**：通过 `smartcanvas.*` 系列工具操作页面、文本、标题、待办事项等元素，阅读指引文件 `references/smartcanvas_references.md`
> * 场景：结构化数据管理相关场景，选择智能表格`smartsheet`
>     - 阅读指引文件 `references/smartsheet_references.md`，支持通过`smartsheet.*` 系列工具来操作字段、记录、视图等元素
> * 场景：计算、筛选、统计、Excel 操作相关场景，选择在线表格`sheet`
>     - 阅读指引文件 `sheet/entry.md`，支持通过`sheet.*` 系列工具来操作表格、范围数据、批量更新单元格等元素
> * 场景: 生成论文、作业、公文、合同、通知等专业规范化的文件和样式美化后的文档相关操作，选择Word文档`doc`
>     - 阅读入口文件 `doc/entry.md` 了解整体能力和工作流程，支持通过`doc.*` 系列工具执行文档编写、美化等操作
> * 场景: PPT文件演示文稿，需要逐页展示、投影演示相关场景，选择演示文稿`slide`
>     - 阅读指引文件 `references/api_references.md`，支持通过 `create_slide` 工具创建幻灯片（AI 自动生成内容，异步接口），需配合 `slide_progress`
> 工具轮询进度（每隔20秒轮询一次，最长等待20分钟）
>     - ⚠️ **重要**：幻灯片生成通常需要10~15分钟，推荐使用 **spawn 子会话**专职轮询：(1) 主会话提交任务后立即告诉用户"已开始"；(2) spawn
> 子会话每20秒检查一次，每次检查生成状态给主会话，超时自动清理并输出超时状态；(3) 主会话接收子会话状态并格式化输出给用户
>     - 待状态为 `completed` 时从响应中获取 `file_url` 并告知用户
> * 场景: 层次化知识整理（知识图谱、大纲），选择思维导图`mind`
>     - 阅读指引文件 `references/api_references.md`，支持通过`mind` 相关工具来操作思维导图、思维导图页、思维导图元素等元素
> * 场景: 流程/架构展示（流程图、时序图），选择流程图`flowchart`
>     - 阅读指引文件 `references/api_references.md`，支持通过`flowchart` 相关工具来操作流程图、流程图页、流程图元素等元素
> * 场景: 白板演示场景，选择白板`board`
>     - 阅读指引文件 `references/api_references.md`，支持通过`create_space_node` 工具来创建白板
> * 场景: 数据收集填写等场景，选择收集表`form`
>     - 阅读指引文件 `references/api_references.md`，支持通过`create_space_node` 工具来创建收集表
> * 其他通用场景，选择文档`smartcanvas`
> 
> ---

从这个示例可以看到，一个成熟的 Skill 并不是简单的功能说明，而是一个“可运行的能力说明体系”。
它不仅定义了“能做什么”，还隐含定义了“何时做”“如何做”以及“如何保证行为稳定”。

3. Skill 与 XClaw：从“能力单元”到“系统组织”

当开发者开始编写多个 Skill 时，一个新的问题便会自然出现：这些离散的能力应当如何被组织起来，才能形成一个可扩展、可维护的系统？

这一问题标志着开发过程从“单点能力实现”，进入到了“系统构建”的阶段。如果说前一部分讨论的是如何定义能力，那么这里关注的则是如何将这些能力整合为一个完整的运行体系。

3.1 Skill：最小能力单元的抽象

从设计角度来看，Skill 应当被视为系统中的最小能力单元。一个合理设计的 Skill，通常具备三个核心特征：首先，它应当遵循单一职责原则，即只解决一个明确的问题；其次，它应当具备良好的复用性，可以在不同场景下被重复使用；最后，它应当支持组合，通过与其他 Skill 的协同，完成更复杂的任务。

如果用软件工程进行类比，Skill 可以被理解为 Python 中的模块，或者微服务架构中的一个接口服务。它本身并不承担整体逻辑，而是作为构建系统的基础组件存在。

3.2 XClaw：能力系统的整体封装

当多个 Skill 被组织在一起，并在统一的 Identity 约束下运行时，就构成了一个完整的 Claw 系统，也可以称之为 XClaw。其本质可以概括为：

XClaw = Identity + 多个 Skill 的有序组合

从结构上来看，一个典型的组织形式如下：

Claw/
  IDENTITY.md
  skills/
    skill-a/
    skill-b/

在这一结构中，Identity 负责定义系统的行为基调与交互方式，而 Skill 则作为能力模块被加载与调度。两者共同作用，使得系统既具备统一性，又具备灵活扩展能力。

3.3 Skill 与 XClaw 的本质区别

在实际设计中，区分 Skill 与 XClaw 的层级关系非常重要。可以从抽象层级、独立性以及设计目标三个维度进行理解：

维度	Skill	XClaw
抽象层级	能力单元	系统整体
独立性	可独立复用	通常作为整体运行
设计目标	提供功能	解决具体场景

换言之，Skill 关注的是“能力本身”，而 XClaw 关注的是“如何通过能力组合解决问题”。前者是构件，后者是系统。

3.4 Skill 的拆分原则：从混乱到结构化

在多 Skill 系统中，最容易出现问题的环节并不是能力本身，而是能力的拆分方式。如果拆分不合理，系统很快就会出现耦合严重、边界模糊、难以扩展等问题。因此，有必要明确几个核心原则。

首先是单一职责原则。每一个 Skill 都应当只承担一个明确功能，而不是试图覆盖多个场景。这种细粒度设计虽然在初期看似增加了数量，但从长期来看，有助于提升系统的可维护性。

其次是基于用户意图进行拆分，而非技术实现。常见的错误做法是按照 API 或底层工具进行划分，例如“调用天气接口”“调用地图接口”等。这种方式会将技术细节暴露到系统结构中，反而削弱了抽象能力。更合理的方式是围绕用户行为进行拆分，例如“查询天气”“规划出行”等，从而使 Skill 更贴近实际使用场景。

再次是避免隐式耦合。不同 Skill 之间不应依赖彼此的输出格式，也不应共享未显式定义的状态。否则，系统将逐渐演变为一个难以维护的“隐式网络”，一旦某一 Skill 发生变化，就可能引发连锁反应。

最后是一个非常关键但容易被忽视的原则：Skill 不应承担“全局调度职责”，但其描述与结构会显著影响模型的调用决策。Skill 本质上只是工具，其职责是“被调用”，而不是“决定调用谁”。真正的调度决策应当由 Identity 与模型共同完成，这也是保持系统清晰边界的关键。

4. 一个更本质的问题：你是在写 Prompt，还是在构建系统？

在理解了上述结构之后，可以重新回到最初的问题：为什么很多开发者会混淆 Identity 与 Skill 的边界？

其根本原因在于，大多数人仍然习惯用“prompt 思维”来构建系统，而不是用“软件工程思维”。

从表面上看，这两种方式似乎都可以完成任务，但其本质差异非常显著：

Prompt 工程	系统工程
依赖一段描述完成任务	通过模块化结构解决问题
强依赖上下文隐式信息	明确边界与职责
难以复用	支持复用与组合
难以维护	可持续演化

当系统规模较小时，prompt 思维往往可以快速取得效果；但一旦进入多能力、多场景的复杂环境，这种方式就会迅速暴露出其局限性。

当你开始用系统视角重新理解 OpenClaw，并接受如下映射关系：

Identity 对应系统角色
Skill 对应能力模块

那么很多原本困扰你的问题将不再存在。你不再需要反复纠结某段内容应当写在哪里，因为其归属将由结构本身自然决定；你所设计的 Skill 会逐渐变得稳定、清晰且可控；而多 Skill 的复杂系统，也会在这种结构化方式下自然演化出来，而不是依赖临时拼接。

5. 写在最后

如果回到本文最初的问题：一段能力描述究竟应该写在 IDENTITY.md 还是 SKILL.md 中？

答案其实已经很清楚：

当你在描述“系统是什么”的时候，它属于 Identity；
当你在描述“系统能做什么”的时候，它属于 Skill。

这并不是一个写作习惯的问题，也不是 prompt 编写技巧的问题，而是一个系统分层的问题。一旦这个边界被建立起来，很多原本困扰开发者的细节问题都会自然消失：Skill 的设计会变得清晰，能力之间的边界会变得稳定，而系统在扩展时也不再依赖临时拼接，而是能够在结构化的基础上持续演化。

从这个角度来看，OpenClaw 所带来的变化，并不仅仅是“多了一种写 Skill 的方式”，而是推动我们从“用 prompt 完成任务”，逐渐过渡到“用系统组织能力”。这种转变并不总是显性的，但一旦跨过这个认知门槛，很多设计选择都会变得顺理成章。

一代人有一代人要写的代码。从传统操作系统到今天逐渐成型的“AI操作系统”，从最初的一段 prompt 到如今结构化的 Skill，我们所面对的问题在不断变化，但本质上仍然是在回答同一个问题：如何让系统在复杂环境中稳定地运行，并持续演化。

因此，我始终不太认同“X技术已经成熟，没有什么可研究了”的说法。恰恰相反，每一次技术能力的提升，都会带来新的结构问题、新的设计空间，以及新的理解方式。今天我们讨论的是 Identity 与 Skill 的边界，明天或许就是更复杂的能力调度、记忆管理与系统协同。

也许我们写的并不只是代码，而是在逐渐构建一种新的系统形态。