Agent-Skills on KnightLi Blog

Scientific Agent Skills: a skill library that gives AI Agents scientific workflows

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

K-Dense-AI/scientific-agent-skills is an Agent Skills collection for scientific and research work.

Its goal is not to create yet another chatbot. Instead, it turns common research tasks such as reading documentation, querying databases, writing analysis scripts, processing files, creating charts, and preparing reports into skills that an AI Agent can discover and call.

Project: https://github.com/K-Dense-AI/scientific-agent-skills

As of 2026-05-17, the GitHub API showed about 23.4k stars, 2.5k forks, an MIT license, and a latest push time of 2026-05-11. The README says the repository contains 135 ready-to-use scientific and research skills, while the scientific-skills directory currently shows 137 entries through the GitHub API. The difference may come from counting rules, recent additions, or README lag.

Bottom line

Scientific Agent Skills is useful if you already use Codex, Claude Code, Cursor, Gemini CLI, or another tool that supports the Agent Skills standard.

Its value is mainly in three areas:

It writes scientific toolchain usage into SKILL.md, so the agent does not have to guess how a library works every time.
It organizes common scientific databases, Python packages, document processing, scientific writing, and visualization workflows into one skill collection.
It makes an AI Agent feel more like a workflow-capable research assistant, not just a concept-answering bot.

But it is not a magic button that automatically does science after installation. Skills can help an agent choose the right tools and generate more reliable code and workflows, but data quality, experimental design, statistical assumptions, clinical decisions, and research conclusions still require human judgment.

What it includes

The README describes the project as a skill collection for research, scientific computing, engineering, analysis, finance, and writing. Major areas include:

Bioinformatics and genomics.
Cheminformatics and drug discovery.
Proteomics and mass spectrometry.
Clinical research and precision medicine.
Healthcare AI and clinical machine learning.
Medical imaging and digital pathology.
Machine learning and AI.
Materials science and chemistry.
Physics and astronomy.
Engineering simulation and optimization.
Data analysis and visualization.
Geospatial science and remote sensing.
Laboratory automation.
Scientific writing, literature review, peer review, and citation management.

The point of these skills is not to limit an agent to specific libraries. The README also says the agent can still write Python and call any available API or package. The skills provide curated documentation, examples, best practices, and integration paths.

In other words, it is closer to a collection of “scientific tool manuals + workflow templates + agent calling conventions.”

Database and Python package coverage

The most attractive part for researchers is the coverage of scientific databases and the Python ecosystem.

The README mentions:

Unified access to 78 public databases through database-lookup.
Coverage of PubChem, ChEMBL, UniProt, COSMIC, ClinicalTrials.gov, FRED, USPTO, and more.
Dedicated access skills for DepMap, Imaging Data Commons, PrimeKG, U.S. Treasury Fiscal Data, Hugging Science, and others.
More than 70 optimized Python Package Skills.

The directory includes many familiar names:

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

For developers, these libraries are not surprising by themselves. What matters is that an agent can read library-specific constraints, examples, workflows, and caveats while doing a task. That is more stable than relying only on old model memory.

Typical scenarios

Scientific Agent Skills is better suited to multi-step research tasks than single-turn Q&A.

For drug discovery, an agent might query ChEMBL for EGFR inhibitors, analyze structure-activity relationships with RDKit, run virtual screening with DiffDock, search the literature, and generate a report.

For single-cell analysis, it might load 10X data into Scanpy, perform QC, integrate datasets, identify cell types, run differential expression, and do pathway enrichment.

For multi-omics, it might connect RNA-seq, mass spectrometry, metabolites, protein interactions, clinical trials, and statistical modeling.

Without skills, these tasks can easily become “the agent knows the general direction, but you have to remind it at every step.” The value of a skill library is to preserve these high-frequency paths so the agent takes fewer wrong turns.

Installation

The README recommends the standard Agent Skills tool:

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

If you use GitHub CLI v2.90.0+, you can also install with gh skill:

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

Install a specific skill:

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

Target a specific 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

