创建 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(可选)— 获取该值的帮助文本或 URLrequired_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
工作原理:
-
存储: 值会被写入
config.yaml中的skills.config.<key>下:skills:
config:
myplugin:
path: ~/my-data -
发现:
kopi config migrate会扫描所有已启用的 skill,找出未配置的设置并提示用户。这些设置也会出现在kopi config show的 "Skill Settings" 下。 -
运行时注入: 当 skill 加载时,其 config 值会被解析并附加到 skill 消息中:
[Skill config (from ~/.kopi/config.yaml):
myplugin.path = /home/user/my-data
]agent 无需自行读取
config.yaml,即可看到已配置的值。 -
手动设置: 用户也可以直接设置这些值:
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/skillscommunity— 非危险性发现可使用--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 端点来提供它们。