📦 金融業範例
├── 前台交易系統 → API 設計 Skill、風控規則 Skill
├── 中台核心系統 → 批次處理 Skill、資料轉換 Skill
├── 後台報表系統 → 報表生成 Skill、稽核檢查 Skill
└── 共用基礎設施 → CI/CD Skill、安全掃描 Skill

# ✅ 好的描述 - 清晰、具體、包含觸發條件
name: spring-boot-api-design
description: >
  Guide for designing RESTful APIs using Spring Boot 3.x with 
  Clean Architecture. Use this when asked to design, create, 
  or scaffold a new REST API endpoint.

# ❌ 壞的描述 - 模糊、無法明確觸發
name: api-stuff  
description: Helps with API things.

skill-name/
├── SKILL.md              # 核心：Metadata + 指令（必要）
├── scripts/              # 可執行腳本（選填）
│   ├── generate-openapi.sh
│   └── validate-api.py
├── references/           # 參考資料（選填）
│   ├── REFERENCE.md
│   ├── api-standards.md
│   └── error-codes.md
└── assets/               # 靜態資源（選填）
    ├── controller.java.template
    └── openapi.yaml.template

---
name: api-design
description: >
  Guide for designing RESTful APIs using Spring Boot 3.x.
  Use when asked to design or create REST API endpoints.
license: MIT
compatibility: Requires Java 21+ and Maven
metadata:
  author: platform-team
  version: "1.0"
allowed-tools: shell
---

# API Design Skill

## 觸發條件
- 使用者要求設計新的 API
- 使用者需要建立 Controller / DTO / Service

## 執行步驟
1. 分析需求，確認 API 端點
2. 設計 OpenAPI 規格
3. 生成 Controller、Service、Repository 程式碼
4. 建立對應的單元測試

## 設計規範
- 遵循 RESTful 設計原則
- 使用 Clean Architecture 分層
- DTO 與 Entity 分離
...

---
# === 必要欄位 ===
name: spring-boot-api-design
# 1-64 字元，僅限小寫英數字與連字號
# 不可以連字號開頭/結尾，不可連續連字號
# 必須與父目錄名稱一致

description: >
  Guide for designing RESTful APIs using Spring Boot 3.x 
  with Clean Architecture. Use this when asked to design, 
  create, or scaffold a new REST API endpoint.
# 1-1024 字元，應包含「做什麼」+「何時觸發」

# === 選填欄位 ===
license: MIT
# 授權條款（名稱或檔案引用）

compatibility: Requires Java 21+ and Maven
# 1-500 字元，環境需求（目標產品、系統套件、網路存取等）

metadata:
  author: platform-team
  version: "1.0"
  category: development
  ssdlc-phase: development
# 任意 key-value 對，供客戶端或企業內部使用

allowed-tools: Bash(git:*) Read Grep
# 空格分隔的工具清單，預核准在 Skill 啟動時使用
# ⚠️ 實驗性欄位，各 Agent 實作支援度不同
---

---
name: deploy-to-prod
description: Deploy the application to production
when_to_use: >
  Use when the user asks to deploy, release, push to production,
  or mentions "go live". Also triggered by CI/CD related questions.
# 額外觸發條件描述，附加在 description 後方
# description + when_to_use 合計上限 1,536 字元

arguments: [env, version]
# 具名位置參數（空格分隔或 YAML list）
# 定義後可在 Skill 內容中用 $env、$version 引用
# 按順序對應叫用時傳入的參數位置

# Claude Code 擴展欄位
argument-hint: "[env] [version]"
# 在自動完成選單中顯示的參數提示

disable-model-invocation: true
# 設 true 時 Claude 不會自動觸發此 Skill，僅能透過 /name 手動叫用
# 適用於有副作用的操作（如部署、發送訊息）

user-invocable: true
# 設 false 時從 / 選單隱藏，僅供 Claude 自動觸發
# 適用於背景知識類 Skill

context: fork
# 設為 fork 時在獨立 Subagent 中執行（隔離的上下文）

agent: Explore
# context: fork 時使用的 Subagent 類型
# 內建選項：Explore、Plan、general-purpose
# 或自訂 Subagent（.claude/agents/ 中定義）

model: claude-sonnet-4-20250514
# 執行此 Skill 時使用的模型（覆蓋 Session 預設）

effort: high
# 推理力度：low / medium / high / xhigh / max（max 僅限 Opus 4.6）

hooks:
  PreToolUse:
    - matcher: Bash
      hooks:
        - type: command
          command: echo "About to run bash"
# Skill 生命週期鉤子，格式參見 Hooks 文件

paths: "src/**/*.java, tests/**/*.java"
# Glob 模式，限制此 Skill 僅在處理匹配檔案時自動觸發

shell: bash
# !`command` 區塊使用的 Shell（bash 或 powershell）
---

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
argument-hint: "<issue-number>"
---

Fix GitHub issue #$ARGUMENTS following our coding standards.

1. Read the issue description
2. Understand the requirements
3. Implement the fix
4. Write tests
5. Create a commit

---
name: migrate-component
description: Migrate a component from one framework to another
argument-hint: "<component> <from-framework> <to-framework>"
---

Migrate the $0 component from $1 to $2.
Preserve all existing behavior and tests.

---
name: fix-and-branch
description: Fix a GitHub issue on a new branch
arguments: [issue, branch]
argument-hint: "<issue-number> <branch-name>"
disable-model-invocation: true
---

1. Checkout a new branch: $branch
2. Read GitHub issue #$issue
3. Implement the fix
4. Commit with message "fix: resolve #$issue"

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull Request 上下文
- PR diff: !`gh pr diff`
- PR 評論: !`gh pr view --comments`
- 變更檔案: !`gh pr diff --name-only`

## 你的任務
根據以上資訊摘要此 Pull Request...

📦 my-project/
├── .github/
│   ├── copilot-instructions.md   # 全局指令（每次都載入）
│   └── skills/                    # Skills 目錄
│       ├── api-design/
│       │   └── SKILL.md
│       ├── code-review/
│       │   └── SKILL.md
│       └── unit-test/
│           └── SKILL.md
├── src/
└── pom.xml

Custom Instructions（copilot-instructions.md / CLAUDE.md）
├── 專案概述
├── 命名規範
├── 分層架構要求
└── 基本安全規範

Skills（.github/skills/ 或 .claude/skills/）
├── api-design/          → 需要設計 API 時載入
├── code-review/         → 進行 Code Review 時載入
├── security-scan/       → 安全掃描時載入
├── db-migration/        → 資料庫異動時載入
└── batch-job-design/    → 設計批次程式時載入

# 方式 1：直接叫用（斜線命令）
/api-design 設計一個轉帳 API

# 方式 2：自動觸發（Claude 根據描述匹配）
使用者：「請幫我設計一個轉帳 API」
Claude：（自動載入匹配的 api-design Skill）→ 依規範產出 API 設計

# 方式 3：Subagent 執行（context: fork）
/deep-research 分析 src/auth 模組的安全性
# → 在獨立 Subagent（Explore Agent）中執行，結果回傳主對話

📦 org-copilot-skills/
├── README.md                      # 總覽與使用說明
├── CONTRIBUTING.md                # 貢獻指南
├── GOVERNANCE.md                  # 治理規範
├── catalog.yaml                   # Skills 目錄索引
│
├── core/                          # 核心 Skills（全公司適用）
│   ├── code-review/
│   ├── security-scan/
│   ├── api-design/
│   ├── unit-test-generation/
│   └── documentation/
│
├── domain/                        # 領域 Skills
│   ├── banking/                   # 銀行業
│   │   ├── transaction-api/
│   │   ├── risk-assessment/
│   │   └── regulatory-report/
│   ├── insurance/                 # 保險業
│   │   ├── claim-processing/
│   │   └── policy-management/
│   └── payment/                   # 支付業
│       ├── settlement/
│       └── reconciliation/
│
├── ssdlc/                         # SSDLC 階段 Skills
│   ├── requirements/
│   ├── design/
│   ├── development/
│   ├── testing/
│   ├── security/
│   ├── deployment/
│   └── maintenance/
│
├── templates/                     # Skill 建立範本
│   └── skill-template/
│       └── SKILL.md
│
└── scripts/                       # 共用腳本
    ├── validate-skill.py          # Skill 格式驗證
    └── sync-skills.sh             # Skills 同步至專案

# 搜尋特定主題的 Skills
gh skill search testing

# 預覽 Skill 內容（不安裝），用於安全審查
gh skill preview github/awesome-copilot documentation-writer

# 互動式安裝（瀏覽 Repository 中所有 Skills）
gh skill install github/awesome-copilot

# 直接安裝指定 Skill
gh skill install github/awesome-copilot documentation-writer

# 安裝特定版本（@TAG 或 @SHA）
gh skill install github/awesome-copilot documentation-writer@v1.2.0

# 鎖定版本（--pin），更新時跳過此 Skill
gh skill install github/awesome-copilot documentation-writer --pin v1.2.0

# 指定 Agent Host 與安裝範圍
gh skill install github/awesome-copilot documentation-writer --agent claude-code --scope user

# 互動式檢查更新
gh skill update

# 更新指定 Skill
gh skill update documentation-writer

# 更新所有已安裝 Skills（跳過 pinned）
gh skill update --all

# 驗證 Skills（不發布）
gh skill publish --dry-run

# 自動修復 metadata 問題
gh skill publish --fix

# 驗證並發布
gh skill publish

---
name: generate-user-story
description: >
  Generates User Stories with Acceptance Criteria from business 
  requirements. Use when asked to create user stories, write 
  acceptance criteria, or break down requirements into stories.
version: 1.0.0
category: requirements
ssdlc-phase: requirements
---

# User Story 生成 Skill

## 輸入要求
請提供以下資訊：
1. 業務需求描述
2. 目標使用者角色
3. 系統範圍

## User Story 格式
使用標準格式：

## 產出規範
1. 每個 Story 須符合 INVEST 原則
   - Independent（獨立）
   - Negotiable（可協商）
   - Valuable（有價值）
   - Estimable（可估算）
   - Small（小型）
   - Testable（可測試）

2. 每個 Story 至少包含 3 個驗收條件
3. 包含異常情境的驗收條件
4. 標注優先順序（P0 / P1 / P2）
5. 標注估算故事點（Story Points）

## 安全需求
- 涉及個資的 Story 須標注「PII」標籤
- 涉及金融交易的 Story 須標注「需安全審查」

📝 原始 Prompt：
「請根據以下需求，產出 User Story 和 Acceptance Criteria：
  使用者需要能在 ATM 進行跨行轉帳…」

📦 轉換為 Skill 後：
.github/skills/generate-user-story/
├── SKILL.md           # 標準化的 User Story 生成指令
├── references/
│   ├── invest-principles.md    # INVEST 原則說明
│   └── story-examples.md       # 範例 Story
└── templates/
    └── user-story.md.template  # Story 範本

---
name: generate-brd
description: >
  Generates Business Requirement Document (BRD) from meeting 
  notes, stakeholder interviews, or business context. Use when 
  asked to write BRD, document business requirements, or 
  formalize project scope.
metadata:
  version: "1.0"
  category: requirements
  ssdlc-phase: requirements
---

# BRD 生成 Skill

## 輸入要求
請提供以下資訊（至少一項）：
1. 會議記錄 / 訪談紀錄
2. 現有系統問題描述
3. 業務目標與願景

## BRD 標準結構

### 1. 專案概述（Executive Summary）
- 專案背景與動機
- 業務目標（量化指標）
- 預期效益（ROI 分析）

### 2. 範圍定義（Scope）
- In Scope（納入範圍）
- Out of Scope（排除範圍）
- 系統邊界圖

### 3. 利害關係人分析

| 角色 | 姓名/部門 | 關注點 | 影響力 |
|------|-----------|--------|--------|
| Sponsor | ... | ... | 高 |
| End User | ... | ... | 中 |

### 4. 業務需求清單

| 編號 | 需求描述 | 優先順序 | 來源 |
|------|----------|----------|------|
| BR-001 | ... | P0 | ... |

### 5. 非功能需求
- 效能：回應時間 < 2 秒
- 可用性：99.9% SLA
- 安全性：符合 ISO 27001

### 6. 限制與假設
- 限制條件
- 前提假設

### 7. 交付時程
- 里程碑列表
- 預估時程

## 產出規範
- 格式：Markdown 文件
- 需求編號：BR-XXX（三碼流水號）
- 每個需求須標注優先順序（P0 / P1 / P2）
- 每個需求須標注來源（哪次會議 / 誰提出）

## 安全需求
- 涉及個資處理的需求須標注「PII」
- 涉及法規遵循的需求須標注「Regulatory」

---
name: generate-frd
description: >
  Generates Functional Requirement Document (FRD) from BRD 
  or business requirements. Use when asked to write FRD, 
  detail functional specifications, or translate business 
  requirements into system functions.
metadata:
  version: "1.0"
  category: requirements
  ssdlc-phase: requirements
---

# FRD 生成 Skill

## 輸入要求
請提供以下資訊：
1. BRD 或業務需求描述
2. 系統架構概述（若有）
3. 現有介面規格（若有）

## FRD 標準結構

### 1. 功能概述
- 系統功能清單
- 功能層級分解（Feature → Function → Sub-function）

### 2. 功能規格
對每個功能項目，須包含：

```text
#### F-001：[功能名稱]

**對應業務需求**：BR-001
**功能描述**：[一段話描述此功能]
**觸發條件**：[何時觸發此功能]
**前置條件**：[執行前須滿足的條件]

**主要流程**：
  1. 使用者 [操作]
  2. 系統 [回應]
  3. ...

**替代流程**：
  - 2a. 若 [條件]，則 [處理]

**例外流程**：
  - E1. 若 [錯誤]，顯示 [錯誤訊息]

**後置條件**：[執行後的系統狀態]

**業務規則**：
  - Rule-001：[規則描述]

**畫面需求**：[畫面原型參考]

**資料需求**：
  | 欄位 | 型別 | 必填 | 說明 |
  |------|------|------|------|
  | accountId | String | ✅ | 帳號編號 |
  | amount | BigDecimal | ✅ | 交易金額 |

**範例：需求追溯矩陣 Skill**

```markdown
---
name: requirement-traceability
description: >
  Builds Requirement Traceability Matrix (RTM) linking business 
  requirements to functional specs, design, code, and test cases. 
  Use when asked to create traceability matrix, verify requirement 
  coverage, or audit requirement completeness.
