skills-il-skill-creator

Skills-IL 技能创建器

概述

此技能将引导你为 skills-il 组织创建可用于生产环境的高质量技能。它遵循 Anthropic 的《构建技能完整指南》，并确保符合所有 skills-il 规范。

你创建的每项技能都将包含 SKILL.md、希伯来语配套文件（SKILL_HE.md）、双语 metadata.json，并通过验证。

说明

第 1 步：选择分类仓库

询问用户此技能属于 13 个分类仓库中的哪一个：tax-and-finance、government-services、security-compliance、localization、developer-tools、communication、food-and-dining、legal-tech、marketing-growth、education、health-services、accounting 或 travel。每个仓库的侧重点见 references/skill-spec.md。

如果此技能不符合任何分类，请与用户讨论它是否应归入现有分类，或是否值得新建一个仓库。

第 2 步：收集创建者信息（必须询问）

继续之前，你必须询问用户的创建者信息。这些信息是将技能提交到 Skills IL 目录所必需的。

询问用户：

“你的 GitHub 用户名是什么？它将成为技能的 author，目录会据此生成你的创建者链接和头像。”

等待用户回复，并将答案保存为 creator_name。

然后询问：

“你的电子邮件地址是什么？我们需要通过它通知你技能发布、推荐展示，或在需要联系你更新相关事项时通知你。该地址不会公开显示。”

等待用户回复，并将答案保存为 creator_email。

规则：

• creator_name 为必填项，且必须是真实的 GitHub 登录名，不能是全名、品牌名或笔名。目录会链接到 github.com/<author>，并从 github.com/<author>.png 加载头像，因此，任何非账号名称都会导致链接失效且图片无法显示。使用前请先检查：curl -sL -o /dev/null -w '%{http_code}' https://github.com/<author>.png 必须输出 200（账号不存在时会输出 404）。
• creator_email 必填，且必须是有效的电子邮件地址。未提供时不得继续。
• 保存这两个值。将 creator_name 填入 metadata.json 的 author 字段；提交表单时也要填写这两个值。
• 如果用户拒绝提供，请说明提交时必须提供电子邮件地址。

第 3 步：定义用例

重要：编写任何代码之前，先确定 2-3 个具体用例。

对于每个用例，记录：

• 触发语句：用户会说什么（英文和希伯来语转写）
• 步骤：所需的多步工作流
• 工具：需要哪些工具（内置或 MCP）
• 结果：成功的表现

格式示例：

Use Case: Validate Israeli e-invoice
Trigger: User says "validate hashbonit electronit" or "check SHAAM allocation"
Steps:
1. Parse invoice fields
2. Validate allocation number format
3. Check against SHAAM rules
Result: Invoice validated with pass/fail report

请用户描述他们的技能构想，然后帮助他们从中提炼出 2-3 个用例。所有领域术语都要附上希伯来语转写（例如，“payroll” = “tlush maskoret”，“invoice” = “hashbonit”）。

现在就记录基准，先于任何搭建工作。 将一个用例交给一个没有该技能的 Agent，并记下三行：你交给它的任务、使用的 Agent，以及它具体在哪一步出错（数字错误、漏掉步骤、编造表单编号）。此后技能中写下的所有内容都应解决清单中的某一项问题。如果该 Agent 已经能正确完成所有用例，请在此处停止：这项技能只会重复模型已知的内容。

第 4 步：核实领域信息

撰写任何内容之前，请核实你的技能将引用的关键事实。这对涉及以色列法律、法规、政府服务、金融规则或医疗政策的技能尤为重要，因为这些内容经常变化。

**需要核实的内容：**法律门槛和限额、政府流程和表格编号、机构名称和联系方式、价格和费用，以及今年生效的任何法律变更。

**核实方式：**使用官方来源（gov.il、以色列议会、Bituach Leumi），结合当前年份进行搜索，并至少通过 2 个来源交叉核对关键数据（金钱数额、法律要求）。

**需要记录的内容：**每项关键事实、来源和核实日期。在 SKILL.md 中，在数值旁注明生效日期（例如，金额后注明“截至 2025 年 1 月”）。

