【Agent 】--- 全局 Skills 实战：OpenCode 使用全局技能统一配置保姆级教程

秋知叶i2026-04-18 17:57
  • 在编程的艺术世界里，代码和灵感需要寻找到最佳的交融点，才能打造出令人为之惊叹的作品。
  • 而在这座秋知叶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 目录

  1. 在打开的 opencode 文件夹内，右键新建文件夹
  2. 文件夹命名严格小写：skills
  3. 此目录就是 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 两款工具，实现一份技能全工具通用：

  1. 分别打开两款工具的全局技能目录
bash 复制代码 
explorer %USERPROFILE%\.config\opencode\skills
bash 复制代码 
explorer %USERPROFILE%\.claude\skills
  1. 将写好的技能文件夹，分别复制到两个目录中
  2. 两套目录独立维护，互不影响，实现一份规则全工具生效

十一、💡 小课堂

  • 全局技能修改后无需额外配置 ，直接保存 SKILL.md，重启对应工具即可加载新规则；
  • 临时需要项目专属特殊规范时，在项目内新建对应工具的专属skills目录，同名技能会自动覆盖全局规则。

十二、💻 编程冷笑话

  • 为什么 AI 技能经常失效？
  • 因为它也认「家门」，进错了专属目录，再完美的规则也白搭。

十三、✨ 今日金句

  • 规范的本质是一次性的麻烦，换取长期的高效与统一，全局配置就是开发提效最简单的捷径。
相关推荐
是小蟹呀^4 小时前
【总结】LangChain中的中间件Middleware
python·中间件·langchain·agent
去伪存真4 小时前
Superpowers 从“调教提示词”转向“构建工程规范”
前端·agent
loong_XL5 小时前
2026智能体爆发现象级产品：OpenClaw、Hermes Agent、Claude Cowork
大模型·agent·智能体·claw·龙虾
一个处女座的程序猿6 小时前
Agent之Memory：EverOS的简介、安装和使用方法、案例应用之详细攻略
agent·memory·everos
fundroid7 小时前
Google 发布 Android Skill & Android CLI：大幅提升 Android Agent 能力
android·agent·cli·skill
花千树_0107 小时前
Java 实现 ReAct Agent：工具调用与推理循环
agent
Cosolar8 小时前
PageIndex技术全解析：基于推理的无向量RAG框架，重构长文档智能检索范式
llm·agent·chatglm (智谱)
Makoto_Kimur9 小时前
Agent 面试速成清单
java·agent
程序员陆业聪9 小时前
Agent时代的工程师危机：当会写代码不再是护城河
agent
热门推荐
012026年4月技术前沿：AI大模型爆发、智能体革命与量子安全新纪元02GitHub 镜像站点032026 年 AI 编程助手全面对比评测：Cursor vs Copilot vs Claude Code vs GitHub Copilot Free04AI Weekly | 2026年4月第二周 · GitHub热门项目与AI发展趋势深度解析05GPT-6发布日深度解析-Symphony架构200万Token实战06零成本！Ollama本地部署国产大模型全指南（支持Kimi-K2.5/GLM-5/Qwen，新手秒上手）07一周AI热点速览（2026.03.31-04.06）：GPT-6曝光、谷歌开源Gemma 4、资本狂飙与模型军备竞赛08从限购到畅通：GLM-5.1 Coding Plan接入攻略09基于 Docker 部署 Hermes Agent 并接入飞书机器人的完整指南10从零部署 Hermes Agent：一只"会成长的 AI 马"保姆级安装教程