編寫跨代理的 SKILL.md 技能
技能是一個包含 SKILL.md 檔案的資料夾。檔案開頭為 YAML
前端區塊（名稱 + 描述），後接代理會按需載入的 Markdown 指令。由於 Claude Code、DeepSeek Harness (dsh)、Codex CLI、Gemini CLI、Copilot 和 Cursor 都讀取此相同格式，因此一份編寫良好的技能可供所有代理使用。
結構
my-skill/
├── SKILL.md # 必填：前端區塊 + 指令
├── references/ # 選填：模型可按需讀取的長篇文件
└── scripts/ # 選填：技能可能會執行的輔助腳本
---
name: my-skill
description: >-
一兩句話：它的功能以及何時使用。這是代理根據使用者請求比對的觸發條件——請像撰寫路由規則一樣撰寫它。
---
# My skill
逐步指示。假設對象為能幹的工程師；要具體，不要含糊。
決定技能是否有效的規則
name必須為 kebab-case — 小寫字母、數字、連字號；最多 64 個字元。代理會拒絕或變造其他名稱。aipx會自動為你規範化，但還是請直接送出正確的名稱。description是觸發條件，而非說明文件。 錯誤範例：「用於處理事物的工具。」 正確範例：「從 URL 摘要 YouTube/Bilibili 影片和 Podcast。當使用者貼上影片或音訊連結時使用。」- 將 SKILL.md 控制在約 500 行以內。 將深度內容放入
references/*.md並連結至該處（例如「參閱 references/schema.md」）。代理僅在技能觸發時載入主體；過大的主體會浪費上下文並稀釋行為。 - 不要巢狀技能。 探索只會掃描技能根目錄的直接子項目——
skills/a/SKILL.md會被找到，skills/a/b/SKILL.md則不會。 - 相對連結必須保持相對。 如果 SKILL.md 參照
scripts/x.py，則整個資料夾必須一起移動——切勿連結到技能目錄外部。
技能存放位置（使用者根目錄）
| 根目錄 | 讀取者 |
|---|---|
~/.agents/skills/<name>/SKILL.md | DeepSeek Harness (dsh)、Codex CLI |
~/.claude/skills/<name>/SKILL.md | Claude Code |
~/.gemini/skills/<name>/SKILL.md | Gemini CLI |
~/.copilot/skills/<name>/SKILL.md | GitHub Copilot CLI |
另外也有專案範圍的對應目錄（例如儲存庫中的 .claude/skills/、.agents/skills/）。請勿手動複製——請使用 aipx sync 將一個副本連結至每個代理根目錄。
發布前測試
# 是否可解析並被發現？
aipx install ./my-skill --dry-run
aipx install ./my-skill
aipx list
然後開啟你的代理，確認技能有出現（Claude Code：會顯示在技能清單中；dsh：/ 指令面板 → Skills 群組）。
發布檢查清單
- 儲存庫中包含位於穩定路徑的技能資料夾，例如
skills/my-skill/ -
description說明觸發條件，而不只是功能 - 透過全新安裝可正常運作（
aipx install owner/repo#path:/skills/my-skill） - 新增 GitHub 主題以便探索：
agent-skills、claude-code、dsh-plugin（如果它也附帶 dsh 套件）、deepseek（如果與 DS 相關） - 選填：雙目標套件封裝——請參閱
dsh-plugin-dev和claude-plugin-dev技能