Skills脚本封装术：从Shell到智能Skill

传统脚本调用：  ./deploy.sh --env staging --skip-tests
Skill调用：     /deploy 到staging环境，跳过测试

my-deploy-skill/
├── SKILL.md              # 指令入口（必需）
├── scripts/
│   ├── deploy.sh         # 部署脚本
│   ├── rollback.sh       # 回滚脚本
│   └── health-check.py   # 健康检查脚本
└── templates/
    └── config.yaml       # 配置模板（可选）

#!/bin/bash
# deploy.sh - 原始脚本
set -euo pipefail

ENV=${1:-staging}
VERSION=${2:-latest}
SKIP_TESTS=${SKIP_TESTS:-false}

echo "Deploying version $VERSION to $ENV..."

# 构建Docker镜像
docker build -t myapp:$VERSION .
docker tag myapp:$VERSION registry.example.com/myapp:$VERSION
docker push registry.example.com/myapp:$VERSION

# 部署到K8s
kubectl set image deployment/myapp \
  myapp=registry.example.com/myapp:$VERSION \
  -n $ENV

# 等待滚动更新完成
kubectl rollout status deployment/myapp -n $ENV --timeout=300s

echo "Deployment complete: $ENV/$VERSION"

mkdir -p ~/.claude/skills/deploy-tool/scripts
mkdir -p ~/.claude/skills/deploy-tool/templates

#!/bin/bash
# scripts/deploy.sh - 封装版
set -euo pipefail

ENV=${1:-staging}
VERSION=${2:-latest}
SKIP_TESTS=${3:-false}

# ===SKILL_OUTPUT_START===
echo "::deploy::phase=build"
docker build -t myapp:$VERSION . 2>&1 | tail -1
echo "::deploy::phase=push"
docker push registry.example.com/myapp:$VERSION 2>&1 | tail -1
echo "::deploy::phase=rollout"
kubectl set image deployment/myapp \
  myapp=registry.example.com/myapp:$VERSION \
  -n $ENV
kubectl rollout status deployment/myapp -n $ENV --timeout=300s
# ===SKILL_OUTPUT_END===

echo "DEPLOY_SUCCESS env=$ENV version=$VERSION"

on_error() {
  echo "DEPLOY_FAILED phase=$PHASE message='$BASH_COMMAND'"
  exit 1
}
trap on_error ERR

---
name: deploy-tool
description: |
  部署工具：将应用部署到指定K8s环境。
  当用户提到部署、deploy、发布、上线、滚动更新时使用此Skill。
  支持staging/production环境，可指定版本号。
