Skill 技能系统

Skill 是 AI 助手的知识层——纯 Markdown 文档，用于教 AI 如何使用工具或注入领域知识。

Skill 不是什么

• ❌ 不注册工具
• ❌ 不定义 JSON Schema
• ❌ 不包含可执行代码

Skill 就是文档。区别只在于内容是否提及工具。

创建技能文档

1. 创建目录和文件

skills/
└── my-guide/
    └── SKILL.md

2. 编写 SKILL.md

必须包含 frontmatter（--- 包裹的元数据）：

---
name: my-guide
description: 我的服务器自定义指南
---

# 我的指南

这里写你的知识内容...

## 常用命令

- /spawn — 回到主城
- /home — 回到家
- /sethome — 设置家的位置

## 新手 FAQ

Q: 怎么赚钱？
A: 可以出售物品给 NPC 商店，或者完成每日任务。

3. 在助手配置中启用

# assistants/player-helper/config.yml
skills:
  load:
    - server-wiki
    - my-guide      # 新增的技能

4. 重载

执行 /ark reload。

Frontmatter 字段

字段	必填	说明
name	✅	技能唯一标识
description	✅	简短描述（显示在技能索引中）

按需加载机制

为节省 token，技能内容不会全量注入到系统提示中。

工作流程

1. 系统提示中只注入技能索引（名称 + 描述）
2. AI 根据玩家问题选择最匹配的技能
3. AI 调用 skill_read 工具按需读取完整文档
4. AI 基于文档内容回答玩家

优势

• 💰 节省 token — 只在需要时读取
• 📈 可扩展 — 添加再多技能也不影响系统提示大小
• 🎯 精确 — AI 自己判断读哪个文档

多文件技能（Wiki 模式）

技能可以包含多个子文件，形成 Wiki 结构：

skills/
└── server-wiki/
    ├── SKILL.md              # 入口文件（包含章节列表）
    └── docs/
        ├── _meta.yml          # 目录元信息
        ├── getting-started.md
        ├── economy/
        │   ├── _meta.yml
        │   ├── currency.md
        │   └── shop.md
        └── territory/
            ├── _meta.yml
            ├── claiming.md
            └── permissions.md

AI 可以逐层浏览：

skill_read(skill_name: "server-wiki", path: "/")
  → 列出所有章节

skill_read(skill_name: "server-wiki", path: "economy/")
  → 列出经济系统文档

skill_read(skill_name: "server-wiki", path: "economy/shop.md")
  → 读取商店文档

这种方式特别适合服务器百科等大型知识库。

技能优先级

同名技能按优先级覆盖：

1. 助手专属技能  assistants/{id}/skills/   （最高）
2. 全局技能      skills/                    （默认）
3. 第三方技能    API 注册                    （最低）

助手专属技能可以覆盖全局同名技能，实现差异化。

默认技能

技能	说明
server-wiki	服务器百科（Wiki 模式）
building-basics	建筑基础知识
blueprint-guide	蓝图使用指南
complex-building-guide	复杂建筑指南

第三方注册技能

其他插件可通过 API 注册技能：

ArkPilotApi.registerSkill("my-skill", markdownContent)

注册后在助手 skills.load 中添加名称启用。