metadata:
  version: "1.0"
  category: requirements
  ssdlc-phase: requirements
---

# 需求追溯矩陣（RTM）生成 Skill

## 追溯矩陣結構

### 前向追溯（Forward Traceability）
從業務需求追溯到實作：

| 業務需求 | 功能需求 | 設計文件 | 程式模組 | 測試案例 | 狀態 |
|----------|----------|----------|----------|----------|------|
| BR-001 | F-001 | DD-001 | TransferService.java | TC-001, TC-002 | ✅ |
| BR-002 | F-003 | DD-002 | AccountController.java | TC-005 | ✅ |
| BR-003 | — | — | — | — | ❌ 未實作 |

### 反向追溯（Backward Traceability）
從程式碼追溯到業務需求：

| 程式模組 | 設計文件 | 功能需求 | 業務需求 |
|----------|----------|----------|----------|
| TransferService.java | DD-001 | F-001 | BR-001 |
| OrphanUtil.java | — | — | ⚠️ 無對應需求 |

## 分析指標
1. **需求覆蓋率**：已實作需求 / 總需求數 × 100%
2. **測試覆蓋率**：有測試的需求 / 已實作需求 × 100%
3. **孤兒程式碼**：無法追溯到需求的程式模組
4. **未實作需求**：尚未對應到任何功能的業務需求

## 產出規範
- 格式：Markdown 表格 + 覆蓋率統計摘要
- 標注所有缺口（Gap）並建議處理方式
- 孤兒程式碼須標注風險等級
- 未實作需求須標注延遲原因與預計時程

---
name: clean-architecture-api
description: >
  Designs RESTful APIs following Clean Architecture and DDD 
  principles for Spring Boot 3.x projects. Use when asked to 
  design system architecture, create API specs, or scaffold 
  a new microservice.
version: 2.0.0
category: design
ssdlc-phase: design
---
# Clean Architecture API 設計 Skill

## 分層規範

```text
src/main/java/com/company/service/
├── adapter/                  # 介面轉接器層
│   ├── in/
│   │   ├── web/             # REST Controller
│   │   └── messaging/       # MQ Consumer
│   └── out/
│       ├── persistence/     # JPA Repository
│       └── external/        # 外部 API Client
├── application/              # 應用層
│   ├── port/
│   │   ├── in/              # Use Case 介面
│   │   └── out/             # Repository 介面
│   └── service/             # Use Case 實作
├── domain/                   # 領域層
│   ├── model/               # Entity / Value Object
│   ├── event/               # Domain Event
│   └── exception/           # Domain Exception
└── config/                   # 設定
    └── BeanConfig.java

**範例：系統架構設計 Skill**

```markdown
---
name: architecture-design
description: >
  Designs system architecture using C4 Model and generates 
  architecture diagrams in Mermaid format. Use when asked to 
  design system architecture, draw architecture diagrams, 
  or evaluate architectural decisions.
metadata:
  version: "1.0"
  category: design
  ssdlc-phase: design
---

# 系統架構設計 Skill（C4 Model）

## C4 Model 四層結構

### Level 1：System Context Diagram（系統上下文圖）
描述系統與外部使用者、外部系統的互動關係。

```mermaid
graph TB
    User[客戶<br/>使用網路銀行] --> System[網路銀行系統]
    Admin[行員<br/>管理後台] --> System
    System --> CoreBanking[核心銀行系統<br/>外部系統]
    System --> EmailGW[Email Gateway<br/>外部系統]
    System --> SMSGW[SMS Gateway<br/>外部系統]

# ADR-001：選擇 PostgreSQL 作為主資料庫

## 狀態
已採納（Accepted）

## 上下文
系統需要支援 ACID 交易、JSON 查詢、高併發讀寫。

## 決策
採用 PostgreSQL 15+。

## 理由
- 完整的 ACID 支援
- 原生 JSONB 欄位支援
- 成熟的生態系與社群

## 後果
- 需要 DBA 維運能力
- 水平擴展需搭配 Read Replica

**範例：資料庫設計 Skill**

```markdown
---
name: database-design
description: >
  Designs database schema including ER Model, DDL scripts, 
  and migration files for relational databases. Use when asked 
  to design database, create ER diagram, write DDL, or plan 
  database migration.
metadata:
  version: "1.0"
  category: design
  ssdlc-phase: design
---

# 資料庫設計 Skill

## ER Model 設計（使用 Mermaid）

```mermaid
erDiagram
    ACCOUNT ||--o{ TRANSACTION : "發起"
    ACCOUNT {
        bigint id PK
        varchar account_no UK "帳號（唯一）"
        varchar account_name "戶名"
        decimal balance "餘額"
        varchar status "狀態：ACTIVE/FROZEN/CLOSED"
        timestamp created_at
        timestamp updated_at
    }
    TRANSACTION {
        bigint id PK
        varchar txn_no UK "交易編號"
        bigint from_account_id FK
        bigint to_account_id FK
        decimal amount "交易金額"
        varchar txn_type "類型：TRANSFER/DEPOSIT/WITHDRAW"
        varchar status "狀態：PENDING/SUCCESS/FAILED"
        varchar description "摘要"
        timestamp created_at
    }
    TRANSACTION }o--|| AUDIT_LOG : "記錄"
    AUDIT_LOG {
        bigint id PK
        varchar entity_type "實體類型"
        bigint entity_id "實體 ID"
        varchar action "操作：CREATE/UPDATE/DELETE"
        jsonb old_value "變更前"
        jsonb new_value "變更後"
        varchar operator "操作者"
        timestamp created_at
    }

-- 命名規範
-- 表名：snake_case，複數形式
-- 欄位名：snake_case
-- 索引名：idx_{table}_{column}
-- 外鍵名：fk_{table}_{ref_table}
-- 唯一約束：uk_{table}_{column}

CREATE TABLE accounts (
    id            BIGSERIAL       PRIMARY KEY,
    account_no    VARCHAR(20)     NOT NULL UNIQUE,
    account_name  VARCHAR(100)    NOT NULL,
    balance       DECIMAL(18, 2)  NOT NULL DEFAULT 0.00,
    status        VARCHAR(20)     NOT NULL DEFAULT 'ACTIVE',
    created_at    TIMESTAMP       NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at    TIMESTAMP       NOT NULL DEFAULT CURRENT_TIMESTAMP,
    
    CONSTRAINT chk_balance_non_negative CHECK (balance >= 0),
    CONSTRAINT chk_status CHECK (status IN ('ACTIVE', 'FROZEN', 'CLOSED'))
);

CREATE INDEX idx_accounts_status ON accounts(status);

-- Flyway Migration 命名：V{version}__{description}.sql
-- 範例：V1.0__create_accounts_table.sql

**範例：DDD 領域建模 Skill**

```markdown
---
name: ddd-modeling
description: >
  Performs Domain-Driven Design modeling including Bounded 
  Context identification, Aggregate design, Entity/Value 
  Object definition, and Domain Event mapping. Use when asked 
  to do DDD modeling, design domain model, or identify 
  bounded contexts.
metadata:
  version: "1.0"
  category: design
  ssdlc-phase: design
---

# DDD 領域建模 Skill

## Step 1：識別 Bounded Context

```mermaid
graph TB
    subgraph "帳戶管理 Context"
        A1[Account Aggregate]
        A2[Customer Entity]
    end
    
    subgraph "交易 Context"
        T1[Transaction Aggregate]
        T2[Transfer Service]
    end
    
    subgraph "通知 Context"
        N1[Notification Service]
        N2[Template Entity]
    end
    
    A1 -->|Account Created Event| T1
    T1 -->|Transaction Completed Event| N1

    style A1 fill:#4CAF50,color:#fff
    style T1 fill:#2196F3,color:#fff
    style N1 fill:#FF9800,color:#fff

// Aggregate Root
public class Transaction {
    private TransactionId id;           // Entity ID（Value Object）
    private AccountId fromAccount;      // Value Object
    private AccountId toAccount;        // Value Object
    private Money amount;               // Value Object
    private TransactionStatus status;   // Enum
    private List<DomainEvent> events;   // Domain Events
    
    // 業務行為封裝在 Aggregate 內
    public void execute() {
        validate();
        this.status = TransactionStatus.SUCCESS;
        events.add(new TransactionCompletedEvent(this));
    }
    
    private void validate() {
        if (amount.isNegativeOrZero()) {
            throw new InvalidAmountException("金額必須大於零");
        }
        if (fromAccount.equals(toAccount)) {
            throw new SameAccountTransferException("不可轉帳至同一帳戶");
        }
    }
}

// Value Object（不可變、無 ID、以值比較）
public record Money(BigDecimal amount, Currency currency) {
    public Money {
        if (amount == null || amount.compareTo(BigDecimal.ZERO) < 0) {
            throw new IllegalArgumentException("金額不可為負");
        }
    }
    public boolean isNegativeOrZero() {
        return amount.compareTo(BigDecimal.ZERO) <= 0;
    }
    public Money add(Money other) {
        return new Money(this.amount.add(other.amount), this.currency);
    }
}

**範例：UI/UX 設計 Skill**

```markdown
---
name: uiux-design
description: >
  Generates UI/UX design specifications including wireframe 
  descriptions, component guidelines, interaction flows, 
  responsive layout rules, and accessibility (a11y) checklist. 
  Use when asked to design user interface, create wireframes, 
  define design system components, or review UX flows.
metadata:
  version: "1.0"
  category: design
  ssdlc-phase: design
---

# UI/UX 設計 Skill

## 輸入要求
請提供以下資訊（至少一項）：
1. 功能需求描述（FRD）或 User Story
2. 目標使用者角色（Persona）
3. 現有畫面截圖或設計稿（若有）
4. 設計系統 / Brand Guideline（若有）

## 設計產出結構

### 1. 使用者流程圖（User Flow）

使用 Mermaid 繪製使用者操作流程：

```mermaid
graph TD
    Start([進入頁面]) --> Auth{已登入?}
    Auth -->|否| Login[登入頁面]
    Auth -->|是| Dashboard[儀表板]
    Login --> |登入成功| Dashboard
    Login --> |登入失敗| ErrMsg[顯示錯誤訊息]
    ErrMsg --> Login
    Dashboard --> Action[執行功能操作]
    Action --> Confirm{需要確認?}
    Confirm -->|是| Dialog[確認對話框]
    Confirm -->|否| Result[顯示結果]
    Dialog -->|確認| Result
    Dialog -->|取消| Dashboard
    Result --> Feedback[Toast 回饋訊息]
    Feedback --> Dashboard

#### Page-001：[頁面名稱]

**對應功能需求**：F-001
**頁面用途**：[一段話描述此頁面目的]
**進入條件**：[使用者如何到達此頁面]

**頁面佈局（Layout）**：
┌─────────────────────────────────────┐
│  Header（Logo / Nav / User Menu）   │
├──────────┬──────────────────────────┤
│ Sidebar  │  Main Content Area       │
│ - Nav 1  │  ┌──────────────────┐    │
│ - Nav 2  │  │  Search / Filter  │    │
│ - Nav 3  │  ├──────────────────┤    │
│          │  │  Data Table /     │    │
│          │  │  Card Grid        │    │
│          │  ├──────────────────┤    │
│          │  │  Pagination       │    │
├──────────┴──────────────────────────┤
│  Footer（Copyright / Links）        │
└─────────────────────────────────────┘

**元件清單**：
| 元件 | 類型 | 說明 | 互動行為 |
|------|------|------|----------|
| 搜尋欄 | Input + Button | 關鍵字搜尋 | 輸入後按 Enter 或點擊搜尋 |
| 資料表 | Table | 顯示交易清單 | 可排序、可分頁 |
| 操作按鈕 | Button Group | 新增/編輯/刪除 | 刪除需二次確認 |

**狀態變化**：
- 空狀態（Empty State）：顯示引導文字與操作按鈕
- 載入中（Loading）：Skeleton Screen
- 錯誤狀態（Error）：錯誤訊息與重試按鈕
- 成功狀態（Success）：Toast 通知

> **🏦 金融業實務案例**：某銀行的網路銀行改版專案，將轉帳頁面、帳戶總覽、交易明細等 UI 設計規格封裝為 Skills，新進前端工程師只需輸入功能需求，即可產出符合企業 Design System 的 Wireframe 規格、元件清單與無障礙檢核報告，大幅縮短從設計到開發的銜接時間。

### 3.3 Development（開發階段）

**可轉換為 Skills 的內容**：

| 常見工作 | 轉換為 Skill | 說明 |
|----------|-------------|------|
| 程式碼生成 | `spring-boot-codegen` | 產出 Spring Boot 元件程式碼 |
| Code Review | `code-review-checklist` | 依企業規範進行程式碼審查 |
| 重構 | `refactoring-patterns` | 引導常用重構手法 |
| 程式碼規範 | `coding-standards` | 企業程式碼風格檢查 |

**範例：Spring Boot Code Generation Skill**

```markdown
---
name: spring-boot-codegen
description: >
  Generates Spring Boot 3.x components following enterprise 
  coding standards. Use when asked to create controllers, 
  services, repositories, DTOs, or complete CRUD endpoints.
version: 1.5.0
category: development
ssdlc-phase: development
---

# Spring Boot 程式碼生成 Skill

## Controller 規範

