.claude/skills/
└── deploy/
    └── SKILL.md    ← 部署技能

---
name: deploy
description: 部署应用到生产环境
when_to_use: 当用户要求部署或发布时
allowed-tools:
  -Bash(npm run build)
  -Bash(aws s3 sync *)
  -Bash(aws cloudfront create-invalidation *)
argument-hint: "[环境名称]"
arguments:
  -environment
---
 
# 部署流程
 
1.运行构建: `npm run build`
2.上传到 S3: `aws s3 sync dist/ s3://my-bucket/${environment}/`
3.清除 CDN 缓存: `aws cloudfront create-invalidation --distribution-id XXX --paths "/*"`
4.验证部署: 访问 https://${environment}.example.com 确认正常

// 源码：skills/loadSkillsDir.ts — parseSkillFrontmatterFields
export function parseSkillFrontmatterFields(
  frontmatter: FrontmatterData,
  markdownContent: string,
  resolvedName: string,
): {
  displayName: string | undefined      // 显示名称
  description: string                  // 描述
  allowedTools: string[]               // 允许使用的工具
  argumentHint: string | undefined     // 参数提示
  argumentNames: string[]              // 参数名列表
  whenToUse: string | undefined        // AI 何时自动调用
  version: string | undefined          // 版本
  model: string | undefined            // 指定模型
  disableModelInvocation: boolean      // 禁止 AI 自动调用
  userInvocable: boolean               // 用户是否可通过 / 调用
  hooks: HooksSettings | undefined     // 关联的钩子
  executionContext: 'fork' | undefined // 执行上下文
  agent: string | undefined            // 关联的 agent 类型
  effort: EffortValue | undefined      // 努力程度
  shell: FrontmatterShell | undefined  // Shell 配置
} { /* ... */ }

graph TD
    A[技能发现] --> B[管理员技能<br/>policySettings]
    A --> C[用户技能<br/>~/.claude/skills/]
    A --> D[项目技能<br/>.claude/skills/]
    A --> E[额外目录<br/>--add-dir]
    A --> F[遗留命令<br/>.claude/commands/]
 
    B --> G[合并 + 去重]
    C --> G
    D --> G
    E --> G
    F --> G
    G --> H[最终技能列表]
 
    style G fill:#fff3e0
    style H fill:#c8e6c9

// 源码：skills/loadSkillsDir.ts — getSkillDirCommands
export const getSkillDirCommands = memoize(
  async (cwd: string): Promise<Command[]> => {
    // 并行加载所有来源
    const [
      managedSkills,       // 管理员配置的
      userSkills,          // 用户全局的
      projectSkillsNested, // 项目级的
      additionalSkillsNested, // 额外目录的
      legacyCommands,      // 遗留命令目录的
    ] = await Promise.all([...])
    // 去重（相同文件只加载一次）
    // 优先级：管理员 > 用户 > 项目
    return deduplicatedSkills
  }
)

// 源码：skills/loadSkillsDir.ts — 通过 realpath 去重
async function getFileIdentity(filePath: string): Promise<string | null> {
  try {
    return await realpath(filePath)
  } catch {
    return null
  }
}
// 即使通过符号链接或不同路径引用
// 只要真实路径相同，就只加载一次

// 源码：skills/loadSkillsDir.ts — discoverSkillDirsForPaths
export async function discoverSkillDirsForPaths(
  filePaths: string[],
  cwd: string,
): Promise<string[]> {
  for (const filePath of filePaths) {
    let currentDir = dirname(filePath)
    // 从文件所在目录向上遍历到 cwd
    while (currentDir.startsWith(resolvedCwd + pathSep)) {
      const skillDir = join(currentDir, '.claude', 'skills')
      // 检查目录是否存在
      // 检查是否被 gitignore
      // 如果存在且未忽略，加入发现列表
    }
  }
}

graph BT
    A[src/features/auth/.claude/skills/] -->|发现| D[动态加载]
    B[src/features/.claude/skills/] -->|发现| D
    C[src/.claude/skills/] -->|跳过：已在启动时加载| E[已加载]
 
    F[读取 src/features/auth/login.ts] -->|触发| A
    F -->|触发| B
 
    style D fill:#e3f2fd
    style E fill:#c8e6c9

// 源码：skills/loadSkillsDir.ts — activateConditionalSkillsForPaths
export function activateConditionalSkillsForPaths(
  filePaths: string[],
  cwd: string,
): string[] {
  for (const [name, skill] of conditionalSkills) {
    const skillIgnore = ignore().add(skill.paths)
    for (const filePath of filePaths) {
      if (skillIgnore.ignores(relativePath)) {
        // 匹配！激活这个技能
        dynamicSkills.set(name, skill)
        conditionalSkills.delete(name)
      }
    }
  }
}

