# Skills

Skills 模块负责加载、选择、注入、学习和发布 Beaver 技能。技能不是普通文档摘要，而是会被 ContextBuilder 作为显式 user 消息注入当前 run 的操作指导。

## 大模块流程

目录加载published/builtin/drafts/specs
->
候选召回embedding retrieve
->
LLM 选择shortlist/final 或 node skill selection
->
注入SkillContext -> activation message
->
学习accepted task evidence -> candidate -> draft -> review -> publish

## 小模块拆分

### catalog loader

扫描和加载 published skills、builtin skills，并构建供 embedding/LLM 选择的候选摘要。它也提供 load_published_skill、get_skill_record、get_skill_tool_hints。

读取 SKILL.md 和 frontmatter。
记录 name、description、version、content_hash、tool hints。
输出 selection candidates。

### SkillAssembler

主 agent 每个 run 的 skill 选择器。先用 embedding 召回候选；候选太多时先 LLM shortlist；再把完整 skill 正文截断后交给 LLM final selection。

query = task_description 或 AgentService 提供的 skill_selection_context。
embedding top-k 召回 selection candidates。
shortlist 阶段只看摘要，返回最多 N 个 skill names。
final 阶段看候选正文，返回最终激活 skill names。
加载正文，strip frontmatter，生成 SkillContext。

详细 prompt 见 Prompt Atlas。

### activation injection

ContextBuilder 不把 skill 正文塞进 system prompt，而是每个 skill 生成一条 user-role activation message。这样 skills 的正文和主 system prompt 分层清晰。

    [SYSTEM: The "{skill.name}" skill (version {skill.version}) is active for this run.
    Follow its instructions as active guidance unless the user overrides them.]

    {skill.content}

### drafts / reviews / publisher

草稿、审核和发布构成 skill 的人工治理链路。Learning 只生成候选和草稿，不直接把新能力静默注入 published 目录。

DraftService 保存草稿内容和 metadata。
ReviewService 记录审核意见、状态、决策。
SkillPublisher 把通过审核的草稿写成正式 skill spec。

### learning

从用户接受后的 Task evidence 中提取学习候选，合成新 skill 或修订草稿，再经过 safety/eval/review。Safety/Eval 只评估 skill draft，不评估 task result。

Task accepted 后触发 learning；一个 task 的所有 runs 都进入证据包，并标记 final_accepted_run_id。
LearningService 构建 learning candidates。
EvidencePacket 收集 task summary、session excerpts、tool names、user acceptance event 和 revision history。
SkillDraftSynthesizer 用 LLM 生成 frontmatter/content/change_reason JSON。
SafetyChecker 做确定性扫描，Eval 评估后进入 draft/review。

### missing skill guidance

当 team node 没有匹配 published skill 时，TaskSkillResolver 生成一次性 ephemeral guidance。它以 SkillContext 形式进入 delegated agent，但不会发布为正式 skill。

输入 task goal、user request、node id/task、skill query、required capabilities。
LLM 返回 guidance_name、description、content、tags。
若失败，用 fallback payload 生成基础指导。
SkillContext name = `ephemeral:{guidance_name}`，version = `ephemeral:{guidance_id}`。