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

# 技能

> 教導 AI 認識你的應用程式，並給予它可呼叫的工具。

# 技能

技能是一個**資料夾**，告訴 AI 它對你的應用程式的了解以及可以做什麼。它包含：

* `SKILL.md` — AI 讀取的說明（必需）。
* `tools.ts` — AI 可以呼叫的工具清單（選用）。

`SKILL.md` 描述應用程式及其工具；`tools.ts` 宣告工具；每個工具由應用程式其中一個元件中的 HTTP 路由實現。

## 定義技能

在 `kazzle.config.ts` 中指向每個技能的 `SKILL.md`。Kazzle 使用其資料夾，所以旁邊的 `tools.ts` 會自動被選取。

```typescript theme={"theme":"material-theme-darker"}
import { defineConfig } from '@kazzle/app';

export default defineConfig({
  components: [{ name: 'api', type: 'process', path: './components/api/index.ts' }],
  skills: [
    { name: 'API guide', path: './skills/api/SKILL.md' },
  ],
});
```

## SKILL.md

Markdown 搭配前置資料，然後是 AI 應該遵循的說明。

```markdown theme={"theme":"material-theme-darker"}
---
name: API guide
description: How to use this app's tools.
alwaysActive: true
---

Use `save_bookmark` to store a link. It returns a confirmation.
```

## tools.ts

`SKILL.md` 旁邊的 `tools.ts` 宣告該技能可以呼叫的工具。完整的工具合約——宣告類型、處理程式請求/回應形狀，以及 `content` 與 `markdown` 結果通道——位於[工具](/apps/tools)。

```ts theme={"theme":"material-theme-darker"}
import { z } from 'zod';
import type { KazzleTool } from '@kazzle/app/tools';

export const tools = [
  {
    name: 'save_bookmark',
    displayName: 'Save bookmark',
    description: 'Save a bookmark URL and return a confirmation.',
    input: z.object({ url: z.string().url(), title: z.string().optional() }).strict(),
    target: {
      type: 'app',
      component: 'api',
      path: '/tools/save-bookmark',
      method: 'POST',
      body: '${input}',
    },
  },
] as const satisfies readonly KazzleTool[];
```

## AI 如何使用技能

AI 依需求讀取 `SKILL.md`（不是預先讀取所有技能）來支撐其回答，並可以呼叫在 `tools.ts` 中宣告的工具。沒有相符路由的工具不會執行任何動作；需要同時新增兩者。不支援 `tools.json`。