Claude Code Skill 脚本化实战：把复杂逻辑下沉到可执行脚本，设计 agent 友好的接口

flowchart TD
    A[Skill 被触发] --> B{任务复杂度?}
    B -->|"调用现成工具+几个flag"| C[第一层: one-off 命令<br/>直接写在 SKILL.md 里<br/>如 npx eslint@9 --fix .]
    B -->|"可复用逻辑、需自含依赖"| D[第二层: scripts/ 自包含脚本<br/>PEP 723 / Deno / Bun 内联依赖]
    C --> E[CLaude 执行<br/>消费 stdout]
    D --> E
    E --> F{需要深度参考?}
    F -->|是| G[第三层: references/*.md<br/>按需 Read, 不进默认上下文]
    F -->|否| H[完成]
    G --> E

## Available scripts

- **`scripts/inspect.py`** — 解析日志，按级别统计，提取 ERROR 上下文窗口
- **`scripts/burst_detect.py`** — 检测错误突发（单位时间错误数突增）

## Workflow

1. 先巡检日志，输出结构化摘要：
   ```bash
   python3 scripts/inspect.py --format json "$LOG_FILE"
   ```
2. 若摘要显示有 ERROR，再做突发检测：
   ```bash
   python3 scripts/burst_detect.py --input "$LOG_FILE" --window 60s
   ```
3. 综合两份结果，生成给人看的结论。

# /// script
# dependencies = [
#   "rich>=13.7,<14",
# ]
# ///

import sys
from rich.console import Console
from rich.table import Table

console = Console()
# ...业务逻辑...

uv run scripts/inspect.py --format json app.log

# 错误：挂起等待输入
$ python scripts/deploy.py
Target environment: _

# 正确：缺参就报清晰的错并给指引
$ python scripts/deploy.py
Error: --env is required. Options: development, staging, production.
Usage: python scripts/deploy.py --env staging --tag v1.2.3

Usage: scripts/inspect.py [OPTIONS] LOG_FILE
Parse a log file and emit a structured summary.

Options:
  --format FORMAT    Output format: json, table (default: json)
  --offset N         Skip first N findings (for pagination)
  --limit N          Cap number of findings (default: 50)
  --dry-run          Show what would be analyzed, exit 0
Examples:
  scripts/inspect.py app.log
  scripts/inspect.py --format table --offset 50 app.log

Error: --format must be one of: json, table.
       Received: "xml"

# 空格对齐——难以程序化解析
NAME          STATUS    CREATED
my-service    running   2025-01-15

# 定界——字段边界毫无歧义
{"name": "my-service", "status": "running", "created": "2025-01-15"}

sequenceDiagram
    participant A as Claude 主循环
    participant S as scripts/inspect.py
    A->>S: 读 SKILL.md，看到脚本清单
    A->>S: bash inspect.py --help（学习接口）
    S-->>A: stdout: Usage + Options
    A->>S: bash inspect.py --format json --limit 50 app.log
    S-->>S: 解析、统计（stderr 打印进度 "parsing 1.2MB…"）
    S-->>A: stdout: 干净的 JSON 数组
    S-->>A: stderr: 警告 "3 lines unparseable"
    A->>A: 用 JSON 决策（是否有 ERROR？是否要分页？）
    A->>S: bash inspect.py --offset 50 app.log（取下一页）
    S-->>A: stdout: 下一批 JSON
    Note over A,S: 数据走 stdout 可 jq 管道；诊断走 stderr 不污染数据

log-inspector/
├── SKILL.md
├── scripts/
│   └── inspect.py        # PEP 723 自包含，agentic 接口
└── references/
    └── report-schema.md  # 按需加载的字段说明

---
name: log-inspector
description: Parses a log file and emits a structured health report
  (level counts, ERROR context windows, burst detection). Use when the
  user asks to inspect, triage, or summarize a .log file, or to find
  errors/anomalies in logs. Emits JSON to stdout by default.
---

# Log Inspector

巡检一个日志文件，输出结构化健康报告。

## Available scripts

- **`scripts/inspect.py`** — 解析日志：级别计数、提取 ERROR 上下文窗口、突发检测。自包含，PEP 723 声明依赖。

## Workflow

1. 先拿总览（默认 JSON，限 50 条发现，防截断）：
   ```bash
   uv run scripts/inspect.py --format json --limit 50 "$LOG_FILE"
   ```
2. 若 JSON 里 `error_count > 0`，取下一页细查：
   ```bash
   uv run scripts/inspect.py --offset 50 --limit 50 "$LOG_FILE"
   ```
3. 字段含义见 `references/report-schema.md`（仅在需要解释字段时再读）。
4. 基于报告结论给人建议；不要复述原始日志行，只引用必要上下文窗口。

## Do NOT use when

- 用户只是想 `grep` 某个关键词——直接用 shell 即可。
- 文件不是文本日志（二进制、压缩包）——先解压/转换。

#!/usr/bin/env python3
# /// script
# requires-python = ">=3.10"
# dependencies = []
# ///
"""
Log Inspector — parse a text log and emit a structured health report.
Designed for agentic use: non-interactive, --help documented,
structured stdout, diagnostics on stderr, paginated, meaningful exit codes.
"""
import argparse
import json
import re
import sys
from collections import Counter

# 形如: 2026-06-19T10:22:31Z ERROR [auth] login failed for user=alice
LINE_RE = re.compile(
    r'^(?P<ts>\S+)\s+(?P<level>\w+)\s+(?:\[(?P<ctx>[^\]]+)\]\s+)?(?P<msg>.*)$'
)
LEVELS = {"DEBUG", "INFO", "WARN", "ERROR"}
EXIT_OK, EXIT_HAS_ERRORS, EXIT_BAD_ARGS = 0, 2, 3


def eprint(*a):  # 诊断一律走 stderr
    print(*a, file=sys.stderr)


def parse_args(argv):
    p = argparse.ArgumentParser(
        prog="scripts/inspect.py",
        description="Parse a log file and emit a structured summary.",
        epilog="Exit codes: 0 ok | 2 found errors | 3 bad arguments",
    )
    p.add_argument("log_file", help="Path to the .log file to inspect")
    p.add_argument("--format", default="json", choices=["json", "table"],
                   help="Output format (default: json)")
    p.add_argument("--offset", type=int, default=0,
                   help="Skip first N error findings (pagination)")
    p.add_argument("--limit", type=int, default=50,
                   help="Cap error findings shown (default: 50)")
    p.add_argument("--window", type=int, default=2,
                   help="Context lines around each ERROR (default: 2)")
    p.add_argument("--dry-run", action="store_true",
                   help="Show planned analysis, emit nothing, exit 0")
    return p.parse_args(argv)


def main(argv=None):
    args = parse_args(argv)
    # —— 契约 5：输入约束 ——
    if args.limit < 1:
        eprint('Error: --limit must be >= 1. Use --limit 50 for the default.')
        return EXIT_BAD_ARGS

    # —— 契约 6：输出大小可预测，默认摘要 + 分页 ——
    try:
        with open(args.log_file, "r", errors="replace") as fh:
            raw_lines = fh.readlines()
    except FileNotFoundError:
        eprint(f'Error: file not found: {args.log_file}\n'
               f'Usage: scripts/inspect.py --format json <LOG_FILE>')
        return EXIT_BAD_ARGS

    if args.dry_run:  # 契约 5：干跑
        eprint(f"[dry-run] would parse {len(raw_lines)} lines "
               f"from {args.log_file}, window={args.window}, "
               f"limit={args.limit}, offset={args.offset}")
        return EXIT_OK

    eprint(f"[progress] parsing {len(raw_lines)} lines …")

    counts = Counter()
    errors = []  # 收集带上下文的 ERROR
    for i, line in enumerate(raw_lines):
        line = line.rstrip("\n")
        m = LINE_RE.match(line)
        if not m:
            continue
        level = m.group("level").upper()
        if level not in LEVELS:
            continue
        counts[level] += 1
        if level == "ERROR":
            start = max(0, i - args.window)
            end = min(len(raw_lines), i + args.window + 1)
            errors.append({
                "ts": m.group("ts"),
                "ctx": m.group("ctx") or "",
                "msg": m.group("msg"),
                "window": raw_lines[start:end],
            })

    total = len(errors)
    paged = errors[args.offset: args.offset + args.limit]
    eprint(f"[progress] found {total} errors; "
           f"showing {len(paged)} (offset={args.offset}, limit={args.limit})")

    summary = {
        "file": args.log_file,
        "lines": len(raw_lines),
        "counts": {lvl: counts[lvl] for lvl in LEVELS},
        "error_count": total,
        "errors": paged,
        "truncated": total > args.offset + args.limit,
    }

    # —— 契约 4：结构化数据走 stdout ——
    if args.format == "json":
        print(json.dumps(summary, ensure_ascii=False))
    else:
        print(f"{'LEVEL':<8}{'COUNT':>8}")
        for lvl in LEVELS:
            print(f"{lvl:<8}{counts[lvl]:>8}")

    # —— 契约 5：有意义的退出码 ——
    return EXIT_HAS_ERRORS if total > 0 else EXIT_OK


if __name__ == "__main__":
    sys.exit(main())

# Report field schema

- `counts`: 各级别行数（DEBUG/INFO/WARN/ERROR）
- `error_count`: ERROR 总数（未受 offset/limit 影响）
- `errors[]`: 当前页的 ERROR，每条含 `ts`、`ctx`（方括号标签）、`msg`、`window`（上下文行）
- `truncated`: true 表示还有更多未展示，应用 `--offset` 续取

$ uv run scripts/inspect.py --help          # 学习接口
$ uv run scripts/inspect.py --dry-run app.log   # 干跑预览
[progress] would parse 1240 lines from app.log, window=2, limit=50, offset=0

$ uv run scripts/inspect.py --format json app.log   # 正式巡检
[progress] parsing 1240 lines …
[progress] found 7 errors; showing 7 (offset=0, limit=50)
{"file":"app.log","lines":1240,"counts":{"DEBUG":...,"ERROR":7},...,"truncated":false}

$ echo $?     # 退出码 2 = 有错误（agent 可据此分支）
2

$ uv run scripts/inspect.py app.log | jq '.error_count'   # 结构化可入管道
7

/plugin marketplace add anthropics/skills
/plugin install example-skills@anthropic-agent-skills