2.2 结构与配置——各工具的技能文件规范
引言
小王的技能包越写越长。API 规范放进去、部署流程放进去、审查清单也放进去……配置文件从 5 行膨胀到 200 行。
他意识到一个问题：又犯了和项目指令文件一样的错误——什么都往一个文件里塞。
技能包的目录结构就是为了解决这个问题：主文件是身份证（轻量、核心信息），辅助文件是行李箱（需要时才打开）。
各工具的技能文件结构
| 工具 | 技能文件位置 | 主文件命名 | 辅助文件结构 |
|---|---|---|---|
| Claude Code | .claude/skills/name/ | SKILL.md | references/、scripts/、examples/ |
| Cursor | 设置 → Commands | Command 名称 | Prompt 模板内容（无独立目录） |
| Windsurf | .windsurfrules | 规则块名称 | 同一文件内多规则块 |
| Cline | .clinerules 或设置 | 配置项名称 | 各配置项分段 |
📋 课程说明
本节以 Claude Code 的目录结构为详细示例（因其文件组织最清晰），但"主文件轻量、辅助文件按需加载"的原则适用于所有工具。
Claude Code 完整目录结构（详细示例）
my-skill/
├── SKILL.md # 主指令文件（必需）
├── template.md # Claude 填写的模板（可选）
├── examples/
│ └── sample-output.md # 输出示例（可选）
├── scripts/
│ └── validate.sh # 可执行脚本（可选）
└── references/
└── api-spec.md # 详细参考文档（可选）只有 SKILL.md 是必需的。 其他都是可选的——按需添加，不要提前设计。
配置字段详解
配置字段（Claude Code 称为 Frontmatter）是技能文件顶部 --- 之间的 YAML 配置块。它就像一张身份证——告诉系统这个技能包是谁、做什么、怎么用。
通用概念：核心字段（所有工具都有）
| 通用概念 | Claude Code | Cursor | Windsurf | 说明 |
|---|---|---|---|---|
| 名称 | name | Command 名称 | 规则块名称 | 标识技能包 |
| 描述 | description | Prompt 说明 | instructions | 功能描述 + 触发场景 |
| 触发依据 | description 内容 | 无自动触发 | globs 路径匹配 | 什么时候激活 |
Claude Code 详细字段（CC 特有）
| 字段 | 作用 | 什么时候需要 |
|---|---|---|
name | 命令名 | 想覆盖目录名时 |
description | 功能描述 + 触发场景 | 永远需要 |
when_to_use | 额外触发上下文 | description 不够用时 |
arguments | 命名参数 | 需要传参时 |
argument-hint | 参数提示 | 有参数时 |
disable-model-invocation | 禁止自动触发 | 有副作用的操作 |
user-invocable | 从 / 菜单隐藏 | 纯知识库型技能包 |
allowed-tools | 预授权工具 | 想减少权限提示时 |
context | 设为 fork | 长任务需隔离时 |
agent | 子代理类型 | 配合 context: fork |
model | 模型覆盖 | 想用便宜模型时 |
effort | 思考努力度 | 简单任务降级 |
paths | 文件路径限制 | 语言/框架特定技能包 |
⚠️ 字段工具差异
arguments、allowed-tools、context、agent、paths 是 Claude Code 特有功能，其他工具无直接等价物。
调用控制矩阵（Claude Code）
三个关键字段决定"谁能调用这个技能包"：
用户可以调用 Claude 可以自动调用
默认 ✅ ✅
disable-model-invocation ✅ ❌
user-invocable: false ❌ ✅⚠️ 有副作用就必须禁止自动调用
部署、发送消息、创建 PR——这些操作一旦执行就无法撤回。必须设置 disable-model-invocation: true，否则 Claude 可能觉得"代码看起来准备好了"就自动部署。
辅助文件：按需加载的知识库
什么时候需要辅助文件？
当主文件超过 200 行时，就该考虑把内容移出去。
Claude Code 怎么引用？
在 SKILL.md 中用 Markdown 链接：
---
description: API 开发规范。当开发 REST API 端点时使用
---
# API 开发规范
## 核心原则
- URL 使用 kebab-case
- 响应使用 camelCase
- 使用标准 HTTP 状态码
## 详细规范
完整的 REST API 规范参见 [rest-spec.md](references/rest-spec.md)。
完整的 GraphQL 规范参见 [graphql-spec.md](references/graphql-spec.md)。Claude 在需要时会自动读取这些文件——这就是渐进式披露的 Level 3。
📋 其他工具的辅助文件
- Windsurf：在同一
.windsurfrules文件内定义多个规则块，无独立辅助目录 - Cursor：Command Prompt 内直接写完整内容，无辅助文件机制
- Cline：
.clinerules文件分段写不同规范，或用多个配置文件
小王的 API 技能包重构（Claude Code 示例）
重构前（SKILL.md 200 行，全塞在一起）：
---
description: API 开发规范
---
# API 开发规范
## 核心原则
（20 行）
## REST API 规范
（80 行）← 大部分时间不需要
## GraphQL 规范
（60 行）← 大部分时间不需要
## 错误处理规范
（40 行）← 偶尔需要重构后（SKILL.md 30 行，详细内容按需加载）：
api-guide/
├── SKILL.md # 30 行：核心原则 + 链接
└── references/
├── rest-spec.md # 80 行：REST 详细规范
├── graphql-spec.md # 60 行：GraphQL 详细规范
└── error-handling.md # 40 行：错误处理规范效果：Claude 加载技能包时只消耗 30 行的 token，只在需要时才读取具体规范。
最佳实践
- 主文件行数标准：
- 推荐：50-150 行（甜蜜区）
- 警告线：200 行（超过就该拆分）
- 硬上限：500 行（可接受但需重构）
- 配置字段只写需要的，不要为了"完整性"加空字段
- 辅助文件按需创建，不要提前设计"完美"的目录结构
- 用
${CLAUDE_SKILL_DIR}引用脚本路径（Claude Code 特性），确保可移植性
本节小结
📌 本节核心要点
- 主文件是身份证：配置字段告诉系统这个技能包是谁、怎么用
- 辅助文件是行李箱：references/、scripts/、examples/ 按需加载（Claude Code 目录结构）
- 通用核心字段：name、description——所有工具都有
- 调用控制：disable-model-invocation（禁止自动）和 user-invocable: false（禁止手动）——Claude Code 特有
- 有副作用必须禁止自动调用：deploy、commit、send 都要设
disable-model-invocation: true - 重构原则：主文件超 200 行就该拆分，详细参考移到辅助文件
思考题
- （Claude Code 用户）下面哪些技能包应该设
disable-model-invocation: true？为什么？/deploy（部署到生产）/api-spec（API 规范查询）/commit（提交代码）/python-lint（Python 代码检查）
- 一个技能包的
user-invocable: false，这意味着什么？什么场景下会用？ - 如果你有 3 个框架的规范（Vue、React、Angular），你会怎么组织技能包目录？
- （其他工具用户）你使用的工具如何组织多个规范？有没有辅助文件机制？
下一节预告
结构清楚了，接下来学技能包最强大的特性之一——动态上下文注入。让技能包读懂项目的实时状态，而不是用过时的信息做判断。