For reproducibility, pin a release tag or 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

This matters in research. The worst situation is “it ran last week, the result changed this week, and nobody knows why.” If a skill participates in analysis, record the skill version, dependency versions, and data version together.

Runtime requirements

The README lists:

Python 3.11+, with 3.12+ recommended.
uv for installing Python dependencies.
A client that supports the Agent Skills standard.
macOS, Linux, or Windows with WSL2.

Windows users should pay attention to the WSL2 detail. Many scientific computing libraries can run on native Windows, but dependency chains, compilers, binary wheels, and path behavior are more likely to cause trouble. The README’s “Windows with WSL2” wording suggests a Unix-like research computing environment is the better target.

How this differs from a prompt collection

A regular prompt collection usually tells the model how to answer. Scientific Agent Skills goes further: it describes tools, libraries, databases, and workflows as discoverable skills.

The practical differences are:

A skill can contain structured instructions and example code.
A skill can be maintained around a specific library or database.
An agent can choose relevant skills by task instead of stuffing every rule into the system prompt.
A team can install only the skills it needs and reduce context noise.
Skills can be versioned, reviewed, and updated with the repository.

For complex research work, this is easier to maintain than copying one giant universal prompt. Models change, databases change, and Python packages change. Capturing those changes in skills is more controllable than scattering them across personal prompt documents.

Security and trust boundaries

The README’s security warning is direct: Skills can execute code and affect coding-agent behavior.

That matters. Research skills may:

Install Python dependencies.
Access network databases.
Read and write local files.
Run analysis scripts.
Process sensitive experimental or clinical data.
Generate reports that people may later cite.

So do not blindly install every skill. A safer approach is:

Install only the skills required for the current task.
Read the relevant SKILL.md before installation.
Check which packages, APIs, files, and external services the skill may call.
Be extra careful with community-contributed skills.
Run data-processing and code-execution tasks in an isolated environment.
Keep human review for research conclusions, clinical suggestions, and statistical results.

The README also mentions Cisco AI Defense Skill Scanner and suggests local scanning of third-party skills. Scanning does not replace human review, but it shows that the maintainers are aware of skill supply-chain risk.

Who it is for

This project is most useful for people who:

Already use AI coding agents daily.
Often process scientific data, papers, charts, and reports.
Need to move frequently across the Python scientific ecosystem.
Want an agent to execute multi-step analysis instead of just explaining concepts.
Want a team to turn research workflows into reusable skills.
Want to study how the Agent Skills standard applies to professional domains.

It is less suitable if:

You only want AI to explain a paper once in a while.
You do not have a local Python environment or do not want to manage dependencies.
You do not yet control data privacy, network access, and code-execution boundaries.
You need a strictly compliant clinical or production decision system without human review and validation.

For one-off analysis, asking the agent to write a script may be lighter. If you repeat similar research workflows often, the skill library becomes more valuable.

Usage advice

Do not start by installing the entire repository and handing every task to the agent.

A more practical path is:

Choose a low-risk task, such as literature organization, chart generation, or public-data exploration.
Install only relevant skills, such as literature-review, scientific-writing, scanpy, or rdkit.
Ask the agent to explain the plan before running code.
Preserve input data, scripts, environment, and skill versions.
Review outputs manually.
If the workflow stabilizes, write it into your team’s SOP or custom skill.

The key to a research agent is not automating everything. It is handing repetitive, tedious, documentation-heavy work to tools while leaving judgment, assumptions, and conclusions to humans.

Summary

Scientific Agent Skills matters because it pushes Agent Skills from general programming into research.

Scientific work is naturally multi-tool, multi-database, multi-file, and multi-step. Chat-style prompts alone rarely cover these details reliably. This project turns common scientific libraries, data sources, and research workflows into skills, making it easier for an AI Agent to enter real research workflows.

But the stronger it is, the more it needs boundaries. Skills can affect agent behavior, run code, access the network, and process files. Read the skill before installing it, isolate execution, and never skip human validation of research conclusions.