```java
@RestController
@RequestMapping("/api/v1/transactions")
@RequiredArgsConstructor
@Slf4j
public class TransactionController {

    private final TransactionUseCase transactionUseCase;

    /**
     * 查詢交易記錄
     * 
     * @param request 查詢條件
     * @return 交易記錄列表
     */
    @GetMapping
    public ResponseEntity<PageResponse<TransactionResponse>> 
            getTransactions(@Valid TransactionQueryRequest request) {
        log.info("查詢交易記錄: {}", request);
        var result = transactionUseCase.query(request.toDomain());
        return ResponseEntity.ok(PageResponse.of(result));
    }
}

@Service
@RequiredArgsConstructor
@Slf4j
public class TransactionService implements TransactionUseCase {

    private final TransactionRepository transactionRepository;
    private final EventPublisher eventPublisher;

    @Override
    @Transactional
    public TransactionResult execute(TransactionCommand command) {
        // 1. 驗證業務規則
        validate(command);
        
        // 2. 執行核心邏輯
        var transaction = Transaction.create(command);
        var saved = transactionRepository.save(transaction);
        
        // 3. 發布領域事件
        eventPublisher.publish(new TransactionCreatedEvent(saved));
        
        // 4. 回傳結果
        return TransactionResult.from(saved);
    }
}

**範例：Code Review Skill**

```markdown
---
name: code-review-standard
description: >
  Performs code review following enterprise coding standards 
  and security guidelines. Use when asked to review code, 
  check code quality, or perform pull request review.
version: 2.1.0
category: development
ssdlc-phase: development
---

# 程式碼審查 Skill

## 審查維度

### 1. 安全性（Security）—— 最高優先
- [ ] 無 SQL Injection 風險（使用 Parameterized Query）
- [ ] 無 XSS 風險（輸入已 Sanitize）
- [ ] 敏感資料已加密 / 遮罩
- [ ] 無硬編碼密碼 / API Key
- [ ] 適當的權限檢查

### 2. 正確性（Correctness）
- [ ] 業務邏輯正確
- [ ] 邊界條件處理
- [ ] Null 值處理
- [ ] 併發安全（Thread Safety）

### 3. 可維護性（Maintainability）
- [ ] 命名清晰有意義
- [ ] 方法長度 < 30 行
- [ ] 類別職責單一（SRP）
- [ ] 適當的抽象層級

### 4. 效能（Performance）
- [ ] 無 N+1 查詢問題
- [ ] 適當使用快取
- [ ] 批次處理大量資料
- [ ] 資料庫索引適當

### 5. 測試（Testing）
- [ ] 單元測試覆蓋主要路徑
- [ ] 異常路徑有測試
- [ ] 測試可重複執行

---
name: refactoring-patterns
description: >
  Guides common refactoring techniques including Extract Method, 
  Replace Conditional with Polymorphism, and Introduce Parameter 
  Object. Use when asked to refactor code, improve code structure, 
  reduce code smells, or simplify complex methods.
metadata:
  version: "1.0"
  category: development
  ssdlc-phase: development
---

# 重構模式 Skill

## Code Smell 識別與對應重構手法

| Code Smell | 識別標準 | 推薦重構手法 |
|------------|----------|-------------|
| **Long Method** | 方法 > 30 行 | Extract Method |
| **Large Class** | 類別 > 300 行或職責 > 2 個 | Extract Class |
| **Long Parameter List** | 參數 > 4 個 | Introduce Parameter Object |
| **Duplicated Code** | 相似邏輯出現 ≥ 2 處 | Extract Method / Template Method |
| **Switch / If-else 鏈** | ≥ 3 個分支依型別判斷 | Replace Conditional with Polymorphism |
| **Feature Envy** | 方法大量使用其他類別資料 | Move Method |
| **Data Clump** | 同一組參數反覆出現 | Extract Class / Parameter Object |
| **Primitive Obsession** | 用基本型別表達領域概念 | Replace Primitive with Value Object |

## 重構範例 1：Extract Method

```java
// ❌ 重構前：方法職責過多
public void processOrder(Order order) {
    // 驗證訂單（10 行）
    if (order.getItems().isEmpty()) { throw new EmptyOrderException(); }
    if (order.getTotalAmount().compareTo(BigDecimal.ZERO) <= 0) { throw new InvalidAmountException(); }
    
    // 計算折扣（15 行）
    BigDecimal discount = BigDecimal.ZERO;
    if (order.getMemberLevel().equals("VIP")) {
        discount = order.getTotalAmount().multiply(new BigDecimal("0.1"));
    } else if (order.getMemberLevel().equals("GOLD")) {
        discount = order.getTotalAmount().multiply(new BigDecimal("0.05"));
    }
    order.setDiscount(discount);
    
    // 儲存與通知（10 行）
    orderRepository.save(order);
    notificationService.sendConfirmation(order);
}

// ✅ 重構後：各方法職責單一
public void processOrder(Order order) {
    validateOrder(order);
    applyDiscount(order);
    completeOrder(order);
}

private void validateOrder(Order order) {
    if (order.getItems().isEmpty()) { throw new EmptyOrderException(); }
    if (order.getTotalAmount().compareTo(BigDecimal.ZERO) <= 0) { throw new InvalidAmountException(); }
}

private void applyDiscount(Order order) {
    BigDecimal rate = discountRateFor(order.getMemberLevel());
    order.setDiscount(order.getTotalAmount().multiply(rate));
}

private void completeOrder(Order order) {
    orderRepository.save(order);
    notificationService.sendConfirmation(order);
}

// ❌ 重構前：switch 依型別分派邏輯
public BigDecimal calculateFee(Transaction txn) {
    switch (txn.getType()) {
        case "TRANSFER": return txn.getAmount().multiply(new BigDecimal("0.001"));
        case "WITHDRAW": return new BigDecimal("15");
        case "DEPOSIT": return BigDecimal.ZERO;
        default: throw new UnsupportedOperationException();
    }
}

// ✅ 重構後：策略模式
public interface FeeCalculator {
    BigDecimal calculate(Transaction txn);
}

public class TransferFeeCalculator implements FeeCalculator {
    public BigDecimal calculate(Transaction txn) {
        return txn.getAmount().multiply(new BigDecimal("0.001"));
    }
}

public class WithdrawFeeCalculator implements FeeCalculator {
    public BigDecimal calculate(Transaction txn) {
        return new BigDecimal("15");
    }
}

// 使用 Map 取代 switch
private final Map<String, FeeCalculator> calculators = Map.of(
    "TRANSFER", new TransferFeeCalculator(),
    "WITHDRAW", new WithdrawFeeCalculator(),
    "DEPOSIT", txn -> BigDecimal.ZERO
);

**範例：程式碼規範 Skill**

```markdown
---
name: coding-standards
description: >
  Enforces enterprise coding standards for Java/Spring Boot 
  projects including naming conventions, code structure, and 
  documentation requirements. Use when asked to check coding 
  standards, enforce code style, or review naming conventions.
metadata:
  version: "2.0"
  category: development
  ssdlc-phase: development
---

# 企業程式碼規範 Skill

## 命名規範

| 元素 | 規則 | 正確範例 | 錯誤範例 |
|------|------|----------|----------|
| **類別** | PascalCase，名詞 | `TransactionService` | `transactionService`、`TxnSvc` |
| **介面** | PascalCase，名詞/形容詞 | `TransactionRepository` | `ITransactionRepository`（不加 I 前綴） |
| **方法** | camelCase，動詞開頭 | `findByAccountId()` | `accountIdFind()` |
| **變數** | camelCase，有意義名稱 | `accountBalance` | `ab`、`temp`、`data` |
| **常數** | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` | `maxRetryCount` |
| **Package** | 全小寫，點分隔 | `com.company.service.transaction` | `com.Company.Service` |
| **DTO** | 後綴 Request/Response | `TransferRequest` | `TransferDto`（不用 Dto 後綴） |
| **Enum** | PascalCase，值為 UPPER_SNAKE | `TransactionStatus.PENDING` | `transactionStatus.pending` |

## 結構規範

```java
// 檔案結構順序（由上至下）
public class ExampleService {
    // 1. 靜態常數
    private static final int MAX_RETRY = 3;
    
    // 2. 實例變數（final 優先）
    private final TransactionRepository repository;
    private final EventPublisher publisher;
    
    // 3. 建構子
    // 4. public 方法（業務方法）
    // 5. package-private 方法
    // 6. protected 方法
    // 7. private 方法（輔助方法）
}

### 3.4 Testing（測試階段）

**可轉換為 Skills 的內容**：

| 常見工作 | 轉換為 Skill | 說明 |
|----------|-------------|------|
| 單元測試生成 | `junit-test-gen` | 產出 JUnit 5 測試程式碼 |
| 整合測試 | `integration-test-gen` | 產出 Spring Boot 整合測試 |
| API 測試 | `api-test-gen` | 產出 REST API 測試案例 |
| 測試案例設計 | `test-case-design` | 依據等價類別 / 邊界值設計測試案例 |

**範例：JUnit 測試生成 Skill**

```markdown
---
name: junit-test-generation
description: >
  Generates comprehensive JUnit 5 test cases for Java classes 
  following AAA (Arrange-Act-Assert) pattern. Use when asked 
  to write tests, generate unit tests, or improve test coverage.
version: 1.3.0
category: testing
ssdlc-phase: testing
---

# JUnit 5 測試生成 Skill

## 測試命名規範

## 測試結構（AAA Pattern）

```java
@ExtendWith(MockitoExtension.class)
class TransactionServiceTest {

    @Mock
    private TransactionRepository transactionRepository;
    
    @Mock
    private EventPublisher eventPublisher;
    
    @InjectMocks
    private TransactionService transactionService;

    @Test
    @DisplayName("執行轉帳 - 餘額充足時 - 應成功扣款並發布事件")
    void execute_whenBalanceSufficient_shouldDebitAndPublishEvent() {
        // Arrange
        var command = TransactionCommand.builder()
                .fromAccount("A001")
                .toAccount("B001")
                .amount(BigDecimal.valueOf(1000))
                .build();
        
        when(transactionRepository.save(any()))
                .thenReturn(Transaction.of("TXN001", command));
        
        // Act
        var result = transactionService.execute(command);
        
        // Assert
        assertThat(result).isNotNull();
        assertThat(result.getStatus()).isEqualTo("SUCCESS");
        verify(eventPublisher).publish(any(TransactionCreatedEvent.class));
    }
    
    @Test
    @DisplayName("執行轉帳 - 餘額不足時 - 應拋出 InsufficientBalanceException")
    void execute_whenBalanceInsufficient_shouldThrowException() {
        // Arrange
        var command = TransactionCommand.builder()
                .fromAccount("A001")
                .amount(BigDecimal.valueOf(999999999))
                .build();
        
        // Act & Assert
        assertThatThrownBy(() -> transactionService.execute(command))
                .isInstanceOf(InsufficientBalanceException.class)
                .hasMessageContaining("餘額不足");
    }
}

**範例：整合測試生成 Skill**

```markdown
---
name: integration-test-gen
description: >
  Generates Spring Boot integration tests using @SpringBootTest, 
  TestContainers, and MockMvc. Use when asked to write integration 
  tests, create end-to-end API tests, or test with real database.
metadata:
  version: "1.0"
  category: testing
  ssdlc-phase: testing
---

# Spring Boot 整合測試生成 Skill

## 整合測試架構

```text
src/test/java/
├── integration/                    # 整合測試
│   ├── BaseIntegrationTest.java    # 基底類別（共用設定）
│   ├── TransactionApiTest.java     # API 端到端測試
│   └── TransactionFlowTest.java    # 業務流程測試
└── resources/
    ├── application-test.yml         # 測試環境設定
    └── testdata/
        └── transactions.json        # 測試資料

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@ActiveProfiles("test")
@Testcontainers
public abstract class BaseIntegrationTest {

    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15-alpine")
            .withDatabaseName("testdb")
            .withUsername("test")
            .withPassword("test");

    @DynamicPropertySource
    static void configureProperties(DynamicPropertyRegistry registry) {
        registry.add("spring.datasource.url", postgres::getJdbcUrl);
        registry.add("spring.datasource.username", postgres::getUsername);
        registry.add("spring.datasource.password", postgres::getPassword);
    }

    @Autowired
    protected TestRestTemplate restTemplate;

    @Autowired
    protected ObjectMapper objectMapper;
}

class TransactionApiTest extends BaseIntegrationTest {

    @Autowired
    private AccountRepository accountRepository;

    @BeforeEach
    void setUp() {
        accountRepository.deleteAll();
        accountRepository.save(Account.builder()
                .accountNo("A001").accountName("測試帳戶A")
                .balance(BigDecimal.valueOf(10000)).status("ACTIVE")
                .build());
    }

    @Test
    @DisplayName("POST /api/v1/transactions — 轉帳成功應回傳 201")
    void createTransaction_shouldReturn201_whenValid() {
        // Arrange
        var request = new TransferRequest("A001", "B001", BigDecimal.valueOf(1000));

        // Act
        var response = restTemplate.postForEntity(
                "/api/v1/transactions", request, TransactionResponse.class);

        // Assert
        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.CREATED);
        assertThat(response.getBody().getStatus()).isEqualTo("SUCCESS");
        
        // 驗證資料庫狀態
        var account = accountRepository.findByAccountNo("A001").orElseThrow();
        assertThat(account.getBalance()).isEqualByComparingTo("9000.00");
    }

    @Test
    @DisplayName("POST /api/v1/transactions — 餘額不足應回傳 400")
    void createTransaction_shouldReturn400_whenInsufficientBalance() {
        var request = new TransferRequest("A001", "B001", BigDecimal.valueOf(99999));

        var response = restTemplate.postForEntity(
                "/api/v1/transactions", request, ErrorResponse.class);

        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.BAD_REQUEST);
        assertThat(response.getBody().getCode()).isEqualTo("INSUFFICIENT_BALANCE");
    }
}

**範例：API 測試案例生成 Skill**

