Agent Skills on KnightLi的博客

Scientific Agent Skills：把科研工作流交给 AI Agent 的技能库

Sun, 17 May 2026 17:52:04 +0800

K-Dense-AI/scientific-agent-skills 是一个面向科研和研究工作的 Agent Skills 集合。

它的定位不是再做一个聊天机器人，而是把科研里经常要查文档、连数据库、写分析脚本、处理文件、生成图表和整理报告的流程，拆成一组可以被 AI Agent 发现和调用的技能。

项目地址：https://github.com/K-Dense-AI/scientific-agent-skills

截至 2026-05-17 写作时，GitHub API 显示这个仓库约有 23.4k stars、2.5k forks，许可证为 MIT，最近一次推送时间是 2026-05-11。README 里写的是 135 个 ready-to-use scientific and research skills，不过仓库 scientific-skills 目录当前通过 GitHub API 能看到 137 个条目。这个差异可能来自统计口径、近期新增目录或 README 尚未同步更新。

先说结论

Scientific Agent Skills 适合已经在用 Codex、Claude Code、Cursor、Gemini CLI 或其他支持 Agent Skills 标准工具的人。

它的价值主要在三点：

把科研工具链的使用方式写成 SKILL.md，让 agent 不必每次从零猜库怎么用。
把常见科学数据库、Python 包、文档处理、科研写作和可视化流程整理到同一个技能集合里。
让 AI Agent 更像一个能执行科研工作流的助手，而不只是回答概念问题。

但它也不是“装上就自动做科研”的魔法按钮。技能可以让 agent 更容易找到正确工具、生成更靠谱的代码和流程，但数据质量、实验设计、统计假设、临床或科研结论仍然需要人来判断。

它包含什么

README 把这个项目描述为一个覆盖科研、科学计算、工程、分析、金融和写作任务的技能集合。大类包括：

生物信息学与基因组学
化学信息学与药物发现
蛋白质组学与质谱分析
临床研究与精准医学
医疗 AI 与临床机器学习
医学影像与数字病理
机器学习与 AI
材料科学与化学
物理与天文学
工程仿真与优化
数据分析与可视化
地理空间科学与遥感
实验室自动化
科研写作、文献综述、同行评审和引用管理

这类技能的重点不是限制 agent 只能使用某些库。README 也明确说，agent 仍然可以自己写 Python、调用任意可用 API 或包；这些技能的作用是提前提供整理过的说明、示例、最佳实践和集成路径。

换句话说，它更像“科研工具说明书 + 工作流模板 + agent 调用约定”的集合。

数据库和 Python 包覆盖

项目里最吸引科研用户的部分，是数据库和 Python 科学生态的覆盖面。

README 提到：

通过 database-lookup 统一访问 78 个公共数据库。
覆盖 PubChem、ChEMBL、UniProt、COSMIC、ClinicalTrials.gov、FRED、USPTO 等数据库。
额外包含 DepMap、Imaging Data Commons、PrimeKG、U.S. Treasury Fiscal Data、Hugging Science 等专门数据访问技能。
提供 70+ 个优化过的 Python Package Skills。

从目录看，技能名里能看到很多熟悉工具：

rdkit
scanpy
biopython
bioservices
pydeseq2
scvelo
scvi-tools
pymatgen
qiskit
pennylane
openmm
mdanalysis
scikit-learn
statsmodels
matplotlib
seaborn
networkx
sympy
pytorch-lightning
transformers
timesfm-forecasting

对普通开发者来说，这些库本身不稀奇。真正有用的是：agent 在处理具体任务时，可以读到与该库相关的使用约束、代码样例、常见流程和注意事项。这样比只靠模型参数里的旧记忆更稳。

典型场景

Scientific Agent Skills 更适合多步骤科研任务，而不是单轮问答。

比如药物发现方向，可以让 agent 查询 ChEMBL 里的 EGFR 抑制剂，用 RDKit 分析结构活性关系，再用 DiffDock 做虚拟筛选，最后搜索文献并生成报告。

单细胞分析方向，可以把 10X 数据加载到 Scanpy，做质控、整合、细胞类型识别、差异表达和通路富集。

多组学方向，可以把 RNA-seq、质谱、代谢物、蛋白互作、临床试验和统计建模串起来。

这些任务如果完全靠手写 prompt，很容易变成“agent 知道大概方向，但每一步都要你提醒”。技能库的意义，就是把这类高频路径沉淀下来，让 agent 在执行时少走弯路。

安装方式

README 推荐的标准安装方式是使用 Agent Skills 工具：

`1`	`npx skills add K-Dense-AI/scientific-agent-skills`

如果使用 GitHub CLI，并且版本为 v2.90.0+，也可以通过 gh skill 安装：

`1`	`gh skill install K-Dense-AI/scientific-agent-skills`

安装某个具体技能：

`1`	`gh skill install K-Dense-AI/scientific-agent-skills scanpy`

指定目标 agent：

gh skill install K-Dense-AI/scientific-agent-skills --agent codex
gh skill install K-Dense-AI/scientific-agent-skills --agent cursor
gh skill install K-Dense-AI/scientific-agent-skills --agent claude-code
gh skill install K-Dense-AI/scientific-agent-skills --agent gemini

如果要保证可复现，可以 pin 到 release tag 或 commit SHA：

1
2

gh skill install K-Dense-AI/scientific-agent-skills --pin v1.0.0
gh skill install K-Dense-AI/scientific-agent-skills --pin abc123def

这点对科研环境很重要。科研分析里最怕“上周能跑、这周结果变了但不知道为什么”。如果技能参与了分析流程，最好把技能版本、依赖版本和数据版本一起记录。

运行环境要求

README 给出的基本要求包括：

Python 3.11+，推荐 3.12+
uv，用于安装 Python 依赖
支持 Agent Skills 标准的客户端
macOS、Linux 或 Windows with WSL2

这里要注意 Windows 用户的实际体验。很多科学计算库在原生 Windows 下并不是不能用，但依赖链、编译工具、二进制包和路径问题更容易出意外。README 明确写 Windows with WSL2，也说明项目更偏向类 Unix 科研计算环境。

和普通 prompt 集合有什么区别

