Skills（技能）

OpenCorvus 基于 SKILL.md 的轻量扩展机制。

Skills 是 OpenCorvus 最轻量的扩展单元——一段带 YAML frontmatter 的 Markdown 文件，描述”在什么阶段、满足什么条件时，agent 应遵循哪些操作规则”。无需 TypeScript、无需编译，放进目录或从 URL 拉取即可。

源码：packages/opencorvus/src/skill/skill.ts、packages/opencorvus/src/skill/manager.ts

1. Skill 结构

my-skill/
├── SKILL.md        # 必需，frontmatter + 指令正文
└── references/     # 可选：参考资料

Frontmatter 字段（src/skill/skill.ts）：

字段	类型	说明
`name`	string（必需）	全局唯一 ID，被 permission 引用
`description`	string（必需）	一句话描述，告诉 agent 何时激活
`platforms`	`("windows"\|"macos"\|"linux")[]`	平台过滤，空数组 = 全平台
`auto_detect.files`	string[]	项目中存在这些文件时作为发现提示
`auto_detect.deps`	string[]	`package.json` 中存在这些依赖时作为发现提示
`auto_detect.task_signals`	object	任务级信号：图片附件、非 Figma URL、Figma URL、package scripts、请求文本
`priority`	number	多 skill 命中时的排序（大在前，默认 0）
`required_tools`	string[]	skill 预期可能需要的工具提示

2. 内置 Skills

随二进制打包（src/skill/skill.ts 的 builtins 数组），只有一个：

Skill	用途
`research-report`	用 `websearch` 和按需 `webfetch` 产出带来源的 Markdown 调研报告

其他 skill 需要通过 skills.paths / skills.urls 显式加载。

内置 Skill 默认权限为 allow（src/skill/manager.ts）。

3. 添加本地 Skill

方式 A：放到项目 .opencorvus/skill/<name>/SKILL.md 或全局 config 目录下，启动时自动扫描。

方式 B：兼容 Claude Code 布局，.claude/skills/ 或 .agents/skills/ 也会被发现（src/skill/skill.ts）。

方式 C：在 opencorvus.jsonc 中声明搜索路径：

{
  "skills": {
    "paths": ["./my-skills", "~/shared/skills", "/absolute/path/skills"],
  },
}

路径下所有 **/SKILL.md 都会被加载（src/skill/skill.ts）。

4. 从远程 URL 加载

{
  "skills": {
    "urls": ["https://skills.example.com/my-pack/"],
  },
}

加载流程（src/skill/discovery.ts）：

GET {url}/index.json 期望格式 { skills: [{ name, description, files[] }] }
按 files 逐一下载到 <runtime-root>/cache/skills/<name>/
加载缓存下的 SKILL.md

远程 URL index 是高级 source import 机制，与精确 Skill Market 链路彼此独立。

5. 从 Skill Market 搜索并安装

skills.sh 是当前唯一 Skill Market authority。设置页的 Skill 页面与运行时 Primary Agent 共用同一 OpenCorvus 服务：

按能力文本搜索。结果包含稳定的 owner/repository/skill identity、来源仓库、安装次数、详情 URL 和实时安装状态。
检查单个结果。OpenCorvus 只下载该 Skill，验证根 SKILL.md 与所有文件路径，并返回 OpenCorvus 计算的 SHA-256 内容 digest、上游 hash、文件清单、信任、风险和推荐策略。检查不会安装任何内容。
使用检查阶段得到的精确 digest 安装。OpenCorvus 会再次下载候选；内容改变即拒绝；匹配后原子发布一个 managed Skill，在 .opencorvus-skill-source.json 写入 provenance，更新全局配置并刷新 catalog。

规范 identity 统一为小写，并映射到 <runtime-root>/config/skills-market/skills-sh/<owner>/<repository>/<skill>/。替换与删除前会验证目标 provenance 仍由同一 identity 持有。上游网络、HTTP、JSON 或 bundle 校验失败统一返回可见的 SkillMarketUpstreamError HTTP 502 契约。

运行时 Agent 使用 skill_market Tool。search 与 inspect 是网络读取，install 是需要单独授权的本地写入。安装成功后从下一轮起可挂载，因为当前轮的 Skill surface 已冻结。

项目限定与全局公共路由均可用：

GET /skill/market 与 GET /global/skill/market
GET /skill/market/search?query=... 与 GET /global/skill/market/search?query=...
GET /skill/market/detail?id=... 与 GET /global/skill/market/detail?id=...
POST /skill/market/install 与 POST /global/skill/market/install，请求体包含 id、expected_hash 和可选 policy

6. 通过 Git 安装

opencorvus skill install --git https://github.com/owner/repo.git
# 简写：opencorvus skill install owner/repo

Git 方式克隆到 <runtime-root>/config/skills-market/<slug>/ 并自动追加到 skills.paths；.opencorvus-skill-source.json 记录来源（src/skill/manager.ts）。这是 whole-repository 高级直接来源导入，不是 Skill Market 精确安装器。runtime root 遵循环境变量。

7. Skill ↔ Agent 调用关系

Session 初始化时会提供 Skill Policy 与可用 skill 摘要。Agent 需要通过 skill 工具搜索或按精确名称加载 SKILL.md，然后执行其中的工作流。加载 skill 是会话历史中的可见工具调用。

auto_detect 仅作为发现 / 排序 / 后续 UI 辅助的元数据。Skill 正文通过可见的 skill 工具加载；required_tools 是 skill 搜索结果中的描述性提示；真正的证据要求由加载后的 skill 文档说明。

8. Permission 配置

{
  "permission": {
    "skill": {
      "*": "ask",
      "research-report": "allow",
      "local-note": "deny",
    },
  },
}

推荐策略：内置 allow；社区来源 ask；含 scripts/ 目录的视为高风险（src/skill/manager.ts）。

9. 信任等级与风险

等级	来源
`builtin`	随二进制打包
`official`	openai/skills 或 anthropics/skills
`curated`	Skill Market provider
`community`	community source
`local`	本地路径
`external`	`.claude/` 或 `.agents/` 目录发现

风险评估：目录含 scripts/ → 高风险；含 agents/ 或 references/ → 中等（src/skill/manager.ts）。

10. 禁用外部 Skills

OPENCORVUS_DISABLE_EXTERNAL_SKILLS=1
# 或
OPENCORVUS_DISABLE_CLAUDE_CODE_SKILLS=1

跳过 .claude/ 与 .agents/ 目录扫描，不影响 skills.paths 与 skills.urls（src/flag/flag.ts）。