```markdown
---
name: api-test-gen
description: >
  Generates REST API test cases covering positive, negative, 
  boundary, and security scenarios. Use when asked to create 
  API tests, write REST endpoint tests, or generate test 
  collections for API validation.
metadata:
  version: "1.0"
  category: testing
  ssdlc-phase: testing
---

# REST API 測試案例生成 Skill

## 測試案例分類

### 1. 正向測試（Positive Tests）

| 測試編號 | 測試描述 | HTTP Method | 預期狀態碼 |
|----------|----------|-------------|-----------|
| TC-P-001 | 查詢全部資源（無參數） | GET /api/v1/resources | 200 |
| TC-P-002 | 查詢單一資源（有效 ID） | GET /api/v1/resources/{id} | 200 |
| TC-P-003 | 建立資源（完整必填欄位） | POST /api/v1/resources | 201 |
| TC-P-004 | 更新資源（有效資料） | PUT /api/v1/resources/{id} | 200 |
| TC-P-005 | 刪除資源（有效 ID） | DELETE /api/v1/resources/{id} | 204 |

### 2. 負向測試（Negative Tests）

| 測試編號 | 測試描述 | 預期狀態碼 | 預期錯誤 |
|----------|----------|-----------|---------|
| TC-N-001 | 查詢不存在的資源 | 404 | RESOURCE_NOT_FOUND |
| TC-N-002 | 建立資源（缺少必填欄位） | 400 | VALIDATION_ERROR |
| TC-N-003 | 建立資源（欄位格式錯誤） | 400 | VALIDATION_ERROR |
| TC-N-004 | 建立重複資源 | 409 | DUPLICATE_RESOURCE |
| TC-N-005 | 未授權存取 | 401 | UNAUTHORIZED |
| TC-N-006 | 權限不足 | 403 | FORBIDDEN |

### 3. 邊界值測試（Boundary Tests）

| 測試編號 | 測試描述 | 測試資料 | 預期結果 |
|----------|----------|----------|----------|
| TC-B-001 | 字串欄位最大長度 | 100 字元（上限） | 200 成功 |
| TC-B-002 | 字串欄位超過上限 | 101 字元 | 400 驗證失敗 |
| TC-B-003 | 數值欄位最小值 | 0.01 | 200 成功 |
| TC-B-004 | 數值欄位為零 | 0 | 400 驗證失敗 |
| TC-B-005 | 分頁 — 第一頁 | page=0, size=20 | 200 成功 |
| TC-B-006 | 分頁 — 超大頁碼 | page=999999 | 200 空結果 |

### 4. 安全測試（Security Tests）

| 測試編號 | 測試描述 | 預期結果 |
|----------|----------|----------|
| TC-S-001 | SQL Injection（`' OR 1=1 --`） | 400 或正常回應（不洩漏資料） |
| TC-S-002 | XSS（`<script>alert(1)</script>`） | 輸入被拒絕或正確跳脫 |
| TC-S-003 | 過期 Token 存取 | 401 |
| TC-S-004 | 竄改他人資源 ID（IDOR） | 403 |
| TC-S-005 | 超大 Payload（> 1MB） | 413 |

## MockMvc 測試範本

```java
@WebMvcTest(TransactionController.class)
class TransactionControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @MockBean
    private TransactionUseCase transactionUseCase;

    @Test
    @DisplayName("GET /api/v1/transactions — 查詢成功回傳 200")
    void list_shouldReturn200() throws Exception {
        when(transactionUseCase.query(any())).thenReturn(Page.empty());

        mockMvc.perform(get("/api/v1/transactions")
                        .param("page", "0")
                        .param("size", "20")
                        .contentType(MediaType.APPLICATION_JSON))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.content").isArray());
    }

    @Test
    @DisplayName("POST /api/v1/transactions — 缺少必填欄位回傳 400")
    void create_shouldReturn400_whenMissingRequired() throws Exception {
        var invalidRequest = "{}";

        mockMvc.perform(post("/api/v1/transactions")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content(invalidRequest))
                .andExpect(status().isBadRequest())
                .andExpect(jsonPath("$.code").value("VALIDATION_ERROR"));
    }
}

**範例：測試案例設計 Skill**

```markdown
---
name: test-case-design
description: >
  Designs test cases using equivalence partitioning, boundary 
  value analysis, decision table, and state transition techniques. 
  Use when asked to design test cases, plan test strategy, or 
  create test coverage matrix.
metadata:
  version: "1.0"
  category: testing
  ssdlc-phase: testing
---

# 測試案例設計 Skill

## 設計技術

### 1. 等價類別劃分（Equivalence Partitioning）

將輸入資料分為有效等價類別與無效等價類別，每類別取一代表值。

**範例：轉帳金額**

| 等價類別 | 範圍 | 代表值 | 預期結果 |
|----------|------|--------|----------|
| 無效（負數） | < 0 | -100 | 拒絕 |
| 無效（零） | 0 | 0 | 拒絕 |
| 有效（正常） | 1 ~ 1,000,000 | 5000 | 接受 |
| 無效（超過上限） | > 1,000,000 | 2,000,000 | 拒絕 |

### 2. 邊界值分析（Boundary Value Analysis）

針對等價類別的邊界值進行測試。

**範例：轉帳金額（上限 1,000,000）**

| 邊界 | 測試值 | 預期結果 |
|------|--------|----------|
| 最小值 - 1 | 0 | 拒絕 |
| 最小值 | 1 | 接受 |
| 最小值 + 1 | 2 | 接受 |
| 最大值 - 1 | 999,999 | 接受 |
| 最大值 | 1,000,000 | 接受 |
| 最大值 + 1 | 1,000,001 | 拒絕 |

### 3. 決策表（Decision Table）

多條件組合判斷。

**範例：轉帳權限判斷**

| 條件 \ 規則 | R1 | R2 | R3 | R4 | R5 |
|-------------|----|----|----|----|-----|
| 帳戶狀態 = ACTIVE | Y | Y | Y | N | - |
| 餘額 ≥ 轉帳金額 | Y | Y | N | - | - |
| 未超過日限額 | Y | N | - | - | - |
| **動作** | 轉帳成功 | 拒絕（超限額） | 拒絕（餘額不足） | 拒絕（帳戶凍結） | 拒絕 |

### 4. 狀態轉換（State Transition）

```mermaid
stateDiagram-v2
    [*] --> PENDING : 建立交易
    PENDING --> PROCESSING : 開始處理
    PROCESSING --> SUCCESS : 處理成功
    PROCESSING --> FAILED : 處理失敗
    FAILED --> PENDING : 重試
    SUCCESS --> [*]
    FAILED --> [*] : 超過重試上限

### 3.5 Security（安全）

**可轉換為 Skills 的內容**：

| 常見工作 | 轉換為 Skill | 說明 |
|----------|-------------|------|
| OWASP 檢查 | `owasp-security-check` | 依 OWASP Top 10 進行安全審查 |
| Secure Coding | `secure-coding-guide` | 安全編碼規範指引 |
| 弱點掃描 | `vulnerability-scan` | 整合弱掃工具 |
| 敏感資料保護 | `data-protection` | PII 資料處理規範 |

**範例：OWASP 安全檢查 Skill**

```markdown
---
name: owasp-security-review
description: >
  Reviews code against OWASP Top 10 2025 vulnerabilities. 
  Use when asked to perform security review, check for 
  vulnerabilities, or audit code security.
version: 3.0.0
category: security
ssdlc-phase: security
---

# OWASP Top 10 安全審查 Skill

## 檢查項目

### A01: Broken Access Control（存取控制失效）
- [ ] 每個 API 端點都有權限檢查
- [ ] 使用 RBAC 不使用硬編碼角色
- [ ] 防止 IDOR（Insecure Direct Object Reference）
- [ ] 實作 Rate Limiting

```java
// ✅ 正確：使用 Spring Security 注解
@PreAuthorize("hasRole('ADMIN') or #userId == authentication.principal.id")
@GetMapping("/users/{userId}")
public UserResponse getUser(@PathVariable Long userId) { ... }

// ❌ 錯誤：無權限檢查
@GetMapping("/users/{userId}")
public UserResponse getUser(@PathVariable Long userId) { ... }

// ✅ 正確：使用 JPA Named Parameters
@Query("SELECT t FROM Transaction t WHERE t.accountId = :accountId")
List<Transaction> findByAccountId(@Param("accountId") String accountId);

// ❌ 錯誤：字串拼接 SQL
@Query("SELECT t FROM Transaction t WHERE t.accountId = '" + accountId + "'")

// ✅ 正確：轉帳金額有業務規則上限，並要求二次驗證
@Transactional
public TransferResult transfer(TransferCommand cmd) {
    if (cmd.getAmount().compareTo(DAILY_LIMIT) > 0) {
        throw new BusinessRuleException("超過單日轉帳上限");
    }
    mfaService.verifyOtp(cmd.getUserId(), cmd.getOtpCode());
    return doTransfer(cmd);
}

// ❌ 錯誤：無金額上限、無二次驗證
@Transactional
public TransferResult transfer(TransferCommand cmd) {
    return doTransfer(cmd);
}

// ✅ 正確：自訂錯誤回應，隱藏內部細節
@ExceptionHandler(Exception.class)
public ResponseEntity<ErrorResponse> handleException(Exception ex) {
    log.error("Unhandled exception", ex);  // 內部記錄完整錯誤
    return ResponseEntity.status(500)
        .body(new ErrorResponse("INTERNAL_ERROR", "系統忙碌中，請稍後再試"));
}

// ❌ 錯誤：直接回傳堆疊資訊
@ExceptionHandler(Exception.class)
public ResponseEntity<String> handleException(Exception ex) {
    return ResponseEntity.status(500).body(ex.getStackTrace().toString());
}

<!-- ✅ 正確：在 CI/CD 中整合 OWASP Dependency-Check -->
<plugin>
    <groupId>org.owasp</groupId>
    <artifactId>dependency-check-maven</artifactId>
    <version>9.0.9</version>
    <configuration>
        <failBuildOnCVSS>7</failBuildOnCVSS>
    </configuration>
</plugin>

<!-- ❌ 錯誤：使用已知有 CVE 漏洞的舊版 Log4j -->
<dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-core</artifactId>
    <version>2.14.1</version> <!-- CVE-2021-44228 -->
</dependency>

// ✅ 正確：登入失敗鎖定 + 安全 Session 設定
@PostMapping("/login")
public ResponseEntity<?> login(@Valid @RequestBody LoginRequest request,
                               HttpServletResponse response) {
    if (loginAttemptService.isBlocked(request.getUsername())) {
        throw new AccountLockedException("帳號已鎖定，請 30 分鐘後再試");
    }
    Authentication auth = authenticationManager.authenticate(
        new UsernamePasswordAuthenticationToken(request.getUsername(), request.getPassword()));
    String token = jwtProvider.generateToken(auth);
    Cookie cookie = new Cookie("SESSION", token);
    cookie.setHttpOnly(true);
    cookie.setSecure(true);
    cookie.setMaxAge(1800);
    response.addCookie(cookie);
    return ResponseEntity.ok(new LoginResponse(token));
}

// ❌ 錯誤：無失敗鎖定、Token 永不過期
@PostMapping("/login")
public ResponseEntity<?> login(@RequestBody LoginRequest request) {
    Authentication auth = authenticationManager.authenticate(
        new UsernamePasswordAuthenticationToken(request.getUsername(), request.getPassword()));
    String token = Jwts.builder().setSubject(request.getUsername())
        .signWith(key).compact(); // 無過期時間
    return ResponseEntity.ok(token);
}

// ✅ 正確：反序列化使用白名單，僅允許已知型別
ObjectMapper mapper = new ObjectMapper();
mapper.activateDefaultTyping(
    BasicPolymorphicTypeValidator.builder()
        .allowIfSubType("com.company.dto.")
        .build(),
    ObjectMapper.DefaultTyping.NON_FINAL
);

// ❌ 錯誤：直接反序列化任意物件（可導致 RCE）
ObjectInputStream ois = new ObjectInputStream(untrustedInput);
Object obj = ois.readObject(); // 危險！任意類別實例化

// ✅ 正確：記錄安全事件，敏感資料遮罩
@Slf4j
@Service
public class AuditService {
    public void logTransfer(TransferCommand cmd, String result) {
        log.info("AUDIT | action=TRANSFER | user={} | from={} | to={} | amount={} | result={}",
            SecurityContextHolder.getContext().getAuthentication().getName(),
            maskAccount(cmd.getFromAccount()),  // 遮罩帳號
            maskAccount(cmd.getToAccount()),
            cmd.getAmount(),
            result);
    }
    private String maskAccount(String account) {
        return account.substring(0, 3) + "****" + account.substring(account.length() - 3);
    }
}

// ❌ 錯誤：未記錄安全事件、Log 包含敏感資料
log.info("Transfer: from={}, to={}, password={}", fromAcct, toAcct, password);

// ✅ 正確：URL 白名單驗證 + 禁止內部位址
public String fetchUrl(String userProvidedUrl) {
    URL url = new URL(userProvidedUrl);
    if (!ALLOWED_HOSTS.contains(url.getHost())) {
        throw new SecurityException("不允許的目標主機: " + url.getHost());
    }
    InetAddress addr = InetAddress.getByName(url.getHost());
    if (addr.isLoopbackAddress() || addr.isSiteLocalAddress() || addr.isLinkLocalAddress()) {
        throw new SecurityException("禁止存取內部網路位址");
    }
    return httpClient.get(url).getBody();
}

// ❌ 錯誤：直接請求使用者提供的 URL
public String fetchUrl(String userProvidedUrl) {
    return restTemplate.getForObject(userProvidedUrl, String.class);
}

**範例：安全編碼指引 Skill**

```markdown
---
name: secure-coding-guide
description: >
  Provides secure coding guidelines for Java/Spring Boot 
  projects covering input validation, output encoding, 
  authentication, and cryptography. Use when asked for 
  secure coding practices, security coding standards, or 
  how to write secure code.
metadata:
  version: "2.0"
  category: security
  ssdlc-phase: security
---

# 安全編碼指引 Skill

## 1. 輸入驗證（Input Validation）

所有外部輸入均為不可信，必須在系統邊界進行驗證。