// 源码：skills/loadSkillsDir.ts — createSkillCommand
export function createSkillCommand({
  skillName,
  markdownContent,
  allowedTools,
  ...
}): Command {
  return {
    type: 'prompt',
    name: skillName,
    description,
    allowedTools,
    async getPromptForCommand(args, toolUseContext) {
      let finalContent = markdownContent
      // 替换参数：${environment} → production
      finalContent = substituteArguments(finalContent, args, ...)
      // 替换技能目录变量
      finalContent = finalContent.replace(
        /\$\{CLAUDE_SKILL_DIR\}/g, skillDir
      )
      // 替换会话 ID 变量
      finalContent = finalContent.replace(
        /\$\{CLAUDE_SESSION_ID\}/g, getSessionId()
      )
      // 执行内嵌 Shell 命令（非 MCP 技能）
      if (loadedFrom !== 'mcp') {
        finalContent = await executeShellCommandsInPrompt(...)
      }
      return [{ type: 'text', text: finalContent }]
    }
  }
}

// 源码：plugins/builtinPlugins.ts
const BUILTIN_PLUGINS: Map<string, BuiltinPluginDefinition> = new Map()
export function registerBuiltinPlugin(
  definition: BuiltinPluginDefinition,
): void {
  BUILTIN_PLUGINS.set(definition.name, definition)
}

// 源码：plugins/builtinPlugins.ts — getBuiltinPlugins
export function getBuiltinPlugins(): {
  enabled: LoadedPlugin[]
  disabled: LoadedPlugin[]
} {
  const settings = getSettings_DEPRECATED()
  for (const [name, definition] of BUILTIN_PLUGINS) {
    // 检查可用性
    if (definition.isAvailable && !definition.isAvailable()) continue
    // 检查用户设置
    const userSetting = settings?.enabledPlugins?.[pluginId]
    const isEnabled = userSetting !== undefined
      ? userSetting === true
      : (definition.defaultEnabled ?? true)  // 默认启用
    // 分类到 enabled 或 disabled
  }
}

// 源码：plugins/builtinPlugins.ts — getBuiltinPluginSkillCommands
export function getBuiltinPluginSkillCommands(): Command[] {
  const { enabled } = getBuiltinPlugins()
  const commands: Command[] = []
  for (const plugin of enabled) {
    const definition = BUILTIN_PLUGINS.get(plugin.name)
    if (!definition?.skills) continue
    for (const skill of definition.skills) {
      commands.push(skillDefinitionToCommand(skill))
    }
  }
  return commands
}

// 源码：skills/mcpSkillBuilders.ts
// MCP 服务器可以暴露技能定义
// Claude Code 自动发现并注册这些技能
export function registerMCPSkillBuilders(builders) {
  // 注册 MCP 技能构建器
  // 复用 createSkillCommand 和 parseSkillFrontmatterFields
}

// 源码：skills/loadSkillsDir.ts
// MCP 技能是远程和不受信任的
// 不执行内嵌 Shell 命令
if (loadedFrom !== 'mcp') {
  finalContent = await executeShellCommandsInPrompt(...)
}

// 源码：tools/SkillTool/SkillTool.js（概念）
// AI 调用：SkillTool({ name: "deploy", arguments: "production" })
// SkillTool 找到对应的 SKILL.md
// 加载内容、替换参数
// 将结果作为提示词注入

graph TD
    A[AI 决定使用技能] --> B[调用 SkillTool]
    B --> C[查找技能定义]
    C --> D{找到？}
    D -->|是| E[加载 SKILL.md]
    D -->|否| F[返回错误]
    E --> G[参数替换]
    G --> H[执行内嵌命令]
    H --> I[注入提示词]
    I --> J[AI 按技能指导执行]
 
    style B fill:#e3f2fd
    style I fill:#c8e6c9

---
name: react-lint
paths:
  - src/components/**
  - src/hooks/**
---
# React 代码规范检查
当编辑 React 组件时自动激活...

---
name: risky-refactor
context: fork
---
# 高风险重构
在独立分支中执行，不影响主分支...

---
name: quick-format
model: haiku
---
# 快速格式化
简单任务，用轻量模型即可...

---
name: deploy
hooks:
  PostToolUse:
    - matcher: Bash
      hooks:
        - command: "./scripts/validate-deploy.sh"
---