请勿跳过此步骤。技能中的事实过时或不正确（税率错误、法律已失效、电话号码错误），还不如没有技能。

第 4.5 步：受监管领域筛查（搭建框架前决定）

在以色列，某些行为和头衔仅限持证专业人士从事（律师、会计师和税务顾问、房地产估价师、投资和养老金顾问、医生、心理学家等）。技能可能通过两种互不相关的方式越界，因此现在请分别考虑以下两个问题：

1. 名称或描述是否使用了持证职业的头衔或活动名词（“估价”“顾问”“shamai”“yoetz mas”“orech din”）？如果是，请更改名称。免责声明无法补救让人误以为技能由专业人士提供的名称。
2. 技能是否会针对用户自身情况生成由上述某一职业专属提供的工作成果，例如估值、合同、遗嘱、为用户起草的诉状或其他法律文件、法律意见、税务申报或税务意见、投资或养老金建议、诊断？解释流程如何运作属于提供信息。发票生成器或简历撰写工具也会生成文件，但这些文件都不属于某一职业专属提供的成果，因此不在此问题的范围内。

如果任一问题的答案是肯定的：

• 在 SKILL.md 中紧接 H1 后添加 ## Legal notice 部分，并在 SKILL_HE.md 中添加 ## הבהרה משפטית 部分。说明该技能是什么（由 AI 运行的信息工具；如果免费，也注明免费），说明输出未经持证专业人士审核，说明输出不属于该职业范畴内的什么成果，以及它实际是什么（一般信息、统计性参考），说明它不会执行哪些专业步骤，说明输出可能有误，且不得提交、作为证据依赖或当作专业人士的作品呈现，并说明它不能替代根据用户具体情况提供的建议。目录会将此部分显示在首屏。
• 在 SKILL.md 的 description 以及 metadata.json 中的两个 display_description 值开头加上一句简短、针对该职业的说明，例如“非法律建议。”/“אינו ייעוץ משפטי.”，以确保搜索结果和卡片截断内容时仍能显示。
• 优先输出用户撰写内容所依据的原则和论点，而不是直接输出最终文件。生成可直接提交的异议函，比提供要点让用户自行撰写更难以辩护。

不确定？请在提交表单中说明。目录的受理审核会对此进行检查，并在发布前要求修改。

步骤 5：搭建文件夹结构

**Skill 所在位置：**可以放在你自己的公开 GitHub 仓库中（通常采用这种方式，并在步骤 11 中以“现有仓库”的形式提交），也可以放在作为拉取请求提交的类别仓库分支中。在自己的仓库中，先下载一次验证器，以便在步骤 10 中运行：mkdir -p scripts && curl -sL https://raw.githubusercontent.com/skills-il/developer-tools/master/scripts/validate-skill.sh -o scripts/validate-skill.sh && chmod +x scripts/validate-skill.sh。

在该仓库的根目录中，运行此 Skill 的搭建脚本（必须提供 --author，且值必须是你的 GitHub 用户名）：

python3 <path-to-skills-il-skill-creator>/scripts/scaffold-skill.py --name <skill-name> --category <category-repo> --author <github-login>

该脚本会创建以下文件（SKILL.md 和 SKILL_HE.md 中附带 Gotchas 和 Reference Links 占位内容）：

<skill-name>/
├── SKILL.md          # Minimal frontmatter (name, description, license)
├── SKILL_HE.md       # Hebrew companion stub
├── metadata.json     # Enriched metadata (tags, display names, agents)
├── scripts/          # For helper scripts
└── references/       # For reference documentation

验证输出：

• 文件夹名称采用 kebab-case
• 不含空格、下划线或大写字母
• 名称不含“claude”或“anthropic”
• 名称最多 64 个字符，且不得以连字符开头或结尾，也不得包含连续连字符（Agent Skills 规范）
• Skill 文件夹中不含 README.md（Skill 文件夹不得包含 README.md）
• 仓库级 README.md（位于你的仓库或类别仓库的根目录）必须使用英文撰写。这是必需的，因为该仓库在 GitHub 上公开，README 是面向国际开发者和 AI Agent 的入口。希伯来语内容应放在 Skill 文件夹中的 SKILL_HE.md 文件内，而不是仓库 README 中。

