# Trigger Validator

> Use when a skill doesn't fire or its description needs a rewrite. Not for body (write:writing-skills) or review (skill:quality-assurance). Triggers: "스킬이 트리거 안 돼", "SKILL.md가 안 떠", "skill not firing", "description 개선해줘", "trigger coverage audit".

- Skill: `newkayak12/trigger-validator` (Agent Skill)
- Install (CLI): `npx get-skill add newkayak12/trigger-validator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/newkayak12/trigger-validator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: newkayak12 (https://skillmd.com/u/newkayak12)
- Updated: 2026-11-14
- Page: https://skillmd.com/skills/newkayak12/trigger-validator

---


# Skill Trigger Validator

Analyzes skill `description` fields for trigger coverage gaps and rewrites them to fire reliably on natural language — including Korean.

The description field is the only signal Claude uses to decide whether to invoke a skill. If it lists only formal English keywords, conversational or Korean requests will miss. This skill audits that coverage and produces a drop-in replacement description.

**Not for** editing the body of a skill (`write:writing-skills`) or a quality review of a skill that already fires (`skill:quality-assurance`); this skill touches the `description` field only.

Also triggers on (kept out of the 250-char description): "skill이 안 떠", "한국어 트리거 추가해줘", "skill 발동 조건 점검", "description이 너무 keyword만 있어".

## Process

### Input

Accept one of:
- **Single skill** — path (e.g., `develop/skills/clean-code`) or name (`clean-code`)
- **Plugin** — all skills in a plugin (e.g., `think`, `develop`)
- **All** — full audit across the repo

If no target is given, ask for one before proceeding.

### 1. Read Target Skills

For each target skill, read the `description` field from the SKILL.md frontmatter. Also skim the body to understand what the skill actually does — the description should match the skill's real intent, not just its name.

### 2. Generate Test Queries

For each skill, generate **20 test queries** that a real user might type — 10 that should trigger, 10 that should not:

| # | Type | Example register |
|---|------|-----------------|
| 1–2 | Formal English | exact keywords from the description |
| 3–4 | Natural English | colloquial, indirect phrasing |
| 5–7 | Natural Korean | conversational 한국어, not word-for-word translations |
| 8–9 | Implicit | user has a clear need but never says the skill name |
| 10 | Competing skill | a sibling skill also fits, and this one should win |
| 11–20 | Near-miss | shares keywords or concepts with the skill but needs something else — an adjacent skill, plain Claude, or a different tool |

Make every query concrete and substantive: a file name, a number, a bit of the user's situation, casual phrasing or a
typo. Claude skips skills for trivial one-step asks whatever the description says, so "debug this" tests nothing.
Good Korean queries feel like something a developer would actually type in chat — "이거 어떻게 설계해야 해?",
"Redis 써야 할까?", "코드 너무 복잡한데 어떻게 해?". Bad Korean queries are literal translations of English keywords.

A near-miss is valuable only if a keyword match would fire on it. "Write a fibonacci function" as a negative for a
PDF skill is too easy and measures nothing; for a bug-diagnosis skill, "add a regression test for the paging fix we
just made" is a near-miss.

### 3. Score Trigger Coverage

For each query, ask: **would the current description cause Claude to invoke this skill?**

Default is a judged score — Claude reads the description and predicts. When the user asks for a measured score ("실제로 돌려봐", "measure it"), run each query headless **3 times** and record how often the skill fired; a query counts as fired at 2 of 3 or more (one run is noise):

```bash
claude -p "<query>" --setting-sources project --plugin-dir <plugin> --output-format stream-json --verbose --max-turns 2 < /dev/null \
  | grep -q '"name":"Skill".*<skill-name>' && echo HIT || echo MISS
