跳到主要内容

Skills System

Skill 是一种按需加载的知识文档,agent 可以在需要时加载它们。它们遵循**渐进式披露(progressive disclosure)**模式以最大限度减少 token 使用量,并兼容 agentskills.io 开放标准。

所有 skill 都存放在 ~/.kopi/skills/ 中 —— 这是主目录,也是唯一的事实来源。全新安装时,内置 skill 会从仓库复制过来。通过 Hub 安装的以及 agent 创建的 skill 也会放在这里。agent 可以修改或删除任何 skill。

你还可以将 Kopi Agent 指向外部 skill 目录 —— 这些额外的文件夹会与本地目录一起被扫描。参见下文的外部 Skill 目录。

另请参阅:

从空白开始​

默认情况下,每个 profile 都会预置内置 skill 目录,每次 kopi update 都会补充新发布的内置 skill。如果你希望某个 profile 不包含任何内置 skill —— 并且在更新后依然保持为空,有两条路径:

在安装时(适用于默认的 ~/.kopi profile):

curl -fsSL https://kopiaiagent.com/install.sh | bash -s -- --no-skills

在创建 profile 时(具名 profile):

kopi profile create research --no-skills

对于已安装的 profile(默认或具名),可在运行时切换:

kopi skills opt-out            # stop future seeding — nothing on disk is touched
kopi skills opt-out --remove # also delete UNMODIFIED bundled skills (confirms first)
kopi skills opt-in --sync # undo: remove the marker and re-seed now

以上三种方式都会在 profile 目录中写入一个 .no-bundled-skills 标记文件。只要该标记存在,安装器、kopi update 以及任何 skill 同步都会跳过该 profile 的内置 skill 预置。删除该标记(或运行 kopi skills opt-in)即可重新启用。

默认安全

kopi skills opt-out 仅阻止未来的预置 —— 它绝不会删除磁盘上已有的任何内容。可选的 --remove 标志仅在内置 skill 未被修改过时(与 Kopi Agent 安装的版本逐字节一致)才会删除它们。你编辑过的 skill、从 hub 安装的 skill,以及你自己编写的 skill 始终会被保留。

使用 Skill​

每个已安装的 skill 都会自动作为斜杠命令可用:

# In the CLI or any messaging platform:
/gif-search funny cats
/axolotl help me fine-tune Llama 3 on my dataset
/github-pr-workflow create a PR for the auth refactor
/plan design a rollout for migrating our auth provider

# Just the skill name loads it and lets the agent ask what you need:
/excalidraw

在一条命令中叠加多个 skill​

你可以在一条消息中通过在开头串联多个斜杠命令来调用多个 skill —— 开头的每个 /skill token(最多 5 个)都会被加载,其余内容则成为你的指令:

/github-pr-workflow /test-driven-development fix issue #123 and open a PR

解析会在遇到第一个不是已安装 skill 的 token 时停止,因此恰好以 / 开头的参数(比如文件路径)永远不会被吞掉:

/ocr-and-documents /tmp/scan.pdf extract the tables   # loads one skill; /tmp/scan.pdf is the argument

对于你经常重复使用的组合,建议使用 skill bundle —— 效果相同,但只需一个简短的命令。

内置的 plan skill 就是一个很好的例子。运行 /plan [request] 会加载该 skill 的指令,告诉 Kopi Agent 在需要时检查上下文,编写一份 markdown 实现计划而不是直接执行任务,并将结果保存到相对于当前 workspace/backend 工作目录的 .kopi/plans/ 下。

你也可以通过自然对话与 skill 交互:

kopi chat --toolsets skills -q "What skills do you have?"
kopi chat --toolsets skills -q "Show me the axolotl skill"

从来源学习一个 skill(/learn)​

/learn 是将你已了解的内容 —— 或一堆参考资料 —— 快速转化为可复用 skill 的方法,无需手写 SKILL.md。它是开放式的:把它指向任何你能描述的东西,agent 就会用它已有的工具收集资料,然后编写一个遵循内部编写规范(≤60 字符描述、标准章节顺序、以 Kopi Agent 工具为框架、不虚构命令)的 skill。

# A local SDK or doc directory — read with read_file / search_files
/learn the REST client in ~/projects/acme-sdk, focus on auth + pagination

# An online doc page — fetched with web_extract
/learn https://docs.example.com/api/quickstart

# The workflow you just walked the agent through in this conversation
/learn how I just deployed the staging server

# Pasted notes / a described procedure
/learn filing an expense: open the portal, New > Expense, attach the receipt, submit

