討論 – 人工智能研究

如何让 AI Agent 更懂你：OpenCode Skills 配置完全指南

2026 年 5 月 31 日上午 6:47 #34048

Brave

这篇文章面向新手，我会把每个概念都拆开讲。如果你完全不会编程，前几章也看得懂。如果你已经会用 OpenCode，可以直接跳到第三章。

〇、先搞懂几个基本问题

OpenCode 是什么？Skills 又是什么？

OpenCode 是一个开源 AI 编码助手。你可以理解为：一个在终端或桌面里帮你写代码的 AI。它开源（源代码公开）、免费、可以连任意 AI 模型（ChatGPT、Claude、Gemini 或者你电脑上本地跑的模型都行）。

Skills（技能） 是 OpenCode 的一个功能，简单说就是：给 AI 写一份”操作说明书”。

打个比方：

你是一个项目主管，OpenCode 是你的新员工
你每次分配任务都要重复说一遍公司的代码规范、测试流程、数据库约定
Skills 就是把这些”重复说明”写成文档，新员工（AI）自己会去读，不需要你每次都讲

更准确地说：一个 Skill 就是一个文件夹，里面放一个叫 SKILL.md 的文件。这个文件里写清楚”当你遇到某类任务时，应该怎么做”。

Skills 和”普通聊天”有什么区别？

	普通聊天	用了 Skills
你输入	“帮我写个 API 接口”	“帮我写个 API 接口”
AI 的行为	凭它自己的理解来写	先检查有没有匹配的 Skill，有的话按照 Skill 里写的规范来
结果质量	取决于 AI 的通用知识	高度符合你项目的特定要求
优势	简单直接	稳定、可重复、团队可共享

一、你需要知道的背景：Skills 是怎么工作的？

Skills 的”发现”机制

OpenCode 启动时，会自动扫描多个目录，找 Skill 文件。它不会一次性把所有 Skill 的内容都塞给 AI（那样对话会变得很慢很贵），而是只让 AI 看到 Skill 的名字和一句话描述。当 AI 判断当前任务需要某个 Skill 时，它才会请求加载完整内容。

这个过程非常像手机上的 App Store 搜索：

你打开 App Store，看到一堆应用的名字和简介（对应 Skill 的 name 和 description）
你找到一个需要的，点进去看详情（AI 调用 skill() 加载完整的 SKILL.md）
看完之后决定用不用

OpenCode 会在哪些位置找 Skills？

OpenCode 会扫描以下六个位置（按优先级从低到高）：

位置	路径示例	作用范围
项目目录（OpenCode 格式）	`.opencode/skills/<名称>/SKILL.md`	仅当前项目
项目目录（Claude 兼容格式）	`.claude/skills/<名称>/SKILL.md`	仅当前项目
项目目录（agents 兼容格式）	`.agents/skills/<名称>/SKILL.md`	仅当前项目
全局目录（OpenCode 格式）	`~/.config/opencode/skills/<名称>/SKILL.md`	所有项目
全局目录（Claude 兼容格式）	`~/.claude/skills/<名称>/SKILL.md`	所有项目
全局目录（agents 兼容格式）	`~/.agents/skills/<名称>/SKILL.md`	所有项目

关键区别：

项目级：把这个目录提交到 Git，整个团队都能用
全局级：只属于你个人，所有项目都能用

为什么有三套格式？ 因为 OpenCode 兼容了 Claude Code 和 Cursor 的 Skill 格式。如果你之前用过这些工具，写的 Skill 可以直接拿来用，不需要改。

搜索升级规则

对于项目级路径，OpenCode 会从你当前所在的文件夹开始，向上逐级查找，直到找到 Git 仓库的根目录为止。也就是说，如果你在 ~/projects/myapp/src/components/ 目录下启动 OpenCode，它会逐层往上找：

src/components/ → 没有
src/ → 没有
~/projects/myapp/（Git 根目录）→ 有 .opencode/skills/ → 加载

这意味着你可以把 Skill 放在项目根目录，在项目的任何子目录里都能用。

二、核心操作：怎么写一个 Skill？

一个 Skill 文件长什么样？

每个 Skill 就是一个文件夹 + 一个 SKILL.md 文件。文件必须包含两部分：

第一部分：YAML 头信息（frontmatter）——用 --- 包裹的配置信息区

