agent-skill-creator — 跨平台 Agent Skill 工廠完整教學

一句話定位：把任意工作流（描述 / 連結 / code / PDF / 轉錄稿）丟進去，5 分鐘內產出一份「validated + security-scanned + 自帶 install.sh」的跨 14+ 平台 agent skill。

1. 專案定位

1.1 解決什麼問題

每一個 AI coding 工具（Claude Code / Copilot / Cursor / Windsurf / Codex / Gemini / Kiro…）都從零開始 — 不認識公司流程、資料來源、合規需求。每個人每次對話都要重複解釋同一套工作流，知識散落在個人聊天記錄裡，新人從頭學起。

Agent skills 是修這個問題的標準解：把結構化知識打包成「skill」，agent 自動載入 — 等於裝了一個 app。安裝一次，全團隊任何人在任何平台都能呼叫，每次結果一致。

但寫 skill 本身有門檻：需要懂 spec 格式、寫好 prompt 指令、設計 progressive disclosure、寫可執行程式、設好 activation keywords。即使簡單 skill 也要多輪迭代。

agent-skill-creator 把這個門檻拆掉：你丟原料（messy docs / links / code / PDF / 模糊描述）進去 → 它產出一份 ready-to-install 的 skill。

1.2 與類似專案差異

1.3 適用情境

• 公司內部有重複性工作流（每週拉 CRM、每日跑合規檢查、每月對賬）想包成 skill 共享
• 已有現成 Python script，想 wrap 成 multi-platform skill
• 接到一份 messy PDF / runbook / wiki，要快速做出 reusable agent
• 已有一份 skill 想 export 成 Cursor .mdc / Windsurf .md rules / Claude Desktop .zip

2. 安裝指南

2.1 一鍵安裝（推薦）

1curl -fsSL https://raw.githubusercontent.com/FrancyJGLisboa/agent-skill-creator/main/scripts/bootstrap.sh | sh

clones 到 ~/.agents/skills/agent-skill-creator/ 並 symlink 到所有偵測到的全域平台（Claude Code、Gemini CLI、Goose、OpenCode、Copilot）。日後 git pull 一次即同步全平台。

2.2 手動 git clone

 1# Claude Code / VS Code Copilot（共用路徑）
 2git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git \
 3  ~/.claude/skills/agent-skill-creator
 4
 5# Cursor（per-project）
 6git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git \
 7  .cursor/rules/agent-skill-creator
 8
 9# 通用路徑（Codex CLI / Gemini CLI / Kiro / Antigravity 都認）
10git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git \
11  ~/.agents/skills/agent-skill-creator

2.3 已 clone → 安裝到所有平台

1cd agent-skill-creator
2./install.sh              # 安裝到所有偵測到的平台
3./install.sh --dry-run    # 預覽不執行
4./install.sh --uninstall  # 移除全部 symlinks

2.4 第一次使用

打開你的 agent，輸入：

1/agent-skill-creator Every week I pull sales data from CRM, dedupe, calculate
2regional totals, generate a PDF report.

幾分鐘後會在 ~/.claude/skills/sales-report-skill/（或對應平台路徑）生出一個完整 skill，並回報下一步指令。

3. 核心架構解析

3.1 架構圖（mermaid component）

flowchart TD
    A[使用者輸入
messy docs / links / code / PDF] --> B{Phase 1
Discovery}
    B --> C[Phase 2
Design：4-6 priority analyses]
    C --> D[Phase 3
Architecture：single skill vs suite]
    D --> E[Phase 4
Detection：description <= 1024 chars]
    E --> F[Phase 5
Implementation：寫檔案]
    F --> G[scripts/validate.py]
    F --> H[scripts/security_scan.py]
    F --> I[scripts/install-template.sh
→ 生成 install.sh]
    G --> J{品質檢驗}
    H --> J
    J -->|通過| K[Auto-install 到當前平台]
    J -->|失敗| L[回報問題
停止發佈]
    K --> M[14+ 平台部署
SKILL.md / .mdc / .md rules]
    M --> N[scripts/skill_registry.py
團隊共享]
    M --> O[scripts/staleness_check.py
定期偵測過期]

    style B fill:#e1f5ff
    style C fill:#e1f5ff
    style D fill:#e1f5ff
    style E fill:#e1f5ff
    style F fill:#e1f5ff
    style J fill:#fff4e1
    style K fill:#d4edda
    style L fill:#f8d7da

3.2 三層輸出格式（Tier 系統）

3.3 5 個 Phase 在工廠裡的角色

• Phase 1 Discovery：研究 API、資料來源；比較 cost / rate limit / data quality；有決策
• Phase 2 Design：定義 4-6 個核心分析，覆蓋 80% 使用情境；每個分析寫 name / objective / inputs / outputs / methodology
• Phase 3 Architecture：決定 single skill 還是 multi-skill suite
• Phase 4 Detection：寫 ≤1024 字元的 description field — agent 靠這段決定何時 activate
• Phase 5 Implementation：建目錄 → 寫 SKILL.md → 實作 Python scripts → 寫 references → assets → install.sh → README → validate → security_scan → auto-install

