跳到主要内容

创建 Skill

Skill 是为 KOPI AI AGENT 添加新能力的首选方式。与 tool 相比,它们更易于创建,无需对 agent 进行任何代码改动,并且可以与社区共享。

应该做成 Skill 还是 Tool?​

在以下情况下,做成 Skill:

  • 该能力可以表示为指令 + shell 命令 + 现有工具
  • 它封装了 agent 可以通过 terminal 或 web_extract 调用的外部 CLI 或 API
  • 它不需要将自定义 Python 集成或 API key 管理内置到 agent 中
  • 示例:arXiv 搜索、git 工作流、Docker 管理、PDF 处理、通过 CLI 工具发送邮件

在以下情况下,做成 Tool:

  • 它需要与 API key、认证流程或多组件配置进行端到端集成
  • 它需要每次都必须精确执行的自定义处理逻辑
  • 它处理二进制数据、流式传输或实时事件
  • 示例:浏览器自动化、TTS、视觉分析

Skill 目录结构​

内置 skill 位于 skills/,按类别组织。官方可选 skill 在 optional-skills/ 中使用相同的结构:

skills/
├── research/
│ └── arxiv/
│ ├── SKILL.md # Required: main instructions
│ └── scripts/ # Optional: helper scripts
│ └── search_arxiv.py
├── productivity/
│ └── ocr-and-documents/
│ ├── SKILL.md
│ ├── scripts/
│ └── references/
└── ...

SKILL.md 格式​

---
name: my-skill
description: Brief description (shown in skill search results)
version: 1.0.0
author: Your Name
license: MIT
platforms: [macos, linux] # Optional — restrict to specific OS platforms
# Valid: macos, linux, windows
# Omit to load on all platforms (default)
metadata:
hermes:
tags: [Category, Subcategory, Keywords]
related_skills: [other-skill-name]
requires_toolsets: [web] # Optional — only show when these toolsets are active
requires_tools: [web_search] # Optional — only show when these tools are available
fallback_for_toolsets: [browser] # Optional — hide when these toolsets are active
fallback_for_tools: [browser_navigate] # Optional — hide when these tools exist
config: # Optional — config.yaml settings the skill needs
- key: my.setting
description: "What this setting controls"
default: "sensible-default"
prompt: "Display prompt for setup"
blueprint: # Optional — marks this skill a runnable automation
schedule: "0 9 * * *" # cron expr / "every 2h" / ISO timestamp
deliver: origin # optional (default origin)
prompt: "Task instruction for each run" # optional
no_agent: false # optional
required_environment_variables: # Optional — env vars the skill needs
- name: MY_API_KEY
prompt: "Enter your API key"
help: "Get one at https://example.com"
required_for: "API access"
---

# Skill Title

Brief intro.

## When to Use
Trigger conditions — when should the agent load this skill?

## Quick Reference
Table of common commands or API calls.

## Procedure
Step-by-step instructions the agent follows.

## Pitfalls
Known failure modes and how to handle them.

## Verification
How the agent confirms it worked.

平台专属 Skill​

Skill 可以通过 platforms 字段将自身限制在特定操作系统上:

platforms: [macos]            # macOS only (e.g., iMessage, Apple Reminders)
platforms: [macos, linux] # macOS and Linux
platforms: [windows] # Windows only

设置后,该 skill 会自动从系统提示词、skills_list() 以及不兼容平台上的斜杠命令中隐藏。如果省略或为空,则该 skill 会在所有平台上加载(向后兼容)。

Skill 的条件激活​

Skill 可以声明对特定工具或工具集(toolset)的依赖。这决定了该 skill 是否会出现在给定会话的系统提示词中。

metadata:
hermes:
requires_toolsets: [web] # Hide if the web toolset is NOT active
requires_tools: [web_search] # Hide if web_search tool is NOT available
fallback_for_toolsets: [browser] # Hide if the browser toolset IS active
fallback_for_tools: [browser_navigate] # Hide if browser_navigate IS available
字段行为
requires_toolsets当列出的任一工具集不可用时,该 Skill 隐藏
requires_tools当列出的任一工具不可用时,该 Skill 隐藏
fallback_for_toolsets当列出的任一工具集已可用时,该 Skill 隐藏
fallback_for_tools当列出的任一工具已可用时,该 Skill 隐藏

fallback_for_* 的用例: 创建一个在主工具不可用时充当替代方案的 skill。例如,一个带有 fallback_for_tools: [web_search] 的 duckduckgo-search skill 只有在 Web 搜索工具(需要 API key)未配置时才会显示。