由于资料收集由实际运行的 agent 完成,/learn 在 CLI、消息网关、TUI 和 dashboard 中的用法完全一致 —— 并且适用于任何终端后端(本地、Docker、远程),因为不存在单独的摄取引擎。在 dashboard 中,Skills 页面有一个 Learn a skill 按钮,会打开一个包含目录字段、URL 字段和开放式文本框的面板;它会组合一条 /learn 请求并在聊天中运行。

这里没有任何模型工具(model-tool)足迹:/learn 会构建一条遵循规范的 prompt,并作为普通轮次交给 agent。agent 使用 skill_manage 工具保存结果,因此如果你启用了写入审批门控,该门控同样会生效。

渐进式披露​

Skill 使用一种节省 token 的加载模式:

Level 0: skills_list()           → [{name, description, category}, ...]   (~3k tokens)
Level 1: skill_view(name) → Full content + metadata (varies)
Level 2: skill_view(name, path) → Specific reference file (varies)

agent 只在真正需要时才加载完整的 skill 内容。

SKILL.md 格式​

---
name: my-skill
description: Brief description of what this skill does
version: 1.0.0
platforms: [macos, linux] # Optional — restrict to specific OS platforms
metadata:
hermes:
tags: [python, automation]
category: devops
fallback_for_toolsets: [web] # Optional — conditional activation (see below)
requires_toolsets: [terminal] # Optional — conditional activation (see below)
config: # Optional — config.yaml settings
- key: my.setting
description: "What this controls"
default: "value"
prompt: "Prompt for setup"
---

# Skill Title

## When to Use
Trigger conditions for this skill.

## Procedure
1. Step one
2. Step two

## Pitfalls
- Known failure modes and fixes

## Verification
How to confirm it worked.

平台专属 Skill​

Skill 可以通过 platforms 字段限定自己仅适用于特定操作系统:

值匹配
macosmacOS (Darwin)
linuxLinux
windowsWindows
platforms: [macos]            # macOS only (e.g., iMessage, Apple Reminders, FindMy)
platforms: [macos, linux] # macOS and Linux

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

Skill 输出与媒体传递​

当 skill 响应(或任何 agent 响应)中包含指向媒体文件的裸绝对路径时——例如 /home/user/screenshots/diagram.png ——网关会自动检测到它,将其从可见文本中剥离,并将文件原生地传递到用户的聊天中(Telegram 照片、Discord 附件等),而不是在消息中留下原始路径。

对于音频,[[audio_as_voice]] 指令会将音频文件提升为原生语音消息气泡——在支持该功能的平台上(Telegram、WhatsApp)。

强制以文档方式传递:[[as_document]]​

有时你想要的与内联预览相反:你希望文件作为可下载附件传递,而不是被重新压缩的图片气泡。典型例子是高分辨率截图或图表——Telegram 的 sendPhoto 会将其重新压缩为约 200 KB、1280 px,导致内容无法辨认。而通过 sendDocument 发送的 1-2 MB PNG 则能完整保留原始字节。

如果响应(或其中的任何文本——通常是最后一行)包含字面指令 [[as_document]],则从该响应中提取的每个媒体路径都会作为文档/文件附件传递,而不是图片气泡:

Here is your rendered chart:

/home/user/.kopi/cache/chart-q4-2025.png

[[as_document]]

指令在传递前会被剥离,因此用户永远看不到它。粒度刻意设计为按响应全有或全无:发出一次 [[as_document]],同一响应中的每个图片路径都会以文档形式传递。这与 [[audio_as_voice]] 的作用范围一致。

在以下情况的 skill 中使用它:

  • 你生成的截图或图表需要作为文件交给用户(以便在其他工具中编辑、归档、完整分享)。
  • 默认的有损预览会掩盖细节(小字号文本、像素级精确的图示、对色彩敏感的渲染)。

没有独立文档通道的平台(例如 SMS)会回退到它们现有的任意附件机制。

条件激活(回退 Skill)​

Skill 可以根据当前会话中可用的工具自动显示或隐藏。这对回退 skill 最为有用——即仅当高级工具不可用时才应出现的免费或本地替代方案。

metadata:
hermes:
fallback_for_toolsets: [web] # Show ONLY when these toolsets are unavailable
requires_toolsets: [terminal] # Show ONLY when these toolsets are available
fallback_for_tools: [web_search] # Show ONLY when these specific tools are unavailable
requires_tools: [terminal] # Show ONLY when these specific tools are available
字段行为
fallback_for_toolsets当列出的 toolset 可用时,该 skill 被隐藏。当它们缺失时显示。
fallback_for_tools同上,但检查的是单个工具而非 toolset。
requires_toolsets当列出的 toolset 不可用时,该 skill 被隐藏。当它们存在时显示。
requires_tools同上,但检查的是单个工具。

