create-skill-sap-fiori-tools

创建技能 — SAP Fiori Tools

为 open-ux-tools 生态系统编写技能，无论它们在磁盘上的哪个位置。此技能规范 SAP Fiori Tools 技能的约定，使其能在 SAP 批准的 AI 编码助手（Github Copilot、Claude）和开发环境（VS Code、SAP Business Application Studio）之间移植，并可安全公开发布。

技能位置是输入，而不是约定。 不同的宿主和代码库使用不同的目录（例如，用于贡献者技能的 .agents/skills/、用于用户技能的 ~/.agents/skills/、此单体仓库中用于公开技能的 packages/fiori-mcp-server/skills/ 等）。询问用户应在哪里创建（或重构）技能，并在整个过程中将该路径视为目标目录。此 SKILL.md 从不假定特定位置。

为什么需要专门的创建工具？ 通用的技能创建建议在这里并不足够。我们的技能必须能在多个宿主中运行，面向两个后端（CAP + ABAP RAP）、两个 OData 版本（V2 + V4）和两类受众（内部开发人员与公开终端用户）。此技能涵盖这些限制，让作者不必再自行摸索。

---

步骤 0 — 对技能分类（首先执行）

在编写任何内容之前，先决定技能面向谁。这将影响后续的每个选择。

类别	受众	此代码库中的示例	是否公开发布？
Public	构建 SAP Fiori 应用（CAP 或独立应用）的开发人员	sap-fiori-app-development、sap-fiori-analytical-chart、sap-fiori-tree-table、sap-fiori-create-cli、sap-fiori-eslint-plugin、sap-fiori-opa5-test-development、sap-fiori-add-visual-filter	是
Contributor	在 open-ux-tools 单体仓库中工作的工程师	eslint-rule-development、odata-vocabularies-sync	否 — 仅限单体仓库

命名约定（强制）

类别	模式	示例
Public	sap-fiori-<feature>（kebab-case，限定具体功能；除非技能就是 CLI，否则不要使用 -cli 这类产品后缀）	sap-fiori-tree-table、sap-fiori-analytical-chart
Contributor	<domain>-<action>（kebab-case；不加 sap-fiori- 前缀，以便明确此技能并非公开技能）	eslint-rule-development、odata-vocabularies-sync

不要发布缺少 sap-fiori- 前缀的公开技能，也不要给仅供贡献者使用的技能加上 sap-fiori- 前缀（否则它会出现在面向用户的技能列表中）。

如果无法从请求中明确判断，请询问用户适用哪个类别。然后继续。

Frontmatter 和文件夹结构验证

创建技能时，请确保：

• name 仅使用小写字母、数字和连字符（/^[a-z0-9-]+$/），长度为 3–64 个字符
• 文件夹名称与 name 字段完全一致（例如，name: sap-fiori-tree-table 对应 sap-fiori-tree-table/）
• description 长度为 50–1024 个字符，并包含触发关键词
• 文件名必须严格为 SKILL.md（区分大小写）
• 公开技能放在 packages/fiori-mcp-server/skills/（或等效的公开位置）
• 贡献者技能放在 .agents/skills/（或等效的内部位置）

---

步骤 1 — 确认意图和输入

开始起草前，先通过一次简短交流确认以下信息。不要猜测。