```java
// ✅ 正確：使用 Bean Validation + 自訂驗證
public record TransferRequest(
        @NotBlank(message = "來源帳號不可為空")
        @Pattern(regexp = "^[A-Z0-9]{10,20}$", message = "帳號格式不正確")
        String fromAccount,
        
        @NotBlank(message = "目標帳號不可為空")
        @Pattern(regexp = "^[A-Z0-9]{10,20}$", message = "帳號格式不正確")
        String toAccount,
        
        @NotNull(message = "金額不可為空")
        @DecimalMin(value = "0.01", message = "金額須大於 0")
        @DecimalMax(value = "10000000", message = "金額超過上限")
        BigDecimal amount
) {}

// ❌ 錯誤：無驗證直接使用
public void transfer(String from, String to, BigDecimal amount) {
    // 直接使用未驗證的輸入...
}

// ✅ 正確：使用 OWASP Java Encoder
import org.owasp.encoder.Encode;

String safeHtml = Encode.forHtml(userInput);
String safeJs = Encode.forJavaScript(userInput);
String safeUrl = Encode.forUriComponent(userInput);

// ❌ 錯誤：直接輸出使用者輸入
response.getWriter().write("<div>" + userInput + "</div>");

// ✅ 密碼雜湊：使用 BCrypt
PasswordEncoder encoder = new BCryptPasswordEncoder(12);
String hashed = encoder.encode(rawPassword);
boolean matches = encoder.matches(rawPassword, hashed);

// ✅ 敏感資料加密：使用 AES-256-GCM
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");

// ❌ 禁止事項
// - 自行實作加密演算法
// - 使用 MD5 / SHA1 雜湊密碼
// - 使用 ECB 模式
// - 硬編碼加密金鑰

// ✅ 正確：遮罩敏感資訊
log.info("Transfer from={} to={} amount={}", 
    mask(fromAccount), mask(toAccount), amount);

// ❌ 錯誤：Log 中包含敏感資料
log.info("Login user={} password={}", username, password);
log.info("Card number={}", cardNumber);

**範例：弱點掃描整合 Skill**

```markdown
---
name: vulnerability-scan
description: >
  Integrates vulnerability scanning tools including OWASP 
  Dependency-Check, SpotBugs, and SonarQube into the build 
  process. Use when asked to set up vulnerability scanning, 
  check dependencies for CVEs, or integrate SAST tools.
metadata:
  version: "1.0"
  category: security
  ssdlc-phase: security
allowed-tools: Bash(mvn *) Bash(gradle *)
---

# 弱點掃描整合 Skill

## 掃描工具矩陣

| 工具 | 類型 | 掃描內容 | 整合方式 |
|------|------|----------|----------|
| OWASP Dependency-Check | SCA | 第三方依賴 CVE 漏洞 | Maven Plugin |
| SpotBugs + Find Security Bugs | SAST | Java 原始碼安全弱點 | Maven Plugin |
| SonarQube | SAST + Quality | 程式碼品質 + 安全規則 | CI/CD Plugin |
| Trivy | Container | Docker Image 漏洞 | CI/CD Step |

## Maven 整合設定

```xml
<build>
    <plugins>
        <!-- OWASP Dependency-Check：第三方依賴 CVE 掃描 -->
        <plugin>
            <groupId>org.owasp</groupId>
            <artifactId>dependency-check-maven</artifactId>
            <version>10.0.3</version>
            <configuration>
                <failBuildOnCVSS>7</failBuildOnCVSS>
                <suppressionFiles>
                    <suppressionFile>owasp-suppressions.xml</suppressionFile>
                </suppressionFiles>
                <formats>
                    <format>HTML</format>
                    <format>JSON</format>
                </formats>
            </configuration>
        </plugin>
        
        <!-- SpotBugs + Find Security Bugs：原始碼安全分析 -->
        <plugin>
            <groupId>com.github.spotbugs</groupId>
            <artifactId>spotbugs-maven-plugin</artifactId>
            <version>4.8.6.0</version>
            <configuration>
                <effort>Max</effort>
                <threshold>Medium</threshold>
                <plugins>
                    <plugin>
                        <groupId>com.h3xstream.findsecbugs</groupId>
                        <artifactId>findsecbugs-plugin</artifactId>
                        <version>1.13.0</version>
                    </plugin>
                </plugins>
            </configuration>
        </plugin>
    </plugins>
</build>

  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: OWASP Dependency-Check
        run: mvn dependency-check:check
      
      - name: SpotBugs Security Analysis
        run: mvn spotbugs:check
      
      - name: Trivy Container Scan
        uses: aquasecurity/trivy-action@master
        with:
          image-ref: 'myapp:latest'
          severity: 'CRITICAL,HIGH'
          exit-code: '1'
      
      - name: Upload Reports
        uses: actions/upload-artifact@v4
        with:
          name: security-reports
          path: target/dependency-check-report.*

**範例：敏感資料保護 Skill**

```markdown
---
name: data-protection
description: >
  Implements PII data protection including data masking, 
  encryption at rest, encryption in transit, and data 
  classification. Use when asked about PII handling, data 
  protection, sensitive data masking, or GDPR compliance.
metadata:
  version: "1.0"
  category: security
  ssdlc-phase: security
---

# 敏感資料保護 Skill

## 資料分類

| 分類等級 | 說明 | 範例 | 處理要求 |
|----------|------|------|----------|
| **機密（Confidential）** | 洩漏將造成重大損失 | 密碼、金鑰、信用卡號 | 加密儲存 + 禁止 Log |
| **敏感（Sensitive）** | 個人可識別資訊 | 身分證字號、手機、地址 | 加密儲存 + 遮罩顯示 |
| **內部（Internal）** | 內部營運資料 | 帳號餘額、交易紀錄 | 存取控制 + Audit Log |
| **公開（Public）** | 可對外公開 | 產品名稱、匯率 | 無特殊要求 |

## 資料遮罩規則

```java
public class DataMaskUtil {

    /** 身分證字號：A123456789 → A12****789 */
    public static String maskIdNumber(String id) {
        if (id == null || id.length() < 10) return "***";
        return id.substring(0, 3) + "****" + id.substring(7);
    }
    
    /** 手機號碼：0912345678 → 0912***678 */
    public static String maskPhone(String phone) {
        if (phone == null || phone.length() < 10) return "***";
        return phone.substring(0, 4) + "***" + phone.substring(7);
    }
    
    /** Email：user@example.com → u***@example.com */
    public static String maskEmail(String email) {
        if (email == null || !email.contains("@")) return "***";
        int atIndex = email.indexOf('@');
        return email.charAt(0) + "***" + email.substring(atIndex);
    }
    
    /** 帳號：1234567890 → 123****890 */
    public static String maskAccount(String account) {
        if (account == null || account.length() < 6) return "***";
        return account.substring(0, 3) + "****" 
             + account.substring(account.length() - 3);
    }
    
    /** 信用卡號：4111111111111111 → ************1111 */
    public static String maskCreditCard(String card) {
        if (card == null || card.length() < 4) return "***";
        return "*".repeat(card.length() - 4) 
             + card.substring(card.length() - 4);
    }
}

@Converter
public class EncryptionConverter implements AttributeConverter<String, String> {

    // 金鑰從 Vault / KMS 取得，禁止硬編碼
    private final EncryptionService encryptionService;

    @Override
    public String convertToDatabaseColumn(String attribute) {
        return encryptionService.encrypt(attribute);
    }

    @Override
    public String convertToEntityAttribute(String dbData) {
        return encryptionService.decrypt(dbData);
    }
}

// Entity 中使用
@Entity
public class Customer {
    @Convert(converter = EncryptionConverter.class)
    @Column(name = "id_number")
    private String idNumber;  // 儲存加密值，讀取自動解密
}

// 自訂 Annotation
@JacksonAnnotationsInside
@JsonSerialize(using = MaskSerializer.class)
@Retention(RetentionPolicy.RUNTIME)
public @interface Masked {
    MaskType value();
}

public enum MaskType { ID_NUMBER, PHONE, EMAIL, ACCOUNT, CREDIT_CARD }

// 在 Response DTO 中使用
public record CustomerResponse(
    String name,
    @Masked(MaskType.ID_NUMBER) String idNumber,
    @Masked(MaskType.PHONE) String phone,
    @Masked(MaskType.EMAIL) String email
) {}
// 序列化結果：{"name":"王大明","idNumber":"A12****789","phone":"0912***678",...}

### 3.6 Deployment（部署）

**可轉換為 Skills 的內容**：

| 常見工作 | 轉換為 Skill | 說明 |
|----------|-------------|------|
| CI/CD Pipeline | `cicd-pipeline-gen` | 產出 GitHub Actions Workflow |
| Dockerfile | `dockerfile-gen` | 產出安全的多階段 Dockerfile |
| K8s Manifest | `k8s-manifest-gen` | 產出 Kubernetes 部署清單 |
| 環境設定 | `env-config-gen` | 產出多環境設定檔 |

**範例：CI/CD Pipeline Skill**

```markdown
---
name: github-actions-pipeline
description: >
  Generates GitHub Actions CI/CD pipelines for Spring Boot 
  projects with security scanning and quality gates. Use when 
  asked to create CI/CD pipeline, set up automated builds, 
  or configure deployment workflows.
version: 2.0.0
category: deployment
ssdlc-phase: deployment
---

# GitHub Actions Pipeline 生成 Skill

## 標準 Pipeline 結構

```yaml
name: CI/CD Pipeline

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up JDK 21
        uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'
      
      - name: Build with Maven
        run: mvn clean verify
      
      - name: Run Tests
        run: mvn test
      
  security-scan:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: SAST Scan
        uses: github/codeql-action/analyze@v3
      
      - name: Dependency Check
        run: mvn dependency-check:check
      
  quality-gate:
    needs: [build, security-scan]
    runs-on: ubuntu-latest
    steps:
      - name: SonarQube Analysis
        run: mvn sonar:sonar
      
  deploy:
    needs: quality-gate
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to Production
        run: |
          # 部署指令

**範例：Dockerfile 生成 Skill**

```markdown
---
name: dockerfile-gen
description: >
  Generates secure multi-stage Dockerfiles for Spring Boot 
  applications following container security best practices. 
  Use when asked to create Dockerfile, containerize application, 
  or optimize Docker image.
metadata:
  version: "1.0"
  category: deployment
  ssdlc-phase: deployment
---

# 安全多階段 Dockerfile 生成 Skill

## 多階段建置範本（Spring Boot）

```dockerfile
# ===== Stage 1: Build =====
FROM eclipse-temurin:21-jdk-alpine AS builder

WORKDIR /app

# 先複製依賴定義，利用 Docker Layer Cache
COPY pom.xml mvnw ./
COPY .mvn .mvn
RUN ./mvnw dependency:go-offline -B

# 複製原始碼並建置
COPY src src
RUN ./mvnw package -DskipTests -B && \
    java -Djarmode=tools -jar target/*.jar extract --layers --launcher

# ===== Stage 2: Runtime =====
FROM eclipse-temurin:21-jre-alpine AS runtime

# 安全設定：建立非 root 使用者
RUN addgroup -S appgroup && adduser -S appuser -G appgroup

WORKDIR /app

# 複製分層解壓後的應用
COPY --from=builder /app/target/extracted/dependencies/ ./
COPY --from=builder /app/target/extracted/spring-boot-loader/ ./
COPY --from=builder /app/target/extracted/snapshot-dependencies/ ./
COPY --from=builder /app/target/extracted/application/ ./

# 安全設定
RUN chmod -R 555 /app && \
    chown -R appuser:appgroup /app

USER appuser

EXPOSE 8080

# 健康檢查
HEALTHCHECK --interval=30s --timeout=3s --start-period=15s --retries=3 \
    CMD wget -qO- http://localhost:8080/actuator/health || exit 1

ENTRYPOINT ["java", \
    "-XX:+UseContainerSupport", \
    "-XX:MaxRAMPercentage=75.0", \
    "-Djava.security.egd=file:/dev/./urandom", \
    "org.springframework.boot.loader.launch.JarLauncher"]

.git
.github
.idea
*.md
target/
!target/*.jar
docker-compose*.yml
*.env
*.key
*.pem

**範例：Kubernetes 部署清單生成 Skill**

```markdown
---
name: k8s-manifest-gen
description: >
  Generates Kubernetes deployment manifests including Deployment, 
  Service, ConfigMap, Secret, HPA, and NetworkPolicy. Use when 
  asked to create K8s manifests, deploy to Kubernetes, or 
  configure container orchestration.
metadata:
  version: "1.0"
  category: deployment
  ssdlc-phase: deployment
---

# Kubernetes 部署清單生成 Skill

## 標準 Manifest 結構

```text
k8s/
├── base/
│   ├── kustomization.yaml
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── configmap.yaml
│   ├── hpa.yaml
│   └── networkpolicy.yaml
└── overlays/
    ├── dev/
    │   └── kustomization.yaml
    ├── sit/
    │   └── kustomization.yaml
    └── prod/
        └── kustomization.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: transaction-service
  labels:
    app: transaction-service
    version: v1
spec:
  replicas: 2
  selector:
    matchLabels:
      app: transaction-service
  template:
    metadata:
      labels:
        app: transaction-service
        version: v1
    spec:
      serviceAccountName: transaction-service
      securityContext:
        runAsNonRoot: true
        runAsUser: 1000
        fsGroup: 1000
      containers:
        - name: transaction-service
          image: registry.company.com/transaction-service:1.0.0
          ports:
            - containerPort: 8080
              protocol: TCP
          env:
            - name: SPRING_PROFILES_ACTIVE
              value: "k8s"
            - name: DB_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: db-credentials
                  key: password
          resources:
            requests:
              cpu: 250m
              memory: 512Mi
            limits:
              cpu: 1000m
              memory: 1Gi
          livenessProbe:
            httpGet:
              path: /actuator/health/liveness
              port: 8080
            initialDelaySeconds: 15
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /actuator/health/readiness
              port: 8080
            initialDelaySeconds: 10
            periodSeconds: 5
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            capabilities:
              drop: ["ALL"]
      volumes:
        - name: tmp
          emptyDir: {}

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: transaction-service-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: transaction-service
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: transaction-service-netpol
spec:
  podSelector:
    matchLabels:
      app: transaction-service
  policyTypes:
    - Ingress
    - Egress
  ingress:
    - from:
        - podSelector:
            matchLabels:
              app: api-gateway
      ports:
        - port: 8080
  egress:
    - to:
        - podSelector:
            matchLabels:
              app: postgres
      ports:
        - port: 5432

**範例：多環境設定生成 Skill**

```markdown
---
name: env-config-gen
description: >
  Generates multi-environment configuration files for Spring 
  Boot applications including dev, sit, uat, and prod profiles. 
  Use when asked to create environment configurations, set up 
  Spring profiles, or manage application properties.
