Agent Skills 这个词最近在 AI 编程工具圈出现频率很高。简单说，它是给 AI Agent 预先准备的一组“岗位说明书 + 工具包”，让 Agent 在特定任务上不只靠模型本身的通用能力，而是按照固定流程和资源完成任务。OpenCode 是一个面向终端和编辑器的开源 AI Agent 编程工具，常被看作 Claude Code 的开源替代品；把它和 Agent Skills 结合起来，可以在本地搭建一套可控、可版本管理、可复用的自动化工作流。下面内容会从零开始，完成 OpenCode 的安装和模型接入，创建并运行第一个 Skill，再用一个项目实战把技能应用到真实开发场景，最后给出常见报错排查路径和生产环境使用建议。
需要先说明一个前提：OpenCode 的安装方式、配置项和技能目录命名会随版本变化，不同发行版之间也存在差异。因此本文给出的命令和路径写法用于说明通用思路，实际落地前要打开你所用版本的官方文档确认一遍。遇到“目录不生效”或“命令识别不到”时，优先检查版本和路径约定。
1. 先理解 Agent Skills 到底解决了什么问题
1.1 没有 Skill 的 Agent 为什么不好用
最早的 AI 编程助手，本质上是一个“聊天窗口 + 代码生成器”。你告诉它需求，它根据模型内部知识生成答案。对于一次性问答，这种模式够用。一旦进入真实项目，问题就暴露出来：同一个项目需求，每次对话得到的代码风格可能不同；同一个部署流程，这次记得检查依赖，下次可能忘记；同一个错误处理逻辑，模型可能给出了完全不同的实现方式。
Agent 的出现解决了“让它自己动手”的问题。Agent 可以读取文件、执行命令、调用工具、根据反馈调整下一步。但 Agent 仍然需要一套规则来约束它“应该怎么干活”。如果不给规则，它依赖的是模型在训练阶段见过的通用模式，而不是你这个项目的实际情况。
Skill 的作用就在这里：把高频任务的执行方式显式写下来，包括触发条件、操作步骤、要参考的文档、要调用的脚本、输出格式和失败处理方式。当 Agent 判断任务命中某个 Skill 时，它会优先按照 Skill 里的流程执行，而不是每次重新“自由发挥”。
1.2 Skill 不是 Agent：两者的边界在哪里
很多初学者会把 Skill 和 Agent 混为一谈。可以这样理解：Agent 是干活的人，Skill 是这个人手里的作业指导书和工具箱。没有 Skill，Agent 也能干活，只是干得不够稳定；有了 Skill，Agent 在特定任务上的表现会更快、更规范、更容易被审查。
下面用一张表区分几个容易混淆的概念：
| 概念 | 角色 | 典型内容 | 生命周期 |
|---|---|---|---|
| Agent | 执行主体 | 推理循环、工具调用、上下文管理 | 一次会话内动态运行 |
| Skill | 可复用技能包 | SKILL.md、脚本、参考文档、模板 | 长期保存，随仓库分发 |
| Model | 底层推理引擎 | 大语言模型，负责理解和生成 | 由 API 或本地模型提供 |
| Tool | 外部能力 | 搜索、执行命令、读文件、发请求 | Agent 按需调用 |
在实际使用中，Skill 通常不自己执行命令，而是告诉 Agent“应该调用哪个脚本、按什么顺序执行、什么结果算成功”。它是一份可以被 Agent 读取的指令和资源集合。这个设计的好处是：技能内容可以独立维护，不依赖某个特定 Agent 的实现。
1.3 一个 Skill 的标准结构：SKILL.md 是入口
Agent Skills 最常见的组织方式是每个技能占一个目录，目录里有一个 Markdown 文件作为入口，文件名一般约定为SKILL.md，旁边可以放辅助脚本、参考资料和模板文件。一个典型结构如下：
repo-health-check/ ├── SKILL.md ├── scripts/ │ └── check_repo.sh └── references/ └── report-template.mdSKILL.md的头部通常使用 YAML Frontmatter 描述技能的元信息，下面再写人类可读的操作步骤。Agent 会先解析元信息，判断当前用户请求是否匹配这个技能，匹配后再按正文指令执行。
--- name: repo-health-check description: 对本地代码仓库进行基础健康检查，包括未提交文件、TODO/FIXME 标记、测试文件和依赖状态。当用户要求“检查仓库健康”或“体检”时使用。 --- # 代码仓库体检 ## 执行步骤 1. 获取当前 git 仓库状态。 2. 检查未提交修改和未跟踪文件。 3. 扫描代码中的 TODO 和 FIXME。 4. 查找测试文件，确认测试入口。 5. 汇总为 Markdown 报告。这里最容易踩的坑是 description 写得过于宽泛。如果描述里没有写清楚触发条件和适用边界，Agent 很可能在用户提出相似请求时误用，或者在应该使用的时候没有调用。描述应该包含三个要素：这项技能解决什么问题、什么时候使用、什么时候不要用。
2. 环境准备：安装 OpenCode 并完成模型接入
2.1 安装前先确认本地环境
在安装之前，先检查操作系统、Node.js 和包管理器。OpenCode 这类 CLI 工具通常依赖 Node.js 运行时，也可能提供编译好的二进制文件，适合不想安装 Node 的场景。
推荐先确认以下信息：
| 检查项 | 推荐做法 | 说明 |
|---|---|---|
| 操作系统 | Windows 10+ / macOS / Linux | 不同平台安装命令不同 |
| Node.js | 18 或更高版本 LTS | 具体以项目 engines 字段为准 |
| npm | 随 Node.js 安装 | 用于全局安装 CLI |
| git | 已安装并加入 PATH | 技能运行时常需要 git 操作 |
| 终端 | Windows 推荐 PowerShell 7 或 Git Bash | 避免旧版 cmd 的编码问题 |
检查命令如下：
node -v npm -v git --version如果node -v输出 “command not found” 或类似信息，需要先安装 Node.js。建议使用官方 LTS 版本，不要使用过于激进的测试版，因为第三方 CLI 可能还没有适配最新版 Node 的破坏性变更。
2.2 安装 OpenCode 的几种方式
OpenCode 的具体安装方式需要以官方仓库 README 为准。常见思路有三种：通过 npm 全局安装、通过 Homebrew 安装、直接下载对应平台的二进制压缩包。下面给出常见的命令写法：
# 方式一：npm 全局安装（包名以官方文档为准） npm install -g opencode-ai # 方式二：macOS 使用 Homebrew brew install opencode # 方式三：查看版本 opencode --version如果你使用的包名在当前 npm 源里找不到，不要继续照抄网上的命令，而是去官方仓库的 release 页面下载对应平台的二进制文件，解压后把可执行文件放到系统 PATH 目录下。
Windows 用户安装后如果执行opencode提示无法识别，常见原因是 npm 全局目录没有加入系统 PATH。可以先通过npm config get prefix查看全局安装路径，再把对应目录加入Path环境变量，然后重新打开终端。这个问题在后面的常见报错部分还会细说。
2.3 配置模型 API Key 和模型名
OpenCode 本身不包含模型，它需要连接一个可用的模型服务。常见方式是通过环境变量配置 API Key、基础地址和默认模型名。大多数兼容 OpenAI 接口的服务都可以这样接入。
export OPENAI_API_KEY="你的密钥" export OPENAI_BASE_URL="模型服务商提供的合规接口地址" export OPENCODE_MODEL="模型服务商支持的模型名"在 Windows PowerShell 中使用以下等效写法：
$env:OPENAI_API_KEY = "你的密钥" $env:OPENAI_BASE_URL = "模型服务商提供的合规接口地址" $env:OPENCODE_MODEL = "模型服务商支持的模型名"模型名是最容易出错的地方。模型名必须由你实际使用的模型服务商提供，不能照抄其他教程里出现的名称。如果填错，启动或对话时通常会看到类似 “xxx is not a model this version recognizes” 的报错。遇到这种错误时不要怀疑，直接检查模型名和当前 CLI 识别能力即可。
如果使用本地模型服务，也要确认接口地址和模型名完全匹配。隐私敏感场景下，建议优先考虑本地部署或企业内网服务，避免把业务代码发送到不受控的外部服务。
2.4 第一次启动验证
环境变量配置完成后，在项目目录下运行：
opencode如果一切正常，会进入交互式终端界面。输入一句简单的测试指令，例如：
你好，请用中文回答，并说明当前目录下的文件结构。如果模型能正常返回，说明安装、API Key、模型名和网络连通性都没有问题。如果此时出现错误，先不要继续创建 Skill，而是回到上一小节检查环境变量。
验证时还可以使用/status或/model这类命令查看当前会话使用的模型和上下文状态。不同版本的 OpenCode 命令可能不同，可以输入/help查看支持的命令列表。不要假设某个命令在所有版本里都存在。
3. 从零创建第一个 Agent Skill：代码仓库体检
3.1 技能目标和边界
第一个 Skill 不要设计得太复杂。这里做一个对本地代码仓库进行基础体检的技能，它需要完成四件事：查看 git 状态、统计 TODO/FIXME 标记、查找测试文件、生成简短的体检报告。
为什么选择这个任务？因为它的输入输出清晰，不依赖外部服务，也不会修改项目文件，适合验证 Skill 的加载和执行链路。等这条链路跑通后，再去做真正修改文件的项目脚手架。
在写 SKILL.md 之前，先想清楚边界：
- 触发场景：用户说“检查仓库健康”“体检”“看看这个项目状态”。
- 输入：当前工作目录的代码仓库。
- 输出：一份 Markdown 格式的体检结果。
- 不做什么：不修改代码，不提交 git，不安装依赖。
边界写清楚后，Agent 才不会在用户提出“帮我修复 bug”时误触发体检技能。
3.2 创建技能目录和 SKILL.md
Skill 目录的放置位置取决于 OpenCode 版本对技能目录的约定。如果版本兼容 Claude Code 的 Skills 规范，可以放在.claude/skills下；更贴近 OpenCode 习惯的目录可能是.opencode/skills。最稳妥的做法是查看当前版本的文档，确认它扫描哪个目录。下面以.opencode/skills为例。
mkdir -p .opencode/skills/repo-health-check/scripts mkdir -p .opencode/skills/repo-health-check/references创建SKILL.md：
--- name: repo-health-check description: 检查本地代码仓库的健康状态，包括 git 状态、TODO/FIXME 标记、测试文件和项目描述。当用户要求“检查仓库健康”“体检”“查看项目状态”时使用。 --- # 代码仓库体检 ## 输入 - 当前工作目录必须是 git 仓库。 ## 执行步骤 1. 用 `git status --short` 获取未提交和未跟踪文件。 2. 用脚本 `scripts/check_repo.sh` 扫描 TODO/FIXME 和测试文件。 3. 根据脚本输出整理 Markdown 报告。 4. 报告包含：仓库路径、未提交文件数、TODO/FIXME 数量、测试文件列表。 ## 输出格式 ```markdown ## 仓库体检结果 - 仓库路径：... - 未提交文件：... - TODO/FIXME：... - 测试文件：...注意事项
- 如果当前目录不是 git 仓库，直接告诉用户并停止执行。
- 不要修改任何文件。
注意 SKILL.md 里嵌入了代码块，在使用 Markdown 编写时，外层不需要再额外包裹代码块，但博客正文中展示时需要用正确的 Markdown 代码块表示。实际写文件时保持这个 Markdown 内容完整即可。 ### 3.3 编写辅助脚本，让技能真正可执行 SKILL.md 描述的是流程，真正干活还需要脚本。创建一个 `scripts/check_repo.sh`： ```bash #!/usr/bin/env bash set -euo pipefail echo "== git status ==" git status --short || true echo "== TODO/FIXME count ==" grep -rEn "TODO|FIXME" \ --include="*.js" \ --include="*.ts" \ --include="*.py" \ --include="*.java" \ --include="*.go" \ . || true echo "== test files ==" find . -type f \ \( -name "*test*" -o -name "*spec*" \) \ -not -path "*/node_modules/*" \ -not -path "*/.git/*" \ -not -path "*/vendor/*" \ -not -path "*/dist/*" \ -not -path "*/build/*" \ 2>/dev/null | head -30脚本前的set -euo pipefail是一行很关键的安全配置。-e表示遇到非零退出码时停止，-u表示使用未定义变量时报错，-o pipefail表示管道中任何命令失败都会导致整个管道失败。加上这一行可以避免脚本在出错后继续往下执行，掩盖问题。
在 Windows 上如果直接双击运行.sh文件会失败，需要 Git Bash、WSL 或安装了 bash 的终端来执行。Agent 运行脚本时，如果报权限错误，先执行：
chmod +x .opencode/skills/repo-health-check/scripts/check_repo.sh3.4 加载技能并验证
技能目录创建好之后，重新启动 OpenCode，让它重新扫描技能目录。在交互界面里可以尝试输入：
检查当前仓库的健康状态如果 Agent 成功调用 Skill，它会按 SKILL.md 的步骤执行，最终输出一份包含 git 状态、TODO/FIXME 数量和测试文件的报告。如果 Agent 只是泛泛回复而没有执行脚本，可能的原因有三个：技能目录没有被扫描、SKILL.md 的 description 不够匹配、当前版本不支持该技能目录命名。
在验证时不要只检查“是否返回了文字”，还要确认脚本是否真正执行。比如故意在一个非 git 目录里运行，看 Agent 是否按照“不是 git 仓库就停止”的规则处理。只有异常分支也符合预期，才能说技能真正生效。
4. 项目实战：用 Skill 自动生成项目脚手架
4.1 需求拆解
第一个 Skill 只读不写，适合验证机制。项目实战要做一个真正能生成文件的 Skill：用户提供项目名、语言、包名后，Agent 自动创建目录结构、README、gitignore 和最小代码文件。
在动手前先拆解需求：
| 参数 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|
| project_name | 是 | 无 | 项目目录名 |
| language | 否 | python | 支持 python/node/go |
| package_name | 否 | 等于 project_name | Python 包名，需要合法标识符 |
| author | 否 | 空 | 写入 README 作者信息 |
参数规则要提前定好。比如 Python 包名不能包含连字符，如果用户输入的project_name是my-app，但package_name没填，脚本要能自动把my-app转成my_app，否则生成出来的__init__.py会放在非法目录里。这就是细节坑。
4.2 设计 Skill 目录和模板变量
创建第二个技能目录：
.opencode/skills/scaffold-generator/ ├── SKILL.md └── scripts/ └── generate_scaffold.sh模板不以单独文件方式存放，而是在脚本里用 here-doc 生成文件，这样拷贝技能目录时不会丢模板。对于更复杂的模板，建议把模板文件放到templates/目录里，脚本里用占位符替换。
SKILL.md 内容：
--- name: scaffold-generator description: 根据项目名、语言和包名生成最小项目脚手架。适用于“新建项目”“生成脚手架”“初始化项目”等请求。 --- # 项目脚手架生成 ## 输入参数 - project_name：必填，项目目录名。 - language：可选，python/node/go，默认 python。 - package_name：可选，默认由 project_name 转换而来。 - author：可选，写入 README。 ## 执行步骤 1. 确认 project_name 不为空。 2. 校验 language 是否在支持列表内。 3. 运行 `scripts/generate_scaffold.sh <project_name> <language> <package_name> <author>`。 4. 脚本成功运行后，展示生成的目录结构。 5. 如果参数不合法，告诉用户原因并停止。 ## 注意事项 - 不要覆盖已存在的同名目录。 - Python 的 package_name 不能包含连字符。 - 脚本未完成时不要提前报告创建成功。4.3 编写脚手架脚本
generate_scaffold.sh是核心。下面是一个支持 Python 的简化版本，Node 和 Go 的分支可以按相同思路扩展：
#!/usr/bin/env bash set -euo pipefail PROJECT_NAME="${1:?project_name is required}" LANGUAGE="${2:-python}" AUTHOR="${4:-}" PACKAGE_NAME="${3:-$PROJECT_NAME}" PACKAGE_NAME="${PACKAGE_NAME//-/_}" if [ -e "$PROJECT_NAME" ]; then echo "error: $PROJECT_NAME already exists" >&2 exit 1 fi mkdir -p "$PROJECT_NAME" cat > "$PROJECT_NAME/README.md" <<EOF # $PROJECT_NAME ${AUTHOR:+Author: $AUTHOR} EOF cat > "$PROJECT_NAME/.gitignore" <<EOF __pycache__/ *.pyc .venv/ dist/ build/ EOF case "$LANGUAGE" in python) mkdir -p "$PROJECT_NAME/src/$PACKAGE_NAME" cat > "$PROJECT_NAME/src/$PACKAGE_NAME/__init__.py" <<EOF """$PROJECT_NAME package.""" __version__ = "0.1.0" EOF cat > "$PROJECT_NAME/pyproject.toml" <<EOF [project] name = "$PACKAGE_NAME" version = "0.1.0" description = "$PROJECT_NAME" requires-python = ">=3.10" EOF ;; *) echo "unsupported language: $LANGUAGE" >&2 exit 1 ;; esac echo "created project $PROJECT_NAME"脚本里的${PACKAGE_NAME//-/_}是 Bash 的变量替换语法，表示把所有连字符替换成下划线。${1:?project_name is required}表示第一个参数缺失时直接报错退出。这些细节能确保 Agent 在参数不完整时不会生成残缺项目。
4.4 在 OpenCode 里运行并验证
技能创建好后，重启 OpenCode，在同一会话中输入：
帮我创建一个 Python 项目 demo-app，包名用 demo_app，作者写 zhangsan正常流程下，Agent 会执行scripts/generate_scaffold.sh demo-app python demo_app zhangsan，然后展示目录结构。预期生成结果如下：
demo-app/ ├── README.md ├── .gitignore ├── pyproject.toml └── src/ └── demo_app/ └── __init__.py验证时重点检查三件事：目录是否存在、包名是否被替换为下划线、pyproject.toml 的 name 字段是否合法。还可以故意再次运行同样命令，预期会看到 “error: demo-app already exists”，这样可以确认脚本的防覆盖逻辑生效。
4.5 从生成脚手架到继续扩展
脚手架生成只是入口。技能生成完项目后，Agent 还可以继续执行后续步骤，比如安装依赖、初始化 git、运行测试。这些后续动作最好是显式写在 SKILL.md 里，并在执行前让用户确认。
例如可以在 SKILL.md 里追加：
## 后续动作 - 如果用户要求“初始化 git”，执行 `git init` 和首次提交。 - 如果用户要求“安装依赖”，根据 language 执行对应包管理器命令。 - 不要把“生成目录”和“安装依赖”捆绑执行，除非用户明确要求。之所以要把后续动作拆开，是因为生成脚手架是无副作用的写操作，安装依赖却会创建虚拟环境或下载大量文件。把两种动作混在一起，容易让 Agent 在用户只想要目录结构时执行了重量级操作。
5. 常见报错与排查链路
5.1 OpenCode 不是可识别的命令
这是 Windows 上最常见的错误。现象是执行opencode后 PowerShell 提示：
opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称排查顺序如下：
- 确认是否安装成功：
npm ls -g --depth=0查看全局包列表，或者去 release 目录看二进制是否存在。 - 确认全局 bin 目录是否在 PATH：
npm config get prefix，然后把返回路径下的 bin 目录加入系统 PATH。 - 重新打开终端，再执行
opencode --version。
macOS 和 Linux 上如果出现command not found，也要检查 npm 全局目录是否在 PATH，或者在安装 Homebrew 包后确认brew --prefix opencode路径。
5.2 模型名不识别或模型服务错误
错误日志里出现 “xxx is not a model this version recognizes” 时，说明你配置的模型名不是当前 CLI 所识别的名称。不要试图用其他模型的名称“碰运气”，正确做法是：
- 查看模型服务商实际提供的模型列表。
- 用
/model或配置页确认当前 CLI 支持哪些模型。 - 核对
OPENCODE_MODEL环境变量，空格、大小写、版本号都要一致。
如果配置的接口地址返回 401 或 404，则检查 API Key 是否有效、接口路径是否为/v1格式。这里最容易犯的错误是把网页端登录地址当成 API 地址。
5.3 Skill 不加载或调用不到
如果 Agent 没有按预期调用 Skill，按以下链路检查：
| 现象 | 可能原因 | 检查方式 |
|---|---|---|
| 技能完全没出现 | 目录扫描路径不对 | 查看文档确认是.opencode/skills还是.claude/skills |
| 描述匹配但没执行步骤 | SKILL.md 格式错误 | 检查 YAML Frontmatter 是否完整，name 和 description 是否缩进正确 |
| 部分版本生效部分不生效 | 使用了旧版 CLI | 升级到支持 Skills 的版本 |
| 脚本执行失败 | 脚本没有执行权限 | 执行chmod +x或调整脚本 |
还要注意 SKILL.md 的文件名。多数实现规定为全大写SKILL.md，如果写成skill.md或Skill.md，扫描器可能跳过。遇到不生效时先看文件名。
5.4 API Key、限流和超时问题
如果 Agent 能启动，但每次请求都很快失败，检查环境变量是否在当前会话生效：
echo $OPENAI_API_KEY在 PowerShell 中：
echo $env:OPENAI_API_KEY限流和超时的典型表现是同一个请求反复重试，日志中出现 429、503 或 timeout 关键字。处理方式是降低并发、换用更高额度、或者改用本地模型。生产环境不应该把 API Key 写在脚本里明文共享，应该通过密钥管理服务或环境变量注入。
5.5 脚本执行异常、路径和权限问题
在 Windows 上运行.sh脚本失败很常见。优先使用 Git Bash 或 WSL，避免在 PowerShell 中直接执行 Bash 脚本。Linux/macOS 下如果提示Permission denied，执行：
chmod +x scripts/*.sh路径包含空格或中文时，脚本里要习惯给变量加双引号："$PROJECT_NAME"。如果不加引号，demo app会被拆成两个参数，导致目录创建错误。项目目录名是用户输入时，还要注意不要把~、*等特殊字符直接带入命令。
5.6 按优先级排查的通用链路
遇到问题不要随机试，按下面的顺序排查可以减少大量无效操作：
- 输入检查：参数是否完整，路径是否正确。
- 环境检查：Node、git、PATH 是否可用。
- 依赖检查：OpenCode 版本和模型服务版本。
- 配置检查：环境变量、模型名、Skill 目录名。
- 权限检查：脚本执行权限、文件写权限。
- 网络检查：接口连通性、限流、超时。
- 日志检查：CLI 日志、脚本输出、模型返回错误。
如果以上都正常但问题还在，把错误日志完整复制下来，去掉 Key 等敏感信息，再去仓库 Issue 中搜索。搜索时不要只搜“报错”，要把日志中的唯一标识一起搜。
6. 生产环境使用 Agent Skills 的最佳实践
6.1 学习环境与生产环境要分开
在本地机器上创建一个 Skill 并跑通，只证明机制可用。放到生产环境前，还需要补齐很多内容。下面是两个环境的典型差异：
| 维度 | 学习环境 | 生产环境 |
|---|---|---|
| API Key | 本地环境变量 | 密钥管理服务动态注入 |
| 技能目录 | 项目内.opencode/skills | 独立技能仓库，按版本发布 |
| 日志 | 终端输出 | 持久化日志、审计记录 |
| 权限 | 当前用户权限 | 最小权限，禁止 ROOT |
| 脚本 | 只做演示 | 需要幂等、可重试、失败通知 |
| 回滚 | 删除目录重建 | 版本控制 + 历史可追溯 |
生产环境里，技能脚本一旦出错，影响的不只是当前项目，还可能触发自动部署、数据修改等高风险操作。因此生产环境必须对 Skill 能执行的动作设定边界，不能让它随意运行命令。
6.2 Skill 设计规范：从可运行到可维护
写 Skill 时尽量遵循以下清单：
- 每个 Skill 只解决一个明确问题，不要写“万能技能”。
description必须写清楚触发场景和禁止场景。- 输入参数要有默认值和校验规则。
- 脚本要幂等，重复执行不会造成破坏。
- 输出要有固定格式，方便 Agent 和用户阅读。
- 失败时要给出明确错误信息，而不是静默退出。
- 技能目录必须纳入版本管理，禁止在服务器上手工修改。
这里特别强调幂等。脚手架生成脚本如果发现目录已存在，应当停止而不是覆盖。部署脚本如果重复执行，应当要么跳过已完成步骤，要么允许安全重试。没有幂等保证的技能，在 Agent 自动执行时很容易变成事故源。
6.3 安全边界与权限控制
Agent Skills 最大的安全风险，是 Agent 在执行技能时使用了过高的权限。不要把技能脚本放在 root 用户下运行，也不要在技能里直接读取所有环境变量。
建议的做法：
- 技能脚本里只读取运行时需要的环境变量。
- 涉及删除、覆盖、推送远程分支等危险操作时，先要求用户确认。
- 不要把数据库密码、云厂商密钥写进 SKILL.md 或模板文件。
- 在容器或沙箱里运行不可信技能，限制网络和文件系统访问范围。
- 定期审查技能目录的变更历史，关注是否有人向脚本里添加了额外命令。
安全不是靠模型自律，而是靠环境约束。脚本能做的事，Agent 就一定能做；脚本不能访问的资源，Agent 才真正接触不到。
6.4 团队共享与版本管理
当团队里多个项目要复用同一套技能时，不要在每个项目里复制一份技能目录。推荐做法是把技能集合做成独立 git 仓库，然后在项目里通过子模块或专用工具引用。
技能仓库可以按这样的目录组织：
skills/ ├── repo-health-check/ ├── scaffold-generator/ ├── dependency-upgrade/ └── release-notes/每个技能目录内除了 SKILL.md 和 scripts，还应该包含自己的 README，说明适用范围、依赖环境、已知限制。这样新成员接入时不需要读代码，只看 README 就能判断是否能使用。
使用子模块时要注意“飘忽指针”问题。如果不锁定版本，技能仓库更新后，所有引用项目的技能行为都会变化，可能导致同一个任务在不同项目里生成不同结果。建议在发布周期里给技能仓库打 tag，然后各个项目锁定到稳定 tag。
6.5 从第一个 Skill 到技能库
跑通两个 Skill 之后，可以继续做两件事：一是梳理你日常开发中最常做的重复操作，把它们逐个固化成 Skill；二是为这些 Skill 建立统一的日志和反馈机制，方便追踪每次技能调用的输入、输出和耗时。
一个比较实际的学习路径是：
- 先做只读型 Skill，熟悉加载机制。
- 再做生成文件型 Skill，学习参数校验和幂等处理。
- 然后做执行命令型 Skill，比如自动构建、测试、发布，并加上人工确认步骤。
- 最后把多个 Skill 组合成一条完整工作流，比如“体检 + 生成分支 + 修改代码 + 运行测试 + 生成变更日志”。
组合多个 Skill 时，要让每个 Skill 的输入输出边界保持清晰。不要把 A 技能的脚本直接调到 B 技能目录里，正确做法是让 Agent 先调用 A 产出中间结果，再调用 B 消费这个结果。技能之间是插件关系，不是耦合关系。
真正的价值不在于装上一个 Agent CLI，而在于你愿意投入时间去打磨那些每天重复的固定操作。Agent 的通用能力决定了它“能做什么”，Skill 的质量则决定了它在你的项目里“做得有多稳”。从最小的只读技能开始，跑通一次完整验证，再慢慢扩展，是投入产出比最高的路径。
