SKILL.md 格式

SKILL.md 檔案格式的完整規範。

概述

SKILL.md 檔案使用帶有 YAML 前置資料的 Markdown 來定義 Agent 技能。

檔案結構

markdown

---
# YAML Frontmatter (metadata)
name: Skill Name
description: Brief description
---

# Main Content
Your skill instructions in Markdown format.

前置資料欄位

必填欄位

| 欄位 | 類型 | 說明 | |-------|------|-------------| | name | string | 技能名稱（最多 50 個字元） | | description | string | 簡短描述（最多 200 個字元） |

選填欄位

| 欄位 | 類型 | 說明 | |-------|------|-------------| | version | string | 語意化版本（例如 "1.0.0"） | | author | string | 作者名稱或組織 | | license | string | 授權類型（例如 "MIT"） | | platforms | array | 支援的平台 | | categories | array | 技能分類 | | tags | array | 搜尋關鍵字 | | repository | string | 原始碼儲存庫 URL | | website | string | 文件網站 |

前置資料範例

yaml

---
name: React Best Practices
description: Guidelines for writing clean React components
version: 2.1.0
author: React Community
license: MIT
platforms:
  - claude-code
  - codex
  - chatgpt
categories:
  - development
  - frontend
tags:
  - react
  - javascript
  - components
---

內容結構

建議的區段

markdown

# Skill Name

## Context
Background information and domain knowledge.

## Guidelines
Specific rules and best practices.

## Do's and Don'ts
Clear behavioral guidance.

## Examples
Sample interactions or code snippets.

## References
Links to additional resources.

格式化技巧

使用標題（#、##、###）來組織內容
使用項目清單列出指導原則
使用程式碼區塊呈現範例
使用粗體強調重點
保持段落簡潔

平台欄位

指定您的技能支援哪些平台：

yaml

platforms:
  - claude-code    # Claude Code CLI
  - codex          # Codex CLI
  - chatgpt        # ChatGPT Custom Instructions

驗證

您的 SKILL.md 將進行以下驗證：

有效的 YAML 前置資料語法
必填欄位存在
欄位長度限制
有效的分類/平台值
Markdown 格式

完整範例

markdown

---
name: TypeScript Best Practices
description: Guidelines for writing type-safe, maintainable TypeScript code
version: 1.0.0
author: TypeScript Community
license: MIT
platforms:
  - claude-code
  - codex
categories:
  - development
  - frontend
  - backend
tags:
  - typescript
  - javascript
  - types
---

# TypeScript Best Practices

## Context
This skill provides guidelines for writing high-quality TypeScript code.

## Guidelines

### Type Safety
- Always define explicit types for function parameters
- Avoid using `any` type
- Use type guards for runtime checks

### Code Organization
- One export per file for main modules
- Group related types in a `types.ts` file
- Use barrel exports for public APIs

## Do's and Don'ts

### Do
- Use strict mode
- Define interfaces for object shapes
- Use generics for reusable code

### Don't
- Suppress TypeScript errors with `@ts-ignore`
- Use `any` as a quick fix
- Mix JavaScript and TypeScript in the same project

## Examples

### Good: Explicit Types
\`\`\`typescript
function greet(name: string): string {
  return \`Hello, \${name}!\`;
}
\`\`\`

### Bad: Implicit Any
\`\`\`typescript
// Avoid this
function greet(name) {
  return \`Hello, \${name}!\`;
}
\`\`\`