示例: 内置的 duckduckgo-search skill 使用 fallback_for_toolsets: [web]。当你设置了 FIRECRAWL_API_KEY 时,web toolset 可用,agent 会使用 web_search——DuckDuckGo skill 保持隐藏。如果缺少 API key,web toolset 不可用,DuckDuckGo skill 会自动作为回退出现。

没有任何条件字段的 skill 行为与之前完全一致——它们始终显示。

加载时的安全设置​

Skill 可以声明所需的环境变量,同时不会从发现列表中消失:

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

当遇到缺失的值时,Kopi Agent 仅在 skill 实际通过本地 CLI 加载时才会安全地询问该值。你可以跳过设置并继续使用该 skill。消息界面绝不会在聊天中索要机密——它们会提示你在本地使用 kopi setup 或 ~/.kopi/.env。

设置完成后,声明的环境变量会自动透传到 execute_code 和 terminal 沙箱——skill 的脚本可以直接使用 $TENOR_API_KEY。对于非 skill 的环境变量,请使用 terminal.env_passthrough config 选项。详见环境变量透传。

Skill Config 设置​

Skill 还可以声明存储在 config.yaml 中的非机密 config 设置(路径、偏好):

metadata:
hermes:
config:
- key: myplugin.path
description: Path to the plugin data directory
default: "~/myplugin-data"
prompt: Plugin data directory path

设置存储在 config.yaml 中的 skills.config 下。kopi config migrate 会提示配置缺失的设置,kopi config show 则会显示它们。当 skill 加载时,其解析后的 config 值会被注入上下文,这样 agent 就能自动获知已配置的值。

详见 Skill 设置和创建 Skill — Config 设置。

Skill 目录结构​

~/.kopi/skills/                  # Single source of truth
├── mlops/ # Category directory
│ ├── axolotl/
│ │ ├── SKILL.md # Main instructions (required)
│ │ ├── references/ # Additional docs
│ │ ├── templates/ # Output formats
│ │ ├── scripts/ # Helper scripts callable from the skill
│ │ └── assets/ # Supplementary files
│ └── vllm/
│ └── SKILL.md
├── devops/
│ └── deploy-k8s/ # Agent-created skill
│ ├── SKILL.md
│ └── references/
├── .hub/ # Skills Hub state
│ ├── lock.json
│ ├── quarantine/
│ └── audit.log
└── .bundled_manifest # Tracks seeded bundled skills

外部 Skill 目录​

如果你在 Kopi Agent 之外维护 skill——例如多个 AI 工具共享的 ~/.agents/skills/ 目录——你可以让 Kopi Agent 也扫描这些目录。

在 ~/.kopi/config.yaml 的 skills 部分下添加 external_dirs:

skills:
external_dirs:
- ~/.agents/skills
- /home/shared/team-skills
- ${SKILLS_REPO}/skills

路径支持 ~ 展开和 ${VAR} 环境变量替换。

工作原理​

  • 本地创建,原地更新:由 agent 新建的 skill 会被写入 ~/.kopi/skills/。已有的 skill 会在其被发现的位置就地修改,包括 external_dirs 下的 skill——当 agent 使用 skill_manage 类操作(如 patch、edit、write_file、remove_file 或 delete)时。
  • 外部目录不是写保护边界:如果外部 skill 目录对 Kopi Agent 进程可写,agent 管理的 skill 更新可能会修改该目录中的文件。如果共享的外部 skill 必须保持只读,请使用文件系统权限或独立的 profile/toolset 设置。
  • 本地优先:如果同名 skill 同时存在于本地目录和外部目录,本地版本优先。
  • 完全集成:外部 skill 会出现在系统提示索引、skills_list、skill_view 中,并作为 /skill-name 斜杠命令——与本地 skill 没有任何区别。
  • 不存在的路径会被静默跳过:如果配置的目录不存在,Kopi Agent 会忽略它而不报错。这对于可能并非在每台机器上都存在的可选共享目录非常有用。

示例​

~/.kopi/skills/               # Local (primary, read-write)
├── devops/deploy-k8s/
│ └── SKILL.md
└── mlops/axolotl/
└── SKILL.md

~/.agents/skills/ # External (shared, mutable if writable)
├── my-custom-workflow/
│ └── SKILL.md
└── team-conventions/
└── SKILL.md

全部四个 skill 都会出现在你的 skill 索引中。如果你在本地创建了一个名为 my-custom-workflow 的新 skill,它会遮蔽外部版本。

Skill 包(Bundle)​

