形态一：单文件 Skill（最常见）
├── SKILL.md

形态二：多文件 Skill（中等复杂度）
├── SKILL.md
├── references/
│   ├── api-patterns.md
│   └── troubleshooting.md
└── scripts/
    └── validate.py

形态三：编排型 Skill（最高复杂度）
├── SKILL.md（编排逻辑）
├── references/
│   ├── domain-a.md
│   ├── domain-b.md
│   └── domain-c.md
├── scripts/
│   ├── setup.sh
│   └── transform.py
└── templates/
    └── output-template.txt

flowchart TD
    A[用户发送请求] --> B{Claude扫描所有Skill元数据}
    B -->|匹配description| C[加载L2: SKILL.md正文]
    B -->|不匹配| D[跳过该Skill]
    C --> E{正文引用了附属文件?}
    E -->|是| F[按需加载L3: references/scripts]
    E -->|否| G[直接执行指令]
    F --> G

---
# === 身份与发现 ===
name: my-skill                    # 标识符。小写字母+数字+连字符，≤64字符
description: 做什么+何时用          # ★最关键字段。Claude凭此判断是否触发
argument-hint: "[issue-number]"   # 自动补全时显示的参数提示

# === 调用控制 ===
disable-model-invocation: true    # 禁止Claude自动调用，仅用户可/skill-name触发
user-invocable: false             # 从/菜单隐藏，仅Claude内部调用

# === 执行上下文 ===
context: fork                     # 在隔离子代理中运行
agent: Explore                    # context:fork时使用的子代理类型
model: sonnet                     # 激活时覆盖模型选择
effort: high                      # low|medium|high|max

# === 权限与工具 ===
allowed-tools: Read, Grep, Glob   # 工具白名单（省略=遵循用户权限设置）

# === 路径与钩子 ===
paths: "app/**/*.rb, spec/**/*.rb" # 自动激活的文件路径glob模式
hooks:                            # 生命周期钩子
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/check.sh"
shell: bash                       # bash|powershell
---

# ❌ Claude无法判断何时该用
description: Helps with documents

# ✅ 明确做什么+列举触发场景
description: |
  从PDF提取文本和表格、填充表单、合并文档。
  当用户处理PDF文件，或提到PDF、表单、文档提取时使用。
  即使没有明确说"PDF"，只要涉及文档处理就应考虑此Skill。

# 只读审查Skill——不修改任何文件
allowed-tools: Read, Grep, Glob

# 数据分析Skill——只操作表格
allowed-tools: Read, Write, Bash

# 完全无限制——使用用户的全局权限
# （不设allowed-tools字段）

# 默认行为，不需要显式声明
---
name: code-conventions
description: 本项目编码规范参考
---

---
name: deep-research
description: 使用多源检索深度调研指定主题
context: fork
agent: Explore
---

product-analysis（Inline，编排者）
  ├─ Task agents 并行探索
  ├─ Skill('competitors-analysis', 'X') → Fork子代理
  └─ 综合所有结果

competitors-analysis（Fork，专家）
  └─ 单一聚焦任务：分析一个竞品代码库

---
name: product-analysis
description: |
  多路径并行产品分析，综合竞品调研、技术评估和用户反馈。
  当用户要求产品分析、竞品对比、市场调研时使用。
---

# 产品分析编排器

## 执行流程

1. 检测可用工具（`which codex` 等）
2. 启动 3-5 个 Task 代理并行探索
3. 可选调用 /competitors-analysis via Skill 工具
4. 综合所有结果生成报告

---
name: competitors-analysis
description: 深度分析指定竞品的技术架构与产品策略
context: fork
agent: Explore
---

# 竞品分析专家

## 执行流程

1. 使用 Glob 和 Grep 搜索相关文件
2. 读取并分析代码结构
3. 按模块输出分析结果，附具体文件引用

flowchart LR
    subgraph 主上下文
        A[product-analysis<br/>Inline编排者] --> B[Task Agent 1]
        A --> C[Task Agent 2]
        A --> D[Skill: competitors-analysis]
    end

    subgraph 隔离子代理
        D --> E[Explore子代理<br/>Fork模式]
        E --> F[Glob/Grep/Read]
    end

    B --> G[综合报告]
    C --> G
    F --> G

---
name: issue-fixer
description: 根据GitHub issue编号自动定位并修复问题
argument-hint: "[issue-number]"
---

# Issue 修复器

## 执行步骤

