Write skill descriptions in third person, with non-triggers

You wrote a skill. It never fires, or it fires constantly. Either way you are about to start rewriting the body, and the body is not the problem — before a skill is invoked, the body is not in context at all. Only the description (plus when_to_use, appended to it) is loaded, on every turn, for every skill you have installed. That one field is doing retrieval work, not documentation work.

Two habits have spread through the community skill repos on top of that. One is worth adopting; one is worth knowing about and not spending much on.

What the docs actually pin down

These are stated, not inferred:

So: the budget, the ordering, and the failure modes are documented. Voice is not. The word "third-person" does not appear anywhere in the docs.

The habit that earns its keep: write the six prompts first

Before you write a line of the skill, write three prompts that should trigger it and three near-misses that should not. Then write the description so it separates those six.

should trigger
  "add a column to the orders table"
  "we need a migration for the new users.deleted_at field"
  "roll back the last schema change"

should NOT trigger
  "add a field to the Order model"        <- ORM work, not a migration
  "the orders query is slow"              <- performance, not schema
  "write a test for OrderRepository"      <- neither

This is not folklore. The official skill-creator plugin has a mode built on exactly this shape: per the docs, its description tuning "generates should-trigger and should-not-trigger prompts, measures the hit rate, and proposes description edits when the skill activates on the wrong requests." Writing the six by hand is the same loop, run in your head, before you have anything to tune.

The near-misses are the valuable half. They are what turns "make the description more specific" from an instruction into an action — you now know specific against what.

The habit to know about, not to bank on: third person and non-triggers

The convention, from mgechev/skills-best-practices, is to write the description entirely in third person — "This skill should be used when the user is writing a Postgres migration" rather than "Use this when you are writing a migration" — and to spell out what the skill does not cover, so the negative cases sit in context alongside the positive ones.

What is genuinely unverified here: nobody has published an A/B on voice. The claim that mixed point of view "measurably degrades discovery" is an assertion with no measurement behind it, and the docs' own examples are evidence against it. The non-trigger half is on firmer ground — it is the same idea skill-creator implements, just written down instead of measured.

What would settle it: run one skill's description through skill-creator's description tuning twice, once in mixed voice and once rewritten in strict third person, with the same six prompts, and compare hit rates. That is a real experiment anyone can run in an afternoon.

A description shaped by the six prompts

---
name: pg-migrations
description: Writes and reviews raw Postgres migration files for this repo,
  including up/down pairs, index-concurrently rules, and backfill batching.
  Use when the user mentions a migration, a schema change, altering or adding
  a column, or rolling back a migration. Does not apply to ORM model edits,
  query performance work, or repository-layer tests.
---

Key use case first, so truncation at 1,536 characters eats the exclusions rather than the trigger. Literal words a user would type — "migration", "schema change", "alter a column", "roll back" — because that is what the docs say matching keys off. Exclusions last, in a single sentence, because they are the cheapest part to lose.

Where the budget actually goes

Every installed skill's description is in context on every turn whether or not it ever fires. A long third-person rewrite of forty skills is a real cost against a listing budget of roughly 1% of the context window — and when that budget overflows, Claude Code drops descriptions starting with the skills you invoke least. Spend the characters on trigger phrases and one exclusion sentence. If the listing is already crowded, skillOverrides can demote a low-priority skill to name-only. /skill-doctor reports what each skill costs and how often it gets used, which turns "the listing feels crowded" into a ranked list of candidates. It is a recent addition, and it "requires Claude Code v2.1.252 or later and isn't available in sessions that skip feature-flag fetching" — that second clause bites at any version, so a session with feature-flag fetching turned off has no report to read.