普通 prompt 集合通常只告诉模型“你应该怎么回答”。Scientific Agent Skills 更进一步：它把工具、库、数据库和流程写成 agent 可发现的技能。

这有几个实际差异：

技能可以包含结构化说明和示例代码。
技能可以围绕某个库或数据库长期维护。
agent 可以按任务选择相关技能，而不是一次性把所有规则塞进系统提示。
团队可以只安装自己需要的技能，减少上下文噪音。
技能可以跟随仓库版本管理、审计和更新。

对复杂科研任务来说，这种方式比“复制一大段万能提示词”更容易维护。模型会变，数据库会变，Python 包也会变。把这些变化沉淀在技能里，比散落在个人 prompt 文档里更可控。

安全和可信边界

这个项目的 README 把安全提醒写得很直接：Skills 可以执行代码，也会影响 coding agent 的行为。

这不是小事。科研技能可能会：

安装 Python 依赖
访问网络数据库
读写本地文件
运行分析脚本
处理敏感实验数据或临床数据
生成后续会被人引用的报告

因此不要无脑安装全部技能。更稳的做法是：

只安装当前任务需要的技能。
安装前阅读对应 SKILL.md。
检查技能会调用哪些包、API、文件和外部服务。
对社区贡献的技能额外谨慎。
在隔离环境里运行涉及数据处理和代码执行的任务。
对科研结论、临床建议和统计结果保留人工复核。

README 还提到项目会使用 Cisco AI Defense Skill Scanner 做扫描，并建议用户也可以本地扫描第三方技能。扫描不能替代人工审查，但至少说明维护者意识到技能供应链风险。

适合谁

这个项目更适合这些人：

已经在日常使用 AI coding agent。
经常处理科研数据、论文、图表和报告。
需要在 Python 科学生态里频繁切换工具。
想让 agent 执行多步骤分析，而不是只回答概念。
团队希望把科研流程沉淀成可复用技能。
想研究 Agent Skills 标准如何落地到专业领域。

暂时不太适合这些场景：

只是想让 AI 帮忙解释一篇论文。
没有本地 Python 环境或不愿意处理依赖。
对数据隐私、网络访问和代码执行边界还没有控制方案。
需要严格合规的临床或生产决策系统，但没有人工审查和验证流程。

如果只是偶尔做一次分析，直接让 agent 写脚本可能更轻。如果你经常重复类似科研流程，技能库的价值会更明显。

使用建议

不要一开始就安装整个仓库，然后把所有任务都交给 agent。

更实际的路径是：

先选一个低风险任务，比如文献整理、图表生成或公开数据探索。
只安装相关技能，比如 literature-review、scientific-writing、scanpy 或 rdkit。
让 agent 先说明计划，再执行代码。
保留输入数据、脚本、环境和技能版本。
对输出结果做人工复查。
如果流程稳定，再把它写入团队自己的 SOP 或技能。

科研 agent 的关键不是“自动化一切”，而是把重复、繁琐、容易查错文档的部分交给工具，把判断、假设和结论留给人。

小结

Scientific Agent Skills 的意义，在于把 Agent Skills 从通用编程场景推进到科研场景。

科研工作天然是多工具、多数据库、多文件、多步骤的流程。单靠聊天式 prompt，很难稳定覆盖这些细节。这个项目把常见科学库、数据源和研究流程整理成技能，让 AI Agent 更容易进入真实科研工作流。

但它越强，也越需要边界感。技能会影响 agent 行为，也可能运行代码、联网和处理文件。安装前要看清楚技能内容，运行时要隔离环境，科研结论更不能跳过人工验证。

如果你已经在用 Codex、Claude Code、Cursor 或 Gemini CLI 做科研和数据分析，Scientific Agent Skills 值得认真看一眼。哪怕不直接全量安装，它的技能拆分方式也很适合作为团队整理科研 AI 工作流的参考。

参考链接：

分享一个电商商品图抠图与标准化的 Agent Skill

Thu, 09 Apr 2026 21:43:50 +0800

product-cutout-normalize 是一个给商品图使用的 Agent Skill。

它会把原图处理成统一规格的透明底方图。默认规则是：

1024x1024 画布
透明背景
尽量完整保留主体
竖向主体自动转成横向
主体居中
主体可视宽度统一到 820px

适合电商素材、商品库和详情页图片预处理。

这个 skill 解决什么问题

很多商品图做完基础抠图后，还会有这些问题：

白边或浅灰背景残留
主体横竖方向不一致
画布大小不一致
主体大小忽大忽小
透明区域里有小噪点

这个 skill 会按固定流程处理：

用 Gemini 抠图
清理边缘浅色背景
去掉小碎片噪点
竖图转横图
按目标宽度缩放
放到统一尺寸的透明画布中央

这样导出的图片更整齐，也更适合批量使用。

适用场景

适合下面这些需求：

批量处理商品照片
统一输出透明底 PNG
统一主视觉尺寸
需要稳定、可重复的处理流程

如果你只处理少量图片，或者每张图都要单独调整布局，那它未必适合。

快速开始

最直接的运行方式：

`1`	`& ".\.venv\Scripts\python.exe" ".codex\skills\product-cutout-normalize\scripts\run_pipeline.py" "input_dir" "output_dir" --overwrite`

运行前需要：

GEMINI_API_KEY
google-genai
Pillow

安装依赖：

`1`	`.\.venv\Scripts\python.exe -m pip install google-genai pillow`

设置环境变量：

`1`	`$env:GEMINI_API_KEY="your_api_key"`

输出规则

默认输出：

透明背景 PNG
1024x1024 画布
主体宽度 820px
主体居中
小噪点会被清理

所以它不只是去背脚本，更像一个商品图整理脚本。

主要参数说明

常用参数：

--model 默认 gemini-2.5-flash-image
--canvas-size 输出方形画布尺寸，默认 1024
--target-width 主体可视宽度，默认 820
--min-component-pixels 小于这个像素数的透明碎片会被移除，默认 500
--overwrite 输出文件已存在时直接覆盖

例如：

`1`	`& ".\.venv\Scripts\python.exe" ".codex\skills\product-cutout-normalize\scripts\run_pipeline.py" ".\input" ".\output" --canvas-size 1280 --target-width 960 --overwrite`

处理流程

处理流程很简单：

