Writing skills & prompts

Markdown workflows the agent discovers and loads on demand — no code required.

Skills vs. prompt templates

Both are markdown, and neither needs any code:

• A prompt template is a reusable message — a .md file in a prompts/ directory that you fire manually as a slash command.
• A skill is a discoverable capability: a folder with a SKILL.md whose description is loaded into the system prompt at startup. When a task matches, the agent reads the full file on its own (or you force it with /skill:name). Skills can bundle helper scripts, reference docs and assets alongside the markdown.

Rule of thumb: if you’d trigger it yourself, make a prompt template; if the agent should know when to use it, make a skill.

A minimal skill

my-search/
├── SKILL.md
└── search.js

---
name: my-search
description: Searches web content using an API. Use when research is needed.
---

# My Search

## Usage
./search.js "query"

Frontmatter rules:

• name — required. Max 64 chars, lowercase a-z, 0-9 and hyphens.
• description — required. Max 1024 chars. This is what the model sees at startup, so say what it does and when to use it — the trigger conditions matter more than the mechanics.
• Optional: license, compatibility (environment requirements), metadata (arbitrary key-values), allowed-tools (experimental pre-approval), and disable-model-invocation: true if the skill should only ever load via an explicit /skill:name.

Where they live

Discovery is recursive — any folder containing a SKILL.md becomes a skill.

Writing skills that actually trigger

The description is a retrieval query, not documentation. Compare:

❌ “A skill for database work.”

✅ “Generates and reviews SQL migrations for Postgres. Use when the user asks to add, change or drop tables/columns, or mentions migration files.”

Name concrete verbs, file types and phrases users actually say. Keep the body procedural: numbered steps, exact commands, expected outputs, and what to do when a step fails.

Ship it

Skills travel in packages like everything else — a skills/ directory is auto-discovered when your package installs. See Publishing packages, and check bigpowers (73 skills) for a large-scale example of the format.