Skill 包是极小的 YAML 文件,用于将多个 skill 归到一个斜杠命令下。当你运行 /<bundle-name> 时,包中列出的每个 skill 都会一次性加载——当某个特定任务总是需要同一组 skill 协同工作时,这非常有用。

快速示例​

# Create a bundle for backend feature work
kopi bundles create backend-dev \
--skill github-code-review \
--skill test-driven-development \
--skill github-pr-workflow \
-d "Backend feature work — review, test, PR workflow"

然后在 CLI 或任意 gateway 平台上:

/backend-dev refactor the auth middleware

agent 会收到以一条 user message 加载的全部三个 skill,斜杠命令之后的任何文本都会作为 user instruction 附加上去。

YAML schema​

包存放在 ~/.kopi/skill-bundles/<slug>.yaml 中,格式如下:

name: backend-dev
description: Backend feature work — review, test, PR workflow.
skills:
- github-code-review
- test-driven-development
- github-pr-workflow
instruction: |
Always start by writing failing tests, then implement.
Open the PR through the standard workflow with co-author tags.

字段说明:

  • name(可选——默认为文件名主干)——包的显示名称。会规范化为斜杠命令使用的连字符 slug(Backend Dev → /backend-dev)。
  • description(可选)——显示在 /bundles 和 kopi bundles list 中的简短文本。
  • skills(必填,非空列表)——skill 名称或相对于 skills 目录的路径。使用与传给 /<skill-name> 相同的标识符。
  • instruction(可选)——附加的指导说明,会前置到加载的 skill 内容之前。适合用来固化"我们总是这样组合使用它们"。

管理包​

# List all installed bundles
kopi bundles list

# Inspect one bundle
kopi bundles show backend-dev

# Create a bundle interactively (omit --skill flags to enter them one per line)
kopi bundles create research

# Overwrite an existing bundle
kopi bundles create backend-dev --skill ... --force

# Delete a bundle
kopi bundles delete backend-dev

# Re-scan ~/.kopi/skill-bundles/ and report changes
kopi bundles reload

在聊天会话内部,/bundles 会列出所有已安装的包及其包含的 skill。

行为​

  • 当 slug 冲突时,包优先于单个 skill。 如果你将一个包命名为 research,而同时还有一个名为 research 的 skill,则 /research 会调用该包。这是有意为之——通过命名,你已经选择了这个包。
  • 缺失的 skill 会被跳过,不会导致致命错误。 如果某个包列出了 skill-foo,而你尚未安装它,包仍会加载那些能解析到的 skill,agent 会收到一条列出被跳过项的提示。
  • 包在所有界面都可用——交互式 CLI、TUI、dashboard chat,以及所有 gateway 平台(Telegram、Discord、Slack 等)——因为分发逻辑集中在与单个 skill 命令相同的地方。
  • 包不会使 prompt cache 失效。 它们在调用时生成一条全新的 user message,方式与 /<skill-name> 相同——不会修改 system prompt。

什么时候用包比逐个安装 skill 更好​

在以下情况使用包:

  • 对于某个反复出现的任务,你总是搭配使用相同的 skill(/backend-dev、/release-prep、/incident-response)。
  • 你想要一个比连续输入多个 /skill 调用更省心(少一个字符)的心智模型。
  • 你想要通过把包的 YAML 提交到共享的 dotfiles 仓库并符号链接到 ~/.kopi/skill-bundles/ 来分发团队级的"任务 profile"。

包只是一个 YAML 别名——它不会为你安装 skill。skill 本身必须已经存在(位于 ~/.kopi/skills/ 或外部 skill 目录中)。否则,调用包时只会跳过缺失的那些。

Agent 管理的 Skill(skill_manage 工具)​

agent 可以通过 skill_manage 工具创建、更新和删除自己的 skill。这是 agent 的程序性记忆——当它摸索出一个不简单的工作流时,会将该方法保存为 skill 以供将来复用。

Skill 与 memory 在自我改进循环中协同工作:memory 存储应该始终处于上下文中的少量持久事实,而 skill 存储只在相关时才加载的较长流程。后台审查可以在会话之后提出或暂存 skill 变更,而下面的写入审批门禁可以让你要求在这些变更生效前进行人工审查。

Agent 何时创建 Skill​

  • 成功完成一个复杂任务(5 次以上工具调用)之后
  • 遇到错误或走入死胡同并找到可行路径时
  • 用户纠正了它的做法时
  • 发现了一个不简单的工作流时

操作​

操作用途关键参数
create从零创建新 skillname, content(完整的 SKILL.md),可选 category
patch针对性修复(首选)name, old_string, new_string
edit大规模结构性重写name, content(完整替换 SKILL.md)
delete彻底删除一个 skillname
write_file添加/更新辅助文件name, file_path, file_content
remove_file删除辅助文件name, file_path
提示