1. 运行 `gh issue view $ARGUMENTS[0]` 获取issue详情
2. 分析issue描述，定位相关代码文件
3. 实施修复并运行相关测试
4. 创建PR：`git commit -m "fix: resolve #$ARGUMENTS[0]"`

## Step 0: 检测环境能力
- `which docker` → 如果存在，启用容器化执行
- `ls package.json` → 如果存在，针对Node.js项目优化
- `which python3` → 如果存在，使用Python脚本辅助

# 1. 检查文件路径是否正确
# 个人Skill
ls ~/.claude/skills/my-skill/SKILL.md
# 项目Skill
ls .claude/skills/my-skill/SKILL.md

# 2. 检查YAML语法
cat SKILL.md | head -15
# 确保：第一行是---、关闭---在Markdown之前、无Tab缩进

# 3. 启动调试模式
claude --debug
# 观察Skill加载日志，查找错误信息

# 检查脚本权限
chmod +x .claude/skills/my-skill/scripts/*.py

# 检查路径格式（必须用正斜杠）
# ✅ scripts/helper.py
# ❌ scripts\helper.py

# Skill A - 明确限定范围
description: 分析Excel电子表格、创建数据透视表和图表。当处理Excel文件、电子表格、.xlsx格式数据时使用。

# Skill B - 与A完全不同的触发词
description: 分析系统日志文件和性能指标数据。用于性能监控、故障排查、系统诊断。

flowchart TD
    A[Claude未使用Skill] --> B{文件路径正确?}
    B -->|否| C[修正路径<br/>~/.claude/skills/ 或 .claude/skills/]
    B -->|是| D{YAML语法有效?}
    D -->|否| E[修复Frontmatter<br/>检查---分隔符和缩进]
    D -->|是| F{description足够具体?}
    F -->|否| G[增加触发词<br/>列举使用场景和关键词]
    F -->|是| H{与其他Skill冲突?}
    H -->|是| I[差异化description<br/>使用不重叠的触发词]
    H -->|否| J[用--debug启动<br/>查看加载日志]

{
  "test_cases": [
    {
      "prompt": "帮我审查 src/auth.ts 的安全性",
      "expected_contains": ["SQL注入", "XSS", "输入验证"],
      "expected_not_contains": ["TODO", "不确定"]
    },
    {
      "prompt": "检查最近的commit有没有安全问题",
      "expected_contains": ["敏感信息", "硬编码"],
      "expected_not_contains": ["看起来没问题"]
    }
  ]
}

# 使用Claude Code非交互模式批量测试
claude -p "使用 /security-review 审查 src/auth.ts" --allowedTools "Read,Grep,Glob" 2>&1 | tee results/test1.log
claude -p "使用 /security-review 检查最近的commit" --allowedTools "Read,Grep,Glob,Bash" 2>&1 | tee results/test2.log

flowchart LR
    A[编写测试用例] --> B[批量运行测试]
    B --> C[量化评分]
    C --> D{得分≥阈值?}
    D -->|是| E[✅ Skill可发布]
    D -->|否| F[分析失败案例]
    F --> G[修改SKILL.md]
    G --> B

cloud-deploy/
├── SKILL.md              # 工作流入口 + 平台选择逻辑
├── references/
│   ├── aws.md            # AWS部署详细步骤
│   ├── gcp.md            # GCP部署详细步骤
│   └── azure.md          # Azure部署详细步骤
├── scripts/
│   ├── preflight.sh      # 部署前检查脚本
│   └── rollback.sh       # 回滚脚本
└── templates/
    ├── dockerfile.tmpl   # Dockerfile模板
    └── ci-config.tmpl    # CI配置模板

# 云部署 Skill

## 平台选择

根据项目配置自动选择目标平台：
- 存在 `aws.tf` → 读取 [AWS部署指南](references/aws.md)
- 存在 `cloudbuild.yaml` → 读取 [GCP部署指南](references/gcp.md)
- 存在 `azure-pipelines.yml` → 读取 [Azure部署指南](references/azure.md)

## 预检查

运行部署前检查：
```bash
bash scripts/preflight.sh

Claude 只在检测到对应平台标识文件时才读取具体的参考文档，避免无谓的上下文消耗。

---

## 八、Skill 分发：从个人到团队

### 8.1 三级分发路径

| 路径 | 范围 | 方式 | 适用场景 |
|------|------|------|---------|
| 个人目录 | 仅自己 | `~/.claude/skills/` | 个人生产力工具 |
| 项目仓库 | 团队 | `.claude/skills/` + git | 项目特定工作流 |
| 插件市场 | 社区 | Plugin打包发布 | 通用工具分享 |

### 8.2 项目级分发

```bash
# 1. 在项目中创建Skill
mkdir -p .claude/skills/team-code-review
cat > .claude/skills/team-code-review/SKILL.md << 'EOF'
---
name: team-code-review
description: |
  按团队编码规范审查代码变更。
  当用户请求代码审查、PR审查、检查代码质量时使用。
---

# 团队代码审查

## 审查清单
1. 命名规范（camelCase for JS, snake_case for Python）
2. 错误处理（不允许裸catch）
3. 测试覆盖率（新增代码必须有测试）
4. 安全检查（无硬编码密钥、无SQL拼接）
EOF

# 2. 提交到git
git add .claude/skills/
git commit -m "Add team code review skill"
git push

# 3. 团队成员pull后自动可用
git pull
claude  # Skill立即可用

# 使用skill-creator打包
# 在Claude Code中执行：
/create-skill  # 按引导创建并打包

# 或手动构建插件结构
my-plugin/
├── plugin.json
├── skills/
│   └── my-skill/
│       └── SKILL.md
└── README.md

# 从GitHub安装
claude plugin marketplace add https://github.com/user/my-plugin
claude plugin install my-skill@my-plugin

security-review/
├── SKILL.md
├── references/
│   ├── security-checklist.md
│   ├── performance-patterns.md
│   └── maintainability-guide.md
└── scripts/
    └── diff-analyzer.py

---
name: security-review
description: |
  多维度代码安全审查：安全漏洞、性能瓶颈、可维护性问题。
  当用户请求代码审查、安全检查、PR审查、代码质量分析时使用。
  即使用户只说"看看这段代码"，也应考虑使用此Skill。
allowed-tools: Read, Grep, Glob, Bash
---

# 安全代码审查

## 执行流程

### Step 1: 获取变更范围
```bash
# 如果在git仓库中，获取最近的变更
git diff --name-only HEAD~1 2>/dev/null || echo "非git仓库"

**references/security-checklist.md（示例）：**

```markdown
# 安全检查清单

## 注入攻击
- [ ] SQL参数化查询检查
- [ ] 命令注入防护
- [ ] LDAP注入防护
- [ ] 模板注入检查

## 认证与授权
- [ ] 密码存储方式（bcrypt/argon2）
- [ ] Session管理
- [ ] JWT验证完整性
- [ ] CORS配置合理性

# 创建测试环境
mkdir -p /tmp/skill-test && cd /tmp/skill-test
git init

# 创建一个故意有安全问题的文件
cat > auth.ts << 'EOF'
const password = "admin123"; // 硬编码密码
const query = "SELECT * FROM users WHERE name = '" + userName + "'"; // SQL注入
eval(userInput); // 代码注入
EOF

git add . && git commit -m "add auth"

# 在Claude Code中测试
claude -p "帮我审查 auth.ts 的安全性"

❌ 错误：一个巨型Skill处理所有事情
code-review-all-in-one（安全+性能+风格+测试+部署）

✅ 正确：多个正交Skill按需组合
security-review  ← 安全维度
perf-review      ← 性能维度  
style-review     ← 代码风格
test-coverage    ← 测试覆盖
deploy-check     ← 部署前检查

## Next Step

审查完成后，建议下一步：

> 代码审查已完成。是否需要：
> A) /security-review — 对发现的安全问题深入分析（推荐）
> B) /fix-security — 自动修复发现的安全问题
> C) 结束 — 当前输出已足够

youtube-downloader → asr-transcribe → transcript-fixer → meeting-minutes → pdf-creator

## Version History
- v2.0.0 (2026-05-01): 新增多维度审查，breaking change
- v1.1.0 (2026-04-15): 增加性能检查维度
- v1.0.0 (2026-04-01): 初始版本，仅安全审查

flowchart TD
    A[需求分析] --> B[Prior Art调研<br/>8通道检索]
    B --> C{已有成熟工具?}
    C -->|是| D[采纳/扩展]
    C -->|否| E[从零构建]
    D --> F[设计架构<br/>Inline vs Fork]
    E --> F
    F --> G[编写SKILL.md<br/>+ 附属文件]
    G --> H[编写测试用例]
    H --> I[批量运行测试]
    I --> J{量化评分通过?}
    J -->|否| K[分析失败+修改]
    K --> I
    J -->|是| L[选择分发路径]
    L --> M[个人: ~/.claude/skills/]
    L --> N[团队: .claude/skills/ + git]
    L --> O[社区: Plugin打包发布]