zeroz-lab/learn-opencode/internals

flowchart LR
    subgraph Scan["🔍 扫描"]
        OpenCode[".opencode/skill/"]
        Claude[".claude/skills/"]
        GlobalClaude["~/.claude/skills/"]
    end
    
    subgraph Parse["📄 解析"]
        YAML["YAML Frontmatter"]
        Content["Markdown 正文"]
    end
    
    subgraph Register["📦 注册"]
        SkillMap["Skill Map"]
        Agent["Agent System Prompt"]
    end
    
    OpenCode --> YAML
    Claude --> YAML
    GlobalClaude --> YAML
    YAML --> SkillMap
    Content --> Agent
    SkillMap --> Agent

---
name: python-expert
description: Python 开发最佳实践
---
 
# Python Expert
 
## 代码规范
-使用 type hints
-遵循 PEP 8
-使用 ruff 格式化
 
## 测试
-使用 pytest 框架
-覆盖率要求 > 80%

.opencode/
├── skill/
│   └── python/
│       └── SKILL.md     ✓ 匹配
│   └── SKILL.md         ✓ 匹配
└── skills/
    └── devops/
        └── SKILL.md     ✓ 匹配

.claude/
└── skills/
    └── code-review/
        └── SKILL.md     ✓ 匹配
 
# 全局 Skills
~/.claude/skills/
└── general/
    └── SKILL.md         ✓ 匹配

export const Info = z.object({
  name: z.string(),         // 技能名称 (必须唯一)
  description: z.string(),  // 描述
  location: z.string(),     // 文件路径
})

export const state = Instance.state(async () => {
  const skills: Record<string, Info> = {}
  const addSkill = async (match: string) => {
    // 解析 SKILL.md 的 YAML frontmatter
    const md = await ConfigMarkdown.parse(match)
    if (!md) return
    const parsed = Info.pick({ name: true, description: true }).safeParse(md.data)
    if (!parsed.success) return
    // 检查重复
    if (skills[parsed.data.name]) {
      log.warn("duplicate skill name", {
        name: parsed.data.name,
        existing: skills[parsed.data.name].location,
        duplicate: match,
      })
    }
    skills[parsed.data.name] = {
      name: parsed.data.name,
      description: parsed.data.description,
      location: match,
    }
  }
  // 1. 扫描 .claude/skills/ (项目级 + 全局)
  const claudeDirs = await Filesystem.up({
    targets: [".claude"],
    start: Instance.directory,
    stop: Instance.worktree,
  })
  
  // 添加全局 ~/.claude/skills/
  const globalClaude = `${Global.Path.home}/.claude`
  if (await exists(globalClaude)) {
    claudeDirs.push(globalClaude)
  }
  for (const dir of claudeDirs) {
    for await (const match of CLAUDE_SKILL_GLOB.scan({ cwd: dir })) {
      await addSkill(match)
    }
  }
  // 2. 扫描 .opencode/{skill,skills}/
  for (const dir of await Config.directories()) {
    for await (const match of OPENCODE_SKILL_GLOB.scan({ cwd: dir })) {
      await addSkill(match)
    }
  }
  return skills
})

// 获取单个 Skill
export async function get(name: string) {
  return state().then((x) => x[name])
}
// 获取所有 Skills
export async function all() {
  return state().then((x) => Object.values(x))
}

opencode> use skill: python-expert
 
opencode> 帮我重构这个函数

# .opencode/agent.yaml
agents:
  - name: python-dev
    skills:
      - python-expert
      - code-review

---
name: skill-name      # 必需, 唯一标识
description: 描述     # 必需, 显示给用户
---
 
# 标题
 
正文内容...
这里的内容会被注入到 System Prompt 中。

export const InvalidError = NamedError.create(
  "SkillInvalidError",
  z.object({
    path: z.string(),
    message: z.string().optional(),
    issues: z.custom<z.core.$ZodIssue[]>().optional(),
  }),
)
export const NameMismatchError = NamedError.create(
  "SkillNameMismatchError",
  z.object({
    path: z.string(),
    expected: z.string(),
    actual: z.string(),
  }),
)