Skill descriptions that fit the listing and trigger

# AGENTS.md: skills that get used

This project keeps agent skills in `.agents/skills/` (and `.claude/skills/` for Claude Code). Agents choose a skill
from its `description` alone, inside a listing with a fixed budget. A skill with a weak or cut-off description
might as well not be installed.

## Rules for every SKILL.md
- Front matter has `name` (same as the folder) and `description`. Quote any value that contains `: `.
- The description starts with what the skill does, in one sentence under 200 characters, then "Use when ..." with
  the words a user would type. Keep `description` plus `when_to_use` well under 1,536 characters; 300–600 is plenty.
- Detail, steps, examples and history go in the body or in `references/`, never in the description.
- No two skills with overlapping descriptions. Merge them, or say what makes each different.
- Skills with side effects (deploy, publish, send) use `disable-model-invocation: true` where the agent supports it.
- The most important instructions go near the top of the body: after compaction, agents may keep only the start
  of a skill they already loaded.

## Before you say a skill change is done
1. Run the `skill-listing-audit` skill's audit on the skills folders. It must report `0 error(s)`; explain any warning
   you leave.
2. Try the changed skill on three prompts that should trigger it and one that should not, each in a fresh session.
3. Report the listing total against the budgets the audit prints.

# CLAUDE.md

@AGENTS.md

## Claude Code notes

- Skills from this loadout live in `.claude/skills/`: `skill-listing-audit`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From SetupBay "Skill descriptions that fit the listing and trigger" v1.0.0 — https://setupbay.com/loadouts/skill-descriptions-that-trigger/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes

- Skills from this loadout live in `.agents/skills/`: `skill-listing-audit`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From SetupBay "Skill descriptions that fit the listing and trigger" v1.0.0 — https://setupbay.com/loadouts/skill-descriptions-that-trigger/ -->

---
name: skill-listing-audit
description: Check that every skill's description fits the agent's skill listing and says when to use it. Use when adding, writing or renaming a skill, when a skill works with /name but never fires on its own, or when an agent warns that skill descriptions were truncated.
---

# Skill listing audit

Agents never read your skills up front. They read a **listing**: each skill's name and description, squeezed into a
fixed budget. If the listing overflows, descriptions get cut or dropped, and the keywords that would have matched
the user's request go with them. A skill that only works when typed as `/name` usually has this problem.

What the agents document:
- **Claude Code**: the listing budget is 1% of the model's context window. Each entry (`description` plus
  `when_to_use`) is cut at 1,536 characters. When the listing overflows, the least-used skills lose their
  descriptions first. Raise it with `skillListingBudgetFraction` or `SLASH_COMMAND_TOOL_CHAR_BUDGET`, or set a
  low-priority skill to `"name-only"` in `skillOverrides`. `/doctor` estimates the cost; `/skill-doctor` lists
  skills that are never used.
- **Codex**: the initial list uses at most 2% of the context window, or 8,000 characters when the window is unknown.
  Descriptions are shortened first, then skills are left out with a warning. `skills.max_context_tokens` changes it
  (up to 10,000 tokens). `name` and `description` are both required.

## 1. Run the audit
```bash
python3 .agents/skills/skill-listing-audit/scripts/skill_listing.py .claude/skills .agents/skills
```
Add `--context 1000000` for a 1M-token model. Point it at a plugin's `skills/` folder to check a plugin before
publishing. It only reads files.

## 2. Fix errors first
- **No description**: write one (step 3). Do not rely on the body's first line.
- **Over 1,536 characters**: the end is cut off in Claude Code. Move detail into the body; the description is a
  trigger, not documentation.
- **Front matter not valid**: an unquoted `: ` inside a value (for example `description: Triggers: X, Y`) makes YAML
  read a nested key, and some agents then skip the skill. Quote the whole value.

## 3. Then make each description trigger
Write it in this order, in plain words a user would type:
1. **What it does**, first sentence, under 200 characters. If the listing is cut, this is what survives.
2. **"Use when ..."** with the real triggers: the task, the file types, the error message, the words people use.
3. **What it is not for**, only when a neighbouring skill is easily confused with it.

See `references/description-examples.md` for before/after pairs. Fix overlap warnings by saying what makes each skill
different, or merge the two skills.

## 4. Check it fires
Seeing a skill trigger once is not proof. For each changed skill, write three realistic prompts that should use it
and one that should not. Try each in a fresh session with the skill on, then with it off, and compare. Keep the prompts
in the skill folder (for example `evals/triggers.md`) so the next edit can be checked the same way.

## 5. Report
List each skill you changed with its old and new length, the listing total against both budgets, and the trigger
prompts you tried, with what happened.

