> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bricks.tools/llms.txt
> Use this file to discover all available pages before exploring further.

# 技能

> AI 代理的可重複使用指令集

技能是可重複使用的指令文件，為 AI 代理提供上下文與規則。使用技能來定義代理應遵循的專業工作流程、程式碼模式或領域知識。

## 使用技能

在聊天輸入列中輸入 `/` 以觸發技能指令自動完成。選擇技能後，會將 `/skill-name` 引用插入訊息中，並以可移除的標籤形式顯示在輸入列中。

引用會以一般文字送出。代理會依據技能描述及您的需求，自行決定是否載入每個被引用的技能。

## 技能範圍

技能可在兩個層級定義：

| 範圍     | 位置                                  | 適用對象   |
| ------ | ----------------------------------- | ------ |
| **全域** | `~/.bricks-project-desktop/skills/` | 所有專案   |
| **專案** | `<project>/.bricks/skills/`         | 僅限目前專案 |

當專案技能與全域技能同名時，專案技能優先。

## 技能結構

每個技能是包含以下結構的目錄：

```
my-skill/
├── SKILL.md          # 必填：元資料 + 指令
├── agents/           # 選填：子代理指令檔案（.md）
├── rules/            # 選填：額外規則檔案（.md）
└── references/       # 選填：參考檔案（.md）
```

## SKILL.md 格式

`SKILL.md` 檔案包含 YAML frontmatter，後接 markdown 內容：

```markdown theme={null}
---
name: my-skill
description: A brief description of what this skill does
metadata:
  author: Your Name
  version: 1.0.0
license: MIT
allowed-tools:
  - read_file
  - write_file
  - edit_file
---

Your skill instructions go here. This content is included
in the agent's context when the skill is activated.

## Rules

- Follow these coding patterns...
- Always use this approach...
```

### Frontmatter 欄位

| 欄位              | 說明                            |
| --------------- | ----------------------------- |
| `name`          | 技能名稱（用於顯示與比對）                 |
| `description`   | 顯示於技能清單中的簡短說明                 |
| `metadata`      | 包含 `author` 與 `version` 欄位的物件 |
| `license`       | 授權類型                          |
| `allowed-tools` | 此技能啟用時代理可使用的工具清單              |

## 內建技能

CTOR 在全域與專案範圍均內建技能，開箱即用。

內建全域技能在啟動時會自動安裝至 `~/.bricks-project-desktop/skills/`。若您刪除內建技能，它不會被重新安裝——您可以從技能面板重新安裝。內建技能在技能清單中顯示**內建**標籤。

### 全域技能

