传统方案:    所有功能硬编码 → 系统提示越来越长 → token 爆炸 ❌
Skill 方案:  按需加载     → 元数据常驻 + 正文惰性   → token 可控 ✅

早期:  Slash Commands (/command) — 纯手动触发，需用户知道命令名称
现在:  Skills (/skill-name)      — 自动+手动双触发，系统根据上下文推荐
趋势:  Slash Commands 被逐步吸收进 Skill 体系

---                      # ← YAML Frontmatter：元数据（约 40-100 tokens）
name: skill-name         #   必填：唯一标识 + 斜杠命令名
description: >           #   必填：做什么 + 何时用（单行！）
allowedTools: [...]      #   可选：工具白名单
context: fork            #   可选：隔离执行环境
model: sonnet            #   可选：指定模型
effort: high             #   Optional: 推理深度
priority: high           #   Optional: 触发优先级
paths: [...];            #   Optional: 路径匹配规则
hooks:                   #   Optional: 生命周期钩子
  - event: beforeToolUse
    type: prompt
    prompt: "检查权限"
---                      # ← 分割线

# ← Markdown Instructions：完整指令（仅在激活时加载）

你是安全审计助手...

hooks:
  - event: beforeToolUse       # 触发时机
    type: prompt               # 行为类型：command / http / prompt / agent
    prompt: "确认工具调用合理"

启动时：每个 Skill 仅加载 name + description ≈ 40-100 tokens
──────────────────────────────────────────────────────
运行时：只有匹配的 Skill 才会注入完整 Markdown Instructions
──────────────────────────────────────────────────────
示例：10 个 Skill
  基线开销 = 系统提示 (~2K) + 元数据 (10 × 80 = 800) ≈ 3K tokens
  激活 1 个后 = 3K + skill_body (~2K) ≈ 5K tokens

skill-name/                         # Skill 根目录
├── SKILL.md                        # ⚠️ 必须存在，必须命名为 SKILL.md
│                                   # 包含 YAML frontmatter + Markdown body
│
├── templates/                      # 可选：Prompt 模板、输出模板
│   ├── prompt.tmpl                 # 复杂 Skill 可拆分 prompt 模板
│   ├── output.json.tmpl            # 结构化输出模板
│   └── report.md.tmpl              # 报告生成模板
│
├── scripts/                        # 可选：辅助脚本（用于 hooks 或工具调用）
│   ├── analyze.sh                  # Bash 脚本
│   ├── validate.py                 # Python 脚本
│   └── helper.js                   # Node.js 脚本
│
├── assets/                         # 可选：静态资源
│   ├── icons/                      # UI 图标（未来可能支持）
│   └── examples/                   # 示例文件
│       └── sample-output.md
│
├── README.md                       # 可选：Skill 使用说明文档
│                                   # 对用户可见，不加载到 context
│
├── config.json                     # 可选：Skill 运行时配置
│                                   # 非标准字段，需在 SKILL.md 中引用
│
└── tests/                          # 可选：Skill 测试用例
    └── test-skill.sh               # 验证 Skill 行为的测试

Skill 发现优先级（同名覆盖）
─────────────────────────────────────

1. User-level    ~/.claude/skills/<name>/SKILL.md    ← 最高优先级
    ↓ 覆盖
2. Project-level .claude/skills/<name>/SKILL.md
    ↓ 覆盖  
3. Bundled       <internal>/<name>/SKILL.md          ← 最低优先级

加载时机：
• Claude Code 启动时扫描所有层级
• 按优先级合并，只保留最高优先级的定义
• 项目级 Skill 仅在该项目目录下生效
• 用户级 Skill 全局生效

.claude/
├── skills/
│   ├── security-audit/          # 安全审计
│   │   └── SKILL.md
│   │
│   ├── performance-check/       # 性能分析
│   │   └── SKILL.md
│   │
│   ├── doc-generator/           # 文档生成
│   │   ├── SKILL.md
│   │   └── templates/
│   │       └── api-doc.md.tmpl
│   │
│   └── full-review/             # 组合 Skill（调用其他 Skill）
│   │   ├── SKILL.md
│   │   └── config.json          # 定义调用顺序
│   │
│   └── shared/                  # 共享资源目录（非 Skill）
│       ├── common-prompts.md    # 被多个 Skill 引用
│       └── templates/
│
└── hooks/
    ├── pre-commit.sh            # 全局 hook，影响所有 Skill
    └── post-tool-use.sh

用户输入: /security-audit
系统行为: 立即激活 security-audit Skill，注入完整指令

# SKILL.md
name: my-skill-name    # 会变成 /my-skill-name
# 命名建议：
#   - 使用连字符分隔：code-review 而非 codeReview
#   - 语义清晰：security-audit 而非 sec-aud
#   - 避免冲突：不要与内置 Skill 重名（除非有意覆盖）

用户输入: "帮我检查这段代码有没有安全漏洞"
系统行为:
  1. 语义匹配阶段
  2. 发现 "安全漏洞" 与 security-audit Skill 的 description 高度相关
  3. 自动注入 security-audit 的完整指令
  4. 执行安全审计任务

评分公式（简化）:
  match_score =
    keyword_overlap(user_message, skill_description) × weight1
    + path_relevance(current_files, skill_paths) × weight2
    + priority_boost × weight3

  if match_score > threshold:
    activate(skill)

