Creating Custom Skills for Your AI Agent: A Complete Guide

The most powerful customisation in Skales is the custom skill system. A skill is a reusable AI workflow with a defined structure, named parameters, and a consistent output format. Skills transform Skales from a general-purpose AI assistant into a tool specifically shaped around your exact needs. This guide covers everything from basic skill creation to advanced patterns.

What a Skill Is (And Is Not)

A skill is not a plugin, a script, or a trained model. It is a structured prompt template with named parameters that can be invoked by name from the chat interface. When you invoke a skill, Skales fills in your parameters, assembles the complete prompt, and sends it to the AI. The skill guarantees consistent structure — the same prompt format, the same output template, every time — while letting the content vary based on your inputs.

Skills are stored as .skill files in ~/.skales-data/skills/. They are human-readable text files you can edit directly, export, import, and share with other Skales users.

Basic Skill Structure

Every skill file has the same structure:

name: meeting-notes
description: Format raw meeting notes into a structured summary
version: 1.0
parameters:
  - name: attendees
    description: Comma-separated list of people in the meeting
    required: true
  - name: raw_notes
    description: Your unformatted notes from the meeting
    required: true
  - name: next_meeting
    description: Date of the next meeting (optional)
    required: false
    default: "Not scheduled"
template: |
  You are formatting meeting notes into a structured summary.
  
  Attendees: {{attendees}}
  Next meeting: {{next_meeting}}
  
  Raw notes:
  {{raw_notes}}
  
  Format this into:
  ## Summary
  [2-3 sentence overview of what was discussed]
  
  ## Decisions Made
  [Bulleted list of decisions]
  
  ## Action Items
  [Bulleted list: - Owner: Action, Due: Date]
  
  ## Next Meeting Agenda (if applicable)
  [Bulleted list of topics]
output_format: markdown

The description field is important: it is how Skales' autocomplete suggests this skill and how the AI recognises it when you type /meeting in the chat.

Invoking Skills

Three ways to invoke a skill. Type /meeting-notes in the chat — Skales will prompt you for each parameter in sequence. Use the Skills panel (the bookmark icon in the sidebar) to browse and launch skills with a form interface. Or describe what you want and Skales will suggest the matching skill: "format my meeting notes" → "Did you mean the meeting-notes skill?".

Creating Skills: Three Methods

Method 1: Manually in Settings → Skills. Click "New Skill," fill in the name, description, parameters, and template. Good for simple skills where you know exactly what you want.

Method 2: Ask Skales to create one. Tell Skales: "Create a skill for writing weekly status reports. It should have parameters for completed tasks, current blockers, and next week's goals. Output should be in the format our team uses: a summary paragraph followed by three sections." Skales generates the skill file and asks if you want to save it. You can review and edit the generated file before saving.

Method 3: Learn from observation. If you find yourself doing the same type of task repeatedly — always formatting emails a certain way, always structuring research notes in the same template — tell Skales: "I want to turn what I just did into a skill." It will analyse your recent interaction and propose a skill definition.

Advanced Patterns

Conditional logic in templates. You can use simple conditionals in templates: {{#if urgent}}Please treat this as urgent and flag any time-sensitive items.{{/if}}

Multi-step skills. Some skills chain multiple AI calls. A "research brief" skill might first generate an outline, then fill each section in a second call. Define these as steps in the skill file with the output of one step feeding into the next.

Skills with tool calls. Advanced skills can trigger tool execution — a "project status" skill might read your task list, check recent emails from project stakeholders, and then synthesise a status report from both. Define required tools in the skill's requires_tools field.

Sharing skills. Export a skill as a .skill file and share it. Skales has a community skills repository on GitHub where users share their most useful templates. Learn more about automation with Skales or see all features.