更新时首选 patch 操作——它比 edit 更节省 token,因为工具调用中只会出现变更的文本。

为 agent 的 skill 写入设置门禁(skills.write_approval)​

默认情况下,agent 可以自由写入 skill——包括通过在一轮对话之后运行的后台自我改进审查来写入。如果你希望先审批每一次 skill 写入(小模型可能误判自己学到了什么、安全环境,或者只是想盯住自我改进循环),可以开启写入审批门禁:

skills:
write_approval: false # false = write freely (default) | true = require approval

当 write_approval: true 时,每一次 skill_manage 写入(create / edit / patch / delete / write_file / remove_file)都会被暂存而不是直接提交——SKILL.md 太大,无法内联审查,因此无论写入来自前台轮次还是后台审查,都会进行暂存。暂存的写入在 ~/.kopi/pending/skills/ 下可在重启后保留,并使用与危险命令相同的熟悉审批/拒绝流程进行审查:

/skills pending             # list staged skill writes + a one-line gist each
/skills diff <id> # full unified diff (best viewed in CLI or dashboard)
/skills approve <id> # apply it (or 'all')
/skills reject <id> # drop it (or 'all')
/skills approval on # turn the gate on (or 'off') and persist it

审查界面在交互式 CLI 和消息平台上都可用(diff 输出在聊天气泡中会被截断——完整 diff 请在 CLI 或 pending JSON 文件中查看)。Memory 写入在 memory.write_approval 下也有同样的门禁——参见控制 memory 写入。

独立的 skills.guard_agent_created 设置是一个内容扫描器 (危险模式启发式规则),而非审批门禁——两者相互独立。参见对 agent 创建的 skill 写入进行防护。

Skills Hub​

浏览、搜索、安装并管理来自在线 registry、skills.sh、知名 skill 端点以及官方可选 skill 的 skill。

常用命令​

kopi skills browse                              # Browse all hub skills (official first)
kopi skills browse --source official # Browse only official optional skills
kopi skills search kubernetes # Search all sources
kopi skills search react --source skills-sh # Search the skills.sh directory
kopi skills search https://mintlify.com/docs --source well-known
kopi skills inspect openai/skills/k8s # Preview before installing
kopi skills install openai/skills/k8s # Install with security scan
kopi skills install official/security/1password
kopi skills install skills-sh/vercel-labs/json-render/json-render-react --force
kopi skills install well-known:https://mintlify.com/docs/.well-known/skills/mintlify
kopi skills install https://sharethis.chat/SKILL.md # Direct URL (single-file SKILL.md)
kopi skills install https://example.com/SKILL.md --name my-skill # Override name when frontmatter has none
kopi skills list --source hub # List hub-installed skills
kopi skills check # Check installed hub skills for upstream updates
kopi skills update # Reinstall hub skills with upstream changes when needed
kopi skills audit # Re-scan all hub skills for security
kopi skills uninstall k8s # Remove a hub skill
kopi skills reset google-workspace # Un-stick a bundled skill from "user-modified" (see below)
kopi skills reset google-workspace --restore # Also restore the bundled version, deleting your local edits
kopi skills publish skills/my-skill --to github --repo owner/repo
kopi skills snapshot export setup.json # Export skill config
kopi skills tap add myorg/skills-repo # Add a custom GitHub source

支持的 hub 来源​

来源示例说明
officialofficial/security/1password随 Kopi Agent 一起发布的可选 skill。
skills-shskills-sh/vercel-labs/agent-skills/vercel-react-best-practices可通过 kopi skills search <query> --source skills-sh 搜索。当 skills.sh 的 slug 与仓库文件夹不一致时,Kopi Agent 会解析别名形式的 skill。
well-knownwell-known:https://mintlify.com/docs/.well-known/skills/mintlify直接从网站上的 /.well-known/skills/index.json 提供的 skill。使用站点或文档 URL 进行搜索。
urlhttps://sharethis.chat/SKILL.md指向单文件 SKILL.md 的直接 HTTP(S) URL。名称解析顺序:frontmatter → URL slug → 交互式提示 → --name flag。
githubopenai/skills/k8s直接的 GitHub 仓库/路径安装以及自定义 tap。
clawhub、lobehub、browse-sh各来源特有的标识符社区或 marketplace 集成。

已集成的 hub 与 registry​

Kopi Agent 目前集成了以下 skill 生态系统与发现来源:

1. 官方可选 skill (official)​

