CC源码剖析 #06 · Skills 加载与执行机制

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

---
name: "skill-name"           # Skill 标识符
description: "What this skill does and when to use it"
# 触发短语：用户可用这些短语激活 skill
whenToUse: "When the user asks about X or wants to Y"
arguments:                    # 可选：参数定义
  - name: arg1
    description: Description
    required: true
  - name: arg2
    description: Description
    default: "default value"
tools:                        # 可选：允许使用的工具
  - Read
  - Edit
  - Bash
---

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

---
name: "code-review"
description: "Review code for bugs and style issues"
whenToUse: "User asks for a review or wants to check code quality"
---

# Code Review Skill

Review the following code for:
1. Security vulnerabilities
2. Performance issues
3. Style consistency

Code to review:
{{code}}

1
2
3
4
5
6

// {{arg}} 替换为用户输入的参数值
// {{arg|default}} 提供默认值

substituteArguments(prompt, args)
// "Fix the bug in {{file}}" + { file: "auth.ts" }
// → "Fix the bug in auth.ts"

1
2
3
4
5
6
7

export type LoadedFrom =
  | 'commands_DEPRECATED'  // 旧式命令目录（已废弃）
  | 'skills'               // 用户 skills 目录
  | 'plugin'               // 插件提供的 skills
  | 'managed'              // 企业托管 skills
  | 'bundled'              // 内置 skills
  | 'mcp'                  // MCP 服务器提供的 skills

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

function getSkillsPath(source: SettingSource | 'plugin', dir: 'skills' | 'commands'): string {
  switch (source) {
    case 'policySettings':  // 企业托管
      return join(getManagedFilePath(), '.claude', dir)
    case 'userSettings':    // 用户全局
      return join(getClaudeConfigHomeDir(), dir)
    case 'projectSettings': // 项目本地
      return `.claude/${dir}`
    case 'plugin':          // 插件
      return 'plugin'
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

export function initBundledSkills(): void {
  registerUpdateConfigSkill()
  registerKeybindingsSkill()
  registerVerifySkill()
  // ...

  if (feature('AGENT_TRIGGERS')) {
    const { registerLoopSkill } = require('./loop.js')
    registerLoopSkill()
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

interface ArgumentDef {
  name: string
  description: string
  required?: boolean
  default?: string
}

// 从 frontmatter 解析参数定义
parseFrontmatter(markdown) → FrontmatterData

// 参数验证与替换
substituteArguments(prompt, userArgs) → string
parseArgumentNames(prompt) → string[]

1
2
3
4
5
6
7

---
name: "safe-read"
description: "Read file safely"
tools:
  - Read
  - Glob
---

1
2
3

// SkillTool 执行时设置工具限制
const allowedTools = skillFrontmatter.tools ?? []
// → Agent 只能使用声明的工具

1
2
3
4
5

// 用户输入时，模糊匹配可用 skills
// "run t" → /test, /terminal 等

parseSlashCommandToolsFromFrontmatter(markdown)
// 从 frontmatter 解析可用命令

1
2
3
4
5

// EXPERIMENTAL_SKILL_SEARCH 启用时
// 支持基于语义的 skill 搜索

clearSkillIndexCache()  // 清除缓存
// 本地向量搜索（基于关键词 TF-IDF）

1
2
3
4
5

// plugins/ 目录下的 skills
getPluginSkills() → Command[]

// 插件 Skill 具有更高优先级
// 可覆盖同名内置 Skill

1
2
3
4

// plugins/bundled/index.ts
// 内置插件提供的 skills

getBuiltinPluginSkillCommands()

1
2
3
4
5

// 用户输入
/skillify "My custom prompt" "Description of when to use"

// 系统创建 .claude/skills/my-custom-prompt.md
// 内容为用户 prompt

1
2
3

registerSkillifySkill()
// 提供 /skillify 命令
// 引导用户完成 Skill 创建

1
2
3
4
5

// MCP 服务器的工具包装为 Skill
registerMCPSkillBuilders()

// MCP Skill 具有 MCP 服务器的访问权限
// 可调用 MCP 服务器定义的资源