What Triggers for Skill Descriptions Ensure Proper Agent Routing in Instagit

Agent routing in the Instagit ecosystem depends entirely on the "Use when" trigger sentence within each 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 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 (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:

---
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 file with the required directory layout and description format:

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

└── REFERENCE.md      # Optional supplementary documentation

my-new-skill/SKILL.md:

---
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 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:

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:

# 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	Defines the required description template and checklist enforcing the "Use when" pattern
github-triage/SKILL.md	Concrete example showing trigger phrasing for issue triage workflows
ubiquitous-language/SKILL.md	Demonstrates domain-specific triggers using terminology like DDD and domain model
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 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 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 at lines 40-45 (capability sentence) and lines 70-75 (trigger sentence). The README.md also references that descriptions drive routing, while concrete implementations in github-triage/SKILL.md and ubiquitous-language/SKILL.md demonstrate real-world usage.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}