第二部分：Markdown 正文——具体的操作说明，AI 会读这个

来看一个完整例子。假设你要写一个”处理 Git 发布流程”的 Skill：

---
name: git-release
description: Create consistent releases and changelogs
license: MIT
compatibility: opencode
metadata:
  audience: maintainers
  workflow: github
---

## What I do

- Draft release notes from merged PRs
- Propose a version bump (遵循语义化版本号)
- Provide a copy-pasteable `gh release create` command

## When to use me

Use this when you are preparing a tagged release.
Ask clarifying questions if the target versioning scheme is unclear.

## Steps

1. 先查看最近的 Git 标签：`git tag --sort=-creatordate | head -5`
2. 对比当前版本和上一个版本之间的合并 PR
3. 按 Conventional Commits 规范分类这些 PR
4. 生成发布说明
5. 用 `gh release create` 创建发布

头信息字段详解

字段	是否必填	最长	说明
`name`	必填	64 字符	Skill 名称。只能用小写字母、数字和单个连字符（-），不能以连字符开头或结尾
`description`	必填	1024 字符	一句话描述。AI 根据这个决定是否加载 Skill。这是最重要的字段
`license`	可选	–	许可证，比如 MIT、Apache-2.0
`compatibility`	可选	–	兼容的工具，比如 opencode、claude
`metadata`	可选	–	自定义键值对，随便写什么

name 的命名规则（容易踩坑）

name 必须：

1-64 个字符
只能包含 小写字母 + 数字 + 连字符
不能以连字符开头或结尾
不能出现连续两个 --
必须和文件夹名称完全一致

✅ 正确示例：

git-release
react-best-practices
docker-compose
test-2026

❌ 错误示例：

Git Release（有大写字母和空格）
git_release（下划线不行）
-git-release（以连字符开头）
git--release（连续两个连字符）

description 是最关键的字段

AI 靠 description 来决定要不要加载你的 Skill，而不是靠正文内容。所以 description 必须写得精准。

不好的例子：

description: Help with code

这太模糊了，AI 不知道什么时候该用它。

好的例子：

description: Review TypeScript React components for accessibility issues, including ARIA labels, keyboard navigation, and color contrast compliance

这个描述很具体：什么语言（TypeScript）、什么框架（React）、什么方面（无障碍）、检查哪些具体项目（ARIA、键盘导航、颜色对比度）。

一个小技巧：在 description 里包含你项目中常用的术语和关键词，能提高 Skill 被自动匹配的准确率。

三、进阶配置：权限控制

为什么需要权限控制？

如果你的项目里有很多 Skill，你可能不想让 AI 随便用。比如：

有个 Skill 是用来”删除数据库”的——你希望 AI 每次要用时都问一下你
有个 Skill 是”内部安全审查”——你只想让特定的 AI 智能体用
有些 Skill 还没写完——你想藏起来不让 AI 看到

OpenCode 提供了三种权限级别：

权限值	效果
`allow`	AI 可以直接加载和使用，不需要问你
`deny`	AI 看不到这个 Skill，完全隐藏
`ask`	AI 加载前会弹窗问你”可以吗？”

全局权限配置

在 opencode.json 中配置：

{
  "permission": {
    "skill": {
      "*": "allow",
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"
    }
  }
}

这个配置的意思是：

* 表示”所有 Skill”——默认允许
pr-review 这个 Skill——允许
所有以 internal- 开头的 Skill——隐藏
所有以 experimental- 开头的 Skill——加载前需要你批准

尤其注意：* 放在最前面表示”设置所有 Skill 的默认值”，如果写在后面，它会覆盖前面所有规则。

给不同的 AI 智能体设置不同权限

OpenCode 允许你创建多个 AI 智能体（Agent），比如”写代码模式””审查代码模式””计划模式”。不同模式可以用不同的 Skill 权限。

对内置智能体（在 opencode.json 中配置）：

{
  "agent": {
    "plan": {
      "permission": {
        "skill": {
          "internal-*": "allow"
        }
      }
    },
    "build": {
      "permission": {
        "skill": {
          "*": "allow",
          "dangerous-*": "ask"
        }
      }
    }
  }
}

这样，”计划模式”的智能体可以看到内部 Skill，但”写代码模式”的智能体在调用危险类 Skill 时需要你确认。