If you already use Codex, Claude Code, Cursor, or Gemini CLI for research and data analysis, Scientific Agent Skills is worth a careful look. Even if you do not install it wholesale, its way of splitting skills is a useful reference for building team research AI workflows.

References:

Sharing an Agent Skill for E-commerce Product Image Cutout and Standardization

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

product-cutout-normalize is an Agent Skill for product images.

It turns raw product photos into square transparent images with a consistent layout. The default rules are:

a 1024x1024 canvas
transparent background
preserve the full subject as much as possible
rotate vertical subjects to horizontal
center the subject
normalize visible subject width to 820px

It is a good fit for e-commerce assets, product libraries, and product detail page image preparation.

What this skill solves

Even after a basic cutout, product images often still have issues such as:

leftover white or light gray edges
inconsistent subject orientation
inconsistent canvas size
inconsistent subject scale
small specks in transparent regions

This skill handles them with a fixed workflow:

Use Gemini for cutout
Clean light-colored background from the borders
Remove small noise fragments
Rotate vertical images to horizontal
Scale the subject to a target width
Place it in the center of a transparent square canvas

That makes the output cleaner and more suitable for batch use.

When to use it

This is a good fit when you need to:

batch-process product photos
export transparent PNG assets
keep a consistent visual size
use a stable and repeatable workflow

If you only edit a few images or need to manually adjust each layout, this may not be the right tool.

Quick start

The most direct way to run it is:

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

Before running it, make sure you have:

GEMINI_API_KEY
google-genai
Pillow

Install dependencies:

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

Set the environment variable:

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

Output rules

The default output is:

transparent-background PNG
1024x1024 canvas
820px subject width
centered subject
small noise fragments removed

So this is more than a simple background-removal script. It is closer to a product image cleanup script.

Main parameters

Common flags:

--model Default: gemini-2.5-flash-image
--canvas-size Output square canvas size, default 1024
--target-width Visible subject width, default 820
--min-component-pixels Transparent fragments smaller than this are removed, default 500
--overwrite Overwrite existing outputs

For example:

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

Workflow

The workflow is straightforward:

Use Gemini for cutout
Clean light-colored border background
Remove small fragments
Rotate vertical images to horizontal
Scale to the target width
Place the result on a transparent square canvas

How it differs from a basic cutout script

Compared with a basic background-removal script, it also handles:

subject orientation normalization
subject size normalization
canvas size normalization
small-fragment cleanup
outputs that are easier to place directly into an asset library

SKILL.md source

The full SKILL.md source is preserved below without modification:

---
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 source

The full scripts/run_pipeline.py source is preserved below without modification:

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()

Download attachment: product-cutout-normalize.7z

Using AI Agent Skills to Maintain a Hugo Multilingual Blog

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

If you maintain a Hugo multilingual blog, you probably run into a frequent pain point:

After finishing Chinese content, you still need synchronized English and Traditional Chinese versions
All language files must keep the same structure
Front matter must be translated while still following Hugo format rules

sync-post-translations is built for exactly this scenario.

What Problem This Skill Solves

The positioning of sync-post-translations is straightforward:

Use index.zh-cn.md as the source file
Generate or update index.en.md and index.zh-tw.md in the same directory
Keep Markdown structure consistent
Apply explicit front matter rules (especially date and slug)

Example trigger phrases:

“Sync translation to English and Traditional Chinese”
“Translate this post to English and Traditional Chinese”

Skill Directory Structure

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

Core Code 1: SKILL.md

Below is the core rules file of this skill:

---
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. 章节内容完整，不省略示例、注意点与总结。

Core Code 2: agents/openai.yaml

This file defines how the skill is presented and prompted on the agent side:

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 构建校验。"

Practical Usage Example

1) Natural language trigger

1
2

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

2) Expected output

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

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

Why These Rules Matter

Keeping slug unchanged preserves stable URLs and historical backlinks.
Normalizing date to RFC3339 with timezone avoids Hugo/theme parsing ambiguity.
Keeping Markdown structure unchanged prevents TOC, code block, and shortcode rendering issues.
Not translating technical identifiers significantly reduces broken command/file mismatches.