1. 技能名称 — 遵循步骤 0 中的命名模式。
2. 目标目录 — 创建技能文件夹的绝对路径或工作区相对路径。技能文件位于 <target-directory>/<skill-name>/SKILL.md。对于 open-ux-tools 单体仓库，公共技能默认放在 packages/fiori-mcp-server/skills/，贡献者技能默认放在 .agents/skills/。
3. 文档链接 — 权威参考文档 URL（SAP Help、GitHub 文档、API 参考等）。先获取并分析这些文档，再据此确定技能的内容、要求和实现步骤。
4. 一句话说明用途 — 该技能能让模型做什么？可以根据文档推导。
5. 触发短语 — 3–4 条应触发此技能的真实用户提示词。它们将写入 description 前置元数据。
6. 范围边界 — read-only 或 draft。可选；仅在树形表等复杂功能同时存在只读和可编辑变体时声明。大多数技能默认采用 draft（技能会修改文件或配置）。除非这一区别很重要，否则省略此字段。
7. 后端覆盖范围 — 仅 CAP、仅 RAP 或两者皆有。默认支持两者；如果支持两者，则必须提供各自的示例。如果功能特定于某种后端，请根据文档确定。
8. OData 版本 — V2、V4 或两者皆有。默认采用 V4（SAP Fiori elements 模板，如 FE_FEOP、FE_FPM，仅支持 V4）。请检查文档中的版本要求或对 V2 的支持情况。
9. 宿主环境要求 — 列出技能面向的环境。SAP 认可的宿主环境：Github Copilot（在 VS Code/BAS 中）、Claude（Claude Code、API 等）。技能也可能适用于其他环境（Cursor、Windsurf 等），但这些环境不受官方支持。如果功能需要特定宿主环境的能力（例如，RAP 所需的 VS Code 扩展或 BAS 专用工具），请记录这些要求，并说明其他环境的规范替代方案。默认情况下，除非另有说明，否则适用于所有环境。
10. 前置 MCP 服务／扩展 — Fiori MCP、CDS MCP、ABAP Development Tools 等。请根据实现要求确定。如果 MCP 服务仅适用于特定宿主环境，请注明。

如果缺少任何信息，请先询问，再开始起草。

---

步骤 2 — 起草 SKILL.md

**首先，获取并分析步骤 1 中提供的文档链接。**提取以下信息：

• 实现步骤和前置条件
• 配置要求和文件变更
• 后端差异（CAP 与 RAP）
• OData 版本限制
• 代码示例和注解模式
• 常见错误和故障排除指南

然后，在 <target-directory>/<skill-name>/ 中创建技能文件夹（目标目录在步骤 1 中确认），并在其中放置 SKILL.md。使用规范模板 references/skill-template.md。该模板包含可直接复制的内部和外部技能前置元数据，以及以下标准章节顺序：

1. 标题 + 一段用途说明
2. 示例用户提示词 — 3–4 条能触发此技能的真实自然语言请求（见步骤 1，第 5 项）
3. 前置条件（环境、MCP 服务、OData 版本、后端）
4. 范围边界（read-only / draft）— 在靠前位置用一句话说明（显而易见时可省略）
5. 必需输入（开始操作前需要向用户询问的内容）
6. 实现步骤（按顺序编号 — 见步骤 3）
7. 实现步骤的验证清单（见步骤 4）
8. 测试（如何运行应用并访问该功能 — 见步骤 5）
9. 常见错误和解决方案（见步骤 6）
10. 参考文档链接（见步骤 7）

SKILL.md 必须少于 500 行。如果超过此限制，请拆分到 references/（步骤 8）。

写作风格

• 优先使用祈使语气：写“读取 manifest.json”，而不是“你应该读取……”。
• 对不显而易见的规则说明原因。相比大声强调的 MUST，大模型更能遵循推理。只有在确实危险的两三种情形（数据丢失、凭据泄露、OData 版本错误）下，才使用全大写的 MUST / NEVER。
• 使用表格呈现决策矩阵（后端 × OData 版本、主机 × MCP 可用性等）。表格精简易读，便于快速浏览。
• 主机可移植性。 技能应能在 SAP 批准的环境（VS Code/BAS 中的 Github Copilot、Claude）中运行，也应能在其他环境（Cursor、Windsurf 等）中使用，除非某项功能确实需要特定主机的工具。当某项能力依赖特定环境时（例如 VS Code 的 ABAP Development Tools 扩展），请说明要求并提供备用方案（例如“在 SAP 系统中执行后端更改，然后返回进行 UI 配置”）。
• 在行内展示简短的代码示例。较长的代码片段应放在 references/ 中。
• 产品名称大小写（必须遵守）。 SAP 始终使用全大写，Fiori 首字母大写，elements 使用小写。不要单独写“Fiori”——始终使用 SAP Fiori（或 SAP Fiori elements、SAP Fiori Tools）。示例：✅ SAP Fiori elements、SAP Fiori Tools、SAP Fiori app — ❌ SAPUI5 Fiori、Fiori Elements、fiori app、SAP fiori。