对自定义智能体（在智能体文件中配置）：

---
permission:
  skill:
    "documents-*": allow
    "experimental-*": ask
---

完全禁用 Skills

如果你觉得某个智能体根本不需要 Skills，可以直接关掉：

---
tools:
  skill: false
---

这样 AI 连”有哪些 Skills”都看不到。

四、实用建议：怎么用好 Skills？

什么时候该用 Skills？

场景	建议
团队有统一的代码规范	写一个 Skill，比放在 README 里更有效，因为 AI 会自动读
项目有特定的测试流程	写一个测试 Skill，AI 每次写测试都按这个来
你有重复性的任务（比如发布版本）	写一个 Skill，以后直接说”发布新版”就行
项目用了特殊的框架或约定	写一个 Skill 说明这些约定
每个开发者的习惯不同	全局 Skills 解决你个人的通用需求

项目级 vs 全局级，选哪个？

项目级（.opencode/skills/）：

适合这个项目特有的规范
提交到 Git，整个团队共享
新成员 clone 项目后自动拥有

全局级（~/.config/opencode/skills/）：

适合你自己的通用习惯
适合通用的知识（比如 Docker 最佳实践、Git 工作流）
所有项目都能用

实际建议：通用 Skill 放全局，项目特定 Skill 放项目里。

如何测试一个 Skill 是否正常工作？

检查文件路径：确认 SKILL.md 文件名全大写，且放在正确的目录下
验证 name 匹配：文件夹名称必须和 frontmatter 里的 name 完全一致
重启 OpenCode：Skills 是在启动时加载的，修改后需要重启
检查权限：如果 Skill 没有出现，看看是不是被 deny 了
名字不能重复：所有搜索路径下的 Skill 名字必须唯一，如果重复了，行为不确定

常见错误排查

问题	最可能的原因
AI 完全不按 Skill 说的做	description 写得太模糊，AI 没意识到该用这个 Skill
Skill 根本找不到	文件名不是 `SKILL.md`（全大写），或者 `name` 和文件夹名不一致
某个项目里 Skill 不出现	可能被上级目录的权限配置 `deny` 了
团队其他人用不了	Skill 放在了全局目录而非项目目录，别人电脑上没有

五、高级技巧：用 skill-creator 自动生成

手工写太麻烦？有工具

如果你觉得手写 YAML 和 Markdown 有点繁琐，OpenCode 生态里有一个开源工具叫 opencode-skill-creator，可以帮你自动生成 Skill：

npx opencode-skill-creator install --global

装完之后，你只需要在 OpenCode 里对 AI 说一句话：

“Create a skill that helps with Docker compose files”

然后它会：

问你 3-5 个问题（你要处理什么场景、输出格式要求等）
自动生成一个 Skill 草稿
生成测试用例，测试这个 Skill 能不能正确触发
让你看测试结果，不满意就迭代改进
最终安装到指定目录

评价机制：让你的 Skill 不断变好

这个工具最厉害的一点是：它可以自动测试你的 Skill 描述是否准确。

具体做法是：

它会生成 20 个模拟问题（有些应该触发这个 Skill，有些不应该）
分别测试”有 Skill”和”没有 Skill”两种情况下的输出
对比质量差异
如果描述不准确导致触发错误，它会自动优化描述文字
重复多轮，选出最好的版本

这个过程其实就是”数据驱动的配置优化”——用测试数据说话，而不是凭感觉调整描述文字。

六、小结

Skill 的核心逻辑其实就一句话：把重复的”操作说明”写成文档，让 AI 自己读。

你要做的事	一句话说明
创建	新建文件夹 + 写一个 `SKILL.md` 文件
命名	全小写字母 + 连字符，文件夹名和 name 一致
描述	写精准的 description，AI 靠它判断要不要用
放置	项目通用技能放 `.opencode/skills/`，个人通用技能放 `~/.config/opencode/skills/`
权限	用 `allow/deny/ask` 控制哪些 AI 智能体能用什么 Skill
优化	用 skill-creator 工具自动生成和测试

记住：Skills 不是一次性写了就完的。随着项目发展，你的规范会变，Skills 也要跟着更新。好的 Skills 是活文档。

参考来源：OpenCode 官方文档 skills 页面、opencode-skill-creator GitHub 项目、OpenCode Config 文档

抱歉，回覆主題必需先登入。