技能注册表（Skill Registry）

目标关联

该特性支撑专业工作执行、领域扩展、上下文连续性和专业可靠性。

实现的关键特性：

• Skill-Driven Capability System
• Configurable Professional Identity
• Quality and Governance System
• Learning and Capability Evolution

技术设计对齐

• skills 是 filesystem packages。
• 先加载 metadata，再按需加载完整内容。
• runtime 不硬编码领域知识。
• skills 可包含 references、templates、scripts、examples。
• candidate skill promotion 延后。

范围

Phase 1 包含扫描 skill paths、解析 SKILL.md metadata、构建 skill index、向 context 暴露 summaries、提供 list_skills 和 load_skill(skill_id)、记录 indexed/loaded events、清晰处理 malformed skills。

排除自动技能生成、自动提升、remote registry、脚本依赖安装、skill marketplace、完整 skill tests。

概念模型

Skill
  metadata
  instructions
  references
  templates
  scripts
  examples
  quality standards

SkillRegistry
  discover skill packages
  validate metadata
  build skill index
  load full skill content on demand

Skill Package Layout

skills/
  travel-planning/
    SKILL.md
    references/
    templates/
    scripts/
    examples/

Skill Metadata

---
id: travel-planning
name: Travel Planning
description: Use this skill to design practical travel plans, budgets, and risk checklists.
tags:
  - travel
permissions:
  filesystem: read
  web: optional
---

Phase 1 metadata 包含 id、name、description，可选 tags 和 permissions。

Loaded Skill Budget

加载技能不等于加载整个目录。LoadedSkill 应包含 metadata、SKILL.md 主说明、selected references summary、selected templates summary、declared permissions。

Runtime 应强制 maximum loaded skill size。超过限制时，load_skill 返回 summary 和可用 references，而不是全量内容。

Skill Permissions

Skill permissions 是声明，不是授权。

EffectivePermissionPolicy =
  runtime safe defaults
  + config tool permissions
  + loaded skill permission declarations
  + sandbox constraints

Skill declarations 不能覆盖 runtime deny rules 或 sandbox boundaries。

接口

Config：

skills:
  paths:
    - ./skills
  enabled:
    - travel-planning

Python：

class SkillRegistry:
    def discover(self) -> SkillIndex:
        ...
    def list_skills(self) -> list[SkillSummary]:
        ...
    def load_skill(self, skill_id: str) -> LoadedSkill:
        ...

Agent tools：

list_skills()
load_skill(skill_id)

运行时行为

Registry 从 config 的 skill paths 扫描目录，解析 metadata，构建 skill index。Runtime 将 skill summaries 注入 context。Agent 可调用 list_skills 和 load_skill。Recorder 记录 skill.indexed 和 skill.loaded。

产物

读取 skills/<skill-id>/ 下的 SKILL.md、references、templates、scripts、examples。可在 run archive 中写入 skill-index.json，记录可用技能和已加载技能。

质量和治理

• malformed metadata 明确失败。
• enabled skills not found 在 agent 执行前失败。
• skill ids 稳定且唯一。
• run 期间 skill content 只读。
• 涉及工具能力的技能应声明 permissions。
• candidate skills 不自动激活。

性能和调度考虑

Discovery 只读 metadata；不把所有 skill bodies 放入上下文；限制 loaded content size；记录 skill ids/versions 供未来 scheduler 路由和环境重建。

验收标准

1. Config 可指向 skill paths。
2. Registry 能发现 filesystem skills。
3. 能解析 SKILL.md metadata。
4. Skill index 包含 id、name、description、tags、path。
5. enabled-but-missing skills 执行前失败。
6. Agent context 只包含 summaries。
7. Agent 可调用 list_skills 和 load_skill。
8. Loaded content 有边界并被记录。
9. Candidate skill activation 不自动发生。
10. Skill permissions 作为声明参与 effective permission policy。