第 6 步：编写 YAML Frontmatter 和 metadata.json

重要：Skills-il 将元数据拆分到两个文件中。 Claude Desktop 会拒绝 SKILL.md frontmatter 中的 metadata 键，因此所有扩展元数据都放在单独的 metadata.json 文件中。SKILL.md frontmatter 特意保持精简。

SKILL.md frontmatter（仅包含以下 3–5 个字段）：

---
name: <skill-name>
description: >-
  [What it does -- one sentence]. Use when user asks to [triggers in English],
  "[Hebrew transliteration 1]", "[Hebrew transliteration 2]", or [more triggers].
  [Key capabilities]. Do NOT use for [anti-triggers] (use [alternative-skill] instead).
license: MIT
allowed-tools: '<tools if needed>'      # optional, only when scripts call CLI tools
compatibility: >-                         # optional
  [Network/system requirements, consistent with supported_agents].
---

请勿在 frontmatter 中添加 metadata:、version:、tags:、display_name:、display_description:、author:、category: 或 supported_agents:。Claude Desktop 会拒绝这些字段。

**metadata.json（与 SKILL.md 一同放在 skill 文件夹中）**包含 author（第 2 步中你的 GitHub 用户名）、version（从 1.0.0 开始）、category、作为等长 he / en 数组的 tags、作为 {he, en} 对象的 display_name 和 display_description，以及 supported_agents。脚手架会生成一个已填充内容的模板；完整的注释示例见 references/skill-spec.md。

**支持的 Agent：**只列出确实能够运行该 skill 核心流程的 Agent。脚手架默认包含七个能够运行捆绑脚本的终端 Agent。不要假设桌面、网页和上传平台（claude-desktop、claude-ai、chatgpt、manus、grok）可以运行 python3 scripts/x.py 这样的步骤；只有当该 skill 提供了能在这些平台上运行的路径时，才添加对应平台。gemini-spark 可以运行脚本，但无法访问网络。完整的 slug 列表、能力等级和 Gemini Spark 的限制见 references/skill-spec.md。请在 compatibility 中说明有意排除的平台。

项目风格规则（适用于每个 skill 文件）：

• 任何 skill 文件中都不得使用 em dash（U+2014）或 en dash（U+2013）。请改用逗号、括号、句号、表示范围的 "to" 或 ASCII 连字符。
• 所有 13 个类别仓库都使用 master，而非 main；skill 的 GitHub URL 必须包含完整文件夹路径：https://github.com/skills-il/<repo>/tree/master/<slug>。

**双语标签（必须询问）：**定义英文标签后，询问用户：

"请为每个标签提供希伯来语翻译。对应的希伯来语说法是什么？"

两个数组都必须提供，长度必须相同（每个英文标签对应一个希伯来语标签），且不能包含空字符串。没有希伯来语对应说法的技术术语（API、MCP）在两种语言中都保留英文。

描述规则（重要）：

• 必须遵循以下模式：[功能] + [适用场景] + [主要能力] + [不要用于 X]
• 使用第三人称撰写（“验证以色列身份证号码……”），不得使用“我可以帮助你”或“你可以用它……”等表达。描述会注入 Agent 的系统提示词，因此视角变化会影响发现效果。
• 最多 1023 个字符，计数时包含外围 YAML 引号；建议不超过 950 个字符。规范允许 1024 个字符，但 Gemini Spark 会拒绝达到此上限的描述，验证器则强制限制为 1023 个字符。对于普通的单行值，冒号后跟空格会导致 YAML 解析失败。请使用折叠式 >- 写法（脚手架采用此写法），或给值加引号（增加 2 个字符），或将冒号改写为逗号。
• frontmatter 中不得出现 XML 尖括号（< >）。
• 包含用户实际会说的触发短语。
• 将希伯来语转写形式放在引号中（例如 "tlush maskoret"）。
• 以 Do NOT use for 边界说明和相关 skills 的交叉引用结尾。

