Writing Trigger Phrases Agents Actually Match

A skill nobody can find is dead weight. On ContextPie, discovery is semantic: an agent's request is embedded and compared against your skills by cosine similarity. The text you write in three fields decides whether you ever get matched.

What actually gets embedded

Only a skill's name, description, and trigger_phrases are embedded (OpenAI text-embedding-3-small) and matched by cosine similarity, where similarity = 1 − distance. File bodies are never embedded — the SKILL.md body and supporting files are pulled later via progressive disclosure. So these few fields are your entire surface area for being found.

{
  "name": "Extract tables from PDFs",
  "description": "Pull structured tabular data out of PDF documents, including scanned pages, and return it as CSV or JSON.",
  "trigger_phrases": [
    "extract tables from a pdf",
    "ocr a scanned document",
    "get the data out of this invoice pdf",
    "convert a pdf table to csv"
  ]
}

Write the way a user phrases a request

Trigger phrases are not keywords or tags — they're embeddings of intent. Write them as a real request someone would type or say to an agent. "extract tables from a pdf" embeds close to how an agent will actually phrase the user's need. "pdf utilities" does not.

Cover distinct intents, not synonyms

Each phrase should pull in a different kind of request. Listing "pdf table", "table pdf", "pdf tables" three times wastes the slot — they collapse to nearly the same vector. Instead, span the real intents your skill serves:

• "extract tables from a pdf"
• "ocr a scanned document"
• "convert a pdf table to csv"

Keep them specific and well-scoped

A vague skill matches everything weakly and nothing strongly, so it loses to sharper skills on every query. Narrow scope wins.

• Weak: "pdf stuff", "documents", "data extraction"
• Strong: "extract tables from a pdf", "ocr a scanned document", "parse a financial statement pdf"

The weak phrases sit in a crowded region of embedding space; the strong ones own a precise neighborhood and win the cosine match.

Let the data tell you what to add

You don't have to guess. The discovery-gaps view shows real searches that matched nothing well — every row is a phrasing your registry failed to serve. If agents keep searching "redact PII from a pdf" and your best score is 0.41, that's a missing trigger phrase (or a missing skill). Add the phrase, ship a new immutable version, and watch the gap close.

This is the core loop — see The query is the telemetry. Write phrases like real requests, then refine them from real misses. For the full field reference, see authoring a skill.