Common Pitfalls and How to Avoid Them

If title contains : without quotes, YAML parsing can fail.
Translating --flags, URLs, or package names will break command examples.
If heading levels differ across languages (for example, ## becoming ###), anchors can become inconsistent.
Translating only body content but not front matter can break list pages and SEO metadata.

Analyzing Anthropic's docx Agent Skill: Features, Code Structure, Usage, and Caveats

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

Anthropic’s skills/docx is essentially a workflow spec plus a script toolkit for handling Word documents more reliably with AI.
It does not just tell a model to “generate a .docx.” Instead, it breaks document work into explicit paths: create, read, edit existing files, handle tracked changes, add comments, convert formats, and validate OOXML structure.

If we reduce it to one line:

It treats .docx as ZIP + XML + Office compatibility constraints, not as a black box.

What this skill solves

When general-purpose models handle Word files, we often see the same failure patterns:

They output text, but not a structurally valid .docx.
They break OOXML while editing existing documents.
They do not know which XML parts to update for comments or tracked changes.
Output opens in one app but behaves inconsistently across Word, LibreOffice, and Google Docs.
They lack clear routing for when to use pandoc vs. unpack/edit/repack.

The value of this skill is that it front-loads those decisions:

Use pandoc or unpacking for reading and analysis.
Use docx-js for creating new .docx files.
Use “unpack -> edit XML -> repack -> validate” for existing documents.
Use dedicated scripts for tracked changes/comments/schema-sensitive operations.

That approach works because Word problems are usually not about wording quality. They are about structural correctness and compatibility.

Directory and code structure

This skill can be understood in four layers.

1. Guidance layer: `SKILL.md`

SKILL.md does two important jobs:

It defines trigger conditions.
If a request mentions Word, .docx, comments, tracked changes, TOC, page numbers, or polished document formatting, this skill should be activated.
It defines execution routes.
Different task types map to different toolchains, instead of improvising every run.

It also captures practical compatibility rules, for example:

docx-js defaults to A4, not US Letter.
Landscape page sizing must follow docx-js internals.
Lists should not be built from manual Unicode bullets.
Table width needs coordinated settings at table and cell levels.
Image type is required.
Generated files should be validated.

That is a strong signal that the goal is not just “generate something,” but “generate something that is robust.”

2. Office package layer: `scripts/office/*`

This layer treats .docx/.pptx/.xlsx as Open XML packages.

`unpack.py`

This script unpacks files and prepares XML for safer editing:

Extracts ZIP package content
Pretty-prints XML and .rels
Optionally runs merge_runs for DOCX
Optionally runs simplify_redlines for DOCX
Escapes smart quotes into XML entities

So it is not just decompression. It normalizes content into an editing-friendly shape.

`pack.py`

This script repacks a directory into .docx/.pptx/.xlsx.
Before packaging, it can:

Run validation and auto-repair
Condense XML formatting safely

If --original is provided, it compares and validates against the source context.
That matters because “repacked successfully” is not equal to “semantically safe.”

`validate.py`

This is the quality gate. It checks:

XML well-formedness
Namespace correctness
Unique ID constraints
Relationship/content type consistency
XSD compliance
Whitespace preservation rules
Insertion/deletion/comment marker constraints

For DOCX work, this is a core component, not an optional extra.

`soffice.py`

This helper wraps LibreOffice execution for restricted/sandboxed environments.
It configures SAL_USE_VCLPLUGIN=svp and can apply a shim for AF_UNIX socket limitations when needed.

That tells us the skill is designed for automated agent workflows, not only local manual usage.

3. Word-specific layer: comments, revisions, and redlines

`comment.py`

This script adds comments to DOCX, including required package plumbing across multiple parts:

word/comments.xml
commentsExtended.xml
commentsIds.xml
commentsExtensible.xml
comment range markers in document.xml
declarations in [Content_Types].xml and document.xml.rels

If comment parts do not exist yet, it can initialize templates and required relationships/content types.

`accept_changes.py`

This script accepts all tracked changes via LibreOffice headless + macro (.uno:AcceptAllTrackedChanges) rather than fragile raw XML surgery.

That is a pragmatic choice because accepting revisions is a behavior-level operation, not just deleting <w:ins> / <w:del> tags.

`validators/redlining.py`

This is one of the most valuable pieces.
It removes tracked changes for a specific author in both original and modified documents, then compares resulting text to verify that changes are properly represented in revision markup.

So it validates revision semantics, not only XML syntax.

4. Schema and support layer: `schemas/`, `helpers/`, `templates/`

`schemas/`

Contains OOXML/ECMA/Microsoft-related XSD files used by validators.
Validation is therefore grounded in formal schema constraints.

`helpers/`

Includes utilities such as:

merge_runs.py
simplify_redlines.py

These stabilize XML structure for clearer edits and diffs.

`templates/`

Contains XML templates needed for comment support, including:

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

These templates help avoid package-level inconsistencies when creating comment-related parts.

Typical usage patterns

From SKILL.md, the most common workflows are:

Scenario 1: Read/analyze an existing DOCX

Use pandoc for text-level extraction with tracked changes:

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

Use unpacking for raw XML inspection:

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

Scenario 2: Create a new DOCX

Use docx-js for generation:

`1`	`npm install -g docx`

Then validate:

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

Scenario 3: Edit an existing DOCX

Core workflow:

1
2
3

python scripts/office/unpack.py document.docx unpacked/
# edit XML under unpacked/
python scripts/office/pack.py unpacked/ output.docx --original document.docx

--original is the critical part because it enables stronger structural and revision-aware checks.

Scenario 4: Accept all tracked changes

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

Requires LibreOffice; useful for producing a clean post-review file.

Scenario 5: Add comments

1
2

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

You still need to place comment range markers in document.xml where the comment should attach.

Key caveats to remember

1. `.docx` is not a plain text file

A single edit may involve body XML, relationships, content types, comment parts, IDs, and schema constraints.

2. `docx-js` generation still needs explicit guardrails

Defaults can be wrong for your target layout and compatibility goals.

3. Comments and tracked changes are multi-part operations

They are package-level features, not single-tag edits.

4. “Opens successfully” does not mean “correctly modified”

Many issues only surface later during editing, reviewing, cross-app opening, or acceptance of changes.

5. Environment readiness matters

You need tools such as pandoc, LibreOffice/soffice, docx-js, and Python deps (defusedxml, lxml) available.

What this skill is good for (and not)

Good fit

Batch Word report generation
Structured formal document production
Automated edits to existing .docx
Tracked-changes aware workflows
Automated comment insertion
Agent/script-driven document pipelines

Not ideal

Very simple PDF-only output cases
Pure text extraction with no document fidelity requirement
Fully manual visual editing workflows
Zero-dependency expectations for end-to-end Word automation

Summary

Anthropic’s skills/docx is strong not because it can “generate Word files,” but because it encodes why Word automation fails and how to handle those failure modes systematically.
It combines generation, low-level XML editing, revision semantics, schema validation, and cross-app compatibility into one executable workflow.

If your use case includes existing DOCX edits, comments, tracked changes, or compatibility-sensitive automation, this design is very practical and high value.

Code location: https://github.com/anthropics/skills/tree/main/skills/docx

How to Create and Use Skills: SKILL.md Specification and Practical Principles

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

This article focuses on two questions:

How should SKILL.md be written and structured?
How do we create high-quality, maintainable, reusable Skills?

1. SKILL.md Specification

SKILL.md is the core description file of a skill. It usually contains two parts:

YAML front matter: defines skill metadata.
Markdown body: defines execution guidance and practical workflow.

1.1 Front Matter Example

---
# === Required fields ===
name: skill-name
# Unique skill identifier; kebab-case is recommended

description: >
  Brief but precise description of:
  1) What this skill does
  2) When it should be used
  3) What its core value is