**allowed-tools：**不需要工具时省略此字段；否则使用带引号、以空格分隔的列表，例如 'Bash(python3:*) WebFetch'。更多模式见 references/skill-spec.md。规范中的此字段仍属实验性内容，并非每个 Agent 都会遵循。

第 6.5 步：编写原则（撰写第 7-8 步时应用）

这些原则决定一项技能究竟能改善 Agent 的行为，还是只会增加 token。撰写正文时就要应用这些原则，不要留到最后再清理。

1. 只针对基线撰写。 每个部分都应解决你在第 3 步记录的一项失败。不解决该列表中任何问题的段落，都可以考虑删除。

2. 简洁：上下文窗口由所有内容共享。 每个词都要与对话内容和其他已加载的技能争夺空间。假设 Agent 已具备相应能力，因此不要解释 JSON 是什么、HTTP 如何工作，也不要教它如何编写循环。逐段思考“这段内容值得占用空间吗？”，如果答案是否定的，就删掉它。上游指南的正文不到 500 行，约 5,000 个 token；skills-il 验证器会在达到 5,000 个单词时直接失败，这个限制较宽松（尤其是希伯来语，每个单词通常消耗更多 token）。以接近上游指南的数字为目标，并将其余内容移至 references/（第 8 步）。

3. 自由度应与脆弱程度相匹配。 具体程度取决于任务以不同方式执行时会造成多大影响。

任务类型	自由度	撰写方式
有多种有效方法（审查内容、起草文案）	高	说明目标和决策标准，让 Agent 自行选择方案
存在首选模式（报告格式、数据整形）	中	提供模板或可调整的参数化示例
脆弱、依赖顺序或不可逆（迁移、申报、付款）	低	给出准确的命令或步骤，并明确要求不得偏离

对高自由度任务施加过多限制，会让技能变得脆弱。对脆弱任务限制不足，则会带来危险。

4. 示例重深度，不重数量。 第 7 步要求至少两个示例；在这个数量范围内，优先选择完整、真实且可运行的示例，而不是留空待填的模板。优先使用真实的以色列数据（实际表单编号、真实的市镇、合理的薪资），而不是 <placeholder> 标记。

5. 让技能经久适用且易于阅读。

• 避免使用会悄然过时的表述（如“新规定”“明年之前”）。应将生效日期与对应数值一并说明。
• 引用层级应保持为一层：SKILL.md 链接到 references/x.md，而该文件不要再引导 Agent 查看第三个文件。
• 对于超过约 100 行的参考文件，添加简短目录，让只阅读开头部分的 Agent 也能了解文件涵盖的全部内容。
• 每个概念只选用一个术语，并在全文统一使用。切换同义词会让 Agent 怀疑它们是否指代不同概念。

第 7 步：编写指令正文

按照以下结构编写 SKILL.md 正文：

# <Skill Display Name>

## Instructions

### Step 1: <First Major Step>
<Clear explanation with tables, code examples>

### Step N: <Next Step>
...

## Examples

### Example 1: <Common Scenario>
User says: "<typical user request>"
Actions:
1. ...
Result: ...

## Bundled Resources

### Scripts
- `scripts/<name>.py` -- <What it does, how to run>. Run: `python3 scripts/<name>.py --help`

### References
- `references/<name>.md` -- <What it contains>. Consult when <specific situation>.

## Gotchas

- <Agent failure mode, not a user error: something an agent following this skill gets wrong>
- <A domain assumption that looks reasonable but is false>
- <A field, format, or edge case agents routinely miss>

## Reference Links

| Source | URL | What to Check |
|--------|-----|---------------|
| <Official source> | <https URL> | <What to verify there> |

## Troubleshooting

### Error: "<Error name>"
Cause: <Why>
Solution: <Fix>

易错点应描述 Agent 的失败模式，而非用户的错误。 “Agent 根据含税总额计算 VAT”属于易错点；“用户忘记了密码”则不属于。这些是技能中信号最强的内容，应根据你在第 3 步记录的失败来编写。

必须验证故障排查中的原因。 遇到症状的 Agent 会把给出的原因当作诊断结果转述给用户。如果原因只是猜测，应在该行明确说明。