这些 skill 维护在 Kopi Agent 仓库本身中,安装时自带信任。

kopi skills browse --source official
kopi skills install official/security/1password

2. skills.sh (skills-sh)​

这是 Vercel 的公开 skill 目录。Kopi Agent 可以直接搜索它、查看 skill 详情页、解析别名形式的 slug,并从其底层源仓库安装。

kopi skills search react --source skills-sh
kopi skills inspect skills-sh/vercel-labs/json-render/json-render-react
kopi skills install skills-sh/vercel-labs/json-render/json-render-react --force

3. 知名 skill 端点 (well-known)​

这是基于 URL 的发现方式,来自发布 /.well-known/skills/index.json 的站点。它并非单一的集中式 hub —— 而是一种 Web 发现约定。

kopi skills search https://mintlify.com/docs --source well-known
kopi skills inspect well-known:https://mintlify.com/docs/.well-known/skills/mintlify
kopi skills install well-known:https://mintlify.com/docs/.well-known/skills/mintlify

4. 直接的 GitHub skill (github)​

Kopi Agent 可以直接从 GitHub 仓库以及基于 GitHub 的 tap 安装。当你已经知道 repo/path,或想添加自定义源仓库时,这非常有用。

默认 tap(无需任何配置即可浏览):

kopi skills install openai/skills/k8s
kopi skills tap add myorg/skills-repo

分类分组 (skills.sh.json)。 GitHub tap 可以在其仓库根目录放置一个 skills.sh.json 文件,遵循 skills.sh schema。其 groupings(每项包含一个 title 和一组 skill 名称)会在建立索引 时被读取,并成为 Skills Hub 页面中显示的分类标签 —— 而非基于 tag 的推测。这是通用的:任何附带该文件的 tap 都能获得真正的 分类,无需在 Kopi Agent 侧做任何改动。

{
"$schema": "https://skills.sh/schemas/skills.sh.schema.json",
"groupings": [
{ "title": "Inference AI", "skills": ["dynamo-recipe-runner", "dynamo-router-sla"] },
{ "title": "Decision Optimization", "skills": ["cuopt-developer", "cuopt-install"] }
]
}

5. ClawHub (clawhub)​

一个作为社区来源集成的第三方 skill marketplace。

  • 站点:clawhub.ai
  • Kopi Agent source id:clawhub

6. Claude marketplace 风格仓库 (claude-marketplace)​

Kopi Agent 支持发布 Claude 兼容的 plugin/marketplace manifest 的 marketplace 仓库。

已知的集成来源包括:

Kopi Agent source id:claude-marketplace

7. LobeHub (lobehub)​

Kopi Agent 可以从 LobeHub 的公开目录搜索 agent 条目,并将其转换为可安装的 Kopi Agent skill。

8. browse.sh (browse-sh)​

Kopi Agent 集成了 browse.sh,即 Browserbase 的 200 多个针对特定站点的浏览器自动化 SKILL.md 文件目录(Airbnb、Amazon、arXiv、12306.cn、Etsy、Xero 等等)。每个 skill 描述如何端到端驱动一个网站,可与 Kopi Agent 的浏览器工具以及你已安装的任何浏览器自动化 skill 搭配使用。

  • 站点:browse.sh
  • 目录 API:https://browse.sh/api/skills
  • Kopi Agent source id:browse-sh
  • 信任级别:community
kopi skills search airbnb --source browse-sh
kopi skills inspect browse-sh/airbnb.com/search-listings-ddgioa
kopi skills install browse-sh/airbnb.com/search-listings-ddgioa

标识符采用 browse-sh/<hostname>/<task-id> 形式,并与 browse.sh 目录暴露的 slug 一致。内容通过各 skill 的详情端点解析(/api/skills/<slug> → skillMdUrl),而非通过目录的 GitHub sourceUrl 解析。

9. Direct URL (url)​

直接从任意 HTTP(S) URL 安装单文件 SKILL.md —— 当作者将 skill 托管在自己的站点上时(无 hub 条目、无需输入 GitHub 路径),这很有用。Kopi Agent 会获取该 URL、解析 YAML frontmatter、进行安全扫描,然后安装。

  • Kopi Agent source id:url
  • 标识符:URL 本身(无需前缀)
  • 适用范围:仅限单文件 SKILL.md。包含 references/ 或 scripts/ 的多文件 skill 需要 manifest,应通过上述其他来源之一发布。
kopi skills install https://sharethis.chat/SKILL.md
kopi skills install https://example.com/my-skill/SKILL.md --category productivity

