앱 스킬
앱 스킬은 앱의 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에 기대지 말고 앱의 테이블, 컬럼, 도구를 정확한 이름으로 적으세요. - 따라야 할 순서대로 명령형 단계로 씁니다. 언제 멈출지, 사용자에게 무엇을 알릴지도 적습니다.
- 하지 말아야 할 일을 적습니다.
다음 단계
- AI 에이전트 및 도구 —
ai-template.yml레퍼런스 - 릴리스 및 App Store — 앱 게시