App Skills
An app skill is a set of instructions that one of your app’s AI agents loads on demand, instead of carrying them in its system_prompt on every turn.
The agent first sees only each skill’s name and description. When a task needs a skill, the agent loads its instructions. A skill costs nothing until the agent loads it, so you can give the agent long procedures and reference material without making every conversation heavier.
App skills are instructions for your app’s own agents. They are not the skill that Build with Claude Code installs for your coding agent.
Skill or System Prompt?
The system_prompt is read on every turn. A skill is read only when the agent decides to load it.
Put in the system_prompt | Put in a skill |
|---|---|
| The agent’s role | Knowledge that only some tasks need |
| Rules that always apply | Long procedures, such as a diagnosis or a commissioning check |
| Safety-relevant rules: what the agent must never do, or must confirm first | Domain reference, such as fault codes or a machine’s parameters |
| Short facts |
An agent that never loads a skill must still keep every safety-relevant rule, so those always stay in the system_prompt.
Skill Folder Format
Skills live in your app’s repository, next to the other files in .ironflock/:
.ironflock/
├── ai-template.yml
└── skills/
└── machine-diagnosis/
├── SKILL.md
└── references/
└── codes-press.md.ironflock/skills/<name>/SKILL.mdis required. It starts with YAML frontmatter, followed by the instructions in Markdown..ironflock/skills/<name>/references/<file>.mdis optional. Use reference files for material that only some tasks need. The agent loads each one only when it needs that file, so each reference file must make sense on its own.SKILL.mdsays which file to read and when.- Nothing else may be in the skills folder: no scripts, no images, no symbolic links. All files are UTF-8 text.
The frontmatter has two fields:
---
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.
---| Field | Description |
|---|---|
name | Must be equal to the folder name. |
description | Plain text. This is all the agent sees until it loads the skill. |
Listing a Skill on an Agent
A skill does nothing until an agent lists it. In .ironflock/ai-template.yml, add the skills key to the agent and name each skill by its folder name:
machines:
main: true
skills: [machine-diagnosis]Write only the folder name. Never start an entry with app/ or project/.
The agent is offered the skill as app/<name>, here app/machine-diagnosis. Text in your system_prompt or tool_description that mentions a skill uses that form.
Every skill folder must be listed by at least one agent, and each agent lists a skill once.
Platform Skills
An entry of the form platform/<name> is reserved for skills that the platform provides to apps. No platform skill is available yet, so such an entry fails the release build today.
Limits
| What | Limit |
|---|---|
| Skill name | Lowercase letters and digits, joined by single hyphens; at most 64 characters |
| Description | At most 500 characters |
Instructions (SKILL.md) | At most 20,000 characters |
| One reference file | At most 40,000 characters |
| Reference files per skill | At most 20 |
| Skills per app | At most 20 |
| All skill files of an app together | At most 2 MiB |
| Skills one agent lists | At most 20 |
What the Release Build Checks
When you create a release, the build checks the skills together with ai-template.yml. If a check fails, the release is not built, and the first problem found is shown. Fix it and create the release again.
The build fails when:
- an agent lists a skill that has no folder;
- a skill folder is listed by no agent;
- the app has a skills folder but no
ai-template.yml; - an entry in
skillsstarts withapp/orproject/; - an entry starts with
platform/(no platform skill is available yet); - a file in the skills folder is not UTF-8 text, is a symbolic link, or is not
SKILL.mdor areferences/<file>.mdfile; - a limit in the table above is exceeded;
- an agent has a tool named
load_skill. The name is reserved for loading skills, in every app.
Example
This skill tells the agent how to find out why a machine reports a fault. It is shortened here. A new app starts with three complete skills in .ironflock/skills/ that you can read, change or remove.
.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.The agent that lists it, in .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_readingThe sentence in the system_prompt that starts with “When a user asks” refers to the skill as app/machine-diagnosis. The safety rule stays in the system_prompt, because an agent that does not load the skill must still keep it.
Try Skills Without a Release
You do not need a release to try an agent or a skill. The Cloud IDE has a development chat that runs your own working copy.
In the Cloud IDE’s side panel, the AI agents section has two actions:
- Open development chat applies your working copy and opens a chat that uses it.
- Update AI agents applies further edits to
ai-template.ymland to the skills.
The development chat:
- runs your working copy of the app, with the project’s development data backend;
- is the project’s normal assistant, with this app’s agents, tools and skills taken from your working copy;
- is the only chat that gets them. Nobody else, and no other chat, is offered your working copy.
A running development chat uses your edits from its next message on, so you can change a skill, click Update AI agents and ask again in the same chat.
If the template or a skill is invalid, the same message as for a release build is shown, and the previous version stays in use.
The development chat needs the app’s development data backend in the project of the selected device.
Where Users See Skills
In the Studio, the app’s AI plugin tab lists each agent with its skills, showing the name and the description of each skill. The skill text is never shown there.
Older Installations
An appliance that has not been updated yet installs the app and runs it. Its agents work without the skills, and tell the user so when a task needs one. After the appliance is updated, the skills arrive with the next synchronization of the app.
Writing Good Skills
- The description says what the skill is for and when to load it. Until the agent loads the skill, the description is all it sees. Use the words that users and your data use, such as state values, symptoms and tasks, and end with when to load the skill: “Load it before you answer why a machine is TOO_HOT.” A description like “Information about machines” is never loaded at the right moment.
- Make the instructions self-contained. The agent reads them in the middle of a task, with a user waiting. Name the tables, columns and tools of your app exactly instead of relying on the
system_prompt. - Write imperative steps in the order to follow them. Say when to stop and what to tell the user.
- Say what not to do.
Next Steps
- AI Agents & Tools — The
ai-template.ymlreference - Releases & the App Store — Publish your app