正文规则（篇幅和具体程度见第 6.5 步）：

• 用表格呈现决策矩阵、字段映射和比较数据
• 引用随附资源时，说明“何时查阅……”
• 包含 2-4 个示例和 2-4 条故障排查项
• 将希伯来语术语直接嵌入正文：“分期付款（tashlumim）”

步骤 8：创建参考资料和脚本

每项技能都应包含参考文件和辅助脚本。它们能让一项技能从内容单薄变得达到生产级质量。

• 参考资料： 在 references/ 中创建 2-3 个文件，收录过长、不适合放在 SKILL.md 中的详细内容（目录、详细指南、术语表、检查清单、比较表、模板）。每个文件少于 3,000 个单词，使用标题和表格，在括号中包含希伯来语术语，并在 SKILL.md 中为每个文件添加链接及“在……时查阅”的说明。
• 脚本： 在 scripts/ 中创建 1-2 个用于计算或查询的 Python 辅助脚本。使用 #!/usr/bin/env python3 shebang，采用支持 --help 的 argparse，包含用法说明文档字符串，仅使用标准库，验证输入并给出明确的错误信息，输出整洁。脚本应自行处理错误，而不是把问题丢给 Agent。

references/skill-spec.md 中提供了常见的参考资料和脚本模式，以及文件名示例。

更新 SKILL.md： 添加 ## Bundled Resources 部分（置于 ## Troubleshooting 之前），列出所有参考资料和脚本，并附上“在……时查阅”的说明。

更新 SKILL_HE.md： 添加对应的 ## משאבים מצורפים 部分，并提供希伯来语说明。

推荐的 MCP 服务（存在时）： 如果目录中有已发布的 MCP 服务，能提供你的说明所依赖的数据或操作，请添加 ## Recommended MCP Servers 表格（| MCP | What It Adds |，链接到其目录页面），并在 SKILL_HE.md 中添加对应的 ## שרתי MCP מומלצים。不要使用已弃用的 mcp-server frontmatter 键。

步骤 8.5：添加参考链接部分

每项技能都必须包含 ## Reference Links 部分（置于 ## Recommended MCP Servers 或 ## Bundled Resources 之后、## Troubleshooting 之前），并附上用于核实技能领域特定事实的官方来源网址表格。

使用步骤 7 模板中的表格格式（| Source | URL | What to Check |）。

指南：

• 包含 3-6 个权威链接（政府网站、官方 API 文档、法律数据库）。
• 每个链接都应包含“核查内容”列，说明要在该处核实哪些信息。
• 优先选择 .gov.il、.org.il 和机构来源，而非博客。
• 有英文来源时，至少包含一个英文来源。
• 希伯来语配套文件必须包含对应的 ## קישורי עזר 部分。

这些链接能让用户和之后更新技能的人员根据来源重新核实每项声明。

步骤 9：创建希伯来语配套文件（SKILL_HE.md）

创建 SKILL_HE.md，使用相同的结构，但以希伯来语编写：

• 将正文说明翻译成希伯来语。
• 代码块、字段名称和 API 引用保留英文。
• 使用地道的希伯来语术语（不要使用音译）。
• 保持相同的步骤编号和章节结构，并翻译每个章节标题（验证器会检查 ## Examples 或 ## Gotchas 等常见标题，但不会检查所有标题，因此还需自行检查 ## Overview 和 ## Legal notice）。

希伯来语文件使用与 SKILL.md 相同的 frontmatter（frontmatter 保持英文）。

步骤 9.5：验证所有链接（必须执行）

运行验证器之前，请确认技能文件夹中的每个网址都能正常访问。

提取技能文件夹中所有文件（包括 scripts/ 和 references/）里的每个网址，并确认每个网址都返回 HTTP 200。两条命令以及每种非 200 状态的处理方法见 references/submission-checklist.md。特别留意 .gov.il 网址、.co.il 初创企业域名以及“参考链接”表格中的链接。403 通常是机器人拦截：在判定链接失效前，请先用浏览器打开页面。

如果存在失效链接，请勿继续执行步骤 10。 请先修复所有失效网址。

