How to Create an Agent Skill Inside a Plugin

Learn how to create an agent Skill inside an Agent Plugin: write a SKILL.md, add scripts and references, test it in your harness, and measure how it performs.

This guide shows you how to create an agent Skill inside a plugin - a SKILL.md an AI agent can load and run as one capability of the installed product. If you have not defined the plugin yet, start with How to Build an Agent Plugin for Any Harness.

What you need

An agent harness that supports Skills (e.g. Claude Cowork or Claude Code).
A text editor.
A plugin name and version that this Skill belongs to.
A clear, single job for the Skill to do. Narrow beats broad.

Step 1 — Create the folder and SKILL.md

A Skill is a directory with a SKILL.md at its root, usually under the plugin's skills/ directory:

my-plugin/
└── skills/
    └── my-skill/
        └── SKILL.md

Step 2 — Write the frontmatter

The frontmatter is what the agent reads to decide when to use the Skill. Write the description in the third person and include the phrases a user would actually say.

---
name: invoice-reconciler
description: >
  Use this skill when the user asks to "reconcile invoices",
  "match payments to invoices", or "find unmatched payments".
  Reconciles a list of payments against open invoices and reports
  exceptions.
---

A precise description is the single biggest factor in whether your Skill triggers at the right time.

Step 3 — Write the body as instructions

The body is read only when the Skill triggers. Write it as direct instructions to the agent, not documentation for a human:

## Steps
1. Load the payments file and the open-invoices file.
2. Match each payment to an invoice by reference and amount.
3. List unmatched payments and partially matched invoices.
4. Produce a summary table; never modify the source files.

Keep the body focused. Move long detail into reference files (next step).

Step 4 — Add scripts and references (optional)

Scripts (scripts/): use for deterministic steps you don't want the model to improvise — parsing, math, API calls.
References (references/): detailed docs the agent loads only when needed. This progressive disclosure keeps the main SKILL.md short.

my-skill/
├── SKILL.md
├── scripts/match.py
└── references/edge-cases.md

Step 5 — Test it in your harness

Install the Skill, then phrase a request the way a real user would. Confirm:

It triggers on the right requests (and not the wrong ones).
It follows the steps and produces the expected output.
It fails gracefully when inputs are missing.

Refine the description until triggering is reliable — this is where most iteration happens.

Step 6 — Measure how it performs

A Skill is software inside a plugin, so treat both layers like software: track plugin installs, Skill invocations, errors, latency, and how each new version compares to the last. Publish your plugin with the Telvine CLI and you get install, invocation, error, and feedback events out of the box - no user content collected.

Common mistakes

Vague descriptions → the Skill never triggers, or triggers everywhere.
A body that's too long → move detail into references.
Doing deterministic work in prose → move it into a script.
Shipping a loose Skill with no plugin identity → you can't tell which installed product it belongs to.
Shipping without measuring → you can't tell if a change helped.

Frequently asked questions

How long should a SKILL.md be? The body should be short — aim for under ~1,500 words. Push detail into reference files.

How do I make my Skill trigger reliably? Iterate on the description. Include the exact phrases users say, in the third person.