skill-trigger-metadata

name	skill-trigger-metadata
description	Use when creating, editing, auditing, or debugging skill names, descriptions, SKILL.md frontmatter, plugin skill metadata, discovery triggers, routing phrases, under-triggering, over-triggering, or cases where a relevant skill is not being invoked or read.

Skill Trigger Metadata

Bundled commands use $PLUGIN_ROOT ($env:PLUGIN_ROOT in PowerShell; same path suffix) for the plugin root. Set it once: use the host's plugin-root variable when defined (Claude Code: PLUGIN_ROOT="$CLAUDE_PLUGIN_ROOT"), otherwise the absolute path of this skill folder's ../...

Design name and description as the retrieval contract that makes an agent read the right SKILL.md. Use this before finalizing skill frontmatter or plugin skill metadata.

If the task also changes skill instructions, resources, scripts, packaging, or installation, use this skill for metadata first, then use skill-factory or plugin-factory for the broader lifecycle.

Core Rule

The description must answer: should the agent read this skill now?

Write for progressive disclosure: name is the searchable handle, description is the trigger contract, and SKILL.md body contains workflow, commands, constraints, and examples.

Do not put enough workflow detail in description for the agent to act without reading SKILL.md.

Trigger Selection Model

Treat skill selection as tool lookup plus routing:

• information scent: metadata gives strong proximal cues that the full skill is worth reading;
• local vocabulary: include task terms, artifacts, file types, symptoms, and synonyms from the real work surface;
• tool decision vector: say when to use the skill, expected inputs, adjacent non-use cases, and failure symptoms;
• negative boundaries: include near-miss prompts that should not trigger the skill;
• safety: metadata is part of tool selection, so do not include untrusted imperatives, hidden auto-invocation, or examples that bypass consent.

Top-load trigger boundaries and critical constraints so the agent can decide to read the skill before acting.

Selection Card

Write a selection card before wording the final description:

Use when:
Inputs/signals:
Do not use when:
Failure symptoms:
Adjacent skills:

Then turn it into this shape:

description: Use when <task contexts, artifacts, failures, or agent decision points that should trigger this skill>.

Include concrete terms for user intent, artifacts, symptoms, source evidence, synonyms, adjacent phrasing, and negative boundaries when nearby skills share vocabulary.

For router/process skills where missing the skill is the dominant failure, stronger phrasing is acceptable: "Use when..." or "Use before...". Do not make ordinary domain skills globally mandatory.

Trigger Audit

Before finalizing metadata, write a small trigger set:

• 6-10 should-trigger prompts with varied wording, short and long forms, named and unnamed domain cues.
• 4-8 should-not-trigger prompts, especially near misses that share keywords but need a different skill.
• at least one prompt where the relevant need is buried inside a larger task.

Check each prompt against the description:

• Would the agent know to read the skill without the user naming it?
• Does any should-trigger prompt lack a key input type, synonym, or failure symptom?
• Does any should-not-trigger prompt match because the description is too broad?
• Could the agent complete the workflow from the description alone and skip SKILL.md?
• Are likely transitions to adjacent skills explicit enough for a router skill?

Revise until the boundary is clear. If two skills own the same trigger surface, split responsibilities or make the router skill explicit.

Failure Diagnosis

If the skill under-triggers, add missing concrete intent, artifacts, file types, error text, or domain synonyms.

If it over-triggers, add scope qualifiers or negative boundaries and remove generic nouns.

If it triggers but the agent skips required steps, remove workflow steps from description, top-load constraints in SKILL.md, and shorten body text that hides the required action.

Output

When changing metadata, report:

• old and new name or description;
• why the new wording should trigger;
• key should-trigger and should-not-trigger examples;
• metadata decision and boundary probes used;
• validators run, usually quick_validate.py and any repository/plugin checks.

Use $PLUGIN_ROOT/references/trigger-metadata.md for name rules, description wording patterns, and detailed failure repair.