# Copilot Dev Conventions

> 建立文件、產生檔案、撰寫文檔、建立腳本時必須遵守的慣例。涵蓋回覆語言/文件語言必須遵循專案設定（zhTW）、SKILL.md 作為唯一入口點、腳本使用 Node.js 確保跨平台相容性。

- Skill: `andyhsutw/copilot-dev-conventions` (Agent Skill)
- Install (CLI): `npx skillmds@latest add andyhsutw/copilot-dev-conventions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/andyhsutw/copilot-dev-conventions/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: AndyHsuTW (https://skillmd.com/u/andyhsutw)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/andyhsutw/copilot-dev-conventions

---


# Copilot CLI 開發慣例

從 3 個 workflow 領域本能演化而來的開發慣例 Skill。
當你在為 Copilot CLI 設計功能、撰寫文件或建立腳本時，遵循以下規則。

## 規則 1：SKILL.md 作為唯一入口點

**觸發條件：** 為 Copilot CLI 設計功能或工作流程時

Copilot CLI 的 `/` 選單**只會顯示 Skills**（`.github/skills/*/SKILL.md`），**不會顯示 Prompts**（`.github/prompts/*.prompt.md`）。

因此：
- 所有使用者可觸發的工作流程必須放在 `SKILL.md` 中
- 多個相關子指令應嵌入同一個 SKILL.md，使用 `## Action: <name>` 作為分段
- Prompt 檔案僅作為參考文件，不作為使用者入口

```
# 正確做法
.github/skills/my-feature/SKILL.md    -> 使用者透過 /my-feature 觸發
  ## Action: create
  ## Action: update
  ## Action: delete

# 錯誤做法（使用者看不到）
.github/prompts/my-create.prompt.md
.github/prompts/my-update.prompt.md
```

## 規則 2：文件語言遵循專案設定

**觸發條件：** 專案指定了回覆語言（如 AGENTS.md 中的 "Always respond in zhTW"）

AI 產出的**所有內容**（包含文件檔案）都必須使用專案指定的語言：

- 標題、說明文字、表格描述 -> 使用指定語言
- 程式碼區塊、檔案路徑、YAML 欄位名稱、CLI 指令 -> 保留英文

這條規則適用於：
- 新建的 `.md` 文件
- 更新現有文件的說明段落
- README 中新增的章節

## 規則 3：腳本一律使用 Node.js

**觸發條件：** 為 Copilot CLI 專案建立自動化腳本或工具時

使用 Node.js 而非 Python 或 Bash，確保 Windows 相容性：

- Copilot CLI 在 Windows 上運行，bash 腳本無法原生執行
- Python 可能未安裝，但 Node.js 一定可用
- 使用 Node.js 內建模組：`fs`、`path`、`os`、`child_process`

```
# 正確做法
scripts/copilot/instinct-cli.js     # Node.js，跨平台

# 避免
scripts/copilot/instinct-cli.py     # Python，可能未安裝
scripts/copilot/instinct-cli.sh     # Bash，Windows 不支援
```

## 來源本能

此 Skill 由以下本能演化而來：

| 本能 | 信心 | 關鍵證據 |
|------|------|---------|
| `copilot-skill-as-entry-point` | 85% | 使用者驗證 `/` 選單只顯示 skills |
| `docs-follow-response-language` | 70% | 使用者修正英文文件為中文 |
| `nodejs-for-copilot-scripts` | 70% | 從 Python 移植為 Node.js |