06-opencode Skills 复用

06-Skills 复用掌握 OpenCode 的 Agent Skills 机制创建和复用可共享的指令定义。一、Skills 概述1.1 什么是 Agent SkillsAgent Skills 让 OpenCode 能够自动发现仓库或全局目录中的可复用指令。Skill 通过原生的skill工具按需加载——Agent 可以看到可用的 Skills 列表并在需要时加载完整内容。Skills SKILL.md 定义文件 skill 工具按需加载 示例git-release Skill .opencode/skills/git-release/SKILL.md ├── YAML frontmatter (name, description) └── Markdown 指令内容1.2 复用的优势优势说明自动发现OpenCode 自动扫描 Skills 目录无需手动配置按需加载Agent 通过skill工具在需要时才加载完整内容跨项目复用全局 Skills 可在所有项目中使用团队共享通过 Git 共享项目级 Skills权限控制可配置哪些 Agent 可以使用哪些 Skills二、创建 Skill2.1 文件结构每个 Skill 是一个目录里面包含一个SKILL.md文件.opencode/skills/ ├── git-release/ │ └── SKILL.md # 创建发布和变更日志 ├── python-class/ │ └── SKILL.md # Python 类生成规范 ├── pytest-suite/ │ └── SKILL.md # 测试套件生成规范 └── docker-setup/ │ └── SKILL.md # Docker 配置生成规范2.2 搜索路径OpenCode 会从以下位置加载 Skills路径说明.opencode/skills/name/SKILL.md项目级配置~/.config/opencode/skills/name/SKILL.md全局配置.claude/skills/name/SKILL.mdClaude 兼容路径项目级~/.claude/skills/name/SKILL.mdClaude 兼容路径全局.agents/skills/name/SKILL.mdAgent 兼容路径项目级~/.agents/skills/name/SKILL.mdAgent 兼容路径全局对于项目级路径OpenCode 会从当前工作目录向上遍历直到 git worktree 根目录加载沿途所有匹配的 Skills。2.3 Skill 名称规则name字段必须满足1-64 个字符仅包含小写字母数字和单个连字符分隔符不能以-开头或结尾不能包含连续的--必须与包含SKILL.md的目录名匹配正则表达式^[a-z0-9](-[a-z0-9])*$2.4 YAML Frontmatter每个SKILL.md必须以 YAML frontmatter 开头支持的字段字段必需说明name是Skill 名称description是Skill 描述1-1024 字符license否许可证compatibility否兼容性声明metadata否字符串到字符串的映射未知的 frontmatter 字段会被忽略。三、Skill 示例3.1 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.3.2 Python 类生成 Skill--- name: python-class description: Generate Python classes following PEP8 and modern standards --- ## What I do - Generate Python classes with type annotations (PEP 484) - Include Google-style docstrings - Use dataclass when appropriate - Implement __repr__ methods - Follow PEP 8 naming conventions ## When to use me Use this when creating new Python classes or refactoring existing ones. ## Code structure - Class names: PascalCase - Methods/variables: snake_case - Constants: UPPER_SNAKE_CASE - Private methods: leading underscore _method3.3 FastAPI CRUD Skill--- name: fastapi-crud description: Generate FastAPI CRUD endpoints with SQLAlchemy models and Pydantic schemas --- ## What I do - Create SQLAlchemy models with common fields (id, created_at, updated_at) - Generate Pydantic Create/Response schemas - Implement 5 standard endpoints (list, get, create, update, delete) - Use async/await throughout - Add proper error handling and HTTP status codes ## When to use me Use this when creating new CRUD endpoints for a FastAPI application. ## Code structure app/ ├── models/{model}.py # SQLAlchemy model ├── schemas/{model}.py # Pydantic schemas └── routers/{model}.py # API router3.4 测试套件 Skill--- name: pytest-suite description: Generate pytest test suites with fixtures and parametrization --- ## What I do - Create pytest test files following best practices - Use fixtures for test dependencies - Parametrize tests for edge cases - Include both happy path and error cases - Name test files as test_{module}.py ## When to use me Use this when writing tests for new or existing code. ## Coverage requirements - Normal flow tests - Exception input tests - Boundary value tests四、使用 Skills4.1 自动发现创建 Skill 后OpenCode 会自动发现并列出可用的 Skills。Agent 会在skill工具描述中看到available_skillsskillnamegit-release/namedescriptionCreate consistent releases and changelogs/description/skillskillnamepython-class/namedescriptionGenerate Python classes following PEP8 and modern standards/description/skill/available_skills4.2 加载 SkillAgent 通过调用skill工具加载 Skill 内容skill({ name: git-release })4.3 在对话中使用在 OpenCode 会话中你可以# 方式一直接描述需求AI 会自动发现并使用相关 Skills 帮我创建一个 User 模型的 CRUD # 方式二明确引用 Skill 使用 python-class skill 创建一个 DataProcessor 类 # 方式三内联指令不依赖 Skill 文件 按照以下规范生成代码 - 使用 FastAPI SQLAlchemy - 包含 Model, Schema, Router 三层 - 异步处理五、权限配置5.1 在 opencode.json 中配置通过模式匹配控制 Agent 可以访问哪些 Skills{permission:{skill:{*:allow,pr-review:allow,internal-*:deny,experimental-*:ask}}}权限行为allowSkill 立即加载denySkill 对 Agent 隐藏访问被拒绝ask加载前提示用户批准模式支持通配符internal-*匹配internal-docs、internal-tools等。5.2 按 Agent 覆盖为特定 Agent 设置不同的权限。自定义 Agent在 Agent frontmatter 中---permission:skill:documents-*:allow---内置 Agent在 opencode.json 中{agent:{plan:{permission:{skill:{internal-*:allow}}}}}5.3 禁用 Skill 工具对不应使用 Skills 的 Agent 完全禁用自定义 Agent---tools:skill:false---内置 Agent{agent:{plan:{tools:{skill:false}}}}禁用后available_skills部分将完全省略。六、团队共享6.1 通过 Git 共享 Skills团队仓库结构: team-opencode-config/ ├── README.md └── skills/ ├── company-fastapi-crud/ │ └── SKILL.md ├── company-auth/ │ └── SKILL.md └── company-naming-convention/ └── SKILL.md6.2 团队使用方式# 克隆团队配置gitclone https://github.com/company/opencode-config.git# 复制到项目cp-ropencode-config/skills/* .opencode/skills/# 或者通过符号链接保持同步ln-s/path/to/team-config/skills/* .opencode/skills/6.3 版本管理Skill 文件通过 Git 进行版本管理# 提交 Skill 更新gitadd.opencode/skills/gitcommit-mupdate: 优化 FastAPI CRUD Skill增加异步数据库支持# 查看 Skill 变更历史gitlog -- .opencode/skills/fastapi-crud/# 回退到之前的 Skill 版本gitcheckoutcommit-- .opencode/skills/fastapi-crud/6.4 全局 Skills将常用的 Skills 安装到全局所有项目可用~/.config/opencode/skills/ ├── python-standard/ │ └── SKILL.md ├── react-component/ │ └── SKILL.md └── docker-compose/ └── SKILL.md七、最佳实践7.1 Skill 设计原则单一职责每个 Skill 专注一类任务描述具体description 要足够具体让 Agent 能正确选择保持更新随项目演进更新 Skill 内容版本管理用 Git 追踪 Skill 变更清晰边界说明适用场景和何时不该使用7.2 命名规范格式: 领域-功能 示例: - git-release - python-class - pytest-suite - docker-compose - react-component - naming-convention - fastapi-crud - auth-setup7.3 Skill 内容结构推荐的 SKILL.md 内容结构--- name: skill-name description: 简短描述1-1024字符 --- ## What I do - 列出 Skill 能做的事情 - 具体明确 ## When to use me 说明何时应该使用这个 Skill 以及在不确定时应该问什么问题。 ## 具体规范 - 代码结构规范 - 命名约定 - 最佳实践 - 示例代码如需要7.4 Skill 维护定期检查 1. Skill 内容是否仍然适用当前技术栈 2. 示例代码是否过时 3. 是否有新的最佳实践需要补充 4. 团队反馈和改进建议八、故障排除8.1 常见问题Q: Skill 没有出现在可用列表中解决 1. 确保文件名是 SKILL.md全大写 2. 检查 frontmatter 包含 name 和 description 3. 确保 Skill 名称在所有位置中唯一 4. 检查权限配置—被 deny 的 Skill 对 Agent 隐藏 5. 确认文件在正确的目录下Q: Agent 没有遵循 Skill 中的规范解决 1. 确保 Skill 描述具体明确 2. 提供代码示例作为参考 3. 在对话中补充额外的约束条件 4. 分步骤生成每步确认Q: 生成的代码不符合预期解决 1. 细化 Skill 中的规范描述 2. 提供更多代码示例 3. 在对话中补充额外的约束条件 4. 检查是否加载了正确的 Skill8.2 调试技巧1. 先用简单的需求测试 Skill 效果 2. 逐步增加复杂度 3. 对比生成结果与 Skill 规范的差异 4. 根据差异调整 Skill 描述 5. 将成功的交互模式补充到 Skill 中九、下一步掌握 Skills 复用后建议学习07-代码分析与重构.md - 批量代码处理09-实战PythonWebAPI开发.md - 完整项目实战11-项目规划测试代码审查实战.md - 全流程实战文档版本: 3.0 | 建议学习时长: 30分钟