notis-skill-creator

Notis 技能创建器

此技能用于指导从零创建新技能或迭代现有技能的过程。技能是一个自包含单元，由指令、参考资料和可选脚本组成，可扩展助手的能力。

何时使用此技能

• 用户想要创建新技能（例如，“为 X 创建一个技能”“我需要一个能完成 Y 的技能”）
• 用户正在迭代或打包现有技能
• 用户询问如何构建、验证或分发技能

技能开发工作流

第 1 步：定义技能

创建文件前，先明确以下内容：

• 名称 — 使用 kebab-case（例如，my-skill、api-helper）
• 描述 — 用一两句话说明技能的功能和适用场景
• 范围 — 仅包含指令，还是包含指令、脚本、参考资料和资源

第 2 步：规划内容

• SKILL.md — 必需。包含 YAML frontmatter（name、description）和主要指令。
• scripts/ — 可选。助手可以运行的可执行代码（Python、Bash 等）。
• references/ — 可选。按需加载的文档或参考文件。
• assets/ — 可选。输出中使用的模板、图像或其他文件。
• 状态 — 只要技能需要在多次运行之间保留任何内容，就必须设置状态：历史记录、 进度、审批、队列、缓存或结果。技能可能运行在 Notis 后端上，本地文件无法保留， 因此现在就规划 Notis 数据库：
  • 复用合适的数据库（LOCAL_NOTIS_DATABASE_LIST_DATABASES），或使用 LOCAL_NOTIS_DATABASE_UPSERT_DATABASE 创建一个，并将其关联到技能所属的 Space 及其主视图（参见 notis-query 数据库发现参考文档）。指定其键属性以及每次运行读取和写入的字段。
  • 指示技能使用 LOCAL_NOTIS_DATABASE_GET_DATABASE 针对数据库 slug 返回的 row_write_tool 写入行，绝不要使用硬编码的生成工具名称。
  • 用户需要保留的文档应存放在 Notis 文档或报告中，而非本地文件。
  • 脚本只能在临时目录中写入临时文件。技能绝不能写入自身文件夹：技能同步会上传该文件夹。
• 模型工作 — 生成、分类和研究工作应由运行技能的 Agent 或其子 Agent 完成。只有在用户明确要求时，才提供调用模型提供商 API 的脚本。

智能级别与调用覆盖规则

• 根据工作内容，为每个委派步骤声明 low、medium 或 high；技能未指定级别时使用 high。不要在指令、脚本、模板或示例中嵌入供应商模型名称、版本固定值、系列别名、价格表或单独的工作量映射。
• 通过 LOCAL_NOTIS_GET_INTELLIGENCE_POLICY 直接调用或使用经过身份验证的 Notis CLI，同时获取共享的 contract 和当前 harness 映射。在代码库技能和账户安装的技能中使用相同的运行时 contract；智能级别指引不得依赖相对于检出目录的 docs/ 链接。应同时解析模型和工作量；不要根据级别推断工作量。
• 本次调用中用户明确指定的选项会覆盖技能默认值，包括用户要求的确切模型或工作量。除非用户要求，否则不要更改已保存的账户默认值。
• 固定模型的 harness 会沿用当前配置，并报告请求的级别未生效。需要精确选择的自动化启动器若无法获取实时策略，必须在产生副作用前停止；绝不能猜测回退选项。
• 通过已发现的能力请求媒体，不要硬编码图像、音频或视频引擎名称。将实际模型回执保留为来源凭据；若架构要求填写实际生成结果的标识符，绝不能存储级别。
• 使用已变更的策略、明确的覆盖选项、不受支持的 harness 和不可用的查询进行验证。每周的映射变更不应要求编辑技能。

步骤 3：初始化技能

此时，就该实际创建技能了。

只有在正在开发的技能已经存在，并且需要迭代或打包时，才跳过此步骤。在这种情况下，请继续下一步。

