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 是入口，主要做兩件事：

定義觸發條件
只要需求涉及 Word、.docx、評論、修訂、目錄、頁碼、模板、格式化文件等內容，就應啟用這個 skill。
規定工作路徑
明確指定不同任務要走哪條技術路線，而不是每次臨場發揮。

它同時是使用說明與操作規範。裡面最有價值的是相容性規則，例如：

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 限制。

這代表它考慮的不是只有本機手動場景，也包含 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`

這是我認為很關鍵的一段。
它會把「某作者的修訂」分別從原始文件與修改後文件中剝離，再比較正文文字是否一致，以判斷修訂是否被正確包在 tracked changes 結構裡。

也就是說，它不只驗 XML 格式，而是在驗「是否按修訂語義編輯」。

這對 agent 特別重要，因為 AI 常見錯誤是：

直接改正文，沒包進 <w:ins> / <w:del>
在別人的插入或刪除結構裡改壞層級
最終文字改了，但 redline 語義不成立

這個 validator 就是在擋這類「看似可用、其實語義錯誤」的問題。

4. Schema 與輔助層：`schemas/`、`helpers/`、`templates/`

`schemas/`

這裡放的是一整套 OOXML / ECMA / Microsoft 擴展相關 XSD。
代表校驗規則盡量基於正式 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 建議用 docx-js 生成，而不是手搓 OOXML：

`1`	`npm install -g docx`

生成後再校驗：

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

適合報告、memo、letter，以及含標題、目錄、頁腳、分頁、表格的正式文件。

場景三：編輯既有 DOCX

這是最核心的流程：

1
2
3

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

重點在 --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 就結束。
需要維護多部件一致性，這正是腳本化的價值。

4.「能開啟」不等於「改對了」

文件能被 Word 開啟，不代表結構正確。
很多問題會在再次編輯、審閱模式、批註顯示、Google Docs 開啟、重新接受修訂時才暴露。

因此 validate.py 和 pack.py --original 非常關鍵。

5. 依賴外部工具時要先備好環境

這個 skill 依賴：

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

如果環境缺工具，即使流程正確也無法完整執行。

這個 skill 適合什麼，不適合什麼

適合

批量生成 Word 報告
結構化產生正式文件
自動化修改 .docx
保留或處理 tracked changes
自動加入批註
把 Word 文件納入腳本或 agent 工作流

不太適合

只做簡單 PDF 導出
只要純文字內容，不在意 Word 格式
完全依賴手動可視化編輯
期待零依賴、零環境準備完成全部 Word 自動化

總結

Anthropic 的 skills/docx 強項不在「會生成 Word」，而在「知道 Word 為什麼容易出問題，並先把問題拆開處理」。
它把文件生成、底層 XML 編輯、修訂語義、schema 校驗、Office 相容性等原本零散的知識，整理成一條可執行工作流。

若只是偶爾導出簡單文件，它可能略重；
但只要場景涉及既有 .docx 修改、評論、修訂、自動化批處理或相容性要求，這套 skill 的價值就很高，因為它補上的正是 AI 最容易忽略、也是 Office 文件最容易翻車的細節。

簡單總結：

SKILL.md 負責定義路徑
scripts/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` 能生成，不代表預設值符合你的目標