Why your agent skill never appears in the list

Confirm it is absent before you change a word

Loading and selection fail the same way from the prompt side: you ask, and nothing happens. They share no fixes. Ask the agent to list the skills it has, or open the host's own skills view, and read for your name. Absent means the causes below. Present and idle means the selector saw your description and preferred another one, which is a different problem with a different guide: why a skill never fires.

This is thirty seconds of work and it decides which half of the advice on the internet applies to you. Most of a lost morning goes into tuning a description that was never read.

Four things that keep a file out of the list

1. 1

   The path is one level off.

   A skill is a folder holding a file, not a file. skills/client-brief/SKILL.md loads. skills/client-brief.md and skills/writing/client-brief/SKILL.md do not, because the loader looks one level down and stops. Nothing warns you about either. The list is simply shorter than the folder, which is easy to miss when the folder has nine skills in it.

2. 2

   The filename is not SKILL.md.

   skill.md, Skill.md and SKILL.markdown are all misses. The nasty version is case: on macOS and Windows the filesystem ignores it, so skill.md works on the machine you wrote it on and vanishes the moment the folder is cloned onto Linux. That is the copy your teammate and your CI get, so the bug arrives as a report that it works for you.

3. 3

   The opening block is not read as frontmatter.

   The three hyphens have to be the first thing in the file. A title line, a licence comment or one blank line above them is enough to hide the whole block. Inside it, the two breakers are a colon in an unquoted value (description: Use for X: the short version parses as a nested key and errors) and tabs used for indentation, which YAML rejects outright. A block that fails to parse takes the skill down with it.

4. 4

   The session started before the file did.

   Hosts read the skill folder once, at session start, and hold that list for the session. Save the file, then open a new session. The same lag applies to edits: a description you fixed five minutes ago is not the one the running session is matching against.

What a file that loads looks like

skills/
  client-brief/
    SKILL.md

---
name: client-brief
description: Turns raw discovery notes into a structured client brief.
  Use when the user pastes meeting notes, a call transcript or a
  requirements dump and asks for a brief, a summary for the account
  team, or a scope outline. Not for writing the proposal itself.
---

# Client brief

...

name is a slug: lowercase letters, digits and single hyphens. client_brief, Client-Brief and client brief are all outside the convention, and hosts differ in how forgiving they are, so it is not worth finding out which one bends. Match the folder name while you are there. A file whose name field disagrees with its folder is legal and confusing, and it shows up later as the wrong entry in the list.

The other fields are optional, and the ones worth knowing are covered field by field in the frontmatter reference.

Loading is the low bar

A listed skill still has to beat every other description in the set on the prompts you actually type. That is a separate piece of writing, and there is a guide for it: writing a description that gets picked. Once it is written, prove it with prompts rather than by reading it back, which is what testing a skill covers.

If you would rather start from files that already load and already fire, every skill in the Agency Owner pack ships in the layout above with the eval cases it is measured against.