Skills: teaching it how you do something

What a skill is, and is not

A skill is prose the employee reads: how your business handles a particular thing, written down once, in the level of detail you would give a new starter. It can carry supporting files, scripts and templates alongside the instructions.

It is not an integration, and it is not an automation. It does not grant access to anything and it does not run on its own. It changes how a job is done, not what a job is allowed to touch, and the approval rules still apply exactly as they did.

The shape of one

A folder with a SKILL.md at its root, and frontmatter with a name and a description. The description is not decoration: it is what the employee reads to decide whether this skill applies to the request in front of it. A bundle without one is a document, not a skill, and it is refused.

Text only, and there are limits on how many files and how large: a bundle can arrive from a repository nobody here controls, so the caps are a safety property rather than tidiness. Files that are secrets by name, such as a .env or a private key, are refused whatever they contain.

---
name: quoting-a-repeat-customer
description: How we price a repeat job, including the loyalty discount and when it does not apply.
---

## When this applies

A customer we have invoiced before is asking for a price on similar work.

## The steps

1. Look up what we charged them last time.
2. ...

Adding one

1. 1

   Write it, or find it

   Write the procedure the way you would explain it to someone on their first week. Include the exceptions, because the exceptions are the reason the procedure is not obvious.

2. 2

   Upload the folder, or point at a repository

   Upload the folder from the console, or give it a public GitHub repository as owner/repo, optionally with a branch, tag or commit and a subdirectory. Only GitHub and the skills directory that indexes it are accepted, deliberately: anything else would be a request the server makes to a host you named.

3. 3

   Check it applies when you expect

   Give the job a request the skill should catch and read the work log. If it did not use the skill, the description is usually the reason, not the instructions.

4. 4

   Version it

   Changes are versioned, so you can see what the instructions said on the day a piece of work was done. That matters more than it sounds when you are working out why something was handled the way it was.

Where skills come from

Most useful skills are ones you write, because they are about how your business specifically does something, and nobody else can write that. Skills from a public repository are worth reading before you install one: it is instructions your employee will follow, so treat it the way you would treat any other instructions arriving from outside.