# 發布與分享手冊

這份文件整理技能發布時常見的交付物與最佳做法。

## 1) 交付物清單

最少：
- skill folder（含 SKILL.md + 必要 scripts/references/assets）
- 打包後的 .skill 檔

建議（放在 skill folder 外面，例如 repo root）：
- README（安裝與使用說明）
- screenshots / demo GIF
- Releases（提供 zip/.skill 下載）
- `catalog/skills.yaml` 或等價索引

## 2) 安裝路徑（概念）

個人使用者：
- 下載 skill folder
-（如需要）zip
- 於產品設定頁上傳 / 或放到對應目錄

組織層級：
- 由管理者 workspace-wide 部署
- 設定自動更新與集中管理

## 3) 跨工具封裝原則

- 核心 skill folder 應作為單一真實來源；各平台 plugin / manifest / marketplace / config 只做薄包裝
- 先寫 support matrix：primary hosts、secondary hosts、unsupported hosts
- 若 skill 會包工具，先固定共通 tool contract 與 approval 邊界，再做 host-specific adapter
- 快取、登入狀態、安裝產物與其他可變資料不要放在 skill folder
- 若某平台需要大量改寫 workflow，先承認它不是同一個跨工具 skill，不要硬沿用名稱

## 4) Repo 結構建議

- repo root：README.md、CHANGELOG（可選）、release notes、示例
- skill folder：只放 SKILL.md + scripts/ references/ assets/ + 必要 license

避免：在 skill folder 放 README.md（容易造成混亂且不建議）。

## 5) 版本策略

- 在 frontmatter 的頂層 `version:` 維護日期版本（例如 2026.3.9）
- Release notes 於 repo 或外部文件
- 重大變更：調整 triggers/範圍需清楚公告

## 6) Publish surface audit

公開發佈前，至少逐項檢查：
- README 首屏順序是否先回答：這是什麼、支援平台、代表 skills、怎麼安裝、怎麼搜尋、怎麼貢獻
- GitHub About、topics、homepage、license 是否一致
- 發布頁與 registry 說明是否和 `SKILL.md` 的 scope、安裝路徑、權限敘事一致
- repo README 與單一 skill surface 是否互相導得回去，而不是各講各的
- 若有多個 host wrapper，支援矩陣、授權方式、approval 邊界、state / persistence 敘事是否一致

## 7) 定位與文案

原則：強調 outcome，而不是「這是一個有 YAML 的資料夾」。

也要說清楚 MCP + skills 的價值（如果適用）：
- MCP 提供工具/資料 access
- skill 提供 workflow 與 best practices