requires_* 的用例: 创建一个仅在某些工具存在时才有意义的 skill。例如,带有 requires_toolsets: [web] 的 Web 抓取工作流 skill 在 Web 工具被禁用时不会干扰提示词。

环境变量要求​

Skill 可以声明其所需的环境变量。当一个 skill 通过 skill_view 加载时,其必需的变量会自动注册,以便传递到沙箱执行环境(terminal、execute_code)中。

required_environment_variables:
- name: TENOR_API_KEY
prompt: "Tenor API key" # Shown when prompting user
help: "Get your key at https://tenor.com" # Help text or URL
required_for: "GIF search functionality" # What needs this var

每个条目支持:

  • name(必填)— 环境变量名称
  • prompt(可选)— 向用户询问该值时的提示文本
  • help(可选)— 获取该值的帮助文本或 URL
  • required_for(可选)— 描述哪个功能需要该变量

用户也可以在 config.yaml 中手动配置需要传递的变量:

terminal:
env_passthrough:
- MY_CUSTOM_VAR
- ANOTHER_VAR

参见 skills/apple/,其中包含仅限 macOS 的 skill 示例。

加载时的安全设置​

当 skill 需要 API key 或 token 时,请使用 required_environment_variables。缺失的值不会将该 skill 从发现列表中隐藏。相反,当 skill 在本地 CLI 中加载时,Kopi Agent 会以安全的方式提示用户输入这些值。

required_environment_variables:
- name: TENOR_API_KEY
prompt: Tenor API key
help: Get a key from https://developers.google.com/tenor
required_for: full functionality

用户可以跳过设置并继续加载该 skill。Kopi Agent 绝不会向模型暴露原始的 secret 值。Gateway 和消息会话会显示本地设置指引,而不是在消息流内收集 secret。

沙箱透传

当你的 skill 加载时,任何已声明且已设置的 required_environment_variables 都会被自动透传到 execute_code 和 terminal 沙箱 —— 包括 Docker 和 Modal 等远程后端。你的 skill 脚本可以直接访问 $TENOR_API_KEY(在 Python 中为 os.environ["TENOR_API_KEY"]),用户无需进行任何额外配置。详情请参阅环境变量透传。

旧版的 prerequisites.env_vars 仍作为向后兼容的别名继续支持。

配置设置(config.yaml)​

Skill 可以声明非敏感设置,这些设置存储在 config.yaml 的 skills.config 命名空间下。与环境变量(即存储在 .env 中的 secret)不同,config 设置用于路径、偏好设置和其他非敏感值。

metadata:
hermes:
config:
- key: myplugin.path
description: Path to the plugin data directory
default: "~/myplugin-data"
prompt: Plugin data directory path
- key: myplugin.domain
description: Domain the plugin operates on
default: ""
prompt: Plugin domain (e.g., AI/ML research)

每个条目支持以下字段:

  • key(必填)— 设置的点分路径(dotpath)(例如 myplugin.path)
  • description(必填)— 说明该设置控制的内容
  • default(可选)— 用户未配置时的默认值
  • prompt(可选)— kopi config migrate 期间显示的提示文本;未设置时回退到 description

工作原理:

  1. 存储: 值会被写入 config.yaml 中的 skills.config.<key> 下:

    skills:
    config:
    myplugin:
    path: ~/my-data
  2. 发现: kopi config migrate 会扫描所有已启用的 skill,找出未配置的设置并提示用户。这些设置也会出现在 kopi config show 的 "Skill Settings" 下。

  3. 运行时注入: 当 skill 加载时,其 config 值会被解析并附加到 skill 消息中:

    [Skill config (from ~/.kopi/config.yaml):
    myplugin.path = /home/user/my-data
    ]

    agent 无需自行读取 config.yaml,即可看到已配置的值。

  4. 手动设置: 用户也可以直接设置这些值:

    kopi config set skills.config.myplugin.path ~/my-data
如何选择

对于 API key、token 及其他 secret,请使用 required_environment_variables(存储在 ~/.kopi/.env 中,绝不向模型展示)。对于路径、偏好设置和非敏感设置,请使用 config(存储在 config.yaml 中,可通过 config show 查看)。

凭据文件要求(OAuth token 等)​

使用 OAuth 或基于文件的凭据的 skill 可以声明需要挂载到远程沙箱的文件。这适用于以文件形式存储的凭据(而非环境变量)—— 通常是由设置脚本生成的 OAuth token 文件。

required_credential_files:
- path: google_token.json
description: Google OAuth2 token (created by setup script)
- path: google_client_secret.json
description: Google OAuth2 client credentials