用 Gemini 抠图
清理边缘浅色背景
去掉小碎片噪点
竖图转横图
按目标宽度缩放
放到统一尺寸的透明画布中央

和普通抠图脚本的区别

和普通去背脚本相比，它还会额外处理这些问题：

主体方向统一
主体尺寸统一
画布尺寸统一
小碎片噪点清理
结果更适合直接放进素材库

SKILL.md 源码

下面保留 SKILL.md 的完整源码，内容不做改动：

---
name: product-cutout-normalize
description: Run a reusable Gemini product-image pipeline that removes backgrounds, preserves the full subject, rotates tall products to a horizontal orientation, centers them on a 1024x1024 transparent canvas, and normalizes the visible subject width to 820px. Use when the user wants a repeatable cutout-and-normalize workflow for product photos or asks to batch-process product images into standardized square PNG assets.
---

# Product Cutout Normalize

Use this skill when product photos need the same deterministic finishing pipeline:

- Gemini cutout from the original photo
- border cleanup to transparent
- preserve the full subject
- rotate to horizontal when the subject is taller than it is wide
- center on a `1024x1024` transparent canvas
- normalize the visible subject width to `820px`

## Quick Start

Run the bundled script:

```powershell
& ".\.venv\Scripts\python.exe" ".codex\skills\product-cutout-normalize\scripts\run_pipeline.py" "input_dir" "output_dir" --overwrite
```

Required environment:

- `GEMINI_API_KEY`
- `google-genai`
- `Pillow`

## Workflow

1. Confirm the request matches this standard pipeline. If the user asks for a different canvas size, subject width, or layout rule, pass explicit flags instead of changing the script.
2. Run the bundled script on the input directory.
3. If a result looks misaligned, inspect the alpha bounding box and small detached artifacts first; this pipeline already removes tiny alpha components by default.
4. Report the exact input and output directories used, plus any non-default flags.

## Script

Primary entry point:

- `scripts/run_pipeline.py`

Key flags:

- `--model`: Gemini image model, default `gemini-2.5-flash-image`
- `--canvas-size`: output square size, default `1024`
- `--target-width`: visible subject width after normalization, default `820`
- `--min-component-pixels`: remove detached alpha specks smaller than this, default `500`
- `--overwrite`: replace existing outputs in the destination directory

## Repo Integration

If the current project already has [`scripts/nano_banana_cutout.py`](/c:/Work/my_shop/scripts/nano_banana_cutout.py), prefer that repo script when the user wants the same pipeline inside this repository. Use the bundled skill script when the task is cross-project reuse or when you want the workflow to stay self-contained inside the skill.

scripts/run_pipeline.py 源码

下面保留 scripts/run_pipeline.py 的完整源码，内容不做改动：

from __future__ import annotations

import argparse
import os
from collections import deque
from pathlib import Path

from PIL import Image

try:
    from google import genai
except ImportError as exc:  # pragma: no cover
    raise SystemExit(
        "Missing dependency: google-genai. Install it with "
        r"'.\.venv\Scripts\python.exe -m pip install google-genai'."
    ) from exc


PROMPT = (
    "Remove the entire background from this product photo and return only the product "
    "on a fully transparent background as a PNG. Keep the full product intact, preserve "
    "thin cable details, clean the inner loops and holes, and do not add any new objects "
    "or shadows."
)
DEFAULT_CANVAS_SIZE = 1024
DEFAULT_TARGET_WIDTH = 820
DEFAULT_MIN_COMPONENT_PIXELS = 500
SUPPORTED_EXTENSIONS = {".jpg", ".jpeg", ".png", ".webp"}


def is_light_background_pixel(r: int, g: int, b: int) -> bool:
    brightness = (r + g + b) / 3
    spread = max(r, g, b) - min(r, g, b)
    return brightness >= 170 and spread <= 35


def to_pil_image(image_obj) -> Image.Image:
    if isinstance(image_obj, Image.Image):
        return image_obj
    pil_image = getattr(image_obj, "_pil_image", None)
    if isinstance(pil_image, Image.Image):
        return pil_image
    as_pil = getattr(image_obj, "pil_image", None)
    if isinstance(as_pil, Image.Image):
        return as_pil
    raise TypeError(f"Unsupported image object type: {type(image_obj)!r}")


def make_transparent_from_borders(image: Image.Image) -> Image.Image:
    rgba = image.convert("RGBA")
    width, height = rgba.size
    pixels = rgba.load()

    visited: set[tuple[int, int]] = set()
    queue: deque[tuple[int, int]] = deque()

    def push_if_bg(x: int, y: int) -> None:
        if (x, y) in visited:
            return
        r, g, b, _ = pixels[x, y]
        if is_light_background_pixel(r, g, b):
            visited.add((x, y))
            queue.append((x, y))

    for x in range(width):
        push_if_bg(x, 0)
        push_if_bg(x, height - 1)
    for y in range(height):
        push_if_bg(0, y)
        push_if_bg(width - 1, y)

    while queue:
        x, y = queue.popleft()
        for nx, ny in ((x - 1, y), (x + 1, y), (x, y - 1), (x, y + 1)):
            if 0 <= nx < width and 0 <= ny < height:
                push_if_bg(nx, ny)

    for x, y in visited:
        pixels[x, y] = (0, 0, 0, 0)

    return rgba


def remove_small_components(image: Image.Image, min_component_pixels: int) -> Image.Image:
    if min_component_pixels <= 0:
        return image

    rgba = image.convert("RGBA")
    alpha = rgba.getchannel("A")
    width, height = rgba.size
    alpha_pixels = alpha.load()
    rgba_pixels = rgba.load()
    visited: set[tuple[int, int]] = set()

    for y in range(height):
        for x in range(width):
            if alpha_pixels[x, y] == 0 or (x, y) in visited:
                continue

            queue: deque[tuple[int, int]] = deque([(x, y)])
            visited.add((x, y))
            component: list[tuple[int, int]] = []

            while queue:
                cx, cy = queue.popleft()
                component.append((cx, cy))
                for nx, ny in ((cx - 1, cy), (cx + 1, cy), (cx, cy - 1), (cx, cy + 1)):
                    if 0 <= nx < width and 0 <= ny < height:
                        if alpha_pixels[nx, ny] == 0 or (nx, ny) in visited:
                            continue
                        visited.add((nx, ny))
                        queue.append((nx, ny))

            if len(component) < min_component_pixels:
                for px, py in component:
                    r, g, b, _ = rgba_pixels[px, py]
                    rgba_pixels[px, py] = (r, g, b, 0)

    return rgba