allowed-tools: Bash(bash:docker), Bash(bash:kubectl), Bash(bash:scripts/*), Read, Glob
---

# 部署工具 Skill

## 触发条件

当用户要求执行以下操作时激活此Skill：
- 部署应用 / deploy
- 发布新版本 / release
- 滚动更新 / rollout
- 回滚 / rollback

## 执行流程

### 1. 预检

在执行部署前，必须完成以下检查：

1. 读取项目根目录的`docker-compose.yml`或`Dockerfile`，确认构建配置存在
2. 检查当前git分支和状态：运行`git status`确认没有未提交的变更
3. 如果用户未指定版本号，从`package.json`或`Cargo.toml`获取当前版本

### 2. 参数解析

从用户消息中提取以下参数：

| 参数 | 来源 | 默认值 | 校验规则 |
|------|------|--------|----------|
| ENV | 用户指定或"环境" | staging | 必须是staging/production之一 |
| VERSION | 用户指定或"版本" | package.json中的版本 | 符合semver格式 |
| SKIP_TESTS | 用户说"跳过测试"时为true | false | 布尔值 |

### 3. 执行部署

运行部署脚本：

\`\`\`bash
bash ~/.claude/skills/deploy-tool/scripts/deploy.sh "$ENV" "$VERSION" "$SKIP_TESTS"
\`\`\`

### 4. 结果解析

根据脚本输出判断结果：
- 看到`DEPLOY_SUCCESS`：向用户确认部署成功，报告环境和版本
- 看到`DEPLOY_FAILED`：分析失败阶段和原因，提供修复建议
- 看到超时：建议检查集群状态或增加超时时间

### 5. 回滚（条件触发）

如果部署失败且用户要求回滚：

\`\`\`bash
bash ~/.claude/skills/deploy-tool/scripts/rollback.sh "$ENV"
\`\`\`

## 约束

- 永远不要在没有用户确认的情况下部署到production环境
- 部署前必须通过预检步骤
- 如果Docker构建失败，不要重试，而是分析错误日志给出修复建议

#!/usr/bin/env python3
"""scripts/health-check.py - 部署后健康检查"""
import sys
import subprocess
import json
import time

def check_deployment(env, timeout=120):
    """等待Deployment就绪并检查健康状态"""
    start = time.time()
    while time.time() - start < timeout:
        result = subprocess.run(
            ["kubectl", "get", "pods", "-n", env,
             "-l", "app=myapp", "-o", "json"],
            capture_output=True, text=True
        )
        pods = json.loads(result.stdout)
        all_ready = all(
            p["status"]["phase"] == "Running"
            and any(
                c["ready"]
                for c in p["status"].get("containerStatuses", [])
            )
            for p in pods.get("items", [])
        )
        if all_ready and pods.get("items"):
            print(f"HEALTH_CHECK_PASSED pods={len(pods['items'])} env={env}")
            return 0
        time.sleep(5)

    print(f"HEALTH_CHECK_FAILED env={env} timeout={timeout}s")
    return 1

if __name__ == "__main__":
    env = sys.argv[1] if len(sys.argv) > 1 else "staging"
    sys.exit(check_deployment(env))

### 4.1 部署后健康检查

部署成功后自动执行：

\`\`\`bash
python3 ~/.claude/skills/deploy-tool/scripts/health-check.py "$ENV"
\`\`\`

如果健康检查失败，自动建议回滚。

/deploy 到staging环境

## 测试模式

当用户说"测试deploy skill"时：

1. 使用`staging`环境和`test-0.0.1`版本号
2. 设置`SKIP_TESTS=true`加速测试
3. 验证脚本能正常运行到完成
4. 不执行实际的docker push和kubectl操作

DRY_RUN=${DRY_RUN:-false}

if [[ "$DRY_RUN" == "true" ]]; then
  echo "[DRY RUN] Would deploy version $VERSION to $ENV"
  echo "DEPLOY_SUCCESS env=$ENV version=$VERSION (dry-run)"
  exit 0
fi

用户意图 → Claude解析参数 → 直接执行脚本 → 解析输出

# SKILL.md frontmatter 示例
---
name: db-backup
description: 数据库备份工具。当用户提到备份数据库时使用。
allowed-tools: Bash(bash:scripts/*), Bash(bash:pg_dump), Bash(bash:aws), Read
---

用户意图 → Claude拆解为多步骤 → 逐步执行脚本1,2,3... → 汇总结果

## 执行流程

1. 预检：`bash scripts/pre-check.sh`
2. 准备：`bash scripts/prepare.sh "$ENV"`
3. 执行：`bash scripts/deploy.sh "$ENV" "$VERSION"`
4. 验证：`python3 scripts/health-check.py "$ENV"`
5. 通知：`bash scripts/notify.sh "$RESULT"`

如果任何步骤失败，执行回滚：`bash scripts/rollback.sh "$ENV"`

用户意图 → Claude分析代码 → 生成脚本参数 → 执行脚本 → Claude分析结果 → 自主决策

## 执行流程

1. 使用Read工具读取项目的`go.mod`或`package.json`，识别项目类型
2. 使用Glob工具查找所有源代码文件
3. 根据项目类型选择对应的检查脚本：
   - Go项目：`bash scripts/go-lint.sh "$PROJECT_DIR"`
   - Node项目：`bash scripts/node-lint.sh "$PROJECT_DIR"`
   - Python项目：`bash scripts/python-lint.sh "$PROJECT_DIR"`
4. 分析脚本输出，按严重程度分类（error/warning/info）
5. 对于error级别问题，直接使用Edit工具修复
6. 对于warning级别问题，列出清单由用户决定

┌─────────────────────────────────────────────┐
│  用户消息                                     │
│  "部署v2.1到staging，跳过测试"                 │
└──────────────┬──────────────────────────────┘
               │ Claude解析
               ▼
┌─────────────────────────────────────────────┐
│  SKILL.md 指令层                              │
│  参数映射规则：                                │
│  v2.1 → VERSION                               │
│  staging → ENV                                │
│  跳过测试 → SKIP_TESTS=true                   │
└──────────────┬──────────────────────────────┘
               │ 命令行参数
               ▼
┌─────────────────────────────────────────────┐
│  scripts/deploy.sh "$ENV" "$VERSION" ...     │
└──────────────┬──────────────────────────────┘
               │ 环境变量
               ▼
┌─────────────────────────────────────────────┐
│  脚本内部通过 $ENV/$VERSION/$SKIP_TESTS 访问   │
└─────────────────────────────────────────────┘

运行以下命令，替换参数值：
bash scripts/deploy.sh "<ENV>" "<VERSION>"

## 环境要求

此脚本需要以下环境变量：
- `REGISTRY_URL`：Docker Registry地址
- `KUBECONFIG`：K8s配置文件路径
- `SLACK_WEBHOOK`：通知Webhook（可选）

如果用户未提供，从项目根目录的`.env.deploy`文件读取。
如果文件不存在，提示用户创建。

# templates/deploy-config.yaml
env: staging
version: ""  # 从package.json填充
registry: registry.example.com
namespace: default
replicas: 3
resources:
  limits:
    cpu: "1"
    memory: "512Mi"

1. 复制`templates/deploy-config.yaml`到项目根目录
2. 根据用户要求修改配置值
3. 运行`bash scripts/deploy.sh --config deploy-config.yaml`

# 好的做法：精确声明需要的命令
allowed-tools: Bash(bash:docker build*), Bash(bash:docker push*), Bash(bash:kubectl apply*), Bash(bash:kubectl rollout*), Read

# 危险的做法：给予所有Bash权限
allowed-tools: Bash

# 更危险的做法：给予所有Bash权限且绕过确认
allowed-tools: Bash, Edit, Write

---
name: production-deploy
description: 生产环境部署工具
allowed-tools: Bash(bash:scripts/*), Read
disable-mcp: true
---

#!/bin/bash
# scripts/deploy.sh 中的安全检查

if [[ "$ENV" == "production" ]]; then
  # 生产环境需要二次确认
  echo "::CONFIRM_REQUIRED:: 正在部署到PRODUCTION环境，版本=$VERSION"
  echo "请在Claude Code中确认此操作。"
fi

# 防止误删
if [[ "$ACTION" == "delete" && -z "$CONFIRM_DELETE" ]]; then
  echo "ERROR: 删除操作需要设置CONFIRM_DELETE=true"
  exit 1
fi

#!/bin/bash
# analyze-logs.sh - 分析Nginx访问日志
LOG_FILE=${1:-/var/log/nginx/access.log}
TOP_N=${2:-10}

echo "=== 日志分析报告 ==="
echo "文件: $LOG_FILE"
echo ""

echo "--- Top ${TOP_N} 访问IP ---"
awk '{print $1}' "$LOG_FILE" | sort | uniq -c | sort -rn | head -"$TOP_N"

echo ""
echo "--- Top ${TOP_N} 访问路径 ---"
awk '{print $7}' "$LOG_FILE" | sort | uniq -c | sort -rn | head -"$TOP_N"

echo ""
echo "--- 状态码分布 ---"
awk '{print $9}' "$LOG_FILE" | sort | uniq -c | sort -rn

echo ""
echo "--- 错误请求 (4xx/5xx) ---"
awk '$9 >= 400 {print $9, $7, $1}' "$LOG_FILE" | head -20

log-analyzer/
├── SKILL.md
├── scripts/
│   ├── analyze-logs.sh
│   ├── analyze-errors.py
│   └── generate-report.py
└── templates/
    └── report-template.md

---
name: log-analyzer
description: |
  Nginx日志分析工具。当用户提到分析日志、查看访问统计、
  排查错误请求、日志报告时使用。
  支持访问IP统计、路径分析、状态码分布、错误请求筛选。
allowed-tools: Bash(bash:scripts/*), Bash(bash:awk), Bash(bash:sort), Bash(bash:head), Read, Glob
---

# 日志分析工具

## 触发条件

- "分析日志" / "分析访问日志" / "log analysis"
- "查看访问统计" / "哪些IP访问最多"
- "排查错误请求" / "4xx/5xx错误"
- "生成日志报告"

## 参数提取

| 参数 | 来源 | 默认值 |
|------|------|--------|
| LOG_FILE | 用户指定路径，或搜索项目中的`*.log`文件 | 自动发现 |
| TOP_N | 用户指定"前N个" | 10 |
| FOCUS | "错误"→errors, "IP"→ips, "路径"→paths, 空→all | all |

## 执行步骤

### 1. 定位日志文件

如果用户未指定日志文件路径：

1. 在项目目录中使用Glob搜索`**/*.log`
2. 搜索`/var/log/nginx/access.log`
3. 如果找不到，提示用户指定路径

### 2. 运行分析

根据FOCUS参数选择性执行：

**全量分析**（默认）：

\`\`\`bash
bash scripts/analyze-logs.sh "$LOG_FILE" "$TOP_N"
\`\`\`

**仅错误分析**：

\`\`\`bash
python3 scripts/analyze-errors.py "$LOG_FILE" --top "$TOP_N"
\`\`\`

### 3. 生成报告

如果用户要求"生成报告"：

\`\`\`bash
python3 scripts/generate-report.py "$LOG_FILE" --output log-report.md
\`\`\`

## 输出格式化

将脚本输出格式化为易读的分析报告：
- 使用表格展示Top N数据
- 高亮4xx/5xx错误
- 如果错误率超过5%，主动建议排查方向

#!/usr/bin/env python3
"""scripts/analyze-errors.py - 深度错误分析"""
import sys
import re
from collections import Counter, defaultdict

def analyze_errors(log_file, top_n=10):
    error_patterns = defaultdict(list)
    status_counter = Counter()
    error_ips = Counter()

    pattern = re.compile(
        r'(?P<ip>\S+) \S+ \S+ \[(?P<time>[^\]]+)\] '
        r'"(?P<method>\S+) (?P<path>\S+) \S+" '
        r'(?P<status>\d+) (?P<size>\S+)'
    )

    with open(log_file) as f:
        for line in f:
            m = pattern.match(line)
            if not m:
                continue
            status = int(m.group('status'))
            if status >= 400:
                status_counter[status] += 1
                error_ips[m.group('ip')] += 1
                error_patterns[m.group('path')].append({
                    'status': status,
                    'ip': m.group('ip'),
                    'time': m.group('time')
                })

    print(f"ERROR_SUMMARY total_errors={sum(status_counter.values())}")
    print(f"ERROR_RATE={sum(status_counter.values())} errors")

    print("\n## 状态码分布")
    for status, count in status_counter.most_common(top_n):
        print(f"  {status}: {count}次")

    print(f"\n## 高频错误IP (Top {top_n})")
    for ip, count in error_ips.most_common(top_n):
        print(f"  {ip}: {count}次错误")

    print(f"\n## 高频错误路径")
    for path, errors in sorted(
        error_patterns.items(),
        key=lambda x: len(x[1]),
        reverse=True
    )[:top_n]:
        print(f"  {path}: {len(errors)}次错误")

if __name__ == "__main__":
    log_file = sys.argv[1] if len(sys.argv) > 1 else "/var/log/nginx/access.log"
    top_n = int(sys.argv[3]) if len(sys.argv) > 3 else 10
    analyze_errors(log_file, top_n)

> 分析项目日志中的错误请求

[Claude执行步骤]
1. 搜索日志文件 → 发现 logs/access.log
2. 运行 python3 scripts/analyze-errors.py logs/access.log --top 10
3. 解析输出并格式化报告

┌──────────────────────────────────────┐
│ 日志错误分析报告                        │
├──────────────────────────────────────┤
│ 总错误数: 347                         │
│ 错误率: 2.3%                          │
│                                      │
│ 状态码分布:                           │
│   404: 198次 (57%)                   │
│   500: 89次 (26%)                    │
│   403: 60次 (17%)                    │
│                                      │
│ ⚠️ 500错误占比偏高，建议检查:          │
│   /api/users (32次)                   │
│   /api/orders (28次)                  │
└──────────────────────────────────────┘

建议：/api/users 的500错误集中在下午2-4点，
可能是数据库连接池耗尽。建议检查该时段的DB指标。

# 创建Skill仓库
git init my-team-skills
# 将Skills放入仓库
cp -r deploy-tool my-team-skills/
cp -r log-analyzer my-team-skills/

# 在项目中引用
cd my-project
git submodule add [email protected]:team/my-team-skills.git .claude/skills/team

# install-team-skills.sh
SKILLS_REPO="[email protected]:team/my-team-skills.git"
INSTALL_DIR="$HOME/.claude/skills"

git clone --depth 1 "$SKILLS_REPO" /tmp/team-skills
cp -r /tmp/team-skills/* "$INSTALL_DIR/"
rm -rf /tmp/team-skills

echo "已安装以下Skills:"
ls "$INSTALL_DIR"

# 从Registry安装（示例）
claude skill install @team/deploy-tool@^1.0

❌ 错误：bash /Users/john/.claude/skills/deploy/scripts/deploy.sh
✅ 正确：bash scripts/deploy.sh（相对于Skill目录）

# 每个关键步骤都标记
echo "::STEP::build"
docker build . || { echo "STEP_FAILED step=build"; exit 1; }
echo "::STEP::push"
docker push myapp:latest || { echo "STEP_FAILED step=push"; exit 1; }
echo "ALL_STEPS_PASSED"

# 这等于给了Skill无限制的Shell权限
allowed-tools: Bash

# 应该精确到具体命令
allowed-tools: Bash(bash:docker*), Bash(bash:kubectl*), Bash(bash:scripts/*)

# macOS的date和Linux的date参数不同
# 统一使用Python处理日期
DATE=$(python3 -c "from datetime import datetime; print(datetime.now().strftime('%Y%m%d'))")

flowchart TD
    A[现有脚本/工具] --> B{分析输入输出边界}
    B --> C[创建Skill目录结构]
    C --> D[放入scripts/目录]
    D --> E[编写SKILL.md frontmatter]
    E --> F[配置allowed-tools权限]
    F --> G[编写核心指令]
    G --> H[添加参数传递规则]
    H --> I[本地测试]
    I --> J{测试通过?}
    J -- 否 --> K[分析Claude执行日志]
    K --> L[调整指令/脚本]
    L --> I
    J -- 是 --> M{团队分发?}
    M -- 否 --> N[个人使用]
    M -- 是 --> O[推送到Git仓库]
    O --> P[Git Submodule / 安装脚本 / Registry]
    P --> Q[团队安装使用]

    style A fill:#e1f5fe
    style G fill:#fff3e0
    style I fill:#e8f5e9
    style Q fill:#fce4ec

flowchart LR
    subgraph 封装模式
        direction TB
        M1[纯封装型<br/>直接调用脚本]
        M2[编排型<br/>多脚本串联]
        M3[增强型<br/>Claude+脚本协作]
    end

    subgraph 参数通道
        direction TB
        C1[命令行参数<br/>最直接]
        C2[环境变量<br/>敏感信息]
        C3[配置文件<br/>复杂参数集]
    end

    M1 --> C1
    M2 --> C1
    M2 --> C2
    M3 --> C1
    M3 --> C3