跳到主要内容

Skill 系统

概述​

Skill 是一种 CRD（自定义资源定义），为 AI Agent 提供按需加载的能力和工具。与将所有指令加载到系统提示词中不同，Skill 在 LLM 判断需要时才会动态加载。

为什么需要 Skill？​

  • Token 效率：只在需要时加载详细指令，减少上下文窗口占用
  • 模块化：将相关的提示词和工具打包成可重用的单元
  • 可扩展性：无需修改核心 Agent 即可添加新能力

Skill 与其他 CRD 的关系​

Ghost.spec.skills[] → 引用 Skill 名称
     ↓
Bot (ghostRef) → 从 Ghost 继承 skills
     ↓
Team (members[]) → Bot 的 skills 在任务中可用
     ↓
Task 执行 → LLM 按需调用 load_skill()

要点：

  • Skills 通过名称在 Ghost.spec.skills[] 中引用
  • 一个 Ghost 可以有多个 skills
  • Skills 可以是用户私有的或公共的
  • 查找优先级：用户私有 Skills 优先，然后是公共 Skills

Skill 包结构​

Skills 以 ZIP 包形式上传，包含：

skill-package.zip
├── SKILL.md          # 必需：元数据 + 提示词内容
└── *.py              # 可选：其他工具模块

SKILL.md 格式​

SKILL.md 文件使用 YAML frontmatter 作为元数据，markdown 正文作为提示词内容：

---
description: "简短描述 - LLM 用于决定何时加载"
displayName: "人类可读名称"
version: "1.0.0"
author: "作者名"
tags: ["标签1", "标签2"]
bindShells: ["Chat", "ClaudeCode"]  # 兼容的 Shell 类型
---

# Skill 提示词内容

当 LLM 加载此 skill 时，这些详细指令将被注入到系统提示词中...

元数据字段​

字段必需描述
description是LLM 决定何时加载的简短描述
displayName否UI 显示的人类可读名称
version否语义化版本号
author否作者名
tags否分类标签
bindShells否兼容的 Shell 类型（如 "Chat", "ClaudeCode"）

Skill 工作流程​

  1. 创建 Skill：用户上传包含 SKILL.md 的 ZIP 包
  2. 配置关联：将 skill 名称添加到 Ghost.spec.skills[]
  3. 运行时加载：
    • 任务启动时，skill 元数据（名称和描述）注入系统提示词
    • LLM 根据用户请求判断是否需要加载某个 skill
    • 调用 load_skill() 工具加载完整的 skill 提示词
  4. 更新/删除：可以上传新版本或删除（需先解除 Ghost 引用）

最佳实践​

创建 Skills​

  1. 编写清晰的描述 - 描述被 LLM 用于决定何时加载，应简洁明了
  2. 保持提示词聚焦 - 每个 skill 应有单一、明确的用途
  3. 使用合适的 bindShells - 指定兼容的 Shell 类型
  4. 为 skill 添加版本 - 使用语义化版本追踪变更

相关文档​

更多信息请参见 AGENTS.md 开发指南。