内容质量检查清单

完成 SKILL.md 前，请确认：

• 所有产品名称在全文中均使用正确的大小写
• 实施步骤已编号并按顺序排列，且目标明确
• 每个步骤均包含前置条件和验证提示
• Verification Checklist 部分与实施步骤一一对应
• Testing 部分说明如何启动项目（CAP、独立模式或模拟模式）
• Common Errors and Solutions 部分包含具体的错误消息和修复方法
• References 部分列出所有权威文档链接
• 谨慎使用全大写警告（每个技能不超过 3 个）
• 没有重复其他技能中的内容（使用交叉引用）
• 所有链接均已检查且可正常访问
• 对于公开技能：Prerequisites 中声明后端（CAP/RAP）和 OData 版本（V2/V4）
• 对于公开技能：若同时支持两种后端，则各自都提供示例

---

第 3 步 — 编写可按顺序执行的步骤

将实施内容组织为编号的、自成一体的步骤，使模型无需重新阅读整个文件即可逐步执行。

每个步骤应：

• 以明确的目标开头（“添加 @Aggregation.ApplySupported 注解”）。
• 列出前置条件（“实体必须至少有一个数值属性”）。
• 提供可运行的代码片段或准确的 MCP 调用。
• 以验证提示结尾（“此时应能在 $metadata 中看到聚合函数”）。

原因： 模型会像执行检查清单一样执行技能。混合多个关注点的步骤会迫使模型重新阅读和规划，浪费 token，并导致输出不一致。

另外：遵循 DRY 原则。如果两种后端的流程有 80% 相同，则将共用部分放在 SKILL.md 中，只将差异拆分到 references/ 下各后端对应的文件中（例如 references/cap/implementation.md 和 references/rap/implementation.md）。

---

第 4 步 — 为实施步骤提供验证清单

紧接编号实施步骤之后，添加一个 Verification Checklist，让模型和用户都能确认目标项目中的每个第 3 步均已正确执行。这是功能级检查，而非技能编写检查。

以 references/skill-template.md 中已有的 ## Verification Checklist 区块为起点，然后根据技能中的实际步骤调整 **After Step N — ...** 分组。

步骤 5 — 测试（如何运行应用并体验该功能）

在验证清单后添加一个 测试 部分，准确说明如何启动项目，以便用户逐项检查清单中的运行时和回归测试。不要假设用户知道该运行哪个脚本——CAP、使用实时后端独立运行，以及使用模拟数据独立运行，都需要不同的命令。

环境相关内容（Node 安装、npm 工作区、模拟服务器详情）请参阅 sap-fiori-app-development（应用预览指南部分）。不要在每项功能技能中重复说明通用的项目启动步骤。

步骤 6 — 常见错误和解决方案部分

每项技能都以 常见错误和解决方案 部分结尾。用户在正常流程出错时会查阅此部分——其中应列出具体的错误消息及其对应的确切修复方法。请参考 sap-fiori-tree-table 技能中结构清晰的示例。

请以 references/skill-template.md 中已有的 ## Common Errors and Solutions 块为起点——其中包含一个 `` 占位符，可直接填入内容。

---

步骤 7 — 参考文档链接

每项公开技能都以 ## References 部分结尾，其中包含指向权威来源的链接。若技能摘要内容不足，用户可以点击这些链接。

贡献者技能（monorepo 内部使用）如果没有特定参考资料，可以省略此部分——大多数 monorepo 任务会引用 AGENTS.md 或 package README，贡献者通常已熟悉这些文档。

不要在技能正文中直接粘贴原始 URL——请在 References 部分添加链接，并在正文中通过名称引用。此处的失效链接会直接影响用户体验；打包前请检查链接。

---

步骤 8 — 分块（500 行规则）

技能文件会加载到上下文中。过长的文件会挤占其他内容，并拖慢模型运行速度。请遵循渐进式披露原则：