def normalize_product_image(
    image: Image.Image,
    canvas_size: int,
    target_width: int,
) -> Image.Image:
    rgba = image.convert("RGBA")
    bbox = rgba.getchannel("A").getbbox()
    if bbox is None:
        return Image.new("RGBA", (canvas_size, canvas_size), (0, 0, 0, 0))

    subject = rgba.crop(bbox)
    if subject.height > subject.width:
        subject = subject.rotate(-90, expand=True, resample=Image.Resampling.BICUBIC)
        rotated_bbox = subject.getchannel("A").getbbox()
        if rotated_bbox is not None:
            subject = subject.crop(rotated_bbox)

    scale = target_width / subject.width
    subject = subject.resize(
        (target_width, max(1, int(round(subject.height * scale)))),
        Image.Resampling.LANCZOS,
    )

    canvas = Image.new("RGBA", (canvas_size, canvas_size), (0, 0, 0, 0))
    offset_x = (canvas_size - subject.width) // 2
    offset_y = (canvas_size - subject.height) // 2
    canvas.alpha_composite(subject, (offset_x, offset_y))
    return canvas


def finalize_product_image(
    image: Image.Image,
    canvas_size: int,
    target_width: int,
    min_component_pixels: int,
) -> Image.Image:
    transparent = make_transparent_from_borders(image)
    cleaned = remove_small_components(transparent, min_component_pixels)
    return normalize_product_image(cleaned, canvas_size=canvas_size, target_width=target_width)


def save_first_image_part(
    response,
    dst: Path,
    canvas_size: int,
    target_width: int,
    min_component_pixels: int,
) -> None:
    parts = getattr(response, "parts", None)
    if parts is None and getattr(response, "candidates", None):
        parts = response.candidates[0].content.parts

    if not parts:
        raise RuntimeError("Model returned no content parts.")

    for part in parts:
        inline_data = getattr(part, "inline_data", None)
        if inline_data is None and isinstance(part, dict):
            inline_data = part.get("inline_data")

        if inline_data is None:
            continue

        if hasattr(part, "as_image"):
            image = to_pil_image(part.as_image())
            dst.parent.mkdir(parents=True, exist_ok=True)
            finalize_product_image(
                image,
                canvas_size=canvas_size,
                target_width=target_width,
                min_component_pixels=min_component_pixels,
            ).save(dst)
            return

        data = getattr(inline_data, "data", None)
        if data:
            dst.parent.mkdir(parents=True, exist_ok=True)
            with open(dst, "wb") as handle:
                handle.write(data)
            with Image.open(dst) as image:
                processed = finalize_product_image(
                    image,
                    canvas_size=canvas_size,
                    target_width=target_width,
                    min_component_pixels=min_component_pixels,
                )
                processed.save(dst.with_suffix(".png"))
            if dst.suffix.lower() != ".png":
                dst.unlink(missing_ok=True)
            return

    raise RuntimeError("Model returned text only and no edited image.")


def process_image(
    src: Path,
    dst: Path,
    client,
    model: str,
    canvas_size: int,
    target_width: int,
    min_component_pixels: int,
) -> None:
    with Image.open(src).convert("RGBA") as image:
        response = client.models.generate_content(
            model=model,
            contents=[PROMPT, image],
        )

    save_first_image_part(
        response,
        dst,
        canvas_size=canvas_size,
        target_width=target_width,
        min_component_pixels=min_component_pixels,
    )


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(
        description="Cut out product images with Gemini and normalize them to square transparent PNGs."
    )
    parser.add_argument("input_dir", type=Path)
    parser.add_argument("output_dir", type=Path)
    parser.add_argument("--model", default="gemini-2.5-flash-image")
    parser.add_argument("--canvas-size", type=int, default=DEFAULT_CANVAS_SIZE)
    parser.add_argument("--target-width", type=int, default=DEFAULT_TARGET_WIDTH)
    parser.add_argument("--min-component-pixels", type=int, default=DEFAULT_MIN_COMPONENT_PIXELS)
    parser.add_argument("--overwrite", action="store_true")
    return parser.parse_args()


def main() -> None:
    args = parse_args()
    api_key = os.environ.get("GEMINI_API_KEY")
    if not api_key:
        raise SystemExit("Missing GEMINI_API_KEY environment variable.")
    if not args.input_dir.is_dir():
        raise SystemExit(f"Input directory does not exist: {args.input_dir}")
    if args.canvas_size <= 0:
        raise SystemExit("--canvas-size must be positive.")
    if args.target_width <= 0 or args.target_width > args.canvas_size:
        raise SystemExit("--target-width must be positive and no larger than --canvas-size.")
    if args.min_component_pixels < 0:
        raise SystemExit("--min-component-pixels must be >= 0.")

    args.output_dir.mkdir(parents=True, exist_ok=True)
    client = genai.Client(api_key=api_key)

    for src in sorted(args.input_dir.iterdir()):
        if not src.is_file() or src.suffix.lower() not in SUPPORTED_EXTENSIONS:
            continue
        dst = args.output_dir / f"{src.stem}.png"
        if dst.exists() and not args.overwrite:
            print(f"skip {dst}")
            continue
        process_image(
            src,
            dst,
            client,
            args.model,
            canvas_size=args.canvas_size,
            target_width=args.target_width,
            min_component_pixels=args.min_component_pixels,
        )
        print(dst)


if __name__ == "__main__":
    main()

下载附件： product-cutout-normalize.7z

使用AI维护Hugo多语言博客的Agent Skill

Mon, 06 Apr 2026 10:00:00 +0800

如果你在维护 Hugo 多语言博客，经常会遇到一个高频痛点：

中文写完后，需要同步生成英文和繁体版本
三个语言文件要保持结构一致
front matter 既要翻译又要遵守 Hugo 格式

sync-post-translations 就是为这个场景设计的 Agent Skill。

这个技能解决什么问题

sync-post-translations 的定位很清晰：