metadata:
  version: "1.0"
  category: deployment
  ssdlc-phase: deployment
---

# 多環境設定生成 Skill

## 設定檔結構

```text
src/main/resources/
├── application.yml              # 共用設定
├── application-dev.yml          # 開發環境
├── application-sit.yml          # 系統整合測試
├── application-uat.yml          # 使用者驗收測試
└── application-prod.yml         # 正式環境

spring:
  application:
    name: transaction-service
  jackson:
    date-format: "yyyy-MM-dd'T'HH:mm:ss.SSSZ"
    default-property-inclusion: non_null

server:
  port: 8080
  shutdown: graceful

management:
  endpoints:
    web:
      exposure:
        include: health,info,prometheus
  endpoint:
    health:
      show-details: when_authorized

logging:
  pattern:
    console: "%d{ISO8601} [%thread] %-5level %logger{36} - %msg%n"

# application-dev.yml
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/devdb
    username: dev_user
    # 密碼從環境變數取得：${DB_PASSWORD}
    password: ${DB_PASSWORD}
  jpa:
    show-sql: true
    hibernate:
      ddl-auto: update

logging:
  level:
    com.company: DEBUG
    org.springframework.web: DEBUG

# application-prod.yml
spring:
  datasource:
    url: ${DB_URL}          # 從 ConfigMap / Secret 注入
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}
  jpa:
    show-sql: false
    hibernate:
      ddl-auto: none        # 正式環境禁止自動 DDL

logging:
  level:
    com.company: WARN
    org.springframework.web: WARN

server:
  ssl:
    enabled: true
    key-store: ${SSL_KEYSTORE_PATH}
    key-store-password: ${SSL_KEYSTORE_PASSWORD}

### 3.7 Maintenance（維運）

**可轉換為 Skills 的內容**：

| 常見工作 | 轉換為 Skill | 說明 |
|----------|-------------|------|
| Log 分析 | `log-analyzer` | 分析錯誤日誌並定位問題 |
| 問題排查 | `troubleshooting-guide` | 常見問題排查 SOP |
| 事件回應 | `incident-response` | 事故處理流程 |
| 效能調校 | `performance-tuning` | 效能瓶頸分析與優化 |

**範例：Log 分析 Skill**

```markdown
---
name: log-analyzer
description: >
  Analyzes application logs to identify errors, performance 
  issues, and anomalies. Use when asked to debug issues, 
  analyze logs, or troubleshoot production problems.
version: 1.2.0
category: maintenance
ssdlc-phase: maintenance
---

# Log 分析 Skill

## 分析步驟

### Step 1：識別錯誤模式
```bash
# 統計 ERROR 級別日誌
grep -c "ERROR" application.log

# 找出最常見的錯誤
grep "ERROR" application.log | awk '{print $5}' | sort | uniq -c | sort -rn | head -20

# 每分鐘錯誤趨勢
grep "ERROR" application.log | awk '{print substr($1,1,16)}' | uniq -c

> **🏦 金融業實務案例**：某銀行的維運團隊將常見的「交易失敗排查」、「批次異常處理」、「系統效能告警回應」分別封裝為 Skills，值班人員可透過 AI 快速定位問題根因，平均問題解決時間從 2 小時降至 30 分鐘。

**範例：問題排查 SOP Skill**

```markdown
---
name: troubleshooting-guide
description: >
  Provides structured troubleshooting SOP for common production 
  issues including database connection failures, API timeouts, 
  memory leaks, and deployment rollback. Use when asked to 
  troubleshoot issues, debug production problems, or create 
  troubleshooting runbook.
metadata:
  version: "1.0"
  category: maintenance
  ssdlc-phase: maintenance
---

# 問題排查 SOP Skill

## 排查流程總覽

```mermaid
graph TD
    A[收到告警 / 問題回報] --> B{問題分類}
    B --> |連線問題| C[DB / 網路排查]
    B --> |效能問題| D[效能排查]
    B --> |功能異常| E[邏輯排查]
    B --> |部署異常| F[部署排查]
    
    C --> G[Step 1: 檢查連線池狀態]
    G --> H[Step 2: 檢查 DB 存活與負載]
    H --> I[Step 3: 檢查網路與防火牆]
    
    D --> J[Step 1: 檢查 JVM Heap 使用率]
    J --> K[Step 2: 檢查慢查詢 Log]
    K --> L[Step 3: 檢查 Thread Dump]
    
    E --> M[Step 1: 重現問題]
    M --> N[Step 2: 檢查對應 Log]
    N --> O[Step 3: 比對最近部署變更]
    
    F --> P[Step 1: 檢查部署日誌]
    P --> Q[Step 2: 檢查 Pod 狀態]
    Q --> R[Step 3: 必要時 Rollback]

# Step 1：檢查連線池狀態
curl -s http://localhost:8080/actuator/health | jq '.components.db'

# Step 2：檢查 DB 存活
pg_isready -h <db-host> -p 5432

# Step 3：檢查活動連線數
psql -c "SELECT count(*) FROM pg_stat_activity WHERE state = 'active';"

# Step 4：檢查連線池設定
grep -E "maximum-pool-size|minimum-idle|connection-timeout" \
    src/main/resources/application*.yml

# Step 1：確認逾時的 API 端點
grep "SocketTimeoutException\|ReadTimeoutException" application.log | tail -20

# Step 2：檢查下游服務回應時間
curl -w "@curl-timing.txt" -o /dev/null -s http://downstream-service/health

# Step 3：檢查 Thread Dump（找出阻塞的執行緒）
jcmd <pid> Thread.print > thread-dump.txt
grep -A 5 "BLOCKED\|WAITING" thread-dump.txt

# Step 1：檢查 Pod 狀態
kubectl get pods -l app=transaction-service
kubectl describe pod <pod-name>

# Step 2：檢查 Pod Log
kubectl logs <pod-name> --tail=100

# Step 3：Rollback 到上一版本
kubectl rollout undo deployment/transaction-service
kubectl rollout status deployment/transaction-service

**範例：事件回應 Skill**

```markdown
---
name: incident-response
description: >
  Guides incident response process including severity 
  classification, communication, resolution, and post-mortem. 
  Use when asked to handle production incidents, create 
  incident reports, or establish incident response procedures.
metadata:
  version: "1.0"
  category: maintenance
  ssdlc-phase: maintenance
---

# 事件回應（Incident Response）Skill

## 事件嚴重等級定義

| 等級 | 定義 | 回應時間 | 通知範圍 | 範例 |
|------|------|----------|----------|------|
| **P0（Critical）** | 核心服務全面中斷 | < 15 分鐘 | CTO + 全體 On-call | 交易系統完全停擺 |
| **P1（High）** | 核心功能嚴重受損 | < 30 分鐘 | 部門主管 + On-call | 轉帳功能失敗率 > 50% |
| **P2（Medium）** | 部分功能異常 | < 2 小時 | On-call Team | 報表功能異常 |
| **P3（Low）** | 輕微影響 | < 24 小時 | 建立 Ticket | UI 顯示異常 |

## 事件回應流程

```mermaid
graph TD
    A[事件偵測] --> B[嚴重等級判定]
    B --> C[組建應變小組]
    C --> D[發出事件通知]
    D --> E[問題定位與隔離]
    E --> F{可快速修復?}
    F --> |Yes| G[執行修復]
    F --> |No| H[啟動降級方案]
    G --> I[驗證修復]
    H --> I
    I --> J[發出恢復通知]
    J --> K[撰寫事後報告 Post-Mortem]
    K --> L[改善措施追蹤]
    
    style A fill:#f44336,color:#fff
    style K fill:#4CAF50,color:#fff

🔴 【P1 事件通知】交易服務異常

■ 事件時間：2026-04-07 14:30 (UTC+8)
■ 影響範圍：轉帳功能失敗率上升至 60%
■ 影響使用者：約 5,000 人
■ 目前狀態：排查中
■ 應變指揮：[姓名]
■ 下次更新：15 分鐘後

處置動作：
1. 已隔離異常 Pod
2. 正在分析錯誤日誌
3. 已啟動降級方案（排隊處理）

# Post-Mortem Report

## 事件摘要
- **事件編號**：INC-2026-0407-001
- **嚴重等級**：P1
- **發生時間**：2026-04-07 14:30 ~ 15:45 (UTC+8)
- **影響時長**：75 分鐘
- **影響範圍**：轉帳功能，約 5,000 名使用者受影響

## 時間軸
| 時間 | 事件 |
|------|------|
| 14:30 | 監控告警觸發（轉帳錯誤率 > 10%） |
| 14:33 | On-call 工程師接收告警 |
| 14:45 | 判定為 P1，組建應變小組 |
| 15:00 | 定位根因：DB 連線池耗盡 |
| 15:15 | 執行修復：重啟服務 + 調整連線池參數 |
| 15:30 | 錯誤率回復正常 |
| 15:45 | 確認事件結束，發出恢復通知 |

## 根因分析（Root Cause）
批次作業佔用大量 DB 連線未釋放，導致連線池耗盡。

## 修復措施
1.（立即）重啟受影響服務，釋放連線
2.（立即）調整 HikariCP maximum-pool-size：20 → 50

## 預防措施
1.（短期）批次作業使用獨立連線池
2.（中期）加入連線池使用率監控告警
3.（長期）批次作業改為 Job 模式，與 API 服務分離

## 經驗教訓（Lessons Learned）
- 批次作業與線上 API 共用連線池是風險點
- 需加強連線池水位監控

**範例：效能調校 Skill**

```markdown
---
name: performance-tuning
description: >
  Analyzes and optimizes application performance including 
  JVM tuning, database query optimization, caching strategy, 
  and concurrency tuning. Use when asked to optimize performance, 
  tune JVM, fix slow queries, or analyze performance bottlenecks.
metadata:
  version: "1.0"
  category: maintenance
  ssdlc-phase: maintenance
---

# 效能調校 Skill

## 效能瓶頸定位流程

```mermaid
graph TD
    A[效能問題回報] --> B{瓶頸在哪一層?}
    B --> |應用層| C[JVM / Thread 分析]
    B --> |資料庫| D[慢查詢分析]
    B --> |網路| E[延遲 / 頻寬分析]
    B --> |基礎設施| F[CPU / Memory / Disk]
    
    C --> C1[Thread Dump 分析]
    C --> C2[Heap Dump 分析]
    C --> C3[GC Log 分析]
    
    D --> D1[Slow Query Log]
    D --> D2[執行計畫分析 EXPLAIN]
    D --> D3[索引優化]
    
    F --> F1[kubectl top pods]
    F --> F2[Prometheus / Grafana]

# 生產環境 JVM 參數建議
JAVA_OPTS="\
  -XX:+UseG1GC \
  -XX:MaxGCPauseMillis=200 \
  -XX:+UseContainerSupport \
  -XX:MaxRAMPercentage=75.0 \
  -XX:+HeapDumpOnOutOfMemoryError \
  -XX:HeapDumpPath=/tmp/heapdump.hprof \
  -Xlog:gc*:file=/var/log/gc.log:time,uptime,level,tags:filecount=5,filesize=10m"

# 分析 GC Log
# 推薦工具：GCEasy (https://gceasy.io) 或 GCViewer

-- Step 1：找出慢查詢（PostgreSQL）
SELECT query, calls, mean_exec_time, total_exec_time
FROM pg_stat_statements
ORDER BY mean_exec_time DESC
LIMIT 20;

-- Step 2：分析執行計畫
EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
SELECT * FROM transactions
WHERE account_id = 'A001' AND created_at > '2026-01-01';

-- Step 3：常見優化手法

// Spring Cache 使用範本
@Cacheable(value = "accounts", key = "#accountId", 
           unless = "#result == null")
public Account findByAccountId(String accountId) {
    return accountRepository.findByAccountId(accountId);
}

@CacheEvict(value = "accounts", key = "#account.accountId")
public void updateAccount(Account account) {
    accountRepository.save(account);
}

---

## 第 4 章：Skills 設計最佳實務

### 4.1 高可重用性設計

**設計原則**：

```mermaid
graph TB
    subgraph "可重用性設計原則"
        A[單一職責] --> E[高內聚]
        B[參數化設計] --> E
        C[低耦合] --> E
        D[文件完備] --> E
        E --> F[高可重用性 Skill]
    end
    
    style F fill:#4CAF50,color:#fff

# ❌ 反模式：一個 Skill 做太多事
.github/skills/do-everything/
└── SKILL.md  # 包含 API 設計 + 程式碼生成 + 測試 + 部署

# ✅ 正確：每個 Skill 專注一件事
.github/skills/
├── api-design/        # 只負責 API 設計
├── spring-boot-gen/   # 只負責程式碼生成
├── junit-test-gen/    # 只負責測試生成
└── cicd-pipeline/     # 只負責 CI/CD

---
name: api-endpoint-gen
description: >
  Generates REST API endpoints. Supports configurable 
  framework (Spring Boot / Express / FastAPI), database 
  (JPA / MyBatis), and authentication (JWT / OAuth2).
---

# API 端點生成