# Note: description is typically the key basis for skill selection

# === Optional fields ===
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 Recommended Body Structure

# Skill Title

## Overview
(Skill summary, use cases, technical background)

## Prerequisites
(Runtime environment, dependencies, required permissions)

## Workflow
(Step-by-step guidance: input, process, output)

## Best Practices
(Experience-based tips, caveats, common pitfalls)

## Examples
(Typical cases for faster adoption)

## Troubleshooting
(Common issues and fixes)

2. Principles for Writing High-Quality Skills

Based on official documentation and community practice, the following four principles are recommended.

2.1 Keep Description Precise

description is the key entry point for skill matching. It should:

Clearly define scope; avoid vague wording like “helps with data processing.”
Include trigger keywords to match user intent.
Explain unique value and boundaries from other skills.

Weak example:

`1`	`description: Handle database queries`

Stronger example:

description: >
  Convert Chinese business questions into SQL queries and analyze the MySQL employees sample database.
  Suitable for employee info lookup, salary statistics, department analysis, and role-change history.
  Use this skill when users ask about employee, salary, or department data.

2.2 Modular Design and Single Responsibility

A skill should focus on one clearly defined task domain. If a single skill tries to cover too much, it often leads to:

Broader descriptions and lower matching precision.
Longer instructions and heavier context load.
Higher maintenance and iteration costs.

