> ## 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

包含 frontmatter 的 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` 结果通道——位于 [Tools](/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`。