```

Run from a scratch directory under `$TMPDIR`, not inside the plugin. Label the score `measured` or `judged` in the report.

Assess each query on two axes:
- **Should trigger** (queries 1–10): does the description give enough signal? Score 1 if yes, 0 if no.
- **Should not trigger** (queries 11–20): does the description stay silent? Score 1 if correctly silent, 0 if it would falsely trigger.

**Trigger score** = `(correct answers / 20) × 10`

### 4. Identify Gaps

Common failure patterns to call out explicitly:

| Pattern | Signal |
|---------|--------|
| **Korean blind spot** | English-only description; Korean queries score 0 |
| **Keyword-only** | Lists exact terms but no intent/situation framing |
| **Jargon wall** | Trigger requires domain vocabulary the user wouldn't use naturally |
| **Too narrow** | Only fires when user says the skill's name explicitly |
| **Too broad** | Would fire on loosely related requests, creating noise |

### 5. Write Improved Description

Rewrite the description as a drop-in replacement. Follow these principles:

1. **Lead with what the skill does** — one clear sentence
2. **Frame around intent/situation**, not just keywords — describe *when someone needs this*, not just *what words they say*
3. **Include Korean natural language phrases** — real colloquial expressions in-line, not a separate section
4. **Include English colloquial variants** alongside formal terms
5. **Stay at or under 250 characters** — Claude Code truncates past that, and descriptions are always in context
6. **Start with `Use when`** — the situation first; no workflow summary

When rewriting in measured mode, hold out 8 of the 20 queries (4 should, 4 near-miss) and iterate on the other 12:
rewrite, re-measure, at most 3 iterations. Pick the description with the best **held-out** score, not the best
training score — a description tuned to the 12 it saw can lose on the 8 it didn't. Report both scores.

**Structure:**
```
Use when [situation/intent]. Triggers on: "[한국어 구어체]", "[English phrase]", "[implicit case]".
```

**Before / After example:**

Before:
```
Write readable, maintainable code. Use when the user mentions "code review", "naming conventions", "function too long", "code smells", or "readable code".
```

After:
```
Use when code is hard to read or change and needs review or cleanup. Triggers on: "코드 리뷰해줘", "이 코드 좀 봐줘", "가독성", "리팩토링", "this is hard to read", "code review".
```

## Output Template

### Single Skill

```
## [skill-name] — Trigger Analysis

**Score:** X/10 (judged / measured; measured also shows held-out X/10 when rewritten)
**Current description:** [verbatim]

### Query Results
| Query | Lang | Trigger? | Verdict |
|-------|------|----------|---------|
| "이 코드 좀 봐줘" | KO | ❌ miss | No Korean terms |
| "can you review my code" | EN | ✅ hit | "code review" matches |
| "what's a good linter" | EN | ❌ false neg | intent matches but no signal |
...

### Gaps
- [specific gap with explanation]

### Improved Description
[ready-to-paste rewrite — no surrounding quotes or markdown fences]
```

### Batch (plugin or all skills)

Start with a summary table:

```
| Skill | Score | Primary Gap |
|-------|-------|-------------|
| clean-code | 4/10 | No Korean triggers |
...
```

Then produce individual reports for all skills scoring below 7. For skills scoring 7+, note them as "acceptable — no action needed" unless the user asks for more detail.

## Applying Changes

If the request already asked for a fix ("개선해줘", "rewrite it"), apply the rewrites. Otherwise show them side-by-side and ask once before applying.

Update only the `description` field in each file's frontmatter — do not touch the body. This skill ends at the frontmatter edit; versions and release are governed by the repo's own rules, not here (in this repo, `.claude/rules/maintaining.md` → "Versions and release").

## What Claude Does / What You Do

| Claude | You |
|--------|-----|
| Generates 20 test queries per skill (10 should, 10 near-miss) and scores trigger coverage | Name the target: skill, plugin, or all |
| Rewrites weak descriptions | Review the rewrites |
| Applies description changes to frontmatter only | Say whether to apply, if not already asked |

## Related Skills

- `quality-assurance` — full 6-check review once the skill fires
- `write:writing-skills` — authoring guide the rewrites must satisfy