第 10 步：验证并准备提交

从仓库根目录运行验证器（它位于仓库的 scripts/validate-skill.sh，而不是技能自己的 scripts/ 文件夹中）：

./scripts/validate-skill.sh <skill-name>/SKILL.md

验证器需要 PyYAML（pip install pyyaml）；如果没有安装，将跳过 YAML 检查并显示 NOTICE，CI 仍可能拒绝该技能。除了名称、描述、字数、README 和密钥检查外，如果 frontmatter 无法解析为 YAML、描述（包括引号）超过 1023 个字符、缺少 SKILL_HE.md，或者 SKILL_HE.md 中有未翻译的英文标题，验证器也会报错。如果希伯来语正文超过 5,000 个单词，或标题数量与 SKILL.md 不一致，验证器会发出警告。包含修复方法的完整规则表见 references/submission-checklist.md。

验证器仅检查结构。 未修改的脚手架也能通过验证。提交前，grep -rn TODO <skill-name>/ 必须没有任何输出，不能残留任何 [...] 模板占位符，且以下每项都必须手动检查：

• 已记录基线，且每个章节都针对已观察到的问题进行了修复（第 3 步）
• 已根据官方来源核实领域事实（第 4 步）
• 已完成受监管领域筛查；如适用，两份文件的 H1 后面紧接着都有 Legal notice 章节（第 4.5 步）
• 所有 URL 均返回 HTTP 200（第 9.5 步）
• 描述包含 WHAT 和 WHEN，使用第三人称，且包括引号在内不超过 1023 个字符
• 注意事项描述的是 Agent 的失败模式，而不是用户错误
• 说明具体且可执行
• 示例涵盖 2 个或更多真实场景
• 故障排除内容涵盖可能出现的错误
• 包含 Reference Links 章节，并列出 3-6 个已核实的官方来源 URL
• 希伯来语配套文件存在，且章节结构与 SKILL.md 完全一致（包括 ## קישורי עזר）
• references/ 中至少有 2 个参考文件，并包含“何时查阅……”指引
• scripts/ 中至少有 1 个辅助脚本，支持 argparse 和 --help
• 不存在安全问题（密钥、注入向量）
• supported_agents 仅包含其正常流程可用的 Agent，且 compatibility 与之相符
• 已设置 metadata.version（例如 1.0.0）
• metadata.tags 同时包含 he 和 en 数组，两者长度相同且没有空字符串
• 已从用户处收集 creator_name 和 creator_email（第 2 步），且 author 是真实的 GitHub 登录名
• 仓库级 README.md 使用英文编写（不是希伯来语）

第 10.5 步：提交前设置 GitHub 验证

提交表单会针对你的仓库实时运行 GitHub Verification 评分卡，因此请在提交前设置好相关指标。

五项关键指标为 spec_compliant（运行 gh skill publish --dry-run，GitHub CLI 2.90.0 或更高版本）、secret_scanning、code_scanning、signed_release（由标签触发、带有构建来源证明的发布工作流），以及 license_spdx（根目录中的 LICENSE 文件）。references/submission-checklist.md 中列出了每项的快速设置步骤；完整的复制粘贴步骤见 GitHub Verification 检查清单指南。对于 MCP 服务，spec_compliant 不适用。

除非五项全部通过，否则不会批准；拒绝邮件会列出未通过的指标。

第 11 步：提交你的技能

验证通过后，通过提交页面提交你的技能。

1. 选择提交类型：“Existing Repository”（如果你已将技能推送到 GitHub 仓库）或“Proposal”（如果你希望 skills-il 团队创建仓库）
2. 在表单中填写：GitHub 仓库 URL、创建者姓名和创建者邮箱（来自第 2 步）
3. 表单会获取你的 SKILL.md，并显示每项关键指标的通过/失败状态。根据第 10.5 步修复任何失败项，然后重新提交。
4. skills-il 团队会审核你的提交、运行安全分析，并在通过后发布

示例

示例 1：创建政府服务技能

用户说：“我想创建一个用于查询以色列法院判决的技能。”

操作：