每个条目支持以下字段:

  • path(必填)— 相对于 ~/.kopi/ 的文件路径
  • description(可选)— 说明该文件是什么以及如何创建

加载时,Kopi Agent 会检查这些文件是否存在。缺失的文件会触发 setup_needed。已存在的文件会被自动处理:

  • 挂载到 Docker 容器中,作为只读绑定挂载(bind mount)
  • 同步到 Modal 沙箱中(在创建时以及每条命令执行前进行,以便会话中途的 OAuth 正常工作)
  • 在本地后端上可直接使用,无需任何特殊处理
如何选择

对于简单的 API key 和 token(存储在 ~/.kopi/.env 中的字符串),请使用 required_environment_variables。对于 OAuth token 文件、client secret、service account JSON、证书,或任何以磁盘文件形式存在的凭据,请使用 required_credential_files。

请参阅 skills/productivity/google-workspace/SKILL.md,其中提供了同时使用两者的完整示例。

Skill Guidelines​

不要依赖外部依赖​

优先使用 Python 标准库、curl,以及 Kopi Agent 已有的工具(web_extract、terminal、read_file)。如果确需某个依赖,请在 skill 中说明安装步骤。

渐进式披露​

把最常见的工作流放在最前面。边缘情况和高级用法放在末尾。这样可以降低常见任务的 token 消耗。

包含辅助脚本​

对于 XML/JSON 解析或复杂逻辑,请在 scripts/ 中附带辅助脚本——不要指望 LLM 每次都内联编写解析器。

以文档形式交付媒体([[as_document]])​

如果你的 skill 会生成高分辨率截图、图表,或任何有损预览压缩会损害质量的图片——请在响应中的某个位置(通常是最后一行)输出字面指令 [[as_document]]。网关会剥离该指令,并把该响应中提取出的所有媒体路径作为可下载的文件附件交付,而不是内联的图片气泡。完整语义请参阅 Skill output and media delivery。

从 SKILL.md 引用捆绑脚本​

加载 skill 时,激活消息会把 skill 的绝对目录以 [Skill directory: /abs/path] 的形式暴露出来,同时还会替换 SKILL.md 正文中任意位置出现的两个模板 token:

Token替换为
${KOPI_SKILL_DIR}skill 目录的绝对路径
${KOPI_SESSION_ID}当前会话 id(如果没有会话,则保持原样)

因此,SKILL.md 可以指示 agent 直接运行捆绑脚本:

To analyse the input, run:

node ${KOPI_SKILL_DIR}/scripts/analyse.js <input>

agent 会看到替换后的绝对路径,并调用 terminal 工具执行一条可直接运行的命令——无需手动计算路径,也无需额外的 skill_view 往返。可通过 config.yaml 中的 skills.template_vars: false 全局禁用此替换。

内联 shell 片段(选择启用)​

skill 还可以在 SKILL.md 正文中嵌入写作 !`cmd` 的内联 shell 片段。启用后,每段的 stdout 会在 agent 读取消息之前内联进去,从而让 skill 注入动态上下文:

Current date: !`date -u +%Y-%m-%d`
Git branch: !`git -C ${KOPI_SKILL_DIR} rev-parse --abbrev-ref HEAD`

此功能默认关闭——SKILL.md 中的任何片段都会在未经批准的情况下在主机上运行,因此只对你信任的 skill 来源启用:

# config.yaml
skills:
inline_shell: true
inline_shell_timeout: 10 # seconds per snippet

片段以 skill 目录作为工作目录运行,输出上限为 4000 个字符。失败(超时、非零退出)会显示为一个简短的 [inline-shell error: ...] 标记,而不会中断整个 skill。

测试它​

运行该 skill 并确认 agent 正确遵循了说明:

kopi chat --toolsets skills -q "Use the X skill to do Y"

Skill 应该放在哪里?​

捆绑 skill(位于 skills/)随每次 Kopi Agent 安装一同发布。它们应当对大多数用户普遍有用:

  • 文档处理、网络调研、常见开发工作流、系统管理
  • 被广泛人群经常使用

如果你的 skill 是官方的且有用,但并非人人所需(例如,某项付费服务集成、一个重量级依赖),请把它放到 optional-skills/ 中——它随仓库一起发布,可通过 kopi skills browse 发现(标注为 "official"),并以内置信任的方式安装。

如果你的 skill 是专业化的、社区贡献的或小众的,更适合放在 Skills Hub 中——将其上传到 registry,并通过 kopi skills install 分享。

Blueprints:同时也是自动化的 skill​

Blueprint 是一种普通的 skill,只不过它还在 frontmatter 中声明了一个调度。添加一个 metadata.kopi.blueprint 块,该 skill 就变成了一个可分享、可运行的自动化:

