5.3a Skill 基础

用户：帮我查询数据仓库的收入数据

Claude：我建议用这个 SQL 查询...
SELECT * FROM revenue WHERE date > '2024-01-01'

用户：帮我查询数据仓库的收入数据

Claude：[自动加载 sql-analysis Skill]
我来帮你查询收入数据。根据你们的数据规范：
- 使用 monthly_revenue 汇总表
- 排除测试账户 (account != 'Test')
- 收入按 ARR 计算 (monthly * 12)

SELECT ...

┌─────────────────────────────────────────────────────────┐
│ 第一层：name + description（~100 词）                    │
│ → 始终可见，用于判断是否需要加载                         │
├─────────────────────────────────────────────────────────┤
│ 第二层：SKILL.md 正文                                    │
│ → 任务匹配时加载，包含主要指令                           │
├─────────────────────────────────────────────────────────┤
│ 第三层：references/ 目录中的详细文档                     │
│ → 仅在需要具体细节时加载                                 │
└─────────────────────────────────────────────────────────┘

.opencode/
└── skill/
    └── code-review/
        └── SKILL.md      # 技能定义文件（必须大写）

.opencode/
└── skill/
    └── sql-analysis/
        ├── SKILL.md              # 主文件：工作流程和关键逻辑
        └── references/           # 详细文档（按需加载）
            ├── finance.md        # 财务表结构
            ├── product.md        # 产品表结构
            └── examples.md       # 查询示例

.opencode/
└── skill/
    └── audit/
        └── security/
            └── SKILL.md    # 技能名由 frontmatter 中的 name 决定

✓ code-review
✓ sql-analysis
✓ git-release
✗ Code_Review    ← 不要用大写
✗ sql--analysis  ← 不要用连续横杠
✗ -review        ← 不要以横杠开头

<available_skills>
  <skill>
    <name>sql-analysis</name>
    <description>用于分析业务数据：收入、ARR、客户分群...</description>
  </skill>
  <skill>
    <name>code-review</name>
    <description>执行代码审查，检查规范、Bug、性能和安全</description>
  </skill>
</available_skills>

用户消息：帮我分析上季度的收入数据

Claude 判断：这是数据分析任务，与 sql-analysis Skill 匹配

Claude 调用：skill({ name: "sql-analysis" })

结果：SKILL.md 内容加载到上下文

## Skill: sql-analysis

**Base directory**: /path/to/.opencode/skill/sql-analysis

[SKILL.md 的内容]

{
  "permission": {
    "skill": {
      "pr-review": "allow",        // 立即加载
      "internal-*": "deny",        // 隐藏，拒绝访问
      "experimental-*": "ask",     // 加载前询问用户
      "*": "allow"                 // 其他默认允许
    }
  }
}

{
  "agent": {
    "plan": {
      "permission": {
        "skill": {
          "internal-*": "allow"
        }
      }
    }
  }
}

{
  "agent": {
    "plan": {
      "tools": {
        "skill": false
      }
    }
  }
}

对于不确定的翻译，用括号标注原文。