OpenCode内置Skill格式入门指南：从零构建你的第一个技能模块

共计 1789 个字符，预计需要花费 5 分钟才能阅读完成。

OpenCode 技能系统为开发者提供了快速接入智能交互能力的标准化框架，其核心价值在于通过统一的 Skill 格式 实现功能模块的即插即用。本文将带你从零开始，用最直白的方式掌握技能开发的核心要点。

一、认识 skill.json：技能的身份证

每个 OpenCode 技能都必须包含名为 skill.json 的清单文件，它相当于技能的 ” 身份证 ”。以下是必填字段的详细说明（注意：所有字段名严格区分大小写）：

{
  "manifestVersion": "1.0",  // 必须为 1.0（当前稳定版本）"skillId": "your_skill_id",  // 全局唯一 ID，推荐格式：开发者前缀 + 功能名
  "displayName": "天气查询",  // 用户可见的技能名称
  "version": "0.0.1",  // 语义化版本号
  "permissions": ["location"],  // 所需权限声明
  "entryPoint": "./dist/index.js"  // 编译后的入口文件路径
}

• manifestVersion：当前必须固定为 ”1.0″，未来版本升级时会明确通知兼容方案
• skillId：建议采用 companyname.feature 格式（如acme.weather），避免使用特殊字符

二、基础技能模板实战

下面是一个完整的 TypeScript 技能模板，包含必要的事件处理逻辑：

// 导入 OpenCode 类型定义
import {Skill, SkillRequest, SkillResponse} from '@opencode/skill-sdk';

// 技能类必须实现 Skill 接口
class MyFirstSkill implements Skill {
  // 技能激活时触发（系统级事件）async onEnable() {console.log('技能已加载');
    // 这里可以初始化数据库连接等操作
  }

  // 技能禁用时触发
  async onDisable() {console.log('技能已卸载');
    // 释放资源操作
  }

  // 处理用户请求（核心业务逻辑）async handleRequest(request: SkillRequest): Promise<SkillResponse> {
    // 标准请求格式示例
    /* {
      "userId": "U12345",
      "query": "北京天气怎么样",
      "session": {...}
    } */

    // 构造标准响应
    return {
      version: request.version,
      output: {text: ` 收到请求：${request.query}`,
        card: {/* 富卡片数据 */}
      },
      session: request.session // 保持会话连续性
    };
  }
}

// 导出实例（必须）export default new MyFirstSkill();

关键注意事项：
1. 所有异步方法必须返回 Promise
2. handleRequest的输入输出结构必须严格遵循 SDK 类型定义
3. 生产环境需要处理未捕获的 Promise 异常

三、避坑指南

常见 manifest 校验失败原因

• 字段缺失：比如漏写 manifestVersion 或skillId
• 版本不匹配：`manifestVersion” 填写了不存在的版本号
• 权限未声明：使用了定位功能但 permissions 数组缺少 ”location”

异步事件处理三原则

1. 所有回调函数必须用 async/await 或显式返回 Promise
2. 在 onEnable/onDisable 中不要进行耗时超过 3 秒的操作
3. 使用 try-catch 包裹可能失败的异步调用

权限声明安全规范

• 遵循最小权限原则：只申请必要的权限
• 敏感权限（如user_profile）需要单独审核
• 在代码中动态检查权限是否被授予：

if (!request.hasPermission('location')) {return { /* 引导用户授权的响应 */};
}

四、进阶学习方向

当你能稳定运行基础技能后，建议继续探索：

1. 调试工具 ：使用 OpenCode CLI 的skill debug 命令实时查看日志
2. 性能优化：
3. 对高频操作使用内存缓存
4. 合理设置 keepAlive 减少冷启动时间
5. 生态集成：
6. 研究技能间调用协议
7. 了解技能商店的发布流程

从第一个简单技能出发，逐步掌握 OpenCode 生态的开发模式，你会发现构建智能交互功能变得越来越得心应手。如果在实践过程中遇到问题，官方文档的 常见问题 板块通常能给你答案。