# 场景：用户在讨论性能优化，然后想进行安全审计
用户: "这段代码性能怎么样？"        # → 自动触发 performance-check
系统: [性能分析报告]
用户: "/security-audit"           # → 手动触发安全审计
系统: [安全审计报告]

# full-review/SILL.md
name: full-review
description: Comprehensive code review combining security and performance analysis

---
# Markdown body
执行全面代码审查流程：
1. 首先调用 /security-audit 检查安全问题
2. 然后调用 /performance-check 分析性能瓶颈
3. 综合两个结果生成最终报告

name: code-review
arguments:
  - name: scope
    description: Review scope (file|module|project)
    default: file
  - name: focus
    description: Focus areas (security|performance|style)
    default: all

---
# 用户可以这样调用：
# /code-review scope=project focus=security

用户: [打开一个包含数据库查询的 Python 文件]
用户: "帮我看看有没有 SQL 注入风险"

系统行为:
  ✓ 扫描所有 Skill 元数据
  ✓ "SQL 注入" 与 security-audit description 匹配
  ✓ 当前文件路径匹配 paths: ["**/*.py"]
  ✓ 激活 security-audit，注入完整指令
  ✓ 执行安全分析，返回结果

用户: "/simplify"

系统行为:
  ✓ 用户显式调用 simplify Skill
  ✓ 扫描当前代码变更
  ✓ 分析可简化、可复用的代码模式
  ✓ 提出重构建议或自动修复

# 场景：准备提交代码
用户: "我要提交代码了，帮我做最后的检查"

系统可能依次触发：
1. /code-review   → 检查代码质量
2. /security-audit → 安全审计（如果发现敏感操作）
3. /simplify      → 优化代码结构

最终输出：综合报告

检查项:
□ description 是否包含用户可能使用的关键词？
□ paths 是否匹配当前文件类型？
□ priority 是否设置过低？
□ 是否有更高优先级的同名 Skill 覆盖？
□ SKILL.md 文件是否放在正确的目录？

检查项:
□ name 字段是否与目录名一致？
□ 文件是否命名为 SKILL.md（必须大写）？
□ 是否放在 .claude/skills/<name>/ 或 ~/.claude/skills/<name>/？
□ 是否重启了 Claude Code？（某些情况需要重启）

行为:
  • 多个 Skill 可能同时被激活
  • 系统会按优先级排序执行
  • 或合并到一个综合响应中

最佳实践:
  • 避免创建功能重叠的 Skill
  • 或用 description 明确区分使用场景

┌─────────────────────────────────────────────────────────┐
│ Phase 1: Startup（启动时）                               │
│ ─────────────────                                     │
│ • 扫描所有 .claude/skills/ 和 ~/.claude/skills/          │
│ • 仅读取每个 SKILL.md 的 YAML frontmatter                │
│ • 注入 Context：[name, description] per skill            │
│ • Token 消耗：n 个 Skill ≈ n × (40~100) tokens          │
└─────────────────────────────────────────────────────────┘
                        │
                        ▼ 用户输入消息
┌─────────────────────────────────────────────────────────┐
│ Phase 2: Semantic Matching（语义匹配）                    │
│ ──────────────────────                                  │
│ • 将用户消息与所有 loaded description 做语义对比          │
│ • 基于 prompt classification（非 embedding），在模型侧完成  │
│ • 匹配成功的 Skill：将其 Markdown Instructions 注入 context│
│ • 未匹配的 Skill：继续休眠，零额外成本                     │
└─────────────────────────────────────────────────────────┘
                        │
                        ▼ Skill body 已注入
┌─────────────────────────────────────────────────────────┐
│ Phase 3: Execution（执行）                                │
│ ──────────────────                                      │
│ • 模型按 Skill 的 Markdown 指令执行                       │
│ • 若 context: fork → 派生子 Agent 隔离执行                 │
│ • allowedTools 生效：白名单工具免弹窗                      │
│ • hooks 按事件触发                                        │
└─────────────────────────────────────────────────────────┘

Context Window 视角
═══════════════════════════════════════════════

Phase 1          │ System Prompt
                 │ [Skill1: name="security", desc="Analyze for vulns..."]
                 │ [Skill2: name="debug",     desc="Structure debugging..."]
                 │ [Skill3: name="review",    desc="Code review for bugs..."]
                 │ ... (所有元数据紧凑排列)

Phase 2          │ System Prompt
                 │ [所有元数据...]
                 │ ╔═══════════════════════════╗
                 │ ║ ← 匹配到的 Skill Body     ║
                 │ ║ "你是一个安全审计助手..."   ║    ← 动态插入
                 │ ╚═══════════════════════════╝

Phase 3          │ System Prompt
                 │ [所有元数据...]
                 │ [Skill Body...]
                 │ User: "帮我看看这段代码有没有 SQL 注入"
                 │ → 模型按指令执行 → Tool Use → Response

# 技巧 1：把通用逻辑放 body，专用细节放 hooks
# （hook 只在特定事件才注入）

# 技巧 2：用 model 字段分层
# 简单验证用 haiku（便宜快），深度分析用 opus（贵但准）

# 技巧 3：用 priority 控制匹配积极性
# 高频场景设 high，低频场景省略

# 技巧 4：用 paths 限定触发范围
# 只对特定文件类型激活，减少误匹配