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

# Skills

> 說明如何載入可重用的 SKILL.md,並透過 SessionConfig 管理領域專屬指令。

## Skills

Skills 是可重用的提示模組。透過載入 `SKILL.md`,可為 Session 加入特定領域的指令。

## 概觀

* 可將領域知識封裝為 Skill 重複使用
* 可在專案之間共用相同的行為
* 可依 Session 切換啟用/停用

Laravel 版透過 `SessionConfig` 的 `skillDirectories` 與 `disabledSkills` 進行設定。

## 基本用法

在 `skillDirectories` 中指定父目錄後,會載入其底下每個子目錄中的 `SKILL.md`。

```php theme={null}
use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionConfig;

Copilot::start(function (CopilotSession $session) {
    $response = $session->sendAndWait(prompt: '請從安全性角度審查此差異');

    dump($response->content());
}, config: new SessionConfig(
    skillDirectories: [
        base_path('skills'),
    ],
));
```

也可用陣列形式指定。

```php theme={null}
Copilot::run(
    prompt: '請提出改進 README 的建議',
    config: [
        'skillDirectories' => [base_path('skills')],
    ],
);
```

## 停用 Skill

使用 `disabledSkills` 可只停用已載入 Skill 的一部分。

```php theme={null}
$config = new SessionConfig(
    skillDirectories: [base_path('skills')],
    disabledSkills: ['experimental-feature', 'deprecated-tool'],
);
```

## 目錄結構

```text theme={null}
skills/
├── code-review/
│   └── SKILL.md
└── documentation/
    └── SKILL.md
```

`skillDirectories` 需指定 `skills/` 這類父目錄。

## SKILL.md 格式

`SKILL.md` 為 Markdown,可選擇性附上 YAML frontmatter。

```markdown theme={null}
---
name: code-review
description: Specialized code review capabilities
---

# Code Review Guidelines

When reviewing code, always check for:

1. Security vulnerabilities
2. Performance issues
3. Code style
4. Test coverage
```

frontmatter 的主要項目:

* `name`: Skill 識別碼(用於 `disabledSkills` 中指定)
* `description`: Skill 的簡短說明

若省略 `name`,會使用目錄名稱。

## 與 Custom Agents 搭配

若在 `customAgents[].skills` 指定 Skill 名稱,啟用該 Agent 時會預先載入該 Skill 內容。

```php theme={null}
use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    skillDirectories: [base_path('skills/security')],
    customAgents: [
        [
            'name' => 'security-auditor',
            'description' => 'Security-focused code reviewer',
            'prompt' => 'Focus on OWASP Top 10 vulnerabilities',
            'skills' => ['security-scan', 'dependency-check'],
        ],
    ],
);
```

> 若省略 `skills`,Skill 內容不會注入該 Agent。

## 透過 RPC 檢查與操作

Skill 的探索與啟用/停用也可以透過 RPC 進行。

```php theme={null}
// 於伺服器層級探索 Skill
$result = Copilot::client()->rpc()->skills()->discover();

// 列出 Session 內 Skill
$session->rpc()->skills()->list();

// 於 Session 內個別切換啟用/停用
$session->rpc()->skills()->enable(['name' => 'security-scan']);
$session->rpc()->skills()->disable(['name' => 'security-scan']);
```

## 最佳實踐

* 依領域切分 Skill(例如 `skills/security`、`skills/testing`)
* 於 frontmatter 加上 `name` 與 `description`
* 若指令有衝突,透過 `disabledSkills` 明確排除
* 建議先單獨測試,再組合多個 Skill

## 參考

* [SessionConfig](/zh-TW/packages/laravel-copilot-sdk/session-config)
* [Custom Agents](/zh-TW/packages/laravel-copilot-sdk/custom-agents)
* [RPC](/zh-TW/packages/laravel-copilot-sdk/rpc)


## Related topics

- [laravel/agent-skills — Laravel 官方 AI Agent 技能集](/zh-TW/blog/agent-skills-introduction.md)
- [建立 Boost 的自定義 Agent](/zh-TW/advanced/boost-custom-agent.md)
- [Laravel 與 AI 開發](/zh-TW/ai.md)
- [Laravel Boost](/zh-TW/boost.md)
- [Streaming Events](/zh-TW/packages/laravel-copilot-sdk/streaming-events.md)