OpenCode技能系统通过SKILL.md文件定义可复用AI行为

banq

OpenCode技能系统允许用户通过SKILL.md文件定义可复用AI行为，实现跨项目、跨设备的智能开发工作流自动化。  点击标题

OpenCode技能系统：把AI变成你的私人编程副手

在AI编程工具OpenCode的世界里，有一种被低估却极其强大的能力——“技能”（skills）系统。它允许用户在自己的配置目录中定义可复用的行为模板，让AI代理在合适时机自动调用这些预设指令。比如自动生成符合规范的发布日志、智能建议版本号、甚至根据最近的代码变更写出清晰的提交摘要。这些技能不是硬编码进程序的，而是以纯文本文件形式存在，放在特定路径下就能被OpenCode自动发现和加载。这种设计让用户能像搭积木一样，逐步构建属于自己的AI开发助手生态。

技能怎么存？位置决定作用范围

OpenCode会在多个位置搜索技能定义，主要分为两类：项目级和个人全局级。

项目级技能放在当前代码仓库的.opencode/skill/目录下，只对该项目生效；
而全局技能则存放在用户主目录的~/.config/opencode/skill/路径中，适用于所有项目。

此外，为了兼容Claude生态，OpenCode也支持从.claude/skills/目录加载技能。这种多层级结构让开发者既能为特定项目定制专属行为，又能保留一套通用的个人工作流模板。

dmmulroy的dotfiles仓库中出现的home/.config/opencode/skill路径，正是典型的全局技能存放位置，意味着他把这些AI辅助行为当作日常开发基础设施的一部分。

一个技能长什么样？YAML头+自然语言说明
OpenCode 允许用户定义可复用的行为模板或指令片段（skills），这些 skill 会被 AI 代理在合适的时候自动调用。比如自动写 release note、格式化 commit message、生成变更摘要等。

每个技能必须是一个独立文件夹，里面包含一个名为SKILL.md的文件。
一个 skill 通常看起来像这样（示例）：
~/.config/opencode/skill//SKILL.md

  • 每个技能有单独的目录
  • 技能定义写在 SKILL.md 里
  • 里面有YAML 元数据 + 自然语言说明
  • OpenCode 会载入这些 skill，根据 prompt 触发调用

这个文件开头要用YAML格式写元数据，至少包含name和description两个字段。name必须是1到64个字符的小写字母、数字或单连字符组合，且不能以连字符开头或结尾；description则需控制在1到1024个字符之间，要足够具体，让AI能准确判断何时该调用它。例如：


---
description: Create consistent releases and changelogs
<hr>
##What I do
- Draft release notes from merged PRs
- Propose a version bump
- Provide a copy-pasteable <code>gh release create</code> command

##When to use me
Ask when you are preparing a tagged release...

---


后面可以跟大段自然语言说明，详细描述这个技能做什么、在什么场景下使用、输出格式要求等。AI代理在运行时会先看到所有可用技能的名称和描述，再决定是否加载完整内容执行。

dotfiles管理技能：跨设备同步你的AI工作流

把技能放进dotfiles仓库，是一种高阶用法。

dmmulroy这样的开发者通过版本控制管理自己的~/.config/opencode/skill目录，意味着无论在哪台机器上部署他的dotfiles，都能立刻获得一整套经过验证的AI辅助能力。这不仅仅是方便，更是一种工作流资产的沉淀。

比如他可能有一个专门用于检查Rust项目内存安全的技能，另一个用于快速生成Solidity合约测试用例——这些都不是临时提示词，而是经过反复打磨、可复用、可共享的“知识乐高块”。

将 skills 放在 dotfiles 的配置目录里有两个好处：

  1. 个人化扩展 OpenCode 行为：你可以定义自己常用的 AI 辅助任务（例如自动描述最近的 git diff 模式、检查代码一致性规则等）；
  2. 跨设备共享：dotfiles 管理工具（如 dmmulroy 的 dot CLI）可以自动把这些技能同步到所有机器上。

个人仓库中这个目录通常相当于：

~/.config/opencode/skill/
├── some-skill/
│   └── SKILL.md
├── other-skill/
│   └── SKILL.md
...

技能 vs 插件 vs 命令：OpenCode扩展体系的三层结构

OpenCode的扩展机制分为三个层次：最底层是commands（命令），提供CLI快捷入口；中间层是skills（技能），封装可复用的行为逻辑；最上层是agents（代理），定义完整的角色行为。

技能处于核心位置——它不改变界面，也不启动新进程，而是增强AI的理解与执行能力。

当Conductor插件规划出一个任务清单后，实际执行时很可能就调用了某个skill来完成具体子任务，比如“生成API文档”或“校验SQL注入风险”。

这种模块化设计让整个系统既灵活又可控。