应用技能
应用技能是一组指令,由应用的 AI 智能体按需加载,而不必在每一轮对话中都放在 system_prompt 里。
智能体起初只能看到每个技能的名称和描述。当任务需要某个技能时,智能体才会加载它的指令。技能在被加载之前不产生任何开销,因此您可以给智能体提供很长的流程和参考资料,而不会让每次对话都变重。
应用技能是写给应用自己的智能体的指令。它们不同于使用 Claude Code 构建应用为您的编程智能体安装的技能。
放进技能,还是放进系统提示词?
system_prompt 在每一轮都会被读取。技能只有在智能体决定加载时才会被读取。
放进 system_prompt | 放进技能 |
|---|---|
| 智能体的角色 | 只有部分任务需要的知识 |
| 始终适用的规则 | 较长的流程,例如诊断或调试检查 |
| 与安全相关的规则:智能体绝对不能做的事,或必须先确认的事 | 领域参考资料,例如故障代码或机器的参数 |
| 简短的事实 |
即使智能体从不加载技能,也必须遵守所有与安全相关的规则,因此这些规则始终保留在 system_prompt 中。
技能文件夹格式
技能位于应用的仓库中,与 .ironflock/ 中的其他文件放在一起:
.ironflock/
├── ai-template.yml
└── skills/
└── machine-diagnosis/
├── SKILL.md
└── references/
└── codes-press.md.ironflock/skills/<name>/SKILL.md是必需的。它以 YAML 前置元数据开头,后面是用 Markdown 编写的指令。.ironflock/skills/<name>/references/<file>.md是可选的。只有部分任务需要的资料,请放进参考文件。智能体只在需要某个文件时才加载它,因此每个参考文件都必须能独立读懂。该读哪个文件、何时读,由SKILL.md说明。- 技能文件夹中不允许有其他内容:不能有脚本、图片或符号链接。所有文件都是 UTF-8 文本。
前置元数据有两个字段:
---
name: machine-diagnosis
description: >-
How to find out why a machine is TOO_HOT or shows NO_READING. Load it
before you answer such a question.
---| 字段 | 说明 |
|---|---|
name | 必须与文件夹名相同。 |
description | 纯文本。在加载技能之前,智能体看到的只有这一项。 |
在智能体上列出技能
技能在被智能体列出之前不会起任何作用。在 .ironflock/ai-template.yml 中,为智能体添加 skills 键,并用文件夹名指定每个技能:
machines:
main: true
skills: [machine-diagnosis]只写文件夹名。条目绝不能以 app/ 或 project/ 开头。
智能体看到的技能名称形如 app/<name>,这里是 app/machine-diagnosis。在 system_prompt 或 tool_description 中提到技能时,请使用这种形式。
每个技能文件夹都必须至少被一个智能体列出,且每个智能体对同一技能只能列出一次。
平台技能
形如 platform/<name> 的条目保留给平台向应用提供的技能。目前还没有可用的平台技能,因此这样的条目现在会导致发布构建失败。
限制
| 项目 | 限制 |
|---|---|
| 技能名称 | 小写字母和数字,以单个连字符连接;最多 64 个字符 |
| 描述 | 最多 500 个字符 |
指令(SKILL.md) | 最多 20,000 个字符 |
| 单个参考文件 | 最多 40,000 个字符 |
| 每个技能的参考文件数 | 最多 20 个 |
| 每个应用的技能数 | 最多 20 个 |
| 应用所有技能文件合计 | 最多 2 MiB |
| 单个智能体列出的技能数 | 最多 20 个 |
发布构建会检查什么
创建版本发布时,构建会把技能和 ai-template.yml 一起检查。如果某项检查失败,该版本不会被构建,并会显示发现的第一个问题。请修复后重新创建版本发布。
出现以下情况时,构建会失败:
- 智能体列出了没有对应文件夹的技能;
- 有技能文件夹没有被任何智能体列出;
- 应用有技能文件夹,但没有
ai-template.yml; skills中的某个条目以app/或project/开头;- 某个条目以
platform/开头(目前没有可用的平台技能); - 技能文件夹中的某个文件不是 UTF-8 文本、是符号链接,或者既不是
SKILL.md也不是references/<file>.md文件; - 超出了上表中的某项限制;
- 某个智能体有名为
load_skill的工具。该名称在所有应用中都保留用于加载技能。
示例
这个技能告诉智能体如何查明机器为什么报告故障。此处做了删减。新应用一开始就带有三个完整的技能,位于 .ironflock/skills/ 中,您可以阅读、修改或删除它们。
.ironflock/skills/machine-diagnosis/SKILL.md:
---
name: machine-diagnosis
description: >-
How to find out why a machine is TOO_HOT or shows NO_READING, or what is
wrong with a machine a user asks about: which rows to read, when to read the
machine now with current_reading, and what to tell the user. Load it before
you answer such a question.
---
# Diagnosing a machine
A user asked why a machine is too hot, why it has no reading, or what is wrong
with it. Find the cause in the app's tables and at the machine, then answer
with the evidence. You only read: you cannot change the limit or a machine.
## 1. Find the device and its state
Run with `execute_sql`:
```sql
SELECT DISTINCT ON (device_id) device_id, device_name, state, tsp
FROM devices
ORDER BY device_id, tsp DESC
```
`state` is `OK`, `TOO_HOT` or `NO_READING`. When the user named no machine,
take the devices whose state is not `OK`.
## 2. Check the machine now
Call `current_reading` for the device and compare its values with the newest
rows of `measurements`. When the call fails, the device is offline: say since
when.
Do not tell anyone that a machine running too hot is safe to keep running.列出该技能的智能体,位于 .ironflock/ai-template.yml 中:
machines:
main: true
tool_description: |
Delegate to this agent when the user asks about the state of a machine.
system_prompt: |
You answer questions about the machines this app watches. You only read.
Never tell anyone that a machine running too hot is safe to keep running.
When a user asks why a machine is too hot or has no reading, load the
skill app/machine-diagnosis and follow it.
data_access: true
skills: [machine-diagnosis]
tools:
current_reading:
description: Reads the machine at one device now.
topic: current_readingsystem_prompt 中以 “When a user asks” 开头的那句话,把该技能称为 app/machine-diagnosis。安全规则保留在 system_prompt 中,因为没有加载该技能的智能体也必须遵守它。
无需发布即可试用技能
试用智能体或技能不需要发布版本。云端 IDE 提供了一个开发聊天,运行的是您自己的工作副本。
在云端 IDE 侧面板的 AI 智能体部分有两个操作:
- 打开开发聊天会应用您的工作副本,并打开一个使用它的聊天。
- 更新 AI 智能体会应用对
ai-template.yml和技能所做的后续修改。
开发聊天:
- 运行您的应用工作副本,使用项目的开发数据后端;
- 是项目的普通助手,其中本应用的智能体、工具和技能取自您的工作副本;
- 是唯一能获得这些内容的聊天。其他任何人、其他任何聊天都不会获得您的工作副本。
正在运行的开发聊天会从下一条消息起使用您的修改,因此您可以修改技能,点击更新 AI 智能体,然后在同一个聊天中再次提问。
如果模板或技能无效,会显示与发布构建相同的消息,并继续使用之前的版本。
开发聊天需要所选设备所在项目中有该应用的开发数据后端。
用户在哪里看到技能
在 Studio 中,应用的 AI 插件标签页会列出每个智能体及其技能,并显示每个技能的名称和描述。技能的正文不会在那里显示。
旧版安装
尚未更新的一体机仍会安装并运行该应用。它的智能体不使用技能也能工作,并在任务需要技能时告知用户。一体机更新后,技能会在应用的下一次同步时到达。
编写好的技能
- 描述要说明技能的用途以及何时加载。在智能体加载技能之前,它看到的只有描述。请使用用户和您的数据中出现的词,例如状态值、症状和任务,并在结尾写明何时加载该技能:“在回答机器为什么 TOO_HOT 之前加载它。”像“关于机器的信息”这样的描述,永远不会在合适的时机被加载。
- 让指令自成一体。智能体是在任务进行中、用户等待的时候读取它们的。请准确写出应用中的表、列和工具的名称,而不要依赖
system_prompt。 - 按应遵循的顺序,用祈使句写出步骤。说明何时停止,以及要告诉用户什么。
- 写明不能做什么。