Skills

​

What are skills?

A skill is a reusable set of instructions, with optional files, that tells Realm how to do one kind of task. For example, a skill can describe how to write a short executive summary, how to format a security questionnaire answer, or which terms to use when writing in German. You write a skill once and reuse it everywhere: attach it to agents, pick it in chat, or start a new document from it. Agents follow their skills wherever they run, in web chat, Slack, the REST API, MCP clients, and automations. Each skill has a Name and a Description. Realm shows the agent the name and description of every skill it can use. When a request matches a description, the agent reads the skill’s full instructions before it acts. A clear description is what makes a skill get used at the right time.

​

How to create a skill

On the Skills page, click Create. Choose one of:

• New skill: opens an empty skill in the editor. Write it yourself, or describe what you want in the chat next to the editor and Realm writes it for you.
• Import a skill: upload a skill you already have. The file can be a .zip or .skill bundle of up to 50 MB, or a single .md or .txt file. Realm reads the name and description from the file, and you can change them before you click Upload.

A new skill starts as a draft. An imported skill is published right away, so it is ready to use as soon as the upload finishes. A bundle must hold one SKILL.md file, either at the top level or inside a single folder. It can hold up to 200 files, and each file can be up to 25 MB. A single .md or .txt file becomes the skill’s SKILL.md.

​

Writing a skill

Open a skill on the Skills page to edit it. The editor shows the skill’s files on the left, the open file in the middle, and a chat on the right. Ask the chat to edit the skill, for example “Add an example of a good summary” or “Make the instructions shorter”.

​

SKILL.md

Every skill has one SKILL.md file. Click it to edit:

• Name: how the skill shows everywhere in Realm. Each published skill in your organization needs its own name.
• Description: what the skill does and when to use it, up to 1,024 characters. Realm decides when to use the skill from this text, so name the situations it fits. For example: “Use when writing an executive summary of an RFP response for a customer’s leadership team.”
• Instructions: what Realm should know or do when it uses the skill. Write them the way you would brief a colleague: the goal, the steps, the format, and what to avoid.

Click the icon next to the skill’s name to pick an emoji for it.

​

Other files

A skill can hold more files next to SKILL.md, such as reference material, worked examples, or scripts. Use New file, New folder, and Upload file in the file list, and refer to the files by path in the instructions. Realm reads a file when the instructions point it there. Keep SKILL.md focused and move long reference material into separate files. SKILL.md can be up to 120,000 characters. Put worked examples of finished documents in an examples folder. Files there must be .docx, .pdf, .md, or .txt. When someone starts a document from the skill, the draft follows these examples.

​

Properties

Click Add property above the instructions to give the skill a template or a translation language.

• Template: upload a Word (.docx) file, pick one from the knowledge base, or choose a Word file already in the skill. Realm names it on the template: line of SKILL.md, and new documents started from the skill start from it. Any Word file in the skill can be the template: set template: to its path, such as template: layouts/brief.docx. A file is the template only when that line names it, whatever its name. Publishing checks that the template opens as a Word document and refuses a damaged or password-protected file.
• Translation language: the language the skill writes in, on the language: line. Each language belongs to one published skill, so a language that another skill already has is shown but can’t be chosen. See Translation languages and glossaries.

​

Publishing

Changes save to a draft as you type. The label next to the skill’s name shows Saving…, Draft, or Couldn’t save. Click Retry save if a save fails. Agents keep using the published version until you publish the draft. Click Publish to make the draft the live version. Agents that use the skill get the new version from their next run. While something keeps the skill from being published, Publish is unavailable. A warning shows at the field, property, or file to fix, and hovering over Publish lists every warning. Common causes:

• The description is missing or longer than 1,024 characters.
• Another published skill already has the same name.
• The SKILL.md header is not valid, for example after a manual edit of the lines between the --- markers.
• The template is missing, damaged, or not a Word file.
• A file in examples is not a .docx, .pdf, .md, or .txt file.
• Another published skill already uses the translation language.

To throw away your unpublished changes, click Discard. The skill goes back to its published version.

​

Using skills

​

Attach a skill to an agent

In the agent editor, open the Skills card and click Add skill. The dialog lists the published skills you can use that are not attached yet. An attached skill is available to the agent every time it runs. From the menu on an attached skill you can:

• Open skill in the editor
• Turn off the skill for this agent without removing it, and Turn on to bring it back
• Remove skill from the agent

A skill that was unpublished, deleted, or is no longer shared with you shows as Unavailable. The agent runs without it. The default Realm agent has no attached skills. It can use every published skill you have access to.

​

Pick a skill in chat

Type / in the chat message box. The menu lists your published skills under Skills. Pick one to add it to your message, and Realm uses that skill for the request.

​

Start a document from a skill

On the Documents page, open the + menu next to the message box and choose Skill. The draft follows the skill’s instructions and examples. If the skill has a template, the new document starts from it, unless you pick a template yourself. See Skills and projects.

​

Built-in skills

Realm also has built-in skills for working with Word, PDF, PowerPoint, and Excel files. Realm uses them on its own when a task needs them. They do not show on the Skills page and cannot be edited.

​

Translation languages and glossaries

A skill with a translation language works as the style guide for that language. Its instructions describe how to write in the language, and its glossary lists the terms to use. Realm applies it without being attached to an agent:

• RFP answers filled in that language
• Translations in the RFP table’s working-language view
• Translated exports
• Chat requests to write or translate in that language

When the skill has a language, the file list shows a dashed glossary.csv entry. Open it to edit the terms as a table, one English term and its translation per row, with an optional note. You can paste rows copied from a spreadsheet. Realm uses the glossary only while the skill has a language. An uploaded glossary.csv can separate its columns with commas, semicolons, or tabs, and can be saved as UTF-8 or UTF-16. A header row is optional: Realm reads columns named source, target, and context (or English, the skill’s language, and notes), and otherwise reads the first column as the English term, the second as its translation, and the third as a note. Rows missing a term are skipped. If Realm finds no terms in the file, the editor shows it as plain text so you can fix it.

​

Managing skills

The Skills page lists every skill you can see. Use the search field to find a skill by name, and filter the list:

• Status: Published or Drafts
• Creator: Created by me or Shared with me

Sort by Newest, Oldest, Name A–Z, or Name Z–A, and switch between grid and list views. Hover over a skill to act on it:

• Publish skill publishes a draft.
• Unpublish skill moves a published skill back to its owner’s drafts. Agents that use it lose access until it is published again.
• Delete draft deletes a skill that was never published.

To delete a published skill, open it and choose Delete skill from the options menu next to Publish. This deletes the skill, its draft, and its published version, and cannot be undone.

​

Sharing and permissions

A new skill is private to the person who created it. Click Share in the editor to choose who can use it. Under general access, choose:

• Restricted: only the people you add can use the skill.
• Your organization’s name: anyone in your organization can use the skill.

You can also add people one at a time. Only the skill’s owner can change who it is shared with. The skill’s owner and organization admins can edit, publish, unpublish, and delete it. Agents and people can use only published skills, and only the ones shared with them.

​

Troubleshooting

If an agent does not use a skill when you expect it to:

• Confirm the skill is published, not a draft.
• Confirm the skill is attached to the agent and turned on, or that you are using the default Realm agent.
• Check that the skill is shared with the person running the agent. A trigger runs with its owner’s access.
• Make the description name the situations the skill is for. Realm decides from the description whether a skill fits the request.
• To make sure a skill is used for one request, pick it in chat with /.