## 設定參數
在使用前，請指定以下參數：
- **框架**：Spring Boot 3.x（預設）/ Express.js / FastAPI
- **ORM**：JPA（預設）/ MyBatis / Prisma
- **認證**：JWT（預設）/ OAuth2 / API Key
- **資料庫**：PostgreSQL（預設）/ Oracle / MySQL

## 完整 API 開發流程
建議依序使用以下 Skills：
1. 先使用 `api-design` Skill 產出 OpenAPI 規格
2. 再使用 `spring-boot-gen` Skill 產出程式碼
3. 使用 `junit-test-gen` Skill 產出測試
4. 最後使用 `code-review-standard` Skill 進行審查

├── Metadata（name + description）  // ~100 Tokens
├── 核心指令                        // ~500-1000 Tokens
├── 範例程式碼                      // ~300-500 Tokens
└── 檢查清單                        // ~200-300 Tokens
    
👉 建議 SKILL.md 主體控制在 5000 Tokens 以內
👉 SKILL.md 建議不超過 500 行（Agent Skills Spec 推薦）
👉 詳細參考資料放入 references/ 資料夾

# ❌ 將所有內容塞入 SKILL.md（消耗約 5000 Tokens）
---
name: api-design
description: ...
---
# API Design（包含完整 OpenAPI Spec 範例、所有 HTTP Status Code、
#  完整的 Error Response 格式、詳細的安全規範...等等）

# ✅ 核心指令在 SKILL.md，詳細內容在 references/（載入約 1500 Tokens）
---
name: api-design
description: ...
---
# API Design
## 核心規範（精簡摘要）
若需詳細規範，請參考：
- references/openapi-template.yaml
- references/error-codes.md
- references/security-standards.md

格式：<domain>-<action>-<target>

範例：
├── banking-generate-brd          # 銀行業-生成-BRD
├── api-design-restful             # API-設計-RESTful
├── test-generate-junit            # 測試-生成-JUnit
├── security-review-owasp          # 安全-審查-OWASP
├── deploy-generate-dockerfile     # 部署-生成-Dockerfile
└── maintenance-analyze-log        # 維運-分析-Log

# SKILL.md frontmatter 中包含版本
---
name: api-design
version: 2.1.0  # Semantic Versioning
---

## Skill 安全審查檢查清單
- [ ] SKILL.md 中無敏感資訊（密碼、Token、金鑰）
- [ ] Scripts 已經過安全審核
- [ ] allowed-tools 遵循最小權限原則
- [ ] 無 Prompt Injection 風險
- [ ] 腳本有輸入驗證
- [ ] 腳本不會刪除或修改系統關鍵檔案
- [ ] 無外部網路呼叫（除非必要且已審核）
- [ ] 輸出不會洩漏系統內部資訊

# CONTEXT.md 範例
## 領域術語
- **Ledger Entry**：一筆帳務紀錄（非「交易」，因交易另有定義）
- **Settlement**：清算——將多筆 Ledger Entry 彙總為淨額
- **Cutoff Time**：截止時間——每日批次處理的分界點

## 架構決策
- 參見 docs/adr/ 目錄中的 ADR 文件

## 常見合理化推託與反駁

| Agent 可能的藉口 | 為什麼這是錯的 |
|-----------------|---------------|
| 「這個改動太小了，不需要測試」 | 小改動引起的迴歸錯誤佔生產事故的 40% |
| 「這只是重構，行為沒變」 | 重構必須有測試保護，否則無法證明行為未改變 |
| 「我之後再加測試」 | 「之後」通常意味著「永遠不會」——現在就寫 |
| 「效能影響可以忽略」 | 除非你已量測過，否則不能斷言「可以忽略」 |

  DEFINE          PLAN           BUILD          VERIFY         REVIEW          SHIP
 ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐
 │ /spec│ ───▶ │/plan │ ───▶ │/build│ ───▶ │/test │ ───▶ │/review│───▶ │/ship │
 └──────┘      └──────┘      └──────┘      └──────┘      └──────┘      └──────┘

.github/skills/generate-api-spec/
├── SKILL.md
├── references/
│   ├── api-standards.md
│   └── error-response-format.md
├── scripts/
│   └── validate-openapi.sh
└── templates/
    └── openapi-template.yaml

---
name: generate-api-spec
description: >
  Generates OpenAPI 3.1 specification documents for REST APIs 
  following enterprise standards. Use when asked to design an 
  API, create API documentation, or generate OpenAPI specs.
version: 1.0.0
category: design
ssdlc-phase: design
---

# API 規格文件生成 Skill

## 使用方式
當使用者要求設計 API 時，請依照以下步驟：

### Step 1：收集資訊
確認以下資訊：
- API 名稱與用途
- 資源（Resource）清單
- 操作（Operations）清單
- 認證方式

### Step 2：產出 OpenAPI Spec
使用 `templates/openapi-template.yaml` 作為基礎範本，
依據 `references/api-standards.md` 中的規範填入內容。

### Step 3：驗證
如果需要驗證規格檔，可執行：
```bash
bash scripts/validate-openapi.sh <output-file>

**templates/openapi-template.yaml**：

```yaml
openapi: 3.1.0
info:
  title: "{{API_TITLE}}"
  description: "{{API_DESCRIPTION}}"
  version: "{{API_VERSION}}"
  contact:
    name: "{{TEAM_NAME}}"
    email: "{{TEAM_EMAIL}}"
    
servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://api-sit.example.com/v1
    description: SIT
    
paths:
  /{{RESOURCE_PATH}}:
    get:
      summary: "查詢{{RESOURCE_NAME}}列表"
      operationId: "list{{RESOURCE_NAME}}"
      tags:
        - "{{TAG_NAME}}"
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 0
        - name: size
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: 查詢成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

components:
  schemas:
    PageResponse:
      type: object
      properties:
        content:
          type: array
          items: {}
        totalElements:
          type: integer
        totalPages:
          type: integer
        
  responses:
    Unauthorized:
      description: 未授權
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: 伺服器內部錯誤
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
            
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        timestamp:
          type: string
          format: date-time

#!/bin/bash
# OpenAPI 規格文件驗證腳本
# 用法: bash validate-openapi.sh <openapi-file>

set -euo pipefail

