Skip to Content

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_promptPut in a skill
The agent’s roleKnowledge that only some tasks need
Rules that always applyLong procedures, such as a diagnosis or a commissioning check
Safety-relevant rules: what the agent must never do, or must confirm firstDomain 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.md is required. It starts with YAML frontmatter, followed by the instructions in Markdown.
  • .ironflock/skills/<name>/references/<file>.md is 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.md says 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. ---
FieldDescription
nameMust be equal to the folder name.
descriptionPlain 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

WhatLimit
Skill nameLowercase letters and digits, joined by single hyphens; at most 64 characters
DescriptionAt most 500 characters
Instructions (SKILL.md)At most 20,000 characters
One reference fileAt most 40,000 characters
Reference files per skillAt most 20
Skills per appAt most 20
All skill files of an app togetherAt most 2 MiB
Skills one agent listsAt 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 skills starts with app/ or project/;
  • 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.md or a references/<file>.md file;
  • 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_reading

The 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.yml and 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

Last updated on