#!/usr/bin/env python3
"""Audit SKILL.md descriptions against the limits agents apply to their skill listings.

Usage: python3 skill_listing.py [--context TOKENS] DIR [DIR ...]
  DIR is a skills folder (.claude/skills, .agents/skills, a plugin's skills/) or one skill folder.
  --context  the model's context window in tokens, for the listing-budget estimate (default 200000).

Checks each skill's front matter, then the whole listing:
  error  no description; description + when_to_use over Claude Code's 1,536-character cap (cut short);
         front matter that is not valid simple YAML (an unquoted ": " inside a value, a missing closing ---).
  warn   name differs from the folder; no "use when" style trigger; first sentence over 200 characters;
         two skills whose descriptions share most of their words (the agent can't tell them apart).
  info   listing size against Claude Code's budget (1% of the context window) and Codex's
         (2% of the context window, 8,000 characters when the window is unknown). Characters/4 is an estimate.
Exit 1 if any error, else 0. Standard library only; read-only.
"""
import os
import re
import sys

CLAUDE_ENTRY_CAP = 1536
TRIGGER = re.compile(r"\b(use (it |this )?(when|for|after|before|if|whenever)|when the user|triggers? (on|when|include)|invoke when)\b", re.I)
STOP = set("a an and are as at be by for from if in into is it its of on or the this to use used when with your you that".split())


def parse_front_matter(text):
    """Return (dict, error). Supports key: value, quoted values, and | or > block scalars."""
    if not text.startswith("---"):
        return None, "no front matter (the file must start with ---)"
    lines = text.splitlines()
    try:
        end = next(i for i in range(1, len(lines)) if lines[i].strip() == "---")
    except StopIteration:
        return None, "front matter has no closing ---"
    data, i = {}, 1
    while i < end:
        line = lines[i]
        if not line.strip() or line.lstrip().startswith("#"):
            i += 1
            continue
        m = re.match(r"^([A-Za-z0-9_-]+):(?:\s+(.*))?$", line)
        if not m:
            if line.startswith((" ", "\t")):
                i += 1
                continue
            return None, f"line {i + 1}: not a 'key: value' line"
        key, val = m.group(1), (m.group(2) or "").strip()
        if val in ("|", ">", "|-", ">-", "|+", ">+"):
            block = []
            i += 1
            while i < end and (lines[i].startswith((" ", "\t")) or not lines[i].strip()):
                block.append(lines[i].strip())
                i += 1
            data[key] = ("\n" if val.startswith("|") else " ").join(b for b in block if b).strip()
            continue
        if val[:1] in "\"'":
            q = val[0]
            if not val.endswith(q) or len(val) < 2:
                return None, f"line {i + 1}: {key} opens a {q} quote that never closes on that line"
            val = val[1:-1]
        elif ": " in val:
            return None, f"line {i + 1}: {key} contains ': ' without quotes, so YAML reads it as a nested key; quote the value"
        elif val == "":
            # nested mapping (metadata:, hooks:) - skip its indented lines
            i += 1
            while i < end and lines[i].startswith((" ", "\t")):
                i += 1
            data[key] = {}
            continue
        data[key] = val
        i += 1
    return data, None


def skill_dirs(paths):
    for p in paths:
        if os.path.isfile(os.path.join(p, "SKILL.md")):
            yield p
            continue
        if not os.path.isdir(p):
            print(f"skip {p}: not a folder", file=sys.stderr)
            continue
        for name in sorted(os.listdir(p)):
            d = os.path.join(p, name)
            if os.path.isfile(os.path.join(d, "SKILL.md")):
                yield d


def words(s):
    return {w for w in re.findall(r"[a-z0-9][a-z0-9.+#-]*", s.lower()) if w not in STOP and len(w) > 2}