以 index.zh-cn.md 为源文件
在同目录生成或更新 index.en.md、index.zh-tw.md
保持 Markdown 结构一致
对 front matter 执行明确规则（尤其是 date、slug）

适用触发词示例：

“同步翻译英文繁体”
“把这篇文章同步成英文和繁体”

技能目录结构

.\sync-post-translations\
├─ SKILL.md
└─ agents\
   └─ openai.yaml

核心代码一：SKILL.md

下面是该技能的核心规则文件：

---
name: sync-post-translations
description: 将 Hugo 文章从简体中文源文件（`index.zh-cn.md`）同步翻译为英文（`index.en.md`）和繁体中文（`index.zh-tw.md`）。当用户提出“en 繁体”“同步翻译英文繁体”或要求同时生成/更新两种语言版本且需保持 front matter 与 Markdown 结构一致时使用。
---

# 同步文章翻译

使用此技能为同一篇文章生成或更新多语言版本。

## 工作流程

1. 在目标文章目录中定位源文件 `index.zh-cn.md`。
2. 读取完整 front matter 与正文内容。
3. 在同目录创建或更新 `index.en.md` 与 `index.zh-tw.md`。
4. 确保三语结构对齐后执行 Hugo 构建检查。

## 翻译规则

1. 严格保留 `slug` 原值。
2. `date` 统一规范为 Hugo 常用带时间格式（RFC3339），示例：`2026-04-05T10:00:00+08:00`。
3. 自然翻译以下 front matter 字段：`title`、`description`、`tags`、`categories`。
4. 保持 Markdown 结构不变：标题层级、列表形态、代码块、链接与命令行示例。
5. 技术标识符保持原样：文件名、CLI 参数、模型名、设备名、URL、包名等。
6. 若 YAML 的 `title` 含有 `:`，必须加引号，避免解析报错。
7. 在不改变语义前提下，使用目标语言自然标点与表达习惯（`en`、`zh-tw`）。

## 输出约定

1. 仅在源文章同目录写入目标文件。
2. 汇报变更的文件路径。
3. 条件允许时执行 `hugo --source . --destination public`，并反馈通过/失败；失败时给出关键报错行。

## 质量标准

1. 全文术语前后一致。
2. 避免机器直译感，优先可发布文风。
3. 章节内容完整，不省略示例、注意点与总结。

核心代码二：agents/openai.yaml

这个文件定义了技能在 Agent 侧的展示和默认提示词：

interface:
  display_name: "同步文章翻译"
  short_description: "生成或更新 EN + ZH-TW 翻译稿"
  default_prompt: "使用该技能在同一 Hugo 文章目录中，从 `index.zh-cn.md` 生成或同步 `index.en.md` 与 `index.zh-tw.md`，保留 `date` 与 `slug`，保持 Markdown 结构一致，并执行 Hugo 构建校验。"

实战调用示例

1) 面向人的自然语言触发

1
2

请把 content/post/2026/04/06/index.zh-cn.md 同步翻译成英文和繁体，
要求 date 用 RFC3339，slug 不变，最后跑 hugo 校验。

2) 你应当期待的输出结果

已更新：
- content/post/2026/04/06/index.en.md
- content/post/2026/04/06/index.zh-tw.md

构建校验：
- hugo --source . --destination public
- 结果：PASS

为什么这些规则很关键

slug 保持不变，能稳定 URL 与历史外链。
date 统一 RFC3339（带时区）可避免 Hugo/主题在时间解析上的歧义。
Markdown 结构不变，能避免翻译后目录、代码块、短代码渲染错位。
技术标识符不翻译，可显著降低“命令不可用/文件名不匹配”问题。

常见坑位与规避

title 里有 : 却没加引号，YAML 会解析失败。
把 --flag、URL、包名翻译了，示例命令会直接失效。
三语标题层级不一致（如中文 ## 变成英文 ###），目录锚点会错位。
只翻译正文不处理 front matter，页面列表与 SEO 信息会异常。

分析 Anthropic 的 Agent Skill docx 功能、代码组成、使用方法与注意事项

Sat, 04 Apr 2026 11:00:00 +0800

Anthropic 的 skills/docx 本质上是一套“让 AI 更稳地处理 Word 文档”的工作规范与脚本工具集。
它不是单纯告诉模型“去写一个 .docx”，而是把 Word 文档处理拆成几条明确路径：新建文档、读取内容、编辑已有文档、处理修订、添加评论、转换格式、校验 OOXML 结构。

如果只看一句话，可以把它理解为：

让 agent 不再把 .docx 当黑盒，而是把它当成 ZIP + XML + Office 兼容性问题来处理。

这个 skill 解决什么问题

普通文本生成模型在处理 Word 文档时，常见问题有几类：

只会输出文本，不会真正生成结构正确的 .docx
修改现有文档时容易破坏 OOXML 结构
遇到批注、修订、评论线程时，不知道该改哪几个 XML
能生成文档，但在 Word、LibreOffice、Google Docs 之间兼容性不稳定
不清楚什么时候该用 pandoc，什么时候该直接解包改 XML

docx skill 的价值就在这里。它把“该怎么做”提前约束好了：

读内容时，优先用 pandoc 或解包
新建 .docx 时，优先用 docx-js
编辑现有 .docx 时，优先走“解包 -> 修改 XML -> 重新打包 -> 校验”
处理接受修订、评论、schema 校验这些细节时，用配套脚本而不是让模型硬编

这套思路非常实用，因为 Word 文档问题往往不是“文字写得对不对”，而是“文件结构是否还能被 Office 正常接受”。

目录和代码组成

这个 skill 大致可以分成四层。

1. 说明层：`SKILL.md`

SKILL.md 是整个 skill 的入口，主要做两件事：

定义触发条件
只要用户需求涉及 Word、.docx、评论、修订、目录、页码、模板、格式化文档等内容，就应该启用这个 skill。
规定工作路径
它明确写出不同任务该走哪条技术路线，而不是每次临场发挥。

从内容看，它既是“使用说明”，也是“操作规范”。
尤其有价值的是里面列出的很多 Word 兼容性规则，比如：

docx-js 默认是 A4，不是 US Letter
横向页面时宽高参数要按它的内部逻辑传
列表不能手工插入 Unicode bullet
表格宽度要同时设置 table 和 cell
图片插入时 type 不能省
生成后要做 validate