if [ $# -eq 0 ]; then
    echo "Usage: bash validate-openapi.sh <openapi-file>"
    exit 1
fi

FILE="$1"

if [ ! -f "$FILE" ]; then
    echo "ERROR: File not found: $FILE"
    exit 1
fi

echo "Validating OpenAPI spec: $FILE"

# 基本 YAML 語法檢查
if command -v python3 &> /dev/null; then
    python3 -c "
import sys
import yaml

try:
    with open('$FILE', 'r') as f:
        spec = yaml.safe_load(f)
    
    # 檢查必要欄位
    required = ['openapi', 'info', 'paths']
    for field in required:
        if field not in spec:
            print(f'ERROR: Missing required field: {field}')
            sys.exit(1)
    
    # 檢查版本
    if not spec['openapi'].startswith('3.'):
        print(f'WARNING: OpenAPI version {spec[\"openapi\"]} is not 3.x')
    
    print('✅ OpenAPI spec validation passed')
except Exception as e:
    print(f'ERROR: {e}')
    sys.exit(1)
"
else
    echo "WARNING: Python3 not found, skipping validation"
fi

.github/skills/enterprise-code-review/
├── SKILL.md
└── references/
    ├── coding-standards.md
    ├── security-checklist.md
    └── performance-checklist.md

---
name: enterprise-code-review
description: >
  Performs comprehensive code review following enterprise 
  coding standards, security guidelines, and performance 
  best practices. Use when reviewing pull requests, 
  checking code quality, or performing peer review.
version: 2.0.0
category: development
ssdlc-phase: development
---

# 企業級程式碼審查 Skill

## 審查流程

### Phase 1：快速掃描（30 秒）
快速瀏覽變更概覽：
- 變更了哪些檔案？
- 變更規模是否合理？（建議 PR < 400 行）
- 是否包含測試？

### Phase 2：安全審查（最優先）
依據 `references/security-checklist.md` 逐項檢查：
- SQL Injection
- XSS
- 敏感資料保護
- 權限控管
- 輸入驗證

### Phase 3：功能正確性
- 業務邏輯是否正確？
- 邊界條件是否處理？
- 錯誤處理是否完整？

### Phase 4：程式碼品質
依據 `references/coding-standards.md` 檢查：
- 命名規範
- 方法長度
- 類別職責
- 程式碼重複

### Phase 5：效能
依據 `references/performance-checklist.md` 檢查：
- N+1 查詢
- 不必要的記憶體配置
- 適當的快取使用

## 輸出格式

```markdown
## Code Review 報告

### 📊 總覽
- 檔案數：X
- 變更行數：+X / -X
- 整體評分：⭐⭐⭐⭐☆

### 🔴 必須修改（Must Fix）
1. [安全] 第 XX 行：SQL Injection 風險
2. [正確性] 第 XX 行：NullPointerException 風險

### 🟡 建議修改（Should Fix）
1. [品質] 第 XX 行：方法過長，建議拆分
2. [效能] 第 XX 行：N+1 查詢問題

### 🟢 建議（Nice to Have）
1. [風格] 第 XX 行：命名可更具描述性

### ✅ 優點
1. 測試覆蓋完整
2. 結構清晰

.github/skills/spring-boot-service-gen/
├── SKILL.md
├── references/
│   ├── clean-architecture.md
│   └── naming-conventions.md
└── templates/
    ├── Controller.java.template
    ├── Service.java.template
    ├── Repository.java.template
    ├── Request.java.template
    ├── Response.java.template
    └── ServiceTest.java.template

---
name: spring-boot-service-gen
description: >
  Generates complete Spring Boot 3.x service components 
  including Controller, Service, Repository, DTOs, and 
  tests following Clean Architecture. Use when asked to 
  create a new API endpoint, service, or CRUD operations.
version: 1.0.0
category: development
ssdlc-phase: development
---

# Spring Boot 服務元件生成 Skill

## 生成項目
依據使用者提供的需求，產生以下元件：

1. **Controller**（使用 `templates/Controller.java.template`）
2. **Service Interface**（Use Case Port）
3. **Service Implementation**
4. **Repository Interface**
5. **Entity**
6. **Request DTO**
7. **Response DTO**
8. **Unit Test**（使用 `templates/ServiceTest.java.template`）

## 命名規範
遵循 `references/naming-conventions.md`

## 分層規範
遵循 `references/clean-architecture.md`

## 程式碼規範
- Java 21+ 語法（Record、Pattern Matching）
- Lombok 最小化使用（僅 @Slf4j、@RequiredArgsConstructor）
- Bean Validation（Jakarta Validation）
- MapStruct 進行 DTO 轉換

## 生成流程
1. 確認資源名稱（如 Transaction）
2. 確認需要的 CRUD 操作
3. 依模板生成各元件
4. 確保 package 路徑正確
5. 生成對應的 Unit Test

package com.{{company}}.{{service}}.adapter.in.web;

import jakarta.validation.Valid;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

/**
 * {{ResourceName}} REST API Controller
 *
 * @author {{author}}
 * @since {{version}}
 */
@RestController
@RequestMapping("/api/v1/{{resourcePath}}")
@RequiredArgsConstructor
@Slf4j
public class {{ResourceName}}Controller {

    private final {{ResourceName}}UseCase {{resourceName}}UseCase;

    @GetMapping
    public ResponseEntity<PageResponse<{{ResourceName}}Response>> list(
            @Valid {{ResourceName}}QueryRequest request) {
        log.info("查詢{{resourceLabel}}列表: {}", request);
        var result = {{resourceName}}UseCase.query(request.toDomain());
        return ResponseEntity.ok(PageResponse.of(result));
    }

    @GetMapping("/{id}")
    public ResponseEntity<{{ResourceName}}Response> getById(
            @PathVariable Long id) {
        log.info("查詢{{resourceLabel}}: id={}", id);
        var result = {{resourceName}}UseCase.getById(id);
        return ResponseEntity.ok({{ResourceName}}Response.from(result));
    }

    @PostMapping
    public ResponseEntity<{{ResourceName}}Response> create(
            @Valid @RequestBody {{ResourceName}}CreateRequest request) {
        log.info("建立{{resourceLabel}}: {}", request);
        var result = {{resourceName}}UseCase.create(request.toCommand());
        return ResponseEntity.status(HttpStatus.CREATED)
                .body({{ResourceName}}Response.from(result));
    }

    @PutMapping("/{id}")
    public ResponseEntity<{{ResourceName}}Response> update(
            @PathVariable Long id,
            @Valid @RequestBody {{ResourceName}}UpdateRequest request) {
        log.info("更新{{resourceLabel}}: id={}, request={}", id, request);
        var result = {{resourceName}}UseCase.update(id, request.toCommand());
        return ResponseEntity.ok({{ResourceName}}Response.from(result));
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<Void> delete(@PathVariable Long id) {
        log.info("刪除{{resourceLabel}}: id={}", id);
        {{resourceName}}UseCase.delete(id);
        return ResponseEntity.noContent().build();
    }
}

📦 enterprise-copilot-skills/
│
├── 📄 README.md                    # 說明文件
├── 📄 CONTRIBUTING.md              # 貢獻指南
├── 📄 GOVERNANCE.md                # 治理規範
├── 📄 SECURITY.md                  # 安全政策
├── 📄 catalog.yaml                 # Skills 目錄索引
├── 📄 .github/
│   ├── CODEOWNERS                  # 審核者指派
│   ├── PULL_REQUEST_TEMPLATE.md    # PR 範本
│   └── workflows/
│       ├── validate-skill.yml      # Skill 格式驗證
│       ├── security-scan.yml       # 安全掃描
│       └── publish-skill.yml       # Skill 發布
│
├── 📂 core/                        # 核心 Skills（全組織適用）
│   ├── code-review/
│   ├── api-design/
│   ├── unit-test-generation/
│   ├── security-scan/
│   ├── documentation/
│   └── cicd-pipeline/
│
├── 📂 ssdlc/                       # 按 SSDLC 階段分類
│   ├── requirements/
│   │   ├── generate-brd/
│   │   ├── generate-frd/
│   │   └── generate-user-story/
│   ├── design/
│   │   ├── clean-architecture/
│   │   ├── api-design-restful/
│   │   └── database-design/
│   ├── development/
│   │   ├── spring-boot-codegen/
│   │   ├── vue-component-gen/
│   │   └── refactoring-patterns/
│   ├── testing/
│   │   ├── junit-test-gen/
│   │   ├── integration-test-gen/
│   │   └── api-test-gen/
│   ├── security/
│   │   ├── owasp-review/
│   │   ├── secure-coding/
│   │   └── dependency-audit/
│   ├── deployment/
│   │   ├── github-actions-pipeline/
│   │   ├── dockerfile-gen/
│   │   └── k8s-manifest-gen/
│   └── maintenance/
│       ├── log-analyzer/
│       ├── incident-response/
│       └── performance-tuning/
│
├── 📂 domain/                       # 按業務領域分類
│   ├── banking/
│   │   ├── transaction-api/
│   │   ├── account-management/
│   │   └── regulatory-report/
│   └── common/
│       ├── batch-job-design/
│       └── notification-service/
│
├── 📂 templates/                    # Skill 開發範本
│   └── new-skill-template/
│       ├── SKILL.md
│       └── README.md
│
└── 📂 scripts/                      # 工具腳本
    ├── validate-all-skills.py       # 批次驗證
    ├── generate-catalog.py          # 自動生成目錄
    └── sync-to-projects.sh          # 同步至專案

# Skills 目錄索引
catalog:
  version: "1.0.0"
  last_updated: "2026-04-01"
  
  skills:
    - name: api-design-restful
      path: ssdlc/design/api-design-restful
      phase: design
      layer: backend
      domain: common
      version: 2.1.0
      author: platform-team
      status: active
      tags: [api, rest, openapi]
      
    - name: junit-test-gen
      path: ssdlc/testing/junit-test-gen
      phase: testing
      layer: backend
      domain: common
      version: 1.3.0
      author: qa-team
      status: active
      tags: [test, junit, java]
      
    - name: transaction-api
      path: domain/banking/transaction-api
      phase: development
      layer: backend
      domain: banking
      version: 1.0.0
      author: banking-team
      status: active
      tags: [banking, transaction, api]

# .github/CODEOWNERS

# 核心 Skills 需要 Platform Team 審核
/core/                @org/platform-team

# 安全相關 Skills 需要 Security Team 審核
/ssdlc/security/      @org/security-team

# 領域 Skills 需要對應領域 Owner 審核
/domain/banking/       @org/banking-team
/domain/payment/       @org/payment-team

# 所有 Scripts 需要 Security Team 審核
**/scripts/            @org/security-team

# .github/workflows/validate-skill.yml
name: Validate Skill

on:
  pull_request:
    paths:
      - '**/SKILL.md'
      - '**/scripts/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Validate SKILL.md format
        run: |
          python scripts/validate-all-skills.py
          
      - name: Check naming convention
        run: |
          # 檢查所有 Skill 目錄名稱是否符合命名規範
          find . -name "SKILL.md" -exec dirname {} \; | while read dir; do
            dirname=$(basename "$dir")
            if [[ ! "$dirname" =~ ^[a-z][a-z0-9-]*$ ]]; then
              echo "ERROR: Invalid skill name: $dirname"
              exit 1
            fi
          done
          
      - name: Security scan scripts
        run: |
          # 掃描腳本中的安全風險
          find . -name "*.sh" -o -name "*.py" | while read script; do
            echo "Scanning: $script"
            # 檢查是否有硬編碼密碼
            if grep -iE "(password|secret|token|api_key)\s*=" "$script"; then
              echo "ERROR: Potential hardcoded secret in $script"
              exit 1
            fi
          done

  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Lint Markdown
        uses: DavidAnson/markdownlint-cli2-action@v19
        with:
          globs: '**/SKILL.md'

📦 my-spring-boot-project/
├── .github/
│   ├── copilot-instructions.md   # 全局指令
│   └── skills/                    # 專案專屬 Skills
│       ├── api-design/
│       │   └── SKILL.md
│       └── code-review/
│           └── SKILL.md
├── .claude/
│   └── skills/                    # Claude Code 專案專屬 Skills
│       └── deploy/
│           └── SKILL.md
├── .agents/
│   └── skills/                    # 跨 Agent 通用 Skills
│       └── unit-test-gen/
│           └── SKILL.md
└── src/

# GitHub Copilot 個人 Skills
# Windows
mkdir -p %USERPROFILE%\.copilot\skills\my-skill
# macOS / Linux
mkdir -p ~/.copilot/skills/my-skill

# Claude Code 個人 Skills
mkdir -p ~/.claude/skills/my-skill

# GitHub Copilot（自動匹配 + 載入）
使用者：「請幫我設計一個轉帳 API」
Copilot：（自動載入 api-design Skill）→ 依規範產出 API 設計

# GitHub Copilot CLI — 斜線命令
/skills list                    # 列出可用 Skills
/skills info api-design         # 查看 Skill 詳情
/skills reload                  # 重新載入（新增 Skill 後）
/skills add <path>              # 新增 Skills 搜尋路徑
/skills remove <skill-dir>      # 移除 Skill

# Claude Code — 自動觸發
使用者：「幫我 Review 這段程式碼」
Claude：（自動載入 code-review Skill）→ 依清單進行審查

# Claude Code — 手動叫用
/deploy staging v2.1.0
# → 觸發 deploy Skill，$0 = staging, $1 = v2.1.0

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:

1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

# 在 /permissions 中控制 Skill 存取
# 允許特定 Skills
Skill(commit)
Skill(review-pr *)

# 禁止特定 Skills
Skill(deploy *)

# 禁止所有 Skills
Skill

// .vscode/settings.json
{
    // Copilot 相關設定
    "github.copilot.chat.codeGeneration.instructions": [
        { "file": ".github/copilot-instructions.md" }
    ],
    
    // 推薦 Extensions
    "recommendations": [
        "github.copilot",
        "github.copilot-chat",
        "vscjava.vscode-java-pack",
        "vmware.vscode-spring-boot"
    ]
}

# .github/workflows/skill-quality.yml
name: Skill Quality Gate

on:
  push:
    paths:
      - '.github/skills/**'

jobs:
  quality-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Validate all SKILL.md files
        run: |
          find .github/skills -name "SKILL.md" | while read file; do
            echo "Checking: $file"
            
            # 檢查 frontmatter
            head -1 "$file" | grep -q "^---$" || {
              echo "ERROR: Missing YAML frontmatter in $file"
              exit 1
            }
            
            # 檢查必要欄位
            if ! grep -q "^name:" "$file"; then
              echo "ERROR: Missing 'name' field in $file"
              exit 1
            fi
            
            if ! grep -q "^description:" "$file"; then
              echo "ERROR: Missing 'description' field in $file"
              exit 1
            fi
          done
          echo "✅ All SKILL.md files are valid"

<!-- .github/PULL_REQUEST_TEMPLATE/skill-pr.md -->

## Skill 資訊
- **名稱**：
- **類別**：core / ssdlc / domain
- **SSDLC 階段**：requirements / design / development / testing / security / deployment / maintenance
- **版本**：

## 變更說明
<!-- 描述這個 Skill 做什麼、為什麼需要 -->

## 檢查清單
- [ ] SKILL.md 包含必要的 frontmatter（name, description）
- [ ] description 清楚說明觸發條件
- [ ] 命名遵循企業命名規範
- [ ] 無敏感資訊（密碼、Token）
- [ ] Scripts 已經過安全審查
- [ ] allowed-tools 遵循最小權限原則
- [ ] 已在本地測試過 Skill 功能
- [ ] 已更新 catalog.yaml

## 測試結果
<!-- 附上使用 Skill 的截圖或結果 -->

#!/usr/bin/env python3
"""Skill 品質檢查腳本"""

import yaml
import sys
import os
from pathlib import Path


def validate_skill(skill_path: str) -> list[str]:
    """驗證單個 Skill 的品質"""
    errors = []
    skill_md = Path(skill_path) / "SKILL.md"
    
    if not skill_md.exists():
        errors.append(f"Missing SKILL.md in {skill_path}")
        return errors
    
    content = skill_md.read_text(encoding="utf-8")
    
    # 1. 驗證 frontmatter
    if not content.startswith("---"):
        errors.append("Missing YAML frontmatter")
        return errors
    
    parts = content.split("---", 2)
    if len(parts) < 3:
        errors.append("Invalid YAML frontmatter format")
        return errors
    
    try:
        metadata = yaml.safe_load(parts[1])
    except yaml.YAMLError as e:
        errors.append(f"Invalid YAML: {e}")
        return errors
    
    # 2. 驗證必要欄位
    if "name" not in metadata:
        errors.append("Missing required field: name")
    elif not metadata["name"].replace("-", "").isalnum():
        errors.append(f"Invalid name format: {metadata['name']}")
    
    if "description" not in metadata:
        errors.append("Missing required field: description")
    elif len(metadata["description"]) < 20:
        errors.append("Description too short (min 20 chars)")
    
    # 3. 驗證描述包含觸發條件
    desc = metadata.get("description", "")
    trigger_keywords = ["use when", "use this when", "trigger when"]
    if not any(kw in desc.lower() for kw in trigger_keywords):
        errors.append(
            "Description should include trigger condition "
            "(e.g., 'Use when asked to...')"
        )
    
    # 4. 檢查 Token 大小（粗略估算）
    body = parts[2]
    estimated_tokens = len(body.split()) * 1.3
    if estimated_tokens > 3000:
        errors.append(
            f"SKILL.md body too large: ~{int(estimated_tokens)} tokens "
            f"(recommended < 2000)"
        )
    
    # 5. 安全檢查
    sensitive_patterns = [
        "password", "secret", "api_key", "token", 
        "private_key", "access_key"
    ]
    for pattern in sensitive_patterns:
        if pattern in content.lower() and "检查" not in content and "check" not in content.lower():
            errors.append(
                f"Potential sensitive data pattern found: {pattern}"
            )
    
    return errors


if __name__ == "__main__":
    skills_dir = sys.argv[1] if len(sys.argv) > 1 else ".github/skills"
    all_errors = {}
    
    for skill_dir in Path(skills_dir).rglob("SKILL.md"):
        skill_path = str(skill_dir.parent)
        errors = validate_skill(skill_path)
        if errors:
            all_errors[skill_path] = errors
    
    if all_errors:
        print("❌ Skill validation failed:")
        for path, errors in all_errors.items():
            print(f"\n  {path}:")
            for error in errors:
                print(f"    - {error}")
        sys.exit(1)
    else:
        print("✅ All skills passed validation")

## Skill 安全審查清單

### 1. 內容安全
- [ ] 無硬編碼密碼、Token、API Key
- [ ] 無內部系統 URL / IP
- [ ] 無個人可識別資訊（PII）
- [ ] 無企業機密資訊

### 2. 腳本安全
- [ ] Scripts 不執行危險操作（rm -rf、drop table）
- [ ] Scripts 有輸入參數驗證
- [ ] Scripts 使用 set -euo pipefail（Bash）
- [ ] Scripts 不下載外部資源（除非已審核）
- [ ] Scripts 不修改系統設定

### 3. Prompt Injection 防護
- [ ] description 不包含可被利用的指令注入
- [ ] 指令中不要求忽略安全檢查
- [ ] 不引導 AI 跳過確認步驟

### 4. 權限控管
- [ ] allowed-tools 遵循最小權限原則
- [ ] 不預核准 shell/bash（除非確實必要且已審核）
- [ ] 不需要系統管理員權限

# ❌ 過度設計：一個簡單的命名規範不需要 Skill
.github/skills/variable-naming/
├── SKILL.md (500 行)
├── scripts/
│   └── check-naming.py (300 行)
├── references/
│   ├── naming-guide-1.md
│   ├── naming-guide-2.md
│   └── naming-guide-3.md
└── templates/
    └── naming-template.md

# ✅ 正確：簡單規範放在 copilot-instructions.md
# 在 .github/copilot-instructions.md 中加入：
## 命名規範
- 類別：PascalCase
- 方法/變數：camelCase
- 常數：UPPER_SNAKE_CASE

# ❌ Token 爆炸：整份設計規範放入 SKILL.md
---
name: api-design
description: API design guide
---

# API Design（5000+ 行的完整規範...）
## HTTP Methods（200 行）
## Status Codes（300 行）
## Error Handling（400 行）
## Security（500 行）
## Performance（300 行）
## 完整範例（2000 行）
...

# ✅ 正確：核心指令精簡，詳細內容在 references/
---
name: api-design
description: API design guide. Use when designing REST APIs.
---

# API Design
## 核心原則（50 行精簡摘要）
## 快速參考（20 行）

若需詳細規範，請參考：
- references/http-methods.md
- references/status-codes.md
- references/security-standards.md

# ❌ 強耦合：Skill B 必須在 Skill A 之後使用
# api-test-gen/SKILL.md
---
name: api-test-gen
description: Generates API tests. MUST use api-design skill first.
---
# 此 Skill 假設已使用 api-design Skill 產出 OpenAPI Spec...
# 如果缺少 OpenAPI Spec 就無法運作...

# ✅ 鬆耦合：Skill 可獨立使用
# api-test-gen/SKILL.md
---
name: api-test-gen
description: >
  Generates API test cases. Can use existing OpenAPI spec 
  or generate tests from code analysis.
---
# 此 Skill 支援兩種模式：
# 1. 有 OpenAPI Spec → 依據 Spec 生成測試
# 2. 無 OpenAPI Spec → 分析程式碼生成測試

# 方式 1：使用官方 skills-ref 驗證工具
# https://github.com/agentskills/agentskills/tree/main/skills-ref
skills-ref validate ./my-skill

# 方式 2：使用 gh skill CLI（GitHub CLI v2.90.0+）
gh skill publish --dry-run    # 驗證 Skills
gh skill publish --fix        # 自動修復 metadata
gh skill publish              # 驗證並發布