name: codex-plugin-dev-structure description: Use when the user asks how to structure Codex skills (folders, SKILL.md, supporting files), wants plugin-dev-like organization, or needs conventions for templates/scripts bundled with a skill.

Codex Plugin-Dev：Skill 結構慣例

建議目錄結構

每個 skill 一個資料夾（與現有 .codex/skills/* 一致）：

<CODEX_HOME>/skills/
  my-skill/
    SKILL.md
    scripts/                # 可選：可重用腳本
    templates/              # 可選：檔案模板
    reference/              # 可選：重型參考文件（100+ 行）

SKILL.md 必要元素（最低限度）

• YAML frontmatter
  • name: 僅允許 a-z0-9-（全小寫 + hyphen）
  • description: 以 "Use when..." 開頭，只寫「什麼情況要用」，不要寫流程
• 內容要包含：
  • Overview（這個 skill 的核心價值）
  • When to use（用症狀/關鍵字讓搜尋命中）
  • Quick start（最短可跑的指令或步驟）

觸發（Discovery）設計要點

description 盡量包含：

• 使用者會打的詞：skill, SKILL.md, frontmatter, trigger, description, YAML
• 症狀：skill 沒觸發, 找不到 skill, 不會自動選用
• 同義詞：template, skeleton, boilerplate, scaffold

Supporting files 原則

• 「可複用工具」放 supporting file（script/template），避免把整段工具塞進 SKILL.md。
• 需要跑 Python 時：必須遵守專案 uv + .venv，且指令要用 .venv\\Scripts\\python.exe。