1. 类别：government-services
2. 创建者信息：询问 GitHub 用户名和电子邮件
3. 使用场景：按案件编号搜索、按法官姓名搜索、按主题搜索（希伯来语法律术语）
4. 事实核查：通过官方来源核实法院系统结构、Nevo 的访问方式和引用格式。受监管领域筛查：查找并引用已发布的裁决属于解释法律，因此无需声明，除非该技能开始评估用户自己的案件
5. 搭建脚手架：python3 <path-to-skills-il-skill-creator>/scripts/scaffold-skill.py --name israeli-court-decisions --category government-services --author <github-login>
6. Frontmatter：name=israeli-court-decisions，author=creator_name，触发词包括 "psakei din"、"beit mishpat"、"nevo"
7. 指令：涵盖不同搜索类型、结果解析和引用格式的步骤
8. 参考资料：references/court-hierarchy.md（法院级别）、references/citation-format.md（以色列法律引用规则）
9. 希伯来语：使用本地法律术语编写 SKILL_HE.md
10. 验证：./scripts/validate-skill.sh israeli-court-decisions/SKILL.md
11. 通过提交页面提交

结果：完整的技能已准备就绪，可加入 Skills IL 目录。

示例 2：创建开发者工具技能

用户说：“我需要一个帮助规范以色列地址格式的技能。”

操作：类别为 developer-tools（如果重点是地址查询 API，则选择 government-services）；询问 GitHub 用户名和电子邮件；使用场景包括邮政地址格式化、mikud 验证和城市名称标准化；核实 mikud 格式规则及 Israel Post API 的可用性；使用 python3 <path-to-skills-il-skill-creator>/scripts/scaffold-skill.py --name israeli-address-formatter --category developer-tools --author <github-login> 搭建脚手架；触发词包括 "format ktovet" 和 "mikud"；添加 references/mikud-format.md 和 scripts/mikud-validator.py；编写 SKILL_HE.md；验证；提交。

结果：支持验证和邮政格式的地址格式化技能。

示例 3：创建集成 MCP 的技能

用户说：“我想创建一个使用 israeli-bank-mcp 服务的技能。”

操作：类别为 tax-and-finance；询问 GitHub 用户名和电子邮件；使用场景包括交易分类、定期扣款检测和月度摘要；使用 --author <github-login> 搭建 israeli-bank-analyzer；在 SKILL.md 中添加 ## Recommended MCP Servers，并在 SKILL_HE.md 中添加 ## שרתי MCP מומלצים，两者均指向 israeli-bank-mcp；指令涵盖 MCP 工具调用、分类逻辑和摘要；添加 references/bank-api-reference.md 和 scripts/transaction-categorizer.py；验证；提交。

结果：通过 MCP 增强的技能，在银行数据访问之上提供工作流智能。

随附资源

脚本

• scripts/scaffold-skill.py -- 为新的 skills-il 技能创建完整的文件夹结构：包含最简 frontmatter 以及 Gotchas 和 Reference Links 占位内容的 SKILL.md、包含希伯来语标题的 SKILL_HE.md 占位文件、metadata.json（扩展元数据，--author 的值为你的 GitHub 登录名），以及 scripts/ 和 references/ 目录。验证名称（kebab-case，最多 64 个字符）和类别，并防止覆盖现有文件。运行：python3 scripts/scaffold-skill.py --help

参考资料

• references/skill-spec.md——完整的 skills-il SKILL.md 规范，包括所有 frontmatter 字段（必需和可选）、附有正反示例的描述撰写公式、Anthropic 指南中的 5 种技能模式、质量检查清单和验证规则。编写 frontmatter 或说明时，如需获取超出上述步骤的详细指导，或需要选择 supported_agents，请查阅此文件。
• references/submission-checklist.md——链接检查命令和状态操作、完整的 validate-skill.sh 规则表，以及 5 项 GitHub Verification 信号。链接检查、验证器或提交评分卡未通过时，请查阅此文件。
• references/domain-checklist.md——完整的技能撰写指南必须涵盖的内容及相关来源。审查或扩展此技能时，请查阅此文件。

注意事项