Instead of one “general analysis” skill, split into specialized skills, for example:

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

2.3 Determinism First

For complex tasks requiring precision, prefer scripted execution over pure LLM generation.

For example, in data export scenarios, instead of generating Excel binary content directly with an LLM, use a dedicated script. SKILL.md should only define when and how to invoke it.

2.4 Progressive Disclosure

Layer information by importance and frequency to reduce unnecessary context usage:

SKILL.md body: core workflow and common patterns
Supplementary docs (for example, advanced.md): advanced usage and edge cases
Data files: large reference data accessed on demand via scripts

Summary

The goal of high-quality Skills is not writing more, but writing clearer boundaries, better triggers, stable execution, and sustainable maintenance.

Start with a standardized SKILL.md, then combine single responsibility with progressive disclosure to build a more efficient skill system.

What Is Agent Skills: From Design Principles to Context Optimization

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

Agent Skills is a standardized way to package procedural knowledge. In short, it answers not only “whether tools exist” but “how to use them correctly and effectively.”

1. Core Design Principles

The core value of Agent Skills is that it captures reusable methodology:

It provides domain knowledge to guide how agents combine and invoke tools in specific scenarios.
It constrains execution paths, reducing trial-and-error and improving consistency.
It makes complex workflows reusable and iterative, forming stable SOPs over time.

If tool capability is like a hardware interface, Skills is closer to an operations manual plus best-practice playbook, defining what should be done and how.

2. Progressive Disclosure: Solving the Context Bottleneck

The key innovation in Agent Skills is Progressive Disclosure: load information only when needed, instead of pushing everything into the context window at once.

2.1 Layer 1: Metadata

Each skill is usually stored in its own folder, with SKILL.md as the core file. This file starts with YAML front matter that defines basic skill information.

At startup, the agent reads only the front matter of all skills and injects that metadata into the system prompt. In practice:

Metadata for one skill costs about 100 tokens
50 skills cost about 5,000 tokens

2.2 Layer 2: Instructions

When a skill is judged highly relevant to the current task, the agent then reads the full SKILL.md, loading detailed instructions, notes, and examples.

Token usage at this layer depends on instruction complexity, typically:

1,000 to 5,000 tokens

2.3 Layer 3: Additional Resources (Scripts & References)

For more complex skills, SKILL.md can reference scripts, config files, and docs, which are loaded only when needed.

Example directory structure:

skills/pdf-processing/
├── SKILL.md                 # Main skill file
├── parse_pdf.py             # PDF parsing script
├── forms.md                 # Form-filling guide (loaded only for form tasks)
└── templates/
    ├── invoice.pdf
    └── report.pdf

Typical invocation pattern:

Run parse_pdf.py when PDF parsing is required
Load forms.md only for form-filling tasks
Access template files only when generating specific output formats