4. Helper Scripts 詳細用法

4.1 常用命令速查

 1# 驗證
 2python3 scripts/validate.py ./my-skill/
 3python3 scripts/validate.py ./my-skill/ --json     # CI/CD
 4
 5# 安全掃描
 6python3 scripts/security_scan.py ./my-skill/
 7
 8# Staleness 檢查
 9python3 scripts/staleness_check.py ./my-skill/
10python3 scripts/staleness_check.py ./my-skill/ --check-deps --check-drift
11
12# Registry
13python3 scripts/skill_registry.py init --name "Acme Corp Skills"
14python3 scripts/skill_registry.py publish ./skill/ --tags t1,t2
15python3 scripts/skill_registry.py list
16python3 scripts/skill_registry.py search "query"
17python3 scripts/skill_registry.py install skill-name
18
19# Export
20python3 scripts/export_utils.py ./skill/ --variant desktop   # → claude.ai zip
21python3 scripts/export_utils.py ./skill/ --variant api       # → API 整合包
22
23# 安裝任何 skill
24./scripts/install-skill.sh https://github.com/someone/skill.git
25./scripts/install-skill.sh ./local-skill --platform cursor --project
26./scripts/install-skill.sh ./local-skill --dry-run

所有命令支援 --json，回傳 exit code 0（成功）/ 1（失敗）。

5. 應用場景

5.1 場景 A：把每週銷售報告 wrap 成 skill

1/agent-skill-creator Every week I pull sales data from Salesforce REST API,
2dedupe by customer email, aggregate by region, and ship a PDF to leadership@.
3Source: docs/runbook-weekly-sales.md, scripts/salesforce_client.py

→ 產出 weekly-sales-report-skill/，含：

• SKILL.md（trigger keywords：weekly sales, regional aggregation, salesforce）
• scripts/run.py（functional code，無 TODO）
• references/（runbook 詳解）
• install.sh（14 平台 installer）

5.2 場景 B：合規檢查 skill

1/agent-skill-creator Based on compliance-checklist.pdf, create a skill
2for SOX audits.

→ 自動讀 PDF、抽 checklist items、生 audit checklist skill；security_scan 會檢查是否誤 hardcode 任何 audit secrets。

5.3 場景 C：multi-agent suite（複雜情境）

1/agent-skill-creator We need: (1) commodity-research-agent that pulls NOAA
2NDVI/VHI + NASA FIRMS + Copernicus Sentinel-2, (2) trade-flow-agent that
3queries PSD API + GTT, (3) report-agent that merges outputs.

→ Phase 3 自動判定要產 multi-skill suite；shared resources 集中、各 sub-skill 獨立 install。

5.4 場景 D：把現有 script 轉成 skill

1/agent-skill-creator See scripts/invoice_processor.py — turn it into
2a reusable skill.

→ 讀 script、抽 entry points、生 wrapper SKILL.md、加 trigger keywords。

6. 資安掃描報告 🟡 黃燈

6.1 結論

🟡 整體中等風險（黃燈） — 無 hardcoded secrets / token；shell scripts 內有 eval 但僅用於變數展開，subprocess 全部以 list args 呼叫；最主要的攻擊面是 curl ... | sh 安裝模式（一般 install convention，但仍屬 supply-chain risk）。

6.2 紅黃綠燈詳列

6.3 部署建議

• 企業內網部署：建議 fork 一份、移除 curl|sh 入口、改用內部鏡像；staleness_check.py 的外連請求走 HTTP proxy
• 個人開發：直接用上游版本即可，注意 version 在 README badge（5.0.0）與 SKILL.md frontmatter（4.0.0）不一致 — 升級時看 git log 而非 frontmatter
• CI/CD 整合：所有掃描命令支援 --json，可直接接 GitHub Actions / GitLab CI

7. FAQ

Q1：skill 為什麼要符合 SKILL.md 標準？不能自訂格式嗎？ 可以自訂，但會喪失「一份 SKILL.md 跑 14 平台」的優勢。Tier 1 平台直接讀 SKILL.md，Tier 2 平台靠 installer 自動轉換 — 自訂格式等於要每平台都寫 adapter。

Q2：description field 為何卡 1024 字元？ 這是 agent activation 的 budget。agent 載入 skill metadata 時會把 description 塞進 context；超過 1024 會被截斷 → 觸發失敗。Phase 4 專門處理這個壓力。

Q3：generated skill 的 install.sh 怎麼自動偵測平台？ 照固定順序檢查 ~/.claude/ / .cursor/ / ~/.cursor/ / .github/ / ~/.codeium/windsurf/ / .windsurf/ / .clinerules/ / ~/.gemini/ / .kiro/ / .trae/ / .roo/ / ~/.config/goose/ / ~/.config/opencode/ / ~/.agents/。第一個找到的就裝。

Q4：multi-skill suite 跟 single skill 怎麼選？ 看 workflow 數量、code complexity、maintenance needs。Phase 3 有 decision logic — 大致：≤2 workflows + 共用資料模型 → single；≥3 workflows / 不同資料源 / 不同更新節奏 → suite。

