- 在编程的艺术世界里，代码和灵感需要寻找到最佳的交融点，才能打造出令人为之惊叹的作品。
- 而在这座秋知叶i博客的殿堂里，我们将共同追寻这种完美结合，为未来的世界留下属于我们的独特印记。
【Agent 】--- 全局 Skills 实战：OpenCode 使用全局技能统一配置保姆级教程
- 开发环境
- 一、前言
- [二、核心底层逻辑 🧠](#二、核心底层逻辑 🧠)
-
- [2.1 Agent 技能加载规则](#2.1 Agent 技能加载规则)
- [2.2 多工具目录隔离机制](#2.2 多工具目录隔离机制)
- [2.3 核心结论：](#2.3 核心结论：)
- [三、全工具目录清晰对比 ⚖️](#三、全工具目录清晰对比 ⚖️)
- [四、极简实操：OpenCode 全局Skills搭建](#四、极简实操：OpenCode 全局Skills搭建)
-
- [4.1 一键打开OpenCode全局根目录](#4.1 一键打开OpenCode全局根目录)
- [4.2 `.config\opencode` 目录内容](#4.2
.config\opencode目录内容) - [4.3 手动创建标准 skills 目录](#4.3 手动创建标准 skills 目录)
- [4.4 规范技能目录结构](#4.4 规范技能目录结构)
- [4.5 手动创建独立技能文件夹](#4.5 手动创建独立技能文件夹)
- [4.6 写入自定义技能规则](#4.6 写入自定义技能规则)
- 五、查看已存在的技能列表
-
- [5.1 opencode 桌面端 查看已存在的技能列表](#5.1 opencode 桌面端 查看已存在的技能列表)
- [5.2 opencode cli 验证 查看已存在的技能列表](#5.2 opencode cli 验证 查看已存在的技能列表)
- 六、技能调用方式
-
- [6.1 全局技能自动生效](#6.1 全局技能自动生效)
- [6.2 项目技能自动生效](#6.2 项目技能自动生效)
- 七、技能手动调用（主动指定，精准生效）
-
- [7.1 opencode 桌面端 直接调用](#7.1 opencode 桌面端 直接调用)
- [7.2 opencode cli 直接调用](#7.2 opencode cli 直接调用)
- 八、查看某个技能的完整内容
-
- [8.1 opencode 桌面端 查看skill完整内容](#8.1 opencode 桌面端 查看skill完整内容)
- [8.2 opencode cli 查看skill完整内容](#8.2 opencode cli 查看skill完整内容)
- [九、核心避坑指南 ⚠️](#九、核心避坑指南 ⚠️)
-
- [9.1. ❌ 禁止使用相对路径](#9.1. ❌ 禁止使用相对路径)
- [9.2. ❌ 目录命名不规范](#9.2. ❌ 目录命名不规范)
- [9.3. ❌ 文件结构错乱](#9.3. ❌ 文件结构错乱)
- [9.4. ❌ 混淆多工具专属目录](#9.4. ❌ 混淆多工具专属目录)
- [9.5. ❌ 文件名大小写错误](#9.5. ❌ 文件名大小写错误)
- 十、多工具兼容方案
- [十一、💡 小课堂](#十一、💡 小课堂)
- [十二、💻 编程冷笑话](#十二、💻 编程冷笑话)
- [十三、✨ 今日金句](#十三、✨ 今日金句)
开发环境
- 开发环境：Windows11
- 软件版本：opencode1.4.7
一、前言
- 日常使用 OpenCode、Claude Code 等 AI 编码工具时，自定义
SKILL.md规则经常不生效、工具读取不到技能 - 核心原因是工具目录完全隔离、全局/项目路径混淆。
- 很多人在用 Agent 自定义技能时都会遇到一个核心问题：
- 自己手写的
SKILL.md明明没问题，换个项目、换个工具就失效； - Claude Code 能用的技能，OpenCode 完全识别不到；
- 分不清「项目专属技能」和「全局通用技能」的区别，配置混乱。
- 本质原因只有一个：不同 AI 编码工具，拥有完全独立专属的技能读取目录，互相隔离、互不读取
- 而 全局 Skills 就是最优解：一次配置、对应工具全项目生效，不用每个项目重复新建规则文件
二、核心底层逻辑 🧠
2.1 Agent 技能加载规则
- AI 编码工具读取技能，固定分为两级优先级，全工具通用：
- 项目级技能：仅当前项目生效，优先级最高，同名规则会覆盖全局
- 全局级技能：本机所有项目通用，优先级更低，负责通用基础规范
2.2 多工具目录隔离机制
Agent 技能加载
全局目录
项目目录
OpenCode: .config/opencode/skills
Claude: .claude/skills
项目内: .opencode/skills
项目内: .claude/skills
OpenCode 专属读取
Claude Code 专属读取
2.3 核心结论：
- OpenCode 独立生态，只识别
.opencode专属目录，不会读取其他工具目录 - Claude Code 独立生态，只识别
.claude专属目录，不会读取其他工具目录 - 想要多工具共用同一份技能，需要在对应工具的专属目录里分别放置文件
三、全工具目录清晰对比 ⚖️
| 工具 | 全局技能读取目录（Windows） | 项目技能读取目录 | 适用范围 |
|---|---|---|---|
| OpenCode | %USERPROFILE%\.config\opencode\skills |
项目根目录 .opencode/skills |
全栈开发、嵌入式开发、多语言编码场景 |
| Claude Code | %USERPROFILE%\.claude\skills |
项目根目录 .claude/skills |
Claude原生生态、海外多模态编码场景 |
重点加粗：只使用单一工具开发，只需维护对应工具的一套目录即可，无需操作其他工具的文件夹
四、极简实操：OpenCode 全局Skills搭建
4.1 一键打开OpenCode全局根目录
- Win+R 直接复制下方命令，回车直达，适配所有Windows用户：
- 优势：使用系统环境变量
%USERPROFILE%，绝对路径、不跳错、不跳转文档文件夹 - 场景：首次配置时，该目录下默认没有
skills文件夹，需要手动创建
bash
explorer %USERPROFILE%\.config\opencode
4.2 .config\opencode 目录内容
- 默认只有这些文件
4.3 手动创建标准 skills 目录
- 在打开的
opencode文件夹内，右键新建文件夹 - 文件夹命名严格小写：
skills - 此目录就是 OpenCode 官方全局技能根目录
4.4 规范技能目录结构
- Agent 对技能结构有强制要求，格式错直接识别失败：
- ✅ 标准正确结构
shell
.config/opencode/skills/
└── c-comment-rule/ // 独立技能文件夹名
└── SKILL.md // 固定文件名，大写规则：
- 一个技能 = 独立单独文件夹
- 文件名必须为
SKILL.md，大小写不可修改 - 文件夹名 与 md 文件内
name字段保持一致
4.5 手动创建独立技能文件夹
- 签名我们已经进入了 OpenCode 全局 skills 目录下：
- 在空白处右键 → 新建 → 文件夹
- 文件夹命名为：
c-comment-rule - 命名要求：全小写字母 + 连字符，禁止空格、大写、特殊符号
4.6 写入自定义技能规则
- 双击进入刚创建的
c-comment-rule文件夹 - 新建文本文档，重命名为
SKILL.md（注意开启文件扩展名显示，避免变成SKILL.md.txt）
- 以C语言注释规范为例，复制以下内容保存：
markdown
---
name: c-comment-rule
description: C语言 嵌入式 统一注释规范，固定作者 qiuzhiye
---
# C代码强制注释规范
AI 编写/修改 C 语言 .c / .h 代码时，必须严格遵守本文档所有规则，不可简化、不可省略。
## 一、全局强制要求
1. 所有文件头、修改记录、更新日志，**作者固定填写：qiuzhiye**
2. 代码命名：函数/变量/宏/枚举 全部英文
3. 注释文字：全部使用简体中文
4. 风格统一、对齐整洁，适配嵌入式、车载开发场景
## 二、文件头部注释
每个C/H文件顶部必须加标准化文件说明，统一版权与作者信息。
## 三、函数/宏/变量注释
核心函数、全局变量、宏定义、枚举结构体，必须配套标准化注释；
仅基础简单逻辑，不写冗余无效注释。
## 四、行内代码注释
只注释业务逻辑、硬件约束、特殊判断逻辑，不注释基础语法。五、查看已存在的技能列表
5.1 opencode 桌面端 查看已存在的技能列表
- 打开 opencode 桌面端
- 直接问 ：
shell
skill list
5.2 opencode cli 验证 查看已存在的技能列表
- 打开 opencode cli
- 直接问 ：
shell
skill list
六、技能调用方式
- 只要技能已放在正确的全局/项目目录，并且重启过 OpenCode
- 技能就会自动加载、自动生效，不需要你输入任何命令、也不需要手动触发。
6.1 全局技能自动生效
- 存放路径：
%USERPROFILE%\.config\opencode\skills\你的技能名\SKILL.md - 生效机制：OpenCode 启动时会自动扫描并加载全部全局技能，所有项目、所有对话默认都遵守这些规则。
- 使用方式：直接正常提需求即可，AI 会自动按照技能规则输出，无需手动调用。
6.2 项目技能自动生效
- 存放路径：
你的项目目录\.opencode\skills\你的技能名\SKILL.md - 生效机制：打开该项目时自动加载，关闭项目自动失效，不影响其他项目。
- 使用方式：在当前项目内对话，AI 自动遵守该项目专属规则，无需额外操作。
七、技能手动调用（主动指定，精准生效）
- 当你需要临时启用某一个技能 、或明确强制使用某条规则时，可以使用手动调用方式。
7.1 opencode 桌面端 直接调用
- 在 OpenCode 聊天输入框中直接输入：
shell
skill c-comment-rule- 发送后，该技能会在当前对话中被强制激活，优先执行。
7.2 opencode cli 直接调用
- 在 OpenCode cli 聊天输入框中直接输入：
shell
skill c-comment-rule- 发送后，该技能会在当前对话中被强制激活，优先执行。
八、查看某个技能的完整内容
8.1 opencode 桌面端 查看skill完整内容
- 把下面的发过AI
shell
把c-comment-rule技能的完整原文发给我，不要摘要，要文件里的全部内容，包括格式和条款
8.2 opencode cli 查看skill完整内容
- 把下面的发过AI
bash
skill show c-comment-rule
九、核心避坑指南 ⚠️
9.1. ❌ 禁止使用相对路径
explorer .opencode\skills无法全局使用- Win+R 会默认指向系统文档目录，必须使用带
%USERPROFILE%的绝对路径
9.2. ❌ 目录命名不规范
- 禁止大写、空格、特殊符号，技能文件夹统一
小写+连字符 - 根目录必须严格匹配工具专属名称
9.3. ❌ 文件结构错乱
- 不能直接把
SKILL.md直接丢在 skills 根目录，必须嵌套独立的技能子文件夹
9.4. ❌ 混淆多工具专属目录
- 把OpenCode技能放在.claude目录
- Claude技能放在.opencode目录
- 工具完全无法识别，必须严格对应工具专属目录
9.5. ❌ 文件名大小写错误
- 必须严格使用
SKILL.md，小写skill.md、大写SKILL.MD都会导致识别失败
十、多工具兼容方案
如果同时需要使用 Claude Code + OpenCode 两款工具，实现一份技能全工具通用：
- 分别打开两款工具的全局技能目录
bash
explorer %USERPROFILE%\.config\opencode\skills
bash
explorer %USERPROFILE%\.claude\skills- 将写好的技能文件夹，分别复制到两个目录中
- 两套目录独立维护，互不影响，实现一份规则全工具生效
十一、💡 小课堂
- 全局技能修改后无需额外配置 ，直接保存
SKILL.md，重启对应工具即可加载新规则； - 临时需要项目专属特殊规范时，在项目内新建对应工具的专属skills目录，同名技能会自动覆盖全局规则。
十二、💻 编程冷笑话
- 为什么 AI 技能经常失效？
- 因为它也认「家门」，进错了专属目录，再完美的规则也白搭。
十三、✨ 今日金句
- 规范的本质是一次性的麻烦，换取长期的高效与统一，全局配置就是开发提效最简单的捷径。