从头创建新技能时，请手动创建目录结构：

mkdir -p my-skill/scripts my-skill/references my-skill/assets

然后创建 my-skill/SKILL.md，并添加正确的 YAML frontmatter：

---
name: my-skill
description: "Description of what this skill does and when to use it"
---

# My Skill

## Instructions

(Add your skill instructions here)

在适当的目录中创建所需的支持文件：

• scripts/ 用于存放可执行代码（Python、Bash 等）
• references/ 用于存放按需加载的文档
• assets/ 用于存放输出中使用的文件（模板、图片等）

步骤 4：撰写并迭代

• 让说明清晰且可执行。说明何时使用该技能、所需输入以及预期输出。
• 按路径引用脚本或资源（例如 scripts/helper.py、references/glossary.md）。
• 让助手在真实场景中遵循该技能，以此进行测试。

步骤 5：保存或更新确切的技能

先发现原生技能工具，并读取当前已安装的技能列表。 根据 LOCAL_NOTIS_LIST_SKILLS 中列出的确切 ID、所有者和 Space 链接来确定现有技能；绝不要仅按名称选择第一个匹配项。编辑会更新该 ID；只有创建真正的新技能时才进行创建。

• 创建单文件技能：使用发现的 LOCAL_NOTIS_CREATE_SKILL，并提供 name、 description 和 skill_md。编辑单文件技能：使用 LOCAL_NOTIS_UPDATE_SKILL，并提供 skill_id 和仅有的变更字段。保留无关的 agent_targets 和 status。
• 创建或更新多文件技能：将完整文件夹打包，其中包含 SKILL.md、 scripts、references 和 assets。使用 CLI 的 --file bundle_url=./skill.zip 上传路径，并调用发现的 CREATE 或 UPDATE 工具（UPDATE 需包含 skill_id）。 不要等待虚构的公开 URL 通知，也不要丢弃现有资源。
• 精选技能在其规范源中维护，并单独发布；普通用户技能更新无法替换精选内容。链接到 Spaces 的 Skill 是共享资源：编辑会影响链接到它的每个 Space，而 Space 源部署会在发布时提交变更后的 Skill 文件夹。
• 验证 frontmatter、资源路径和预期变更；对变更执行 dry-run。读取回同一 ID、内容及保留的分配；对于捆绑包，验证完整资源集。更新不得增加已安装记录的数量。
• 提供原生技能链接。仅在用户提出请求时，才向其导出 zip 文件。

SKILL.md Frontmatter

每个技能都必须包含一个 SKILL.md，至少包含：

---
name: skill-name
description: "Clear description of what the skill does and when to use it."
---

• name — kebab-case 标识符；用于打包和显示。
• description — 显示在技能列表中，并用于分流；应具体明确。

最佳实践

1. 目标明确 — 每个技能都应专注做好一件事。
2. 描述清晰 — 描述用于判断何时调用技能；应便于搜索且表意准确。
3. 结构稳定 — 始终使用 scripts/、references/、assets/，让用户和工具清楚内容的位置。
4. 打包前验证 — 检查 frontmatter、命名，以及所有引用的文件是否存在。
5. 状态保存在 Notis 中 — 后续运行所需的任何内容都应是 Notis 数据库行或文档，绝不能是技能文件夹或机器上的文件。

Notis 专属说明

• 产品源位于 server/skills/；开发工作流位于 .agents/skills/。 不要编辑生成的镜像或供应商缓存；它们不是规范源。
• CLI 所有的同步机制会生成账户捆绑包并管理各 Agent 的链接。自动 Desktop 同步是可选的；仅仅保存一行数据并不能证明本地已可用。 保留目标分配，并针对预期账户使用受支持的同步工作流。在声称可用之前，验证内容已生成并完成物化，且能够被发现。
• 仓库维护者请遵循 docs/notis-skills-lifecycle.md 和 docs/skills-sync.md。