3. Why This Design Works

3.1 Scalable Knowledge Capacity

With scripts and external files, a skill can carry knowledge far beyond context-window limits. For example, a data-analysis skill can include a 1GB dataset plus query scripts, and the agent can access data through execution instead of loading the whole dataset into context.

3.2 Stronger Determinism

Delegating complex computation, data transformation, and format parsing to code significantly reduces uncertainty and hallucination risk in pure text generation.

4. Practical Impact: From 16k to 500 Tokens

Community practice shows that Progressive Disclosure can drastically reduce initial context overhead:

Traditional MCP approach: directly connect to an MCP server with many tool definitions, around 16,000 tokens at initialization
With Skills packaging: use a lightweight gateway skill described mainly in front matter, around 500 tokens at initialization

Detailed instructions and additional resources are loaded only when the task truly requires them. This lowers initial cost and improves context management precision during the conversation.

Summary

The key value of Agent Skills is upgrading from “tools are available” to “capabilities are reusable.” With Progressive Disclosure, systems can preserve capability depth while significantly optimizing token cost and execution stability.

Agent-Skills on KnightLi Blog

Scientific Agent Skills: a skill library that gives AI Agents scientific workflows

Bottom line

What it includes

Database and Python package coverage

Typical scenarios

Installation

Runtime requirements

How this differs from a prompt collection

Security and trust boundaries

Who it is for

Usage advice

Summary

Sharing an Agent Skill for E-commerce Product Image Cutout and Standardization

What this skill solves

When to use it

Quick start

Output rules

Main parameters

Workflow

How it differs from a basic cutout script

SKILL.md source

scripts/run_pipeline.py source

Using AI Agent Skills to Maintain a Hugo Multilingual Blog

What Problem This Skill Solves

Skill Directory Structure

Core Code 1: SKILL.md

Core Code 2: agents/openai.yaml

Practical Usage Example

1) Natural language trigger

2) Expected output

Why These Rules Matter

Common Pitfalls and How to Avoid Them

Analyzing Anthropic's docx Agent Skill: Features, Code Structure, Usage, and Caveats

What this skill solves

Directory and code structure

1. Guidance layer: SKILL.md

2. Office package layer: scripts/office/*

unpack.py

pack.py

validate.py

soffice.py

3. Word-specific layer: comments, revisions, and redlines

comment.py

accept_changes.py

validators/redlining.py

4. Schema and support layer: schemas/, helpers/, templates/

schemas/

helpers/

templates/

Typical usage patterns

Scenario 1: Read/analyze an existing DOCX

Scenario 2: Create a new DOCX

Scenario 3: Edit an existing DOCX

Scenario 4: Accept all tracked changes

Scenario 5: Add comments

Key caveats to remember

1. .docx is not a plain text file

2. docx-js generation still needs explicit guardrails

3. Comments and tracked changes are multi-part operations

4. “Opens successfully” does not mean “correctly modified”

5. Environment readiness matters

What this skill is good for (and not)

Good fit

Not ideal

Summary

How to Create and Use Skills: SKILL.md Specification and Practical Principles

1. SKILL.md Specification

1.1 Front Matter Example

1.2 Recommended Body Structure

2. Principles for Writing High-Quality Skills

2.1 Keep Description Precise

2.2 Modular Design and Single Responsibility

2.3 Determinism First

2.4 Progressive Disclosure

Summary

What Is Agent Skills: From Design Principles to Context Optimization

1. Core Design Principles

2. Progressive Disclosure: Solving the Context Bottleneck

2.1 Layer 1: Metadata

1. Guidance layer: `SKILL.md`

2. Office package layer: `scripts/office/*`

`unpack.py`

`pack.py`

`validate.py`

`soffice.py`

`comment.py`

`accept_changes.py`

`validators/redlining.py`

4. Schema and support layer: `schemas/`, `helpers/`, `templates/`

`schemas/`

`helpers/`

`templates/`

1. `.docx` is not a plain text file

2. `docx-js` generation still needs explicit guardrails