<AccordionGroup>
  <Accordion title="brainstorming" icon="lightbulb">
    在創意工作前進行協作設計探索。引導代理了解專案上下文、提出澄清問題、提議含取捨的方案，並在實作前取得核准。設計定案後，代理會轉換至[計畫模式](/zh-Hant/ctor/reference/plan-mode)以撰寫實作計畫。改編自 [superpowers](https://github.com/obra/superpowers)。

    **使用時機：** 當您有功能想法或創意任務，在撰寫程式碼前需要設計探索時。若任務已定義清楚，可略過此步驟。
  </Accordion>

  <Accordion title="skill-creator" icon="hammer">
    透過聊天建立新技能的指南。教授從規劃到迭代的技能建立生命週期——涵蓋技能結構、漸進式揭露設計與捆綁資源。

    包含用於初始化、驗證和打包技能的輔助指令碼。

    **使用時機：** 當您想為代理建立新技能時。
  </Accordion>

  <Accordion title="template-creator" icon="file-lines">
    從現有 BRICKS 應用程式中提取可重複使用的提示範本。分析專案的設計、資料流和關鍵功能，然後以純語言產生一個簡潔的 5–10 項需求清單，可用作提示來重建類似的應用程式。

    流程：

    1. **讀取專案** — 分析視覺設計、元件、狀態模型、資料流和關鍵行為
    2. **識別關鍵點** — 將應用程式提煉為其核心特徵
    3. **撰寫範本** — 產生 5–10 個純語言需求的編號清單
    4. **呈現與改善** — 與您迭代，直到範本符合需求
    5. **儲存** — 將最終範本寫入專案根目錄的 `template.md`

    **使用時機：** 當您想從現有 BRICKS 應用程式中提取可重複使用的範本時——適用於建立類似專案的起點。
  </Accordion>

  <Accordion title="imagegen" icon="image">
    使用 CTOR 已設定的影像供應商（OpenAI `gpt-image-2`、OpenAI Codex 後端，或透過 Gemini API 或 Vertex AI 的 Google Nano Banana）為目前專案產生與編輯點陣影像。內含一個 Bun 指令碼，會解析供應商認證、將輸出寫入專案（預設：`output/imagegen/output.png`），並支援尺寸、品質、長寬比與格式選項。

    此技能僅在至少設定一個影像能力供應商時才會啟用。搭配 `--provider auto` 時，若目前聊天模型的供應商支援影像生成，CTOR 會優先使用該供應商，否則退回至已設定的預設供應商。

    **使用時機：** 當您需要產生點陣資產（照片、插畫、材質、精靈圖、模擬圖、產品圖、UI 概念圖）或想編輯現有的點陣影像時。若 SVG、HTML/CSS、canvas 或現有原生資產更適合作為確定性輸出，請略過此技能。
  </Accordion>

  <Accordion title="bricks-cli" icon="terminal">
    [BRICKS](https://bricks.tools) CLI 工具（`bricks-cli`）的參考資料。涵蓋 BRICKS Foundation 管理、應用程式與模組操作、Media Flow、LAN 裝置探索、ACP 橋接與 MCP 伺服器整合。

    主要功能：

    * **BRICKS Foundation 管理** — 列出、控制、截圖和監控裝置
    * **BRICKS Foundation 群組** — 派送指令、重新整理和監控群組
    * **應用程式** — 列出、更新、綁定裝置、初始化和部署專案
    * **模組** — 列出、更新、初始化專案
    * **Media Flow** — 管理 Media Box、上傳含處理選項的檔案
    * **DevTools** — 透過 UDP 廣播探索區域網路上的裝置
    * **MCP 伺服器** — 啟動本機 MCP 伺服器以整合工具
    * **ACP 橋接** — 與 CTOR 代理橋接

    **使用時機：** 當您需要與 BRICKS API 互動或從指令列管理 BRICKS Foundation 時。
  </Accordion>
</AccordionGroup>

### 專案技能

BRICKS 專案包含內建技能，提供建立 BRICKS 應用程式的領域知識：

* **bricks-ctor** —架構模式、動畫、自動化、資料計算等
* **bricks-design** —建立獨特、精緻 BRICKS 介面的創意設計指南

<Card title="bricks-ctor 內建技能" icon="cube" href="/zh-Hant/ctor-pkg/skills">
  請參閱 bricks-ctor 文件中的完整技能參考。
</Card>

## 安裝技能

從公開的 GitHub 儲存庫或本機資料夾安裝第三方技能。在技能面板中，點選 **+ Install Skills** 開啟安裝介面。

### 從 GitHub 儲存庫安裝

選擇 **GitHub Repository**，並輸入儲存庫規格：

* `owner/name` —使用儲存庫的預設分支
* `owner/name@branch` —指定特定分支
* 完整的 GitHub 連結— `https://github.com/owner/name` 或 `https://github.com/owner/name/tree/branch`

點選 **Detect**。CTOR 會下載目標分支的 tarball，並遞迴掃描其中的 `SKILL.md` 檔案。

### 從本機資料夾安裝

選擇 **Local Folder**，點選 **Pick Folder** 選擇目錄，然後點選 **Detect**。CTOR 會掃描資料夾中的 `SKILL.md` 檔案。若所選資料夾本身即為技能（根目錄包含 `SKILL.md`），則會被視為單一技能。

在 macOS 上，**Open Folder in CTOR** Finder Service 可加速此流程。在 Finder 中對資料夾按右鍵並選擇 **Services → Open Folder in CTOR**：若資料夾包含 `SKILL.md` 檔案但本身並非 BRICKS 專案，CTOR 會開啟此安裝介面，預先填入該資料夾並使用 **Global** 範圍，直接帶您前往已偵測技能的清單。

### 選擇與安裝

已偵測的技能會以名稱與說明列出。勾選您想安裝的項目，或使用 **Select all** / **Select none**。接著在底部選擇安裝範圍：

* **Global** —安裝至 `~/.bricks-project-desktop/skills/`
* **Project** —安裝至 `<project>/.bricks/skills/`（僅在開啟專案時可用）

點選 **Install (N)** 安裝所選技能。若目標範圍中已存在同名技能，CTOR 會顯示衝突確認橫幅，列出將被覆寫的項目，並要求您確認後才進行覆寫。

## 管理技能

點選側邊欄中的**技能**，開啟技能面板。在此您可以：

* 在**專案**和**全域**範圍之間切換
* 檢視所有可用技能及其說明
* 透過每張卡片上的開關啟用或停用技能
* 編輯技能的 `SKILL.md` 內容
* 刪除技能

### 啟用與停用技能

每張技能卡都有一個開關，可切換是否將該技能載入代理的上下文。停用的技能仍會顯示在清單中，但在您觸發 `/` 自動完成時會被跳過，也不會傳送給代理。此設定同樣適用於內建技能——當您想暫時關閉某個內建技能（例如 `imagegen`）但又不想移除它時，可使用此開關。

## 規則與參考資料

`rules/` 和 `references/` 子目錄可包含額外的 markdown 檔案，這些檔案會與主要 `SKILL.md` 內容一起載入：

* **代理** —[子代理](/zh-Hant/ctor/reference/sub-agents#instructions-file)的指令檔案。主代理可以透過 `instructions_file` 參數將這些檔案傳遞給 `spawn_agent`，以 skill 專屬的指令驅動子代理（通常是 `general`）。
* **規則** —代理的額外指令或限制
* **參考資料** —背景知識、API 文件或範例

`rules/` 和 `references/` 目錄中的所有 `.md` 檔案在技能啟用時都會被包含。`agents/` 中的檔案則在被 `instructions_file` 參照時按需載入。