名称解析顺序:

  1. SKILL.md YAML frontmatter 中的 name: 字段(推荐 —— 每个格式规范的 skill 都有该字段)。
  2. URL 路径中的父目录名(例如 .../my-skill/SKILL.md → my-skill,或 .../my-skill.md → my-skill),前提是它是一个合法的标识符 (^[a-z][a-z0-9_-]*$)。
  3. 在带 TTY 的终端上进行交互式提示。
  4. 在非交互式环境中(TUI 内的 /skills install 斜杠命令、gateway 平台、脚本),则抛出一个明确的错误,指向 --name 覆盖项。
# Frontmatter has no name and the URL slug is unhelpful — supply one:
kopi skills install https://example.com/SKILL.md --name sharethis-chat

# Or inside a chat session:
/skills install https://example.com/SKILL.md --name sharethis-chat

信任级别始终为 community —— 与其他所有来源一样执行相同的安全扫描。URL 会作为安装标识符存储,因此 kopi skills update 会从同一 URL 在需要刷新时会自动更新。

安全扫描与 --force​

所有通过 hub 安装的 skill 都会经过安全扫描器检查,检测数据外泄、prompt 注入、破坏性命令、供应链信号以及其他威胁。

kopi skills inspect ... 现在还会在可用时显示上游元数据:

  • repo URL
  • skills.sh 详情页 URL
  • 安装命令
  • 每周安装量
  • 上游安全审计状态
  • well-known 索引/端点 URL

当你审查过某个第三方 skill 并希望覆盖非危险的策略拦截时,可以使用 --force:

kopi skills install skills-sh/anthropics/skills/pdf --force

重要行为:

  • --force 可以覆盖 caution/warn 级别的策略拦截。
  • --force 不能覆盖 dangerous 的扫描判定。
  • 官方可选 skill(official/...)被视为内置可信,不会显示第三方警告面板。

信任级别​

级别来源策略
builtin随 Kopi Agent 一同提供始终可信
officialrepo 中的 optional-skills/内置可信,无第三方警告
trusted受信任的 registry/repo,如 openai/skills、anthropics/skills、huggingface/skills、NVIDIA/skills策略比社区来源更宽松
community其他所有来源(skills.sh、well-known 端点、自定义 GitHub repo、大多数 marketplace)非危险发现可用 --force 覆盖;dangerous 判定仍被阻止

更新生命周期​

hub 现在会跟踪足够的溯源信息,以便重新检查已安装 skill 的上游副本:

kopi skills check          # Report which installed hub skills changed upstream
kopi skills update # Reinstall only the skills with updates available
kopi skills update react # Update one specific installed hub skill

这会使用存储的来源标识符以及当前上游 bundle 内容哈希来检测漂移。

GitHub 速率限制

Skills hub 操作会使用 GitHub API,未认证用户的速率限制为 60 次请求/小时。如果你在安装或搜索时遇到速率限制错误,请在 .env 文件中设置 GITHUB_TOKEN,将限制提高到每小时 5,000 次请求。出现该情况时,错误消息中会包含可操作的提示。

发布自定义 skill tap​

如果你想共享一组精选的 skill —— 供团队、组织或公开使用 —— 可以将它们发布为一个 tap:一个 GitHub 仓库,其他 Kopi Agent 用户通过 kopi skills tap add <owner/repo> 添加它。无需服务器、无需注册 registry、无需发布流水线。只需要一个包含 SKILL.md 文件的目录。

Repo 结构​

tap 可以是任意 GitHub 仓库(公开或私有 —— 私有仓库需要 GITHUB_TOKEN),其结构如下:

owner/repo
├── skills/ # default path; configurable per-tap
│ ├── my-workflow/
│ │ ├── SKILL.md # required
│ │ ├── references/ # optional supporting files
│ │ ├── templates/
│ │ └── scripts/
│ ├── another-skill/
│ │ └── SKILL.md
│ └── third-skill/
│ └── SKILL.md
└── README.md # optional but helpful

规则:

  • 每个 skill 位于 tap 根路径(默认为 skills/)下的独立目录中。
  • 目录名即为该 skill 的安装 slug。
  • 每个 skill 目录必须包含一个 SKILL.md,并带有标准的 SKILL.md frontmatter(name、description,以及可选的 metadata.kopi.tags、version、author、platforms、metadata.kopi.config)。
  • references/、templates/、scripts/、assets/ 等子目录会在安装时随 SKILL.md 一起下载。
  • 目录名以 . 或 _ 开头的 skill 会被忽略。

Kopi Agent 通过列出 tap 路径下的所有子目录并探测其中是否存在 SKILL.md 来发现 skill。

最小 tap 示例​

my-org/kopi-skills
└── skills/
└── deploy-runbook/
└── SKILL.md

