How to Define Triggers in Skill Description Fields for Invocation in kangarooking/cangjie-skill

In the cangjie-skill framework, triggers are defined in the description field of a skill's YAML front-matter by writing explicit "when to use" scenarios with recognizable language signals in both Chinese and English.

The AI host (Claude Code / Cursor) scans this description field to determine whether a skill should be loaded and executed. This field corresponds to the A2 — Future Trigger section from the RIA++ construction methodology. A well-crafted trigger definition enables precise skill activation while preventing false positives.

Understanding Trigger-Based Skill Invocation

The description field serves as the condensed gatekeeper for skill execution. When the host receives a user request, it parses this field for matching language signals. If the signals align with the request context and satisfy the "when to use" rules, the skill activates.

According to the repository's quality red-lines in SKILL.md (lines 52-53), the description must "明确 trigger 条件" — explicitly defining trigger conditions to pass validation.

Required Components of a Trigger Definition

A complete trigger definition includes five core elements:

• When to invoke — 3-5 concrete situations where the skill applies
• When not to invoke — explicit boundary cases preventing false activation
• Language signals — verbatim user utterances the host matches against
• Scope constraints — concise wording (≤300 words) with specific, non-vague terms
• Dual-language support — both Chinese and English phrasings for broad activation coverage

Writing the description Field in SKILL.md

The description lives in the YAML front-matter of each skill file, following the structure defined in templates/SKILL.md.template (lines 4-5).

Example: Minimal Valid Trigger

---
name: reverse-brainstorm
description: |
  当用户面对一个决策却只想到同类方案，或在寻找新思路时;
  when the user says "I'm stuck with similar ideas" or asks "How can I think outside the box?";
  不适用于仅需事实查询或简单选择题的情形。
source_book: 《逆向思维》 查理·芒格
source_chapter: 第四章
tags: [creativity, decision-making]
related_skills: []
---

Breakdown of this trigger:

Component	Implementation
Activation scenario	"面对决策却只想到同类方案" / "I'm stuck with similar ideas"
Language signals	"How can I think outside the box?"
Boundary condition	"不适用于仅需事实查询或简单选择题"
Dual-language	Parallel Chinese and English phrasings

Following RIA++ Stage 2 Construction Rules

The description field content originates from the A2 — Future Trigger block during RIA++ Stage 2. The methodology in methodology/04-stage2-ria-plus.md (lines 32-40) specifies:

1. Extract concrete trigger scenarios from the source material
2. Draft both positive triggers (when to use) and negative triggers (when not to use)
3. Translate trigger phrases to capture multilingual user queries
4. Copy the finalized A2 content verbatim into the description front-matter field

Validating Trigger Accuracy

Trigger definitions undergo pressure testing as described in methodology/06-stage4-pressure-test.md (lines 11-21). Each skill requires:

• should_trigger test cases: documented user queries that must activate the skill
• should_not_trigger test cases: queries that must not activate the skill, despite surface similarity

These test cases verify that the description field achieves high precision without over-triggering.

Common Pitfalls to Avoid

Mistake	Consequence	Correction
Vague triggers like "需要决策时"	Over-triggering on irrelevant decisions	Specify decision types with concrete constraints
Missing "when not to use" boundaries	False-positive activation	Always include explicit negative triggers
Single-language phrasings	Missed activation in multilingual contexts	Provide parallel Chinese/English signals
Exceeding 300 words	Diluted signal, parsing failures	Edit ruthlessly for concision

Key Source Files Reference

File	Purpose	Key Lines
templates/SKILL.md.template	Skill file skeleton with description placeholder	4-5
methodology/04-stage2-ria-plus.md	A2 — Future Trigger construction methodology	32-40
SKILL.md	Quality red-lines requiring explicit trigger conditions	52-53
methodology/06-stage4-pressure-test.md	Trigger validation via test cases	11-21

Summary

• The description field in YAML front-matter controls skill invocation by defining A2 — Future Trigger conditions
• Effective triggers specify concrete when to use scenarios, when not to use boundaries, and verbatim language signals in both Chinese and English
• Content derives from RIA++ Stage 2 construction and is validated through should_trigger / should_not_trigger pressure tests in Stage 4
• Follow the quality red-lines in SKILL.md (lines 52-53) to ensure explicit, bounded trigger conditions

Frequently Asked Questions

What happens if my description field is too vague?

The AI host will either fail to activate your skill when needed (false negative) or activate it in inappropriate contexts (false positive). The quality red-lines in SKILL.md explicitly reject descriptions missing clear trigger conditions. Concrete boundary definitions in the "when not to use" section prevent these failures.

Can I define triggers without English translations?

Yes, but you sacrifice activation coverage. The host's detection algorithm matches verbatim phrases from the description field against user queries. Omitting English phrasings means the skill won't trigger on English-language requests, per the dual-language guideline in methodology/04-stage2-ria-plus.md.

How do pressure tests interact with the description field?

should_trigger and should_not_trigger test cases in methodology/06-stage4-pressure-test.md verify that your written description actually performs as intended. If a documented test query fails to activate the skill despite matching your described triggers, you must revise the description for greater precision or expanded language signal coverage.

Where does the description content originate?

It comes from the A2 — Future Trigger section completed during RIA++ Stage 2 construction. You analyze the source material's activation patterns, draft concrete trigger scenarios, translate them into parallel Chinese and English phrasings, then copy this content verbatim into the YAML front-matter description field.

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