Skill Basics

What Is a Skill?

A Skill is a structured AI instruction set designed to solve a specific problem. It's stored as a SKILL.md file containing your methodology, workflow logic, and prompts. Once installed, users trigger it via a slash command or by describing their need — the Skill drives the AI to complete the task following the logic you designed.

Skill File Structure

A Skill is a directory:

~/.clacky/skills/my-skill/
├── SKILL.md              # Required: core instruction file
├── scripts/              # Optional: scripts (Ruby preferred)
├── references/           # Optional: reference docs (loaded on demand)
└── assets/               # Optional: templates, icons, static files

SKILL.md Format

Every SKILL.md consists of two parts: YAML frontmatter (metadata) + Markdown body (instructions).

---
name: my-skill
description: 'Solves X problem. Trigger when user mentions X, Y, or Z.'
disable-model-invocation: false
user-invocable: true
---

# My Skill

Instructions for the AI go here...

Frontmatter Fields

Key point: description is the trigger mechanism. The AI reads it to decide whether to invoke the Skill. Be specific — list keywords and scenarios.

Writing the description

description controls when the Skill gets triggered. Two rules:

1. State clearly what the Skill does
2. List trigger scenarios and keywords — err toward over-triggering, not under-triggering

# ❌ Too vague — will miss triggers
description: 'Helps with writing'

# ✅ Specific and accurate
description: 'Helps write and polish professional emails and business documents.
  Use when user wants to draft an email, revise a report, improve tone,
  or needs help with any writing task — even if they just say "help me write".'

Wrap the description value in single quotes to avoid YAML parse errors from colons or special characters.

Three-Level Loading

Skills use progressive loading to keep context usage efficient:

1. Metadata (name + description) — always in context, ~100 words
2. SKILL.md body — loaded when the Skill triggers; keep under 500 lines
3. Bundled resources (references/, scripts/) — loaded on demand, no size limit

When your SKILL.md approaches 500 lines, extract large reference content into references/ files and add pointers in the body for when to read them.

Skill Storage Locations

Clacky loads Skills from three locations, in priority order:

When you publish to OpenClacky, users install your Skills via your branded install link. Skills are distributed encrypted to ~/.clacky/skills/ on the user's machine.

What Makes a Great Skill

1. Focused: Solves one specific problem, not a catch-all assistant
2. Self-contained: Runs without requiring extra context from the user
3. Expert-level: Encodes insights or methodology only you possess
4. Easy to trigger: The description is specific enough that the AI reliably knows when to invoke it

Skill vs. Plain Prompts

Next: Build your first Skill with /skill-creator →