Creating Custom AI Skills

What Are Skills

Skills are reusable, filesystem-based resources that provide the LLM with domain-specific expertise (workflows, context, and best practices that transform general-purpose agents into specialists). Unlike prompts (conversation-level instructions for one-off tasks), Skills load on-demand and eliminate the need to repeatedly provide the same guidance across multiple conversations.

Skills follow the Anthropic skills specification that defines a standard format. This specification ensures that skills are portable, well-structured, and easy to keep.

All chat modes available in AI Positron have access to look up and load all skills specified in the AI Positron preferences.

Skill File Structure

For each skill, a separate folder must be created. In the folder, create a SKILL.md file that follows the Anthropic skills specification format. The file has a YAML front matter block with metadata specifying the skill name and description, followed by a description of the skills purpose and behavior. The SKILL.md can also reference other files placed in the same skill folder that should be used by the LLM (only when working with the AI Positron Desktop and Eclipse Plugin distributions).

A minimal skill file looks like this:

---
name: atlassian-jira-retrieve-note-for-documentation
description: Retrieve the note for documentation from an Atlassian JIRA issue.
---

# Atlassian Jira Retrieve Note For Documentation

When the user asks you to write documentation based on an Atlassian JIRA issue
use this skill to retrieve documentation notes from a particular issue. Call the Model Context 
Protocol tool "retrieve_jira_issue_field" having as parameter the issue ID and the 
field name "note_for_documentation" to retrieve the note for documentation and use it further.

Distributing Skills

When installed in Oxygen XML 27.1 or newer, plugins or frameworks can contain a folder named ai-positron-actions which can contain skill subfolders from which skills are automatically loaded by the AI Positron add-on.

When working in an Oxygen Content Fusion project, AI Positron also loads skills from an ai-positron-actions folder located either in the project root or in .contentfusion/ai-positron-actions. Updates to these skills are applied when you start a new chat.