• SKILL.md — 始终位于上下文中。 保持在 ≤ 500 行。将其用作索引，指向 references/ 中的详细内容。
• references/*.md — 按需加载。 详细的 CAP 流程、RAP 流程、错误目录、较长的 CDS 模板、历史迁移说明。

关键规则：参考文件只能有一层

所有参考文件都必须由 SKILL.md 直接链接。 切勿创建指向其他参考文件的参考文件——Claude 遇到嵌套参考文件时，可能会使用 head -100 等预览命令，导致信息不完整。

✅ 正确 — 一层结构：

SKILL.md → references/cap-implementation.md
SKILL.md → references/rap-implementation.md
SKILL.md → references/rap-read-only.md
SKILL.md → references/shared-implementation.md

❌ 错误 — 嵌套参考文件：

SKILL.md → references/index.md → references/cap-implementation.md
SKILL.md → references/rap-implementation.md → references/detailed-guides/1-read-only.md

如果参考文件需要指向相关内容，请链接回另一个同样由 SKILL.md 直接链接的参考文件，而不要链接到更深层目录中的文件。

何时拆分

使用 wc -l SKILL.md 统计行数。如果文件：

• < 300 行 — 保持单一文件。
• 300–500 行 — 考虑将最大的部分（通常是 RAP 实现）拆分到 references/ 下的文件中（例如 references/rap-implementation.md）。
• > 500 行 — 立即拆分。模型性能会大幅下降。

打包资源验证

如果技能包含 references/、scripts/ 或 assets/ 文件夹：

• 每个参考文件都由 SKILL.md 直接链接（没有嵌套引用）
• 参考文件使用描述性名称（cap-implementation.md，而不是 1.md）
• 参考文件不超过 500 行
• 每个打包文件都有明确用途（辅助脚本、代码模板、参考数据）
• 单个资源不超过 5MB
• 不包含构建输出目录（node_modules/、dist/、bin/、obj/）
• 脚本包含帮助文档和错误处理

效果良好的布局模式（路径相对于 <target-directory>/<skill-name>/）：

<skill-name>/
├── SKILL.md                        # ~200-400 lines: purpose, prerequisites, decision matrix, quick summaries
└── references/
    ├── cap-implementation.md       # Full CAP flow (linked from SKILL.md)
    ├── rap-implementation.md       # Full RAP flow (linked from SKILL.md)
    ├── rap-read-only.md            # RAP variant 1 (linked from SKILL.md)
    ├── rap-editable.md             # RAP variant 2 (linked from SKILL.md)
    └── shared-implementation.md    # Shared code (linked from SKILL.md)

注意 references/ 下的扁平结构——允许使用 cap/ 和 rap/ 等子目录进行整理，但其中的每个 .md 文件仍必须由 SKILL.md 直接链接，而不能通过其他参考文件链接。

请查看现有技能，例如 sap-fiori-tree-table/ 和 sap-fiori-eslint-plugin/（具体位置取决于你的主机存储位置），了解实际示例。

---

第 9 步 — 不要重复造轮子（DRY）

本仓库中的技能经常会发现相同的模式。请将可复用内容写入共享参考文件，而不是在每个技能中重复说明。

以下情况表明你在重复内容：

• 两个技能都说明“如何为 CAP 项目运行 cds watch”→ 改为链接到 sap-fiori-app-development。
• 每个 RAP 技能都重新解释“为 VS Code 安装 ABAP Development Tools”→ 将其写入一个共享的 references/ 文件，并添加链接。
• 三个技能复制了相同的 CDS 代码片段 → 将其移至 references/shared-implementation.md 并添加链接。

不要仅为了让技能“自包含”而重复内容。交叉引用只需一行；重复内容会带来长期维护成本。

唯一的例外是：先决条件部分。即使其他地方已有几乎相同的内容，也要在每个技能中重复说明。用户首先会阅读这一部分，在这里放链接会造成糟糕的用户体验。

---

最终验证

提交之前，运行以下命令以验证技能结构：

# Count lines (must be ≤500)
wc -l <skill-name>/SKILL.md

# List all files (check for unexpected content)
find <skill-name> -type f

# Verify frontmatter parsing (should output name and description)
head -20 <skill-name>/SKILL.md | grep -E '^(name|description):'

查看第 0、2 和 8 步中的检查清单，确认所有验证标准均已满足。请记住：SAP Fiori Tools（Tools 中的 'T' 必须大写）。