Q5：跟 Anthropic 官方 spec 有何關係？ 本專案是 Open Standard 的「實作 + 工廠」。spec 定義格式（SKILL.md frontmatter / naming / progressive disclosure），本專案產出符合 spec 的 skill。

Q6：Cursor 沒有全域 skills 目錄怎麼辦？ README 給的解法：clone 一份到 ~/agent-skills/，每個專案 ln -s 進 .cursor/rules/。配合 shell alias install-skills 一條命令搞定。

8. 進階技巧

8.1 Interactive Mode

1/agent-skill-creator   # 不帶參數 → 走 interactive wizard

詳見 references/interactive-mode.md。適合「我也不知道要做什麼，但每天都很煩」的情境。

8.2 從 transcript 創建

把會議錄音轉錄丟進去：

1/agent-skill-creator transcript.txt — 整理出每週週會的標準議程 skill

agent 會抽出 recurring patterns、生 agenda template skill。

8.3 AgentDB 整合（learning system）

Skill 跑過會把使用者偏好寫進 AgentDB（SQLite），下次自動套用。詳見 references/agentdb-integration.md。

8.4 Staleness 主動偵測

排程跑：

1python3 scripts/staleness_check.py ./my-skill/ --check-deps --check-drift --json

回傳 JSON 含 review-stale / deps-outdated / api-drift 三類事件，可接 Slack / email 通知。

8.5 Team Registry

1python3 scripts/skill_registry.py init --name "Acme Corp Skills"
2python3 scripts/skill_registry.py publish ./skill/ --tags compliance,weekly

Registry 為 JSON 檔，可放 git / S3 / 內部 fileserver。

9. 整合進其他工作流

9.1 跟本專案（AI-knowledge template）整合

1ai-gh-save 抓 metadata → graphify 建知識圖 →
2agent-skill-creator 把工作流 wrap 成 skill →
3quarkdown 排版 → Discord 分享

agent-skill-creator 補足「把已知工作流變成 reusable skill」這一層 — 跟 Layer 4 graphify（建圖）、Layer 7 quarkdown（排版）、Layer 18 research-pipeline-v2（研究 pipeline）正交，可疊用。

9.2 跟 CI/CD 整合

1# .github/workflows/skill-quality.yml
2- run: python3 scripts/validate.py ./ --json
3- run: python3 scripts/security_scan.py ./ --json
4- run: python3 scripts/staleness_check.py ./ --check-deps --json

任何一步 exit code ≠ 0 → block PR。

9.3 跟 Patent Creator（Layer 13）整合

不適合 — patent-creator 有機密邊界，禁用外部 API 與雲端工具；agent-skill-creator 的工廠模式會 follow links / fetch API docs，與機密邊界衝突。

9.4 跟 paper-tutorial（Layer 15）整合

可整合：paper-tutorial 產出 N 篇 paper 教學後，把 method section 整理成 skill 給後續分析使用。

10. 重點摘要 Checklist

• 已用 curl ... | sh 或 ./install.sh 安裝到至少一個平台
• 已執行 /agent-skill-creator <description> 跑過一次完整 pipeline
• 已用 scripts/validate.py + scripts/security_scan.py 驗證產出 skill
• 已了解 5 Phase（Discovery / Design / Architecture / Detection / Implementation）
• 已了解 Tier 1 / Tier 2 / Tier 3 平台差異
• 已了解 description field 1024 字元限制與作用
• 已決定企業內網是否需 fork + 改 install 來源
• 已決定是否啟用 staleness 排程 + registry

11. 進一步閱讀

11.1 官方資源

• 主 repo：https://github.com/FrancyJGLisboa/agent-skill-creator
• Agent Skills Open Standard：https://github.com/anthropics/agent-skills-spec
• Claude Skills 介紹影片：https://www.youtube.com/watch?v=izJkgLqlbN8
• VS Code Copilot Agent Skills：https://code.visualstudio.com/docs/copilot/customization/agent-skills

11.2 Repo 內 references（按需深讀）

• references/pipeline-phases.md（1402 行）— 5 phase 完整 SOP
• references/architecture-guide.md（944 行）— 結構決策
• references/quality-standards.md（1171 行）— 文件與 code 規範
• references/phase4-detection.md（864 行）— description 怎麼寫才會 activate
• references/cross-platform-guide.md（458 行）— Tier 制度詳解
• references/multi-agent-guide.md（385 行）— multi-skill suite
• references/interactive-mode.md（263 行）— interactive wizard
• references/agentdb-integration.md（253 行）— learning system

11.3 本專案內相關文件

• .claude/skills/gh-tutorial-qd/SKILL.md — 本教學使用的工作流
• docs/260513 gh-tutorial-qd workflow skill.md — workflow 設計檢討
• CLAUDE.md — 19 Layer 整體架構

自動生成：AI-knowledge template gh-tutorial-qd workflow（2026-05-28） Mermaid 圖內 . 為 HTML decimal entity，避免 quarkdown 把點開頭字串誤判為函式呼叫。