这说明作者不是只想“能生成”，而是想要“生成后能稳定打开、稳定渲染、稳定兼容”。

2. Office 包操作层：`scripts/office/*`

这一层负责把 .docx/.pptx/.xlsx 当成 Office Open XML 包来处理。

`unpack.py`

作用是把 Office 文件解包到目录中，并做几件辅助工作：

解压 ZIP 包
对 XML / .rels 做 pretty print
对 .docx 可选执行 merge_runs
对 .docx 可选执行 simplify_redlines
把智能引号转成 XML 实体，降低后续处理风险

它的设计重点不是“简单解压”，而是把文件整理成适合 agent 和人类继续编辑的状态。

`pack.py`

作用是把修改后的目录重新打包成 .docx/.pptx/.xlsx。
打包前还会做两件重要的事：

可选运行校验与自动修复
把 XML 重新压缩整理，去掉无意义空白和注释

如果提供 --original，它会结合 validator 做比对，这一点很关键。
因为很多 Word 修改不是“能压回去就算成功”，而是要确认文档结构和追踪修订语义都还成立。

`validate.py`

这是整个 skill 的质量闸门。
它支持校验：

XML 是否良构
namespace 是否正确
各类 ID 是否唯一
relationship / content type 是否匹配
是否符合 XSD schema
空白保留规则是否正确
插入、删除、评论标记是否合法

对 .docx 来说，这一步几乎是核心能力。
很多看起来“只改了一点 XML”的文档，真正问题都出在这里。

`soffice.py`

这是一个很有工程味道的小工具。
它不是简单调用 LibreOffice，而是为受限环境准备了兼容处理，自动设置 SAL_USE_VCLPLUGIN=svp，在必要时还会构造 shim 解决 AF_UNIX socket 受限的问题。

这说明 skill 的目标环境并不只是“本地桌面手工操作”，而是考虑了 agent、CI、沙箱等自动化环境。

3. Word 专项能力层：评论、修订与 redline

`comment.py`

这个脚本负责给 DOCX 添加评论。
它做的事情比“写一段 comment XML”复杂得多，因为 Word 评论不是单文件机制，而是一组部件协同：

word/comments.xml
commentsExtended.xml
commentsIds.xml
commentsExtensible.xml
document.xml 中的 comment range marker
[Content_Types].xml 与 document.xml.rels 中的关系声明

脚本里已经把这些依赖关系考虑进去了。
如果是第一次添加评论，它会自动补齐模板文件、relationship 和 content types，这能显著降低手工改 OOXML 时的出错率。

`accept_changes.py`

这个脚本的目标非常明确：接受所有修订。
实现方式不是自己硬改 XML，而是通过 LibreOffice headless + Basic macro 调 .uno:AcceptAllTrackedChanges。

这个选择很稳妥，因为“接受修订”在 Word 语义里并不只是删掉 <w:ins> / <w:del> 那么简单，直接改 XML 很容易留下边角问题。
借助 Office 引擎自身完成这一步，兼容性通常更好。

`validators/redlining.py`

这是 skill 里我觉得最值得注意的一部分。
它会把“某个作者的修订”从原始文档和修改后文档中分别剥离，再比较正文文本是否一致，用来判断修订是否被正确地包裹在 tracked changes 结构里。

换句话说，它不只是检查 XML 格式，而是在检查“你是不是按修订语义编辑了文档”。

这对 agent 特别重要，因为 AI 很容易做出这种错误：

直接改正文，但没有包进 <w:ins> / <w:del>
在别人的插入或删除结构里改坏层级
让最终文本变了，但 redline 逻辑不成立

这个 validator 就是在挡这种“表面可用、语义错误”的问题。

4. Schema 与辅助层：`schemas/`、`helpers/`、`templates/`

`schemas/`

这里放的是一整套 OOXML / ECMA / Microsoft 扩展相关的 XSD。
这意味着 skill 的校验不是拍脑袋写规则，而是尽量基于正式 schema 约束。

`helpers/`

这里主要是：

merge_runs.py
simplify_redlines.py

作用是把解包后的 Word XML 做适度清理，让结构更稳定、更容易编辑和比较。

`templates/`

这里存放评论功能依赖的 XML 模板，如：

comments.xml
commentsExtended.xml
commentsIds.xml
commentsExtensible.xml
people.xml

这类模板文件很重要，因为很多 Word 部件不是“缺了就自动补”，而是必须按 Office 能接受的格式预置。

典型使用方法

从 SKILL.md 给出的建议来看，这个 skill 最适合下面几种工作流。

场景一：读取或分析现有 DOCX

如果目标是提取内容、阅读结构、转成 Markdown，优先用：

`1`	`pandoc --track-changes=all document.docx -o output.md`

如果要看底层 XML，则用：

`1`	`python scripts/office/unpack.py document.docx unpacked/`

前者适合读内容，后者适合看结构。

场景二：新建 DOCX

skill 的建议不是手搓 OOXML，而是用 docx-js 生成：

`1`	`npm install -g docx`

然后生成文档后再校验：

`1`	`python scripts/office/validate.py doc.docx`

这条路线适合：

报告
memo
letter
有标题、目录、页脚、分页、表格的正式文档

场景三：编辑已有 DOCX

这是整个 skill 最核心的工作流：

1
2
3

python scripts/office/unpack.py document.docx unpacked/
# 修改 unpacked/ 下的 XML
python scripts/office/pack.py unpacked/ output.docx --original document.docx

这里的关键不是“修改 XML”，而是最后那步 --original。
它让系统能在回包时做 schema 和 redline 层面的验证，而不是盲目打包。

场景四：接受所有修订

`1`	`python scripts/accept_changes.py input.docx output.docx`

这一步依赖 LibreOffice。
适合用于把已审阅文档整理成“干净版本”。

场景五：添加评论

1
2

python comment.py unpacked/ 0 "Comment text"
python comment.py unpacked/ 1 "Reply text" --parent 0

这里要特别注意：脚本只是把评论内容和必要的评论部件加进去，实际还需要按注释说明，在 document.xml 中加上 comment range marker，才能把评论真正挂到对应文本范围上。

这个 skill 最值得注意的几个坑

如果只是快速浏览 SKILL.md，很容易低估其中“兼容性规则”的价值。
下面这些点尤其值得记住。

