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):
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:
- Lead with what the skill does — one clear sentence
- Frame around intent/situation, not just keywords — describe when someone needs this, not just what words they say
- Include Korean natural language phrases — real colloquial expressions in-line, not a separate section
- Include English colloquial variants alongside formal terms
- Stay at or under 250 characters — Claude Code truncates past that, and descriptions are always in context
- 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 fireswrite:writing-skills— authoring guide the rewrites must satisfy