twa-skill-authorlisted

# 撰寫 tw-edu-* 技能 ## 先跑一次現況 ```bash python scripts/verify_skill_frontmatter.py python scripts/verify_skill_links.py ``` 現況是綠的才動手。在紅燈上疊改動，會分不清是誰弄壞的。 ## 目錄結構 ``` skills/<name>/ ├── SKILL.md 必要 ├── references/ 漸進揭露：模型需要時才讀，不要塞進 SKILL.md └── scripts/ ├── generate_*.py └── smoke.yml 有腳本就必須有 ``` ## Frontmatter 契約 v1 必填：`name`（kebab-case，**必須等於目錄名**）、`description`（≤300 字元）、 `version`（SemVer，且 CHANGELOG 要有對應條目）、`author`、`license`、 `whenToUse`、`metadata`。 ### description 與 whenToUse 的分工 **`description` 負責召回（recall）** —— 寫觸發詞，讓模型在使用者提到相關字眼時找到你。 **`whenToUse` 負責精確度（precision）** —— 寫「什麼時候**不要**用我、該用哪一支」。 ```yaml whenToUse: > 適用於單課或單一單元的教學設計。若要規劃整學期的課程地圖， 改用 tw-edu-curriculum-mapper；若要的是專題式學習，改用 tw-edu-pbl-designer。 ``` 只寫「適用於 X」而不寫「不適用於 Y」，等於沒寫——那些資訊 description 已經有了。 ### metadata ```yaml metadata: role: teacher # teacher | student | researcher category: 課程設計 # 與 README 索引的分類一致 stage: [E, J, U] # E 國小 / J 國中 / U 高中 subjects: [全領域] outputs: [docx] # 與 smoke.yml 的 output_ext 一致 shared: # 引用了哪幾份 shared/ 協議 - concept-alignment ``` `shared` 列的每一份都必須存在於 `shared/`，gate 會檢查。 ### disable-model-invocation **預設不要設。** 設了就等於告訴註冊表「永遠不要自動叫我」， 那 description 裡的觸發詞就白寫了。 只有「改設定、不產出教學文件」的工具才該設 `true` （目前只有 `tw-edu-synchronizer`）。 ## 引用 shared/ 一律寫 `../../shared/<name>.md`，並在 `metadata.shared` 宣告。 **不要**把協議內容複製進 SKILL.md —— 發版時 `build_standalone_skills.py` 會自動內聯，你手動複製只會產生第二份會過期的副本。 ## 共用程式碼 Word 版面、