1. `.docx` 不是文本文件，而是 Office 包

最危险的误区就是把它当成“一个带格式的文本文件”。
实际上你改的可能同时涉及：

正文 XML
relationships
content types
comments / people / ids
schema 约束
修订语义

所以这个 skill 才会强调“解包 - 编辑 - 校验 - 回包”。

2. `docx-js` 能生成文档，但不保证默认参数符合你的目标

SKILL.md 里强调了很多默认值陷阱，例如：

默认纸张是 A4
横向页面宽高处理有内部逻辑
列表不能直接塞字符 bullet
表格宽度要双重声明
Google Docs 对百分比宽度兼容性差

这说明生成工具只是起点，不是最终质量保证。

3. 评论和修订都不是单点修改

无论是 comment 还是 tracked changes，都不是改一处 XML 就完事。
你需要维护多个部件之间的一致性，这也是 skill 把这些动作脚本化的原因。

4. “能打开”不等于“改对了”

一个文档能被 Word 打开，不代表结构就是对的。
很多错误只会在这些场景暴露：

再次编辑时崩
审阅模式异常
批注丢失
Google Docs 打开后布局错乱
重新接受修订时报错

因此 validate.py 和 pack.py --original 非常重要。

5. 依赖外部工具时要提前准备环境

这个 skill 依赖几类外部工具：

pandoc
LibreOffice / soffice
docx-js
Python 依赖，如 defusedxml、lxml

如果环境里缺这些工具，agent 即使知道流程，也无法完整执行。

这个 skill 适合什么，不适合什么

适合

批量生成 Word 报告
结构化生成正式文档
自动化修改 .docx
保留或处理 tracked changes
自动添加批注
把 Word 文档纳入脚本或 agent 工作流

不太适合

单纯导出 PDF 的简单场景
只需要纯文本内容，不关心 Word 格式
完全依赖手工可视化编辑的工作方式
希望零依赖、零环境准备就完成全部 Word 自动化

总结

Anthropic 的 skills/docx 强项不在“会生成 Word”，而在“知道 Word 为什么容易出问题，并提前把问题拆开处理”。
它把文档生成、底层 XML 编辑、修订语义、schema 校验、Office 兼容性这些原本很零散的知识，整理成了一条可执行的工作流。

如果你只是偶尔导出一份简单文档，它可能显得有点重。
但只要场景涉及现有 .docx 修改、评论、修订、自动化批处理或兼容性要求，这套 skill 就很有价值，因为它补上的恰恰是 AI 最容易忽略、而 Office 文档最容易翻车的那部分细节。

简单总结就是：

