📦 金融業範例
├── 前台交易系統 → 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
# 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 / 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: 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 同步至專案

---
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: 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

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

### 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: 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("餘額不足");
    }
}

### 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);
}

### 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: |
          # 部署指令

### 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 分鐘。

---

## 第 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 風險
- [ ] 腳本有輸入驗證
- [ ] 腳本不會刪除或修改系統關鍵檔案
- [ ] 無外部網路呼叫（除非必要且已審核）
- [ ] 輸出不會洩漏系統內部資訊

.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 設計

# 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 → 分析程式碼生成測試

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