# What Triggers for Skill Descriptions Ensure Proper Agent Routing in Instagit

> Learn how "Use when" triggers in Instagit skill descriptions ensure proper agent routing by matching user intents to the correct skill for efficient support.

- Repository: [Matt Pocock/skills](https://github.com/mattpocock/skills)
- Tags: deep-dive
- Published: 2026-04-04

---

**Agent routing in the Instagit ecosystem depends entirely on the "Use when" trigger sentence within each [`SKILL.md`](https://github.com/mattpocock/skills/blob/main/SKILL.md) description to match user intents to the correct skill.**

In the `mattpocock/skills` repository, the agent makes routing decisions by reading only the `description` field of each skill definition. Understanding what triggers for skill descriptions ensure proper agent routing is critical for building deterministic automation workflows that correctly map user requests to specialized capabilities.

## The Two-Part Description Structure

Every skill description in [`write-a-skill/SKILL.md`](https://github.com/mattpocock/skills/blob/main/write-a-skill/SKILL.md) follows a strict two-sentence pattern that separates capability from activation criteria.

**Capability Sentence**

The first sentence provides a high-level functional hook describing what the skill does. According to the template in [`write-a-skill/SKILL.md`](https://github.com/mattpocock/skills/blob/main/write-a-skill/SKILL.md) (lines 40-45), this should concisely state the skill's core function without ambiguity.

**Trigger Sentence**

The second sentence must start with the literal prefix **"Use when"** and enumerate specific keywords, contexts, or file types that activate the skill. As defined in the same template file (lines 70-75), this sentence supplies the concrete tokens the routing algorithm matches against user utterances.

Omitting this sentence or using vague language results in immediate routing failures. The template includes a validation checklist item `[ ] Description includes triggers ("Use when…")` that prevents registration of malformed skills.

## How the Agent Processes Routing Triggers

The Instagit agent executes a four-step pipeline to evaluate which skill best matches a user request:

1.  **Parse** – The agent extracts text immediately following the `Use when` marker in the description field.
2.  **Tokenize** – It splits the trigger phrase into discrete keywords and phrases (e.g., "PDF files", "triage", "DDD").
3.  **Match** – When a user query contains any of these tokens, the skill receives a relevance score based on token overlap.
4.  **Disambiguate** – If multiple skills match, the agent prefers the skill whose trigger list contains the most specific, domain-focused phrases (longer, more precise terms win over generic ones).

Because the trigger sentence uses the explicit **"Use when"** boundary marker, the routing logic can reliably distinguish between descriptive capability text and actionable trigger tokens.

## Writing Effective Trigger Sentences

Well-formed triggers combine domain terminology with specific file types or actions. Consider the structure used in the `pdf-extractor` skill:

```markdown
---
name: pdf-extractor
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.
---

```

-   The **first sentence** establishes capability: extracting text, filling forms, merging documents.
-   The **second sentence** provides precise triggers: `PDF files`, `forms`, `document extraction`.

When a user asks *"Can you pull the tables out of this PDF?"*, the token "PDF" matches the trigger list, causing the agent to route to `pdf-extractor` rather than a generic document skill.

## Practical Implementation Examples

### Creating a New Skill with Proper Triggers

To create a routable skill, you must structure the [`SKILL.md`](https://github.com/mattpocock/skills/blob/main/SKILL.md) file with the required directory layout and description format:

```bash
my-new-skill/
├── SKILL.md          # Main description file with triggers

└── REFERENCE.md      # Optional supplementary documentation

```

[`my-new-skill/SKILL.md`](https://github.com/mattpocock/skills/blob/main/my-new-skill/SKILL.md):

```markdown
---
name: github-triage
description: Analyze GitHub issues to categorize bugs, feature requests, and questions. Use when user mentions triage, bugs, feature requests, or needs issue categorization.
---

```

The [`github-triage/SKILL.md`](https://github.com/mattpocock/skills/blob/main/github-triage/SKILL.md) file in the repository demonstrates this pattern with triggers like `triage`, `bugs`, and `feature requests`.

### Agent Routing Logic

The following Python pseudo-code mirrors the actual routing implementation in the Instagit agent:

```python
def select_skill(user_input: str, skills: List[Skill]) -> Skill | None:
    """Return the best-matching skill based on trigger tokens."""
    tokens = set(user_input.lower().split())
    best, best_score = None, 0

    for skill in skills:
        # Extract only the text after "Use when"

        if "Use when" not in skill.description:
            continue
        triggers = skill.description.split("Use when", 1)[1] \
                    .replace(".", "").lower()
        trigger_tokens = set(triggers.split())
        
        # Calculate overlap score

        score = len(tokens & trigger_tokens)
        if score > best_score:
            best, best_score = skill, score

    return best if best_score > 0 else None

```

This implementation specifically searches for the `Use when` literal to locate the trigger boundary.

### Validating Triggers in CI

To prevent unroutable skills from entering the repository, add this validation check to your pre-commit hooks:

```bash

# Validate that trigger sentence exists

if ! grep -q "^description:.*Use when" my-new-skill/SKILL.md; then
  echo "❌ Skill description must contain a 'Use when' trigger sentence."
  exit 1
fi

```

This ensures every skill includes the mandatory routing triggers before registration.

## Key Files in the Routing System

| File | Role in Trigger Handling |
|------|-------------------------|
| [`write-a-skill/SKILL.md`](https://github.com/mattpocock/skills/blob/main/write-a-skill/SKILL.md) | Defines the required description template and checklist enforcing the "Use when" pattern |
| [`github-triage/SKILL.md`](https://github.com/mattpocock/skills/blob/main/github-triage/SKILL.md) | Concrete example showing trigger phrasing for issue triage workflows |
| [`ubiquitous-language/SKILL.md`](https://github.com/mattpocock/skills/blob/main/ubiquitous-language/SKILL.md) | Demonstrates domain-specific triggers using terminology like `DDD` and `domain model` |
| [`README.md`](https://github.com/mattpocock/skills/blob/main/README.md) | Documents that descriptions drive routing, reminding contributors to follow the pattern |

These files form the contract between skill authors and the Instagit routing engine. Consistent use of the **"Use when"** trigger sentence ensures deterministic agent behavior.

## Summary

-   **Agent routing** in the Instagit ecosystem relies exclusively on the `description` field of [`SKILL.md`](https://github.com/mattpocock/skills/blob/main/SKILL.md) files.
-   **Two required elements** ensure proper routing: a capability sentence (first) and a trigger sentence starting with **"Use when"** (second).
-   **Token matching** occurs by extracting keywords after the "Use when" marker and comparing them against user queries.
-   **Specificity wins**: When multiple skills match, the agent selects the one with the most specific trigger phrases.
-   **Validation is mandatory**: The template checklist and CI scripts verify that all skills include proper trigger sentences.

## Frequently Asked Questions

### What happens if a skill description lacks a "Use when" trigger?

The agent cannot route user requests to that skill, resulting in a fallback response like "I don't know which skill to use." Additionally, the validation checklist in [`write-a-skill/SKILL.md`](https://github.com/mattpocock/skills/blob/main/write-a-skill/SKILL.md) will flag the omission, preventing the skill from being registered in the system.

### Can I include multiple trigger phrases in one "Use when" sentence?

Yes. The agent tokenizes the entire sentence following "Use when" into discrete keywords and phrases. Listing multiple contexts (e.g., "Use when working with PDF files, forms, or document extraction") increases the surface area for matching without requiring separate sentences.

### How does the agent handle ambiguous triggers?

When multiple skills match a query, the agent applies a specificity heuristic: it prefers the skill whose trigger list contains longer, more domain-focused phrases over generic terms. For example, a trigger containing "domain-driven design" outranks one containing only "help" or "assist."

### Where is the trigger format documented in the source code?

The canonical specification resides in [`write-a-skill/SKILL.md`](https://github.com/mattpocock/skills/blob/main/write-a-skill/SKILL.md) at lines 40-45 (capability sentence) and lines 70-75 (trigger sentence). The [`README.md`](https://github.com/mattpocock/skills/blob/main/README.md) also references that descriptions drive routing, while concrete implementations in [`github-triage/SKILL.md`](https://github.com/mattpocock/skills/blob/main/github-triage/SKILL.md) and [`ubiquitous-language/SKILL.md`](https://github.com/mattpocock/skills/blob/main/ubiquitous-language/SKILL.md) demonstrate real-world usage.