SKILL.md 负责告诉 agent 该走哪条路
scripts/office/* 负责解包、回包、校验和 Office 兼容
comment.py 与 accept_changes.py 负责 Word 专项能力
schemas/ 与 validators 负责把“看起来能用”提升到“结构上靠谱”

代码地址：https://github.com/anthropics/skills/tree/main/skills/docx

如何创建和使用 Skills：SKILL.md 规范与实战原则

Sat, 28 Mar 2026 16:30:00 +0800

本文聚焦两个问题：

SKILL.md 应该怎么写，结构如何设计。
如何写出高质量、可维护、可复用的 Skills。

1. SKILL.md 规范详解

SKILL.md 是一个技能的核心描述文件。它通常由两部分组成：

YAML Frontmatter：定义技能元信息。
Markdown 正文：定义执行说明与实践方法。

1.1 Frontmatter 示例

---
# === 必需字段 ===
name: skill-name
# 技能的唯一标识符，建议使用 kebab-case 命名

description: >
  简洁但精确地说明：
  1) 这个技能做什么
  2) 什么时候应该使用它
  3) 核心价值是什么
# 注意：description 通常是智能体选择技能的关键依据，必须写清楚

# === 可选字段 ===
version: 1.0.0
allowed_tools: [tool1, tool2]
required_context: [context_item1]
license: MIT
author: Your Name <email@example.com>
tags: [database, analysis, sql]
---

1.2 正文推荐结构

# 技能标题

## 概述
（技能介绍、适用场景、技术背景）

## 前置条件
（运行环境、依赖项、权限要求）

## 工作流程
（分步骤说明：输入、处理、输出）

## 最佳实践
（经验总结、注意事项、常见陷阱）

## 示例
（典型任务示例，便于快速上手）

## 故障排查
（常见问题与解决方案）

2. 编写高质量 Skills 的原则

结合官方文档与社区实践，建议遵循以下四条原则。

2.1 Description 要精准

description 是技能匹配的关键入口，建议做到：

明确适用范围，避免“帮助处理数据”这类泛化描述。
包含触发关键词，便于匹配用户意图。
说明独特价值，和其他技能形成边界。

不佳示例：

`1`	`description: 处理数据库查询`

推荐示例：

description: >
  将中文业务问题转换为 SQL 查询，并分析 MySQL employees 示例数据库。
  适用于员工信息查询、薪资统计、部门分析、职位变动历史等场景。
  当用户询问员工、薪资、部门相关数据时使用此技能。

2.2 模块化与单一职责

一个 Skill 应聚焦一个明确任务域。若一个 Skill 试图覆盖过多能力，通常会导致：

Description 变宽，匹配精度下降。
指令变长，增加上下文负担。
维护和迭代成本上升。

建议将“通用大技能”拆分为多个专用技能，例如：

mysql-employees-analysis
sales-data-analysis
user-behavior-analysis

2.3 确定性优先

对于复杂且要求精确的任务，优先“脚本执行”，不要完全依赖 LLM 文本生成。

例如在数据导出场景，与其让 LLM 直接生成 Excel 二进制内容，不如使用专用脚本处理；SKILL.md 只需说明触发条件与调用方式。

2.4 渐进式披露

将信息按重要性和频率分层，避免无效上下文占用：

SKILL.md 主体：核心工作流与常用模式
附加文档（如 advanced.md）：高级用法与边缘场景
数据文件：大型参考数据，通过脚本按需读取

总结

高质量 Skills 的目标不是“写得多”，而是“边界清晰、触发准确、执行稳定、可持续维护”。

从规范化 SKILL.md 开始，再结合单一职责与渐进式披露，你就能构建出更高效的技能体系。

什么是 Agent Skills：从设计理念到上下文优化

Sat, 28 Mar 2026 00:00:00 +0000

Agent Skills 是一种将程序性知识标准化封装的方式。简而言之，它解决的不是“有没有工具”，而是“如何把工具用对、用好”。

1. 核心设计理念

Agent Skills 的核心价值在于沉淀“方法论”：

提供领域知识，指导智能体在具体场景下如何组合与调用工具。
约束执行路径，减少试错成本，提升任务完成的一致性。
让复杂流程可复用、可迭代，逐步形成稳定 SOP。

如果把工具能力比作“硬件接口”，那么 Skills 更像“操作说明书”与“最佳实践集合”，定义的是“该怎么做”。

2. 渐进式披露：破解上下文困境

Agent Skills 最核心的创新是渐进式披露（Progressive Disclosure）：按需加载信息，避免一次性把大量内容塞进上下文窗口。

2.1 第一层：元数据（Metadata）

每个技能通常位于独立文件夹中，核心文件是 SKILL.md。该文件以 YAML Frontmatter 开头，定义技能基础信息。

智能体启动时，只读取所有技能的 Frontmatter 并注入系统提示词。根据实践经验：

单个技能元数据消耗约 100 tokens
50 个技能约消耗 5,000 tokens

2.2 第二层：技能主体（Instructions）

当某个技能被判断为与当前任务高度相关时，智能体才会读取完整 SKILL.md，加载详细指令、注意事项和示例。

这部分 token 消耗通常与技能复杂度相关，常见范围为：

1,000 到 5,000 tokens

2.3 第三层：附加资源（Scripts & References）

复杂技能可在 SKILL.md 中引用脚本、配置和参考文档，仅在需要时加载。

示例目录结构：

skills/pdf-processing/
├── SKILL.md                 # 主技能文件
├── parse_pdf.py             # PDF 解析脚本
├── forms.md                 # 表单填写指南（仅在填表任务时加载）
└── templates/
    ├── invoice.pdf
    └── report.pdf

典型调用方式：

需要解析 PDF 时，执行 parse_pdf.py
遇到填表任务时，再加载 forms.md
模板文件仅在输出特定格式文档时访问

3. 为什么这种设计有效

3.1 可扩展的知识容量

通过“脚本 + 外部文件”，技能可携带远超上下文窗口容量的知识。例如，一个数据分析技能可以附带 1GB 数据文件和查询脚本，智能体通过执行脚本访问数据，而不是把整份数据集直接塞进上下文。

3.2 更强的确定性

将复杂计算、数据转换、格式解析交给代码执行，可以显著降低 LLM 在纯文本生成中的不确定性与幻觉风险。

4. 实际效果：从 16k 到 500 Token

社区实践显示，渐进式披露能显著降低初始上下文开销：

传统 MCP 方式：直接连接包含大量工具定义的 MCP 服务，初始化约 16,000 tokens
Skills 包装后：先用轻量 Skill 作为“网关”，仅通过 Frontmatter 描述能力，初始化约 500 tokens

当任务真正需要时，再按需加载详细指令与附加资源。这样既降低了初始成本，也让对话过程中的上下文管理更精准。

总结

Agent Skills 的关键意义在于：把“工具可用”升级为“能力可复用”。通过渐进式披露，系统可以在保持能力深度的同时，显著优化 token 成本与执行稳定性。

Agent Skills on KnightLi的博客

Scientific Agent Skills：把科研工作流交给 AI Agent 的技能库

先说结论

它包含什么

数据库和 Python 包覆盖

典型场景

安装方式

运行环境要求

和普通 prompt 集合有什么区别

安全和可信边界

适合谁

使用建议

小结

分享一个电商商品图抠图与标准化的 Agent Skill

这个 skill 解决什么问题

适用场景

快速开始

输出规则

主要参数说明

处理流程

和普通抠图脚本的区别

SKILL.md 源码

scripts/run_pipeline.py 源码

使用AI维护Hugo多语言博客的Agent Skill

这个技能解决什么问题

技能目录结构

核心代码一：SKILL.md

核心代码二：agents/openai.yaml

实战调用示例

1) 面向人的自然语言触发

2) 你应当期待的输出结果

为什么这些规则很关键

常见坑位与规避

分析 Anthropic 的 Agent Skill docx 功能、代码组成、使用方法与注意事项

这个 skill 解决什么问题

目录和代码组成

1. 说明层：SKILL.md

2. Office 包操作层：scripts/office/*

unpack.py

pack.py

validate.py

soffice.py

3. Word 专项能力层：评论、修订与 redline

comment.py

accept_changes.py

validators/redlining.py

4. Schema 与辅助层：schemas/、helpers/、templates/

schemas/

helpers/

templates/

典型使用方法

场景一：读取或分析现有 DOCX

场景二：新建 DOCX

场景三：编辑已有 DOCX

场景四：接受所有修订

场景五：添加评论

这个 skill 最值得注意的几个坑

1. .docx 不是文本文件，而是 Office 包

2. docx-js 能生成文档，但不保证默认参数符合你的目标

3. 评论和修订都不是单点修改

4. “能打开”不等于“改对了”

5. 依赖外部工具时要提前准备环境

这个 skill 适合什么，不适合什么

适合

不太适合

总结

如何创建和使用 Skills：SKILL.md 规范与实战原则

1. SKILL.md 规范详解

1.1 Frontmatter 示例

1.2 正文推荐结构

2. 编写高质量 Skills 的原则

2.1 Description 要精准

2.2 模块化与单一职责

2.3 确定性优先

2.4 渐进式披露

总结

什么是 Agent Skills：从设计理念到上下文优化

1. 核心设计理念

2. 渐进式披露：破解上下文困境

2.1 第一层：元数据（Metadata）

1. 说明层：`SKILL.md`

2. Office 包操作层：`scripts/office/*`

`unpack.py`

`pack.py`

`validate.py`

`soffice.py`

`comment.py`

`accept_changes.py`

`validators/redlining.py`

4. Schema 与辅助层：`schemas/`、`helpers/`、`templates/`

`schemas/`

`helpers/`

`templates/`

1. `.docx` 不是文本文件，而是 Office 包

2. `docx-js` 能生成文档，但不保证默认参数符合你的目标