metadata:
hermes:
tags: [blueprint, email]
blueprint:
schedule: "0 8 * * *" # presence of `blueprint:` marks it runnable
deliver: telegram # optional (default: origin)
prompt: "Summarize my unread email and today's calendar." # optional
no_agent: false # optional

由于 blueprint 就是 skill,它会原封不动地走完整个 skill 流水线——搜索、查看、安装、安全扫描、溯源、taps、集中索引,以及用于分享的 kopi skills publish。不需要学任何新东西。

安装 blueprint。 当你安装一个带有 blueprint: 块的 skill 时,Kopi Agent 会把它注册为一个建议的 cron job,而不是直接调度。调度是选择启用的——安装绝不会静默创建周期任务。你可以通过 /suggestions 审阅并接受它:

kopi skills install owner/morning-brief
# → Blueprint: 'morning-brief' is an automation (schedule 0 8 * * *).
# Added to your suggestions — run /suggestions to schedule or dismiss it.

# then, in a session:
/suggestions # lists pending suggestions, numbered
/suggestions accept 1 # creates the cron job
/suggestions dismiss 1 # never offer it again

Blueprint 是统一的 Suggested Cron Jobs 界面的来源之一——精心策划的入门自动化以及(后续的)使用模式和集成建议都出现在同一个地方。请参阅下文的 Suggested Cron Jobs。

分享你构建的自动化。 由 cron job(kopi cron create --skill <name> ...)加载的 blueprint 可以导出回 SKILL.md,并像任何其他 skill 一样发布,因此你为自己调校的一个自动化,对别人来说就变成了一个单命令安装。

Blueprint 层没有引入任何新的对象类型、存储或传输方式——blueprint 就是 skill,schedule 就是 cron job,而分享走的是既有的 publish/tap/index 路径。

Suggested Cron Jobs​

Kopi Agent 可以提出自动化,并让你一键接受,而不是让你手动拼装 cron job。每个提案都通过同一个界面流转——/suggestions 命令——无论它来自哪里:

来源触发条件
catalog精心策划的入门自动化(/suggestions catalog)——每日简报、重要邮件监控、每周回顾、工作日开始提醒
blueprint你安装了一个带有 blueprint: 块的 skill
usage后台审阅发现了一个适合用调度来服务的重复性请求
integration你连接了一个账号(Gmail、GitHub……),并提供了显而易见的自动化
/suggestions             # list pending
/suggestions accept N # schedule suggestion N (creates the cron job)
/suggestions dismiss N # dismiss it — latched, never re-offered
/suggestions catalog # add the curated starter automations

接受一个建议会调用 cronjob 工具所使用的同一个 cron.jobs.create_job——不存在第二套任务引擎。建议永远不会自动创建任务;接受始终是显式的。已忽略的建议会以稳定 key 锁定,因此同一个提案绝不会再次出现。待处理列表设有上限,因此它绝不会变成一堵打扰墙。

重要邮件监控这一 catalog 条目采用的是 poll→classify→surface 模式:它用一个轻量分类模型(config.yaml 中的 auxiliary.monitor)为收件箱条目打分,只交付超过紧急度阈值的邮件,其余时间保持静默。

发布 Skill​

发布到 Skills Hub​

kopi skills publish skills/my-skill --to github --repo owner/repo

发布到自定义仓库​

将你的仓库添加为 tap:

kopi skills tap add owner/repo

之后用户即可从你的仓库中搜索并安装。

安全扫描​

所有通过 hub 安装的 skill 都会经过安全扫描器检查,主要检测以下内容:

  • 数据外泄模式
  • Prompt 注入尝试
  • 破坏性命令
  • Shell 注入

信任级别:

  • builtin — 随 Kopi Agent 一起发布(始终受信任)
  • official — 来自仓库中的 optional-skills/(内置信任,无第三方警告)
  • trusted — 来自 openai/skills、anthropics/skills、huggingface/skills
  • community — 非危险性发现可使用 --force 覆盖;dangerous 的判定结果仍会被阻止

Kopi Agent 现在可以从多种外部发现模式中使用第三方 skill:

  • 直接 GitHub 标识符(例如 openai/skills/k8s)
  • skills.sh 标识符(例如 skills-sh/vercel-labs/json-render/json-render-react)
  • 由 /.well-known/skills/index.json 提供的 well-known 端点

如果你希望自己的 skill 无需依赖特定于 GitHub 的安装器即可被发现,除了在仓库或 marketplace 中发布之外,还可以考虑通过 well-known 端点来提供它们。