def main(argv):
    context = 200000
    if "--context" in argv:
        i = argv.index("--context")
        context = int(argv[i + 1])
        del argv[i:i + 2]
    if not argv or any(a.startswith("-") for a in argv):
        print(__doc__.strip(), file=sys.stderr)
        return 2
    errors = warns = 0
    listing, seen = [], []
    for d in skill_dirs(argv):
        folder = os.path.basename(os.path.normpath(d))
        text = open(os.path.join(d, "SKILL.md"), encoding="utf-8").read()
        fm, err = parse_front_matter(text)
        tag = f"{folder}:"
        if err:
            print(f"error {tag} {err}")
            errors += 1
            continue
        name = fm.get("name") or folder
        if any(n == name for n, _ in seen):
            print(f"same  {tag} also installed in another folder (one per agent); counted once")
            continue
        desc = fm.get("description") if isinstance(fm.get("description"), str) else ""
        when = fm.get("when_to_use") if isinstance(fm.get("when_to_use"), str) else ""
        hidden = str(fm.get("disable-model-invocation", "")).lower() == "true"
        if not desc:
            print(f"error {tag} no description (Codex requires one; Claude Code falls back to the first line of the body)")
            errors += 1
            continue
        combined = (desc + (" " + when if when else "")).strip()
        before = errors
        if len(combined) > CLAUDE_ENTRY_CAP:
            print(f"error {tag} description + when_to_use is {len(combined)} characters; Claude Code cuts each entry at {CLAUDE_ENTRY_CAP}, so the end is lost")
            errors += 1
        if fm.get("name") and fm["name"] != folder:
            print(f"warn  {tag} name '{fm['name']}' differs from the folder '{folder}'; some agents list one, some the other")
            warns += 1
        if not hidden and not TRIGGER.search(combined):
            print(f"warn  {tag} no trigger clause; add 'Use when ...' with the words a user would actually type")
            warns += 1
        first = re.split(r"(?<=[.!?])\s", desc, maxsplit=1)[0]
        if len(first) > 200:
            print(f"warn  {tag} first sentence is {len(first)} characters; put the key use case first, in under 200")
            warns += 1
        w = words(combined)
        for other, ow in seen:
            if w and ow and len(w & ow) / len(w | ow) >= 0.6:
                print(f"warn  {tag} description overlaps '{other}' ({len(w & ow)} shared words); say what makes each one different")
                warns += 1
        seen.append((name, w))
        if not hidden:
            listing.append((name, len(name) + len(combined[:CLAUDE_ENTRY_CAP]) + 4))
        print(f"{'ok   ' if errors == before else 'fix  '} {tag} {len(combined)} chars{' (hidden from the model: disable-model-invocation)' if hidden else ''}")
    total = sum(n for _, n in listing)
    claude_budget = int(context * 0.01 * 4)
    codex_budget = int(context * 0.02 * 4)
    print(f"listing: {len(listing)} skill(s), about {total} characters (~{total // 4} tokens)")
    print(f"budget: Claude Code 1% of {context} tokens ~ {claude_budget} chars: {'fits' if total <= claude_budget else 'OVER, least-used descriptions get dropped'}")
    print(f"budget: Codex 2% of {context} tokens ~ {codex_budget} chars (8000 if the window is unknown): {'fits' if total <= codex_budget else 'OVER, descriptions get shortened'}")
    print(f"skill-listing: {errors} error(s), {warns} warning(s)")
    return 1 if errors else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))

# Skill descriptions: before and after

The description is read by the agent to decide whether to load the skill. It is a trigger, not a summary of the body.

## Too vague
Before: `description: Helps with database stuff.`
After: `description: Write and review Postgres migrations as SQL files. Use when adding a table, column or index, changing a constraint, or when a migration fails to apply.`

Why: "database stuff" matches nothing a user types. The after version names the task, the objects and the failure.

## Key use case buried
Before: `description: This skill was written after several incidents in which our team noticed that agents would sometimes produce release notes that did not match the actual changes, so it now gathers merged PRs and ...`
After: `description: Draft release notes from the PRs merged since the last tag. Use when the user asks for release notes, a changelog entry or "what shipped".`

Why: when the listing is cut, only the start survives. History belongs in the body, if anywhere.

## Missing the words people use
Before: `description: Performs Lighthouse-style auditing of web pages.`
After: `description: Measure page speed and fix slow loads with Chrome DevTools traces. Use when a page feels slow, LCP or CLS is poor, or the user mentions Core Web Vitals, PageSpeed or Lighthouse.`

## Two skills nobody can tell apart
Before:
- `review: Review code changes for problems.`
- `pr-check: Check pull requests for issues.`

After:
- `review: Review the uncommitted diff for bugs and risky changes before a commit. Use when the user asks to review, check or look over their changes.`
- `pr-check: Run the repository's PR checklist (tests, changelog, screenshots) on an open pull request. Use when preparing or updating a PR. Not for reviewing code itself.`

## Unquoted colon
Before: `description: Triggers: deploy, release, ship`
After: `description: "Deploy the app to staging or production. Triggers: deploy, release, ship."`

Why: YAML reads `Triggers:` as a nested key. Quote any value that contains `: `.

## A skill only a human should start
For deploys and other actions with side effects, set `disable-model-invocation: true` (Claude Code) so the
description stays out of the model's listing and the skill runs only when typed as `/name`. It then costs no budget.