#Skills 系统

#一句话概括

Skills 系统从三个来源（内置、工作空间、插件）加载 SKILL.md 文件，构建带硬性 token 限制的目录，注入 system prompt 使 agent 能发现和使用专业能力。

#职责

• 从内置目录（52 个 skills）、agent 工作空间和插件扩展发现 skills
• 解析 SKILL.md frontmatter 获取元数据（需求、调用策略、描述）
• 构建 skills 目录（名称 + 描述 + 路径）注入 system prompt
• 执行目录大小硬限制（最多 150 个 skills，最多 30,000 字符）
• 压缩 skill 路径（~ 替换）以节省 tokens
• 通过文件系统监视器和快照版本控制支持热重载

#架构图

#关键源码文件

#Token 优化影响

#硬限制（workspace.ts:95-98）

DEFAULT_MAX_CANDIDATES_PER_ROOT = 300     （每目录发现上限）
DEFAULT_MAX_SKILLS_LOADED_PER_SOURCE = 200 （每来源加载上限）
DEFAULT_MAX_SKILLS_IN_PROMPT = 150         （prompt 包含上限）
DEFAULT_MAX_SKILLS_PROMPT_CHARS = 30,000   （约 7,500 tokens 硬限制）
DEFAULT_MAX_SKILL_FILE_BYTES = 256,000     （每文件大小限制）

#Token 预算分解

52 内置 skills × 每个约 30-50 tokens = 约 1,500-2,600 tokens（目录）
典型总量：约 1,500-3,000 tokens
最大值：约 7,500 tokens（30,000 字符 / 4 字符每 token）
compactSkillPaths() 节省：约 400-600 tokens

#关键优化：仅目录，非完整内容

System prompt 只包含目录（名称 + 描述 + 文件路径），不含完整 SKILL.md 内容。Agent 只在选中特定 skill 后才读取完整 SKILL.md。这是控制固定 token 成本的关键设计决策。

#与其他模块的关系

• 依赖：config/（skill 设置）、文件系统（SKILL.md 发现和监视）
• 被依赖：system-prompt.ts（接收 skill prompt）、pi-embedded-runner/（接收 skills 快照）、auto-reply/skill-commands.ts（用户调用的 skill 命令）

#我的认知盲区

• applySkillsPromptLimits() 中的二分搜索算法 — 如何优先选择包含哪些 skills
• 工作空间 skills 是否覆盖同名的内置 skills
• Skill 快照缓存行为和失效触发条件
• 插件提供的 skills 如何注册和发现

#相关贡献

• 暂无

#变更频率

• workspace.ts：中 — 限制调整和加载逻辑演进
• refresh.ts：低 — 监视器模式稳定
• frontmatter.ts：低 — 元数据 schema 是增量的