# How to Write Description Strings in SKILL.md for Automatic Triggering in OpenAI Plugins

> Learn how to write effective description strings in SKILL.md for automatic triggering in OpenAI Plugins. Follow intent-focused "Use when..." patterns for seamless integration.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-09-13

---

**Write description strings as intent-focused sentences starting with "Use when..." followed by the user action and product name, keeping the total length under 12 words and avoiding implementation details.**

The [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) files in the `openai/plugins` repository power an automatic skill-triggering mechanism where an LLM matches user queries against skill descriptions. Because the retrieval system relies on plain-text similarity to select the appropriate skill, the exact phrasing of the `description` field in the front matter directly determines whether a skill triggers automatically for a given user intent.

## Why Description Formatting Controls Automatic Triggering

In the OpenAI Plugins architecture, the front-matter parser extracts the `description` string from each [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file and feeds it to the LLM's retrieval engine. The model performs semantic matching against these strings to identify which skill best addresses the user's request. Since this matching algorithm favors exact phrase overlap and domain keywords, descriptions that follow a consistent, user-centric pattern yield significantly higher precision than generic or technical descriptions.

The repository's existing skill set has tuned the LLM to expect descriptions that frame user intent explicitly. When descriptions deviate from this pattern—such as omitting the product name or describing internal code rather than user goals—the model struggles to map queries to the correct skill.

## The "Use When" Pattern for SKILL.md Descriptions

The definitive pattern for reliable automatic triggering follows this structure:

```yaml
description: Use when [action] [product/technology] [context].

```

This template works because it explicitly frames the description as a user intent scenario rather than a technical capability. The phrase "Use when" signals to the matching engine that the following text describes the situation in which a user should invoke the skill.

Key elements of the pattern include:

- **Start with "Use when"** – This phrasing is critical. It shifts the description from stating what the skill does to stating when the user needs it.
- **Lead with the product name** – Mentioning technologies like Zoom, Vercel, Supabase, or Stripe early in the sentence provides essential domain context that differentiates similar skills across different platforms.
- **Use present-tense action verbs** – Words like "building," "configuring," or "authenticating" describe the user's goal state.
- **Stay under 12 words** – Concise descriptions reduce noise and improve matching speed by focusing the LLM on core intent markers.

## Writing Guidelines for SKILL.md Description Strings

Based on the source code analysis of existing skills in the repository, follow these specific guidelines to optimize for automatic triggering:

### Do: Frame as User Intent

**Start with "Use when..."** to clearly indicate the triggering scenario.

```yaml

# Good

description: Use when building Zoom webhooks.

# Bad

description: Handles Zoom webhooks.

```

### Do: Include Product Context Early

Mention the specific product or technology immediately after the action verb to disambiguate from similar skills.

```yaml

# Good

description: Use when configuring Vercel Workflow steps.

# Bad

description: Workflow configuration helper.

```

### Do: Keep It Concise

Limit descriptions to 12 words or fewer. Long sentences introduce ambiguity and reduce the weight of key matching terms.

```yaml

# Good

description: Use when authenticating with Supabase.

# Bad

description: This skill provides helper functions for authenticating users with Supabase auth.

```

### Don't: Include Implementation Details

Avoid mentioning internal functions, library names, or code signatures. The matching engine looks for business-level intent, not technical implementation.

```yaml

# Bad

description: Calls zoomSdk.init() internally to set up meetings.

```

### Don't: Use Passive or Past Tense

Maintain consistency with the repository's established style by using present-tense "use" rather than "used" or "using."

```yaml

# Bad

description: Used for building Zoom webhooks.

```

### Don't: Cover Multiple Intents

If a skill handles multiple actions, describe only the most common user request. Split distinct intents into separate skills to maintain high precision matching.

## Real-World Examples from the OpenAI Plugins Repository

The following examples from `openai/plugins` demonstrate the difference between effective and ineffective description strings:

| File | Effective Description | Ineffective Alternative |
|------|---------------------|-------------------------|
| [`plugins/zoom/skills/webhooks/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/webhooks/SKILL.md) | `Use when building Zoom webhooks.` | `Handles webhook creation for Zoom.` |
| [`plugins/zoom/skills/zoom-apps-sdk/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/zoom-apps-sdk/SKILL.md) | `Use when using Apps SDK.` | `Apps SDK utilities.` |
| [`plugins/vercel/skills/workflow/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/workflow/SKILL.md) | `Use when configuring Vercel Workflow steps.` | `Workflow configuration helper.` |
| [`plugins/supabase/skills/supabase/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/supabase/skills/supabase/SKILL.md) | `Use when authenticating with Supabase.` | `Supabase auth helper functions.` |
| [`plugins/stripe/skills/stripe-apps/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/stripe/skills/stripe-apps/SKILL.md) | `Use when building a Stripe payment checkout.` | `Stripe checkout integration code.` |

Notice that effective examples consistently place the product name (Zoom, Vercel, Supabase, Stripe) within the first few words and use active verbs that describe the user's objective rather than the skill's internal capabilities.

## Key Files to Study

To understand the practical application of these patterns, examine these specific files in the repository:

- **[`plugins/zoom/skills/webhooks/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/webhooks/SKILL.md)** – Demonstrates minimal, intent-focused description for webhook functionality.
- **[`plugins/zoom/skills/zoom-apps-sdk/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/zoom-apps-sdk/SKILL.md)** – Shows proper phrasing for broader SDK usage rather than specific API calls.
- **[`plugins/vercel/skills/workflow/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/workflow/SKILL.md)** – Illustrates the pattern applied to CI/CD workflow configuration.
- **[`plugins/supabase/skills/supabase/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/supabase/skills/supabase/SKILL.md)** – Provides an example of concise authentication-related description.
- **[`plugins/stripe/skills/stripe-apps/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/stripe/skills/stripe-apps/SKILL.md)** – Shows payment-specific intent framing without mentioning implementation details.

## Summary

- Start every description string with **"Use when..."** to align with the LLM's expected pattern for automatic triggering.
- Include the **product or technology name** (Zoom, Vercel, etc.) early in the sentence to provide domain context.
- Keep descriptions **concise (≤12 words)** and free of implementation details, jargon, or internal code names.
- Use **present-tense action verbs** that describe the user's goal (building, configuring, authenticating) rather than passive descriptions of the skill's functionality.
- Focus on **single intent** per skill; split multiple actions into separate skills to maintain matching precision.

## Frequently Asked Questions

### What happens if I don't use the "Use when" format in my SKILL.md description?

The LLM may fail to match user queries to your skill during automatic triggering. The retrieval system in `openai/plugins` has been trained on the existing corpus where the majority of descriptions follow this pattern, so deviations reduce the semantic similarity score between user intents and your skill description.

### Can I include function names or API details in the description?

No. Avoid mentioning function signatures, library names, or internal implementation details like `zoomSdk.init()`. The matching engine operates on business-level intent recognition, not code-level pattern matching. Including technical details increases the risk of mismatch when users describe their goals in plain language rather than technical terms.

### How long should a SKILL.md description be?

Aim for **12 words or fewer**. Concise descriptions improve matching speed and reduce ambiguity. The model assigns higher relevance to skills where the core intent words (product name, action verb, and context) appear without surrounding noise or filler words.

### Should one skill cover multiple related actions in its description?

No. If a skill handles multiple distinct actions, choose the most common user request for the description and consider splitting other actions into separate skills. Listing multiple intents in a single description dilutes the matching precision and increases the likelihood of the LLM selecting an inappropriate skill for a specific query.