skills/deploy-runbook/SKILL.md:

---
name: deploy-runbook
description: Our deployment runbook — services, rollback, Slack channels
version: 1.0.0
author: My Org Platform Team
metadata:
hermes:
tags: [deployment, runbook, internal]
---

# Deploy Runbook

Step 1: ...

推送到 GitHub 后,任何 Kopi Agent 用户都可以订阅并安装:

kopi skills tap add my-org/kopi-skills
kopi skills search deploy
kopi skills install my-org/kopi-skills/deploy-runbook

非默认路径​

如果你的 skill 不在 skills/ 下(当你将 skills/ 子树添加到现有项目时很常见),请编辑 ~/.kopi/.hub/taps.json 中的 tap 条目:

{
"taps": [
{"repo": "my-org/platform-docs", "path": "internal/skills/"}
]
}

kopi skills tap add CLI 会将新 tap 默认设为 path: "skills/";如需不同的路径,请直接编辑该文件。kopi skills tap list 会显示每个 tap 的实际生效路径。

直接安装单个 skill(无需添加 tap)​

用户也可以从任意公开 GitHub 仓库安装单个 skill,而不必将整个仓库作为 tap 添加:

kopi skills install owner/repo/skills/my-workflow

当你只想共享一个 skill,而不想要求用户订阅你的整个 registry 时,这很有用。

Tap 的信任级别​

新 tap 默认被赋予 community 信任级别。从这些 tap 安装的 skill 会经过标准安全扫描,并在首次安装时显示第三方警告面板。如果你的组织或某个被广泛信任的来源应获得更高的信任级别,请将其 repo 添加到 tools/skills_hub.py 中的 TRUSTED_REPOS(需要提交 Kopi Agent core PR)。

Tap 管理​

kopi skills tap list                                # show all configured taps
kopi skills tap add myorg/skills-repo # add (default path: skills/)
kopi skills tap remove myorg/skills-repo # remove

在运行中的会话内:

/skills tap list
/skills tap add myorg/skills-repo
/skills tap remove myorg/skills-repo

Tap 存储在 ~/.kopi/.hub/taps.json 中(按需创建)。

内置 skill 更新 (kopi skills reset)​

Kopi Agent 在仓库的 skills/ 中附带了一组内置 skill。在安装时以及每次 kopi update 时,同步过程会将其复制到 ~/.kopi/skills/,并在 ~/.kopi/skills/.bundled_manifest 记录一份清单,将每个 skill 名称映射到同步时的内容哈希值(即 origin hash)。

每次同步时,Kopi Agent 都会重新计算本地副本的哈希值,并与 origin hash 进行比较:

  • 未更改 → 可以安全地拉取上游更改,复制新的内置版本,并记录新的 origin hash。
  • 已更改 → 将被视为用户已修改并永久跳过,这样你的编辑就永远不会被覆盖。

这种保护机制很不错,但也有一个容易踩坑的地方。如果你修改了某个内置 skill,之后又想放弃这些更改、通过直接从 ~/.kopi/kopi-ai-agent/skills/ 复制粘贴来恢复到内置版本,清单中保存的仍然是上次成功同步时的旧 origin hash。你新复制粘贴的内容(当前内置版本的哈希值)不会匹配那个过期的 origin hash,因此同步会一直将其标记为用户已修改。

kopi skills reset 就是解决这个问题的办法:

# Safe: clears the manifest entry for this skill. Your current copy is preserved,
# but the next sync re-baselines against it so future updates work normally.
kopi skills reset google-workspace

# Full restore: also deletes your local copy and re-copies the current bundled
# version. Use this when you want the pristine upstream skill back.
kopi skills reset google-workspace --restore

# Non-interactive (e.g. in scripts or TUI mode) — skip the --restore confirmation.
kopi skills reset google-workspace --restore --yes

同样的命令也可以在聊天中以斜杠命令的方式使用:

/skills reset google-workspace
/skills reset google-workspace --restore
Profiles(配置文件)

每个 profile 都在自己的 KOPI_HOME 下有独立的 .bundled_manifest,因此 kopi -p coder skills reset <name> 只会影响该 profile。

斜杠命令(在聊天中)​

所有相同的命令都可以配合 /skills 使用:

/skills browse
/skills search react --source skills-sh
/skills search https://mintlify.com/docs --source well-known
/skills inspect skills-sh/vercel-labs/json-render/json-render-react
/skills install openai/skills/skill-creator --force
/skills check
/skills update
/skills reset google-workspace
/skills list

官方可选 skill 仍使用诸如 official/security/1password 和 official/migration/openclaw-migration 这样的标识符。