Download
‹ All Kalon docs

Kalon

Writing a skill

The skill file format, where skills live, how Kalon decides to load one, and a worked example.

The file

A skill is one Markdown file named <name>.SKILL.md. It starts with a front matter block between two --- lines, one key: value per line, followed by the instructions.

---
name: release-notes
description: Turn the commits since the last tag into release notes grouped by feature, fix and change.
icon: doc.text
display_name: Release notes
try_prompt: Write release notes for the changes since the last tag.
---
Run git_status and git_diff. Group what changed into Features, Fixes and Changes.
Write one plain sentence per item, in the past tense, with no commit hashes.
End with a one-line summary suitable for a changelog heading.
KeyPurpose
nameThe id the agent loads it by. Defaults to the file name.
descriptionWhat the skill does and when to use it. This is the only part the model sees before loading the skill, so it decides when the skill is used.
iconAn SF Symbols name shown in the Skills list.
display_nameThe title shown in the Skills list.
try_promptText placed in the composer by Try in chat.

Every key is optional, but a skill without a clear description is rarely chosen. Everything after the front matter is the body: plain instructions for the model.

To give a skill an image instead of a symbol, place <name>.icon.png, .jpg, .jpeg or .svg next to the file, or use Upload in the editor.

Where skills live

On the Mac, skills are in ~/Library/Application Support/Kalon/skills. Kalon reads every .md file at the top level of that folder each time it builds a prompt, so a file you add or edit is picked up on the next message. Subfolders are not read.

On iPhone, skills are kept in Kalon's own storage. Create and edit them in Settings › Tools › Skills.

Creating a skill in the app

  1. Open Settings › Tools › Skills and choose New skill.
  2. Enter a Name. The editor shows the id it will load as.
  3. Write the Description: what it does and when to use it.
  4. Choose an Icon, or upload an image.
  5. Write the Instructions, then save.

New skills are switched on. Use the switch on a skill's row to take it out of the model's list without deleting it.

How a skill is used

  1. The model sees a short index: each enabled skill's name and description.
  2. When a request matches, the agent calls the skill tool with that name.
  3. Kalon returns the body, and the agent follows it for the rest of the task.

Try in chat skips the matching step: it attaches the skill to your next message and tells the model to load it. Nothing is sent until you press send.

Skill bodies are capped when loaded: 12,000 characters on the Mac and 2,500 on iPhone.

Writing good skills

  • Write the description for the moment of choice. Say what the skill produces and the words a person would use when they need it.
  • Name the tools the skill should use, such as doc_draft or git_diff. See Chat and agent mode for the list.
  • Keep steps short and concrete. The body arrives in the middle of a conversation and uses context.
  • For iPhone, keep the whole body under 2,500 characters. The phone's agent has only remember, search_memory and skill, so phone skills should be about writing and reasoning rather than files.
  • A skill can only ask. What the agent may actually do is set by the tools available and the approvals you give.

Removing a skill

Open the skill and choose Uninstall. This deletes its .SKILL.md file from the Mac and cannot be undone. On iPhone, swipe the row and tap Delete.