• 扩展元数据存放在 metadata.json 中，而非 SKILL.md frontmatter 中。Claude Desktop 会拒绝 YAML frontmatter 中的 metadata: 键。基于旧版技能（或旧脚手架模板）训练的 Agent 可能会将 version、tags、display_name 和 supported_agents 放入 frontmatter，从而导致技能无法正常工作。
• metadata.json 中的标签使用 tags.he / tags.en 双语结构，且两种语言的标签数量必须相同。Agent 可能会将标签合并为一个数组。
• SKILL_HE.md 中的希伯来语内容绝不能出现在代码块（```）中，因为代码块不支持从右向左渲染。希伯来语内容请使用纯文本或项目符号列表。
• 技能描述有双重用途：既是 YAML frontmatter 描述，也是 Agent 匹配查询时使用的触发文本。Agent 可能会写出无法响应相关用户查询的通用描述。
• metadata.json 必须包含 version、category、双语 tags、display_name、display_description 和 supported_agents。Agent 可能会遗漏 supported_agents 或 display_name 等必需字段。
• 规范规定描述上限为 1024 个字符，因此 Agent 会将 1024 视为上限。验证器的计数包含 YAML 引号，且上限为 1023，因此带引号的 1023 个字符的值也会验证失败。
• Agent 会将贡献者的全名填入 author。此处必须填写 GitHub 登录名，否则创建者链接和头像会失效。

参考链接

来源	URL	检查内容
Agent Skills 规范	https://agentskills.io/specification	Frontmatter 字段和限制（name、description、compatibility）
Anthropic 技能撰写最佳实践	https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices	简洁性、自由度、渐进式披露、优先评估
Claude 技能构建完整指南（Anthropic，PDF）	https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf	references/skill-spec.md 中总结的 5 种技能模式
skills-il 验证器	https://github.com/skills-il/developer-tools/blob/master/scripts/validate-skill.sh	CI 执行的具体检查，包括 1023 字符限制和 SKILL_HE.md 规则
gh 技能发布手册	https://cli.github.com/manual/gh_skill_publish	spec_compliant 信号背后的 --dry-run 验证
GitHub Verification 检查清单	https://agentskills.co.il/en/guides/github-verification-checklist	5 项关键（Critical）信号的设置步骤

故障排除

错误：“Validation fails on description”

原因：描述缺少触发短语、超过 1023 个字符（包括 YAML 引号），或包含尖括号 解决方案：确保描述包含以下短语之一：“Use when”、“Use for”、“Use if”、“When user”、“When the user”。将描述缩短至 1023 个字符以内，计数时包含引号（建议控制在 950 个字符以内）。移除所有 <> 尖括号。

错误："frontmatter is not valid YAML"

原因：几乎总是因为单行描述中包含冒号和空格，YAML 会将其解析为嵌套键。 解决方案：将描述改为折叠式 >-，用单引号括起来（并将其中的单引号加倍），或将冒号改写为逗号。此检查也会检查 SKILL_HE.md 的 frontmatter。

错误："missing sibling SKILL_HE.md" 或 "untranslated English heading(s)"

原因：缺少希伯来语配套文件，或文件中保留了代码块外的英文章节标题，例如 ## Examples。 解决方案：创建 SKILL_HE.md，并翻译所有章节标题（例如 ## דוגמאות、## מלכודות נפוצות、## קישורי עזר）。代码围栏内的标题会被忽略。

错误："Name doesn't match folder"

原因：SKILL.md 的 name 字段与文件夹名称不同。 解决方案：name 字段必须与文件夹名称完全一致。两者都必须采用 kebab-case。运行：ls -la 检查文件夹名称，并与 frontmatter 中的 name: 对照。

错误："Body exceeds 5,000 words"

原因：SKILL.md 中的细节过多。 解决方案：将详细文档移至 references/ 文件。让 SKILL.md 专注于核心说明。添加链接，并使用“Consult references/filename.md for...”这样的指引。

错误："Scaffold script fails"

原因：文件夹已存在或名称格式无效。 解决方案：检查技能文件夹是否已存在。确保名称仅使用 kebab-case（小写字母、数字和连字符）。不得包含空格、下划线或大写字母。