Agent Skills on KnightLiブログ

eコマース商品画像の切り抜きと標準化されたエージェントスキルを共有する

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

product-cutout-normalize は、商品画像に使用されるエージェントスキルです。

元画像を統一仕様の下透明正方形画像に加工します。デフォルトのルールは次のとおりです。

1024x1024 キャンバス
透明な背景
件名は可能な限り完全なものにしてください
縦長の被写体を横長に自動変換
センターボディ
メインの表示幅は820pxに統一

電子商取引資料、製品ライブラリ、詳細ページの画像の前処理に適しています。

このスキルはどのような問題を解決しますか?

多くの製品画像には、基本的な切り抜き後も次の問題が発生します。

白い枠または薄い灰色の背景が残る
被写体の水平方向と垂直方向が一致しない
キャンバスのサイズが不安定です
被写体のサイズは大きいものから小さいものまでさまざまです
透明部分に小さなノイズがある

このスキルは一定のプロセスに従って処理されます。

ジェミニのカットアウト
明るい背景のエッジをクリーンアップ
ノイズの小さな断片を除去する
縦長画像を横長画像に変換
ターゲットの幅に合わせて拡大縮小する
均一なサイズの透明なキャンバスの中央に配置します。

この方法でエクスポートされた画像はよりきれいになり、バッチ使用に適しています。

該当するシナリオ

以下のニーズに適しています。

商品写真をバッチ処理する
下透過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`

処理の流れ

処理フローは簡単です。

ジェミニのカットアウト
明るい背景のエッジをクリーンアップ
ノイズの小さな断片を除去する
縦長画像を横長画像に変換
ターゲットの幅に合わせて拡大縮小する
均一なサイズの透明なキャンバスの中央に配置します。

通常の切り抜きスクリプトとの違い

通常の暗記スクリプトと比較して、次の問題もさらに処理します。

主な方向性は統一されています
均一なボディサイズ
均一なキャンバスサイズ
小さな破片やノイズのクリーンアップ
結果はマテリアルライブラリに直接入れるのに適しています。

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.

スクリプト/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 の多言語ブログを維持するエージェントスキル

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

Hugo の多言語ブログを維持している場合、頻繁に次のような問題点に遭遇するでしょう。

中国語を作成した後、英語バージョンと繁体字中国語バージョンを同時に生成する必要があります。
3 つの言語ファイルは一貫した構造を持っている必要があります
前付は翻訳され、Hugo 形式に準拠する必要があります

sync-post-translations は、このシナリオ用に設計されたエージェントスキルです。

このスキルはどのような問題を解決しますか?

sync-post-translations のポジショニングは非常に明確です。

index.zh-cn.mdをソースファイルとして取得します
同じディレクトリ内で index.en.md、index.zh-tw.md を生成または更新します
マークダウン構造の一貫性を保つ
前付に明確なルールを適用する (特に date、slug)

適用可能なトリガーワードの例:

「英語と繁体字の同時通訳」
「この記事を英語と繁体字中国語に同期します」

スキルのディレクトリ構造

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

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

コアコード 2: エージェント/openai.yaml

このファイルは、エージェント側のスキルの表示とデフォルトのプロンプト単語を定義します。

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、パッケージ名を変換すると、サンプルコマンドはそのまま無効になります。
3 つの言語のタイトルレベルは一貫性がなく (たとえば、中国語の ## は英語の ### になります)、ディレクトリアンカーの位置がずれます。
前付を加工せずに本文だけを翻訳すると、ページ一覧やSEO情報が異常になります。

Anthropic のエージェントスキル docx の機能、コード構成、使用法、注意事項を分析する

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

Anthropic の skills/docx は本質的に、「AI が Word ドキュメントをより安定して処理できるようにする」作業仕様書とスクリプトツールのセットです。
これはモデルに単に「.docx を書く」と指示するのではなく、Word 文書の処理をいくつかの明確なパス (新しい文書の作成、コンテンツの読み取り、既存の文書の編集、改訂の処理、コメントの追加、形式の変換、OOXML 構造の検証) に分割します。

一文だけ読めば次のように理解できます。

エージェントが .docx をブラックボックスとして扱うのではなく、ZIP + XML + Office の互換性の問題として扱うようにします。

このスキルはどのような問題を解決しますか?

通常のテキスト生成モデルが Word 文書を処理する場合、いくつかの一般的な問題が発生します。

テキストを出力するだけであり、実際には構造的に正しい .docx は生成されません。
既存のドキュメントを変更する場合、OOXML 構造は簡単に壊れてしまう
コメント、改訂、コメントスレッドに遭遇したとき、どの XML を変更すればよいのかわかりません。
ドキュメントを生成できますが、Word、LibreOffice、Google Docs 間の互換性が不安定です
pandoc をいつ使用するか、いつ解凍して XML を直接変更するかがわからない

ここに、docx スキルの価値があります。「何をするか」を事前に制約します。

コンテンツを読み取るときは、pandoc の使用または解凍を優先してください。
新しく .docx を作成する場合は、docx-js を優先してください。
既存の .docx を編集する場合は、まず「解凍 -> XML の変更 -> 再パッケージ化 -> 検証」に進みます。
モデルをハードコーディングするのではなく、コンパニオンスクリプトを使用して、リビジョン、コメント、スキーマ検証の受け入れの詳細を処理します。

Word 文書の問題は、多くの場合、「テキストが正しく記述されているかどうか」ではなく、「ファイル構造が Office で受け入れられるかどうか」であるため、この考え方は非常に実用的です。

ディレクトリとコードの構成

このスキルは大きく4つのレベルに分かれています。

1. 説明レイヤー: `SKILL.md`

SKILL.md はスキル全体への入り口です。主に次の 2 つのことを行います。

トリガー条件を定義する
このスキルは、ユーザーが Word、.docx、コメント、改訂、目次、ページ番号、テンプレート、書式設定されたドキュメントなどを必要とする限り有効にする必要があります。
作業パスを指定する
毎回即興で作るのではなく、さまざまなタスクに対してどの技術的なルートを取るべきかを明確に書き出します。

内容から判断すると、「使用説明書」と「動作仕様書」の両方です。
特に価値があるのは、そこにリストされている次のような多くの Word 互換性ルールです。

docx-js のデフォルトは US レターではなく A4 です
ページが水平の場合、内部ロジックに従って幅と高さのパラメータを渡す必要があります。
リストは手動で挿入できません Unicode 箇条書き
表の幅は表とセルと同時に設定する必要があります。
画像を挿入する場合、typeは省略できません。
生成後、validateを実行

これは、作者が単に「生成できること」ではなく、「安定して開くことができ、安定してレンダリングでき、生成後に互換性があること」を望んでいることを示しています。

2. Office パッケージ操作層: `scripts/office/*`

この層は、.docx/.pptx/.xlsx を Office Open XML パッケージとして処理する役割を果たします。

`unpack.py`

その機能は、Office ファイルをディレクトリに解凍し、いくつかの補助タスクを実行することです。

ZIPパッケージを解凍します
XML/.rels できれいに印刷します
.docx に対する merge_runs のオプションの実行
.docx に対する simplify_redlines のオプションの実行
スマートクオートを XML エンティティに変換して、後続の処理リスクを軽減します

その設計の焦点は、「単純な解凍」ではなく、エージェントや人間が編集を続けるのに適した状態にファイルを整理することにあります。

`pack.py`

この機能は、変更されたディレクトリを .docx/.pptx/.xlsx に再パッケージ化することです。
梱包する前に行うべき重要なことが 2 つあります。

オプションの動作検証と自動修復
XML を再圧縮し、無意味な空白やコメントを削除します。

--original が指定されている場合は、バリデーターと比較されます。これは非常に重要です。
Word の変更の多くは「元に戻すことができれば成功する」わけではなく、文書の構造とリビジョンの追跡セマンティクスがまだ有効であることを確認する必要があるためです。

`validate.py`

これはスキル全体の品質ゲートです。
検証をサポートします。

XML は整形式ですか?
名前空間は正しいですか?
すべての種類の ID は一意ですか?
関係性/コンテンツタイプは一致していますか?
XSDスキーマに準拠
空白の保持ルールは正しいですか?
挿入、削除、コメントマークは合法ですか?

.docx の場合、このステップはほぼコアコンピテンシーです。
「XML が少しだけ変更されているだけ」のように見える多くの文書の場合、本当の問題はここにあります。

`soffice.py`

これは非常にエンジニアリング的なガジェットです。
単に LibreOffice を呼び出すのではなく、制限された環境向けの互換性処理を準備し、自動的に SAL_USE_VCLPLUGIN=svp を設定し、制限された AF_UNIX ソケットの問題を解決するために必要に応じて shim を構築します。

これは、スキルの対象環境が「ローカルデスクトップの手動操作」だけではなく、エージェントやCI、サンドボックスなどの自動化された環境も考慮していることがわかります。

3. Wordの特殊能力レベル：コメント、修正、朱書き

`comment.py`

このスクリプトは、DOCX にコメントを追加する役割を果たします。
Word のコメントは単一のファイルメカニズムではなく、連携して動作する一連のコンポーネントであるため、その動作は「コメント XML を書く」よりもはるかに複雑です。

word/comments.xml
commentsExtended.xml
commentsIds.xml
commentsExtensible.xml
document.xml のコメント範囲マーカー
[Content_Types].xml および document.xml.rels での関係宣言

スクリプトでは、これらの依存関係がすでに考慮されています。
初めてコメントを追加する場合、テンプレートファイル、リレーションシップ、コンテンツタイプが自動的に完成するため、OOXML を手動で変更する際のエラー率を大幅に減らすことができます。

`accept_changes.py`

このスクリプトの目標は非常に明確です。すべてのリビジョンを受け入れることです。
実装方法はXMLを自分で修正するのではなく、LibreOfficeのヘッドレス+Basicマクロで.uno:AcceptAllTrackedChangesを調整する方法です。

Word セマンティクスにおける「リビジョンの受け入れ」は、<w:ins> / <w:del> を削除するほど単純ではないため、この選択は非常に安全です。 XML を直接変更すると、重大な問題が残る可能性があります。
通常、これを Office エンジン自体で行うと、互換性が向上します。

`validators/redlining.py`

これがこのスキルの最も注目すべき部分です。
元の文書と変更された文書から「作成者の改訂」を分離し、テキストが一貫しているかどうかを比較して、改訂が追跡された変更構造に正しくラップされているかどうかを判断します。

言い換えれば、XML 形式をチェックするだけではなく、「リビジョンセマンティクスに従ってドキュメントを編集したか?」をチェックします。

AI は次のような間違いを犯しやすいため、これはエージェントにとって特に重要です。

テキストを直接修正します。ただし、<w:ins> / <w:del> は含めません。
他の人の挿入または削除構造の階層を変更する
最終的なテキストは変更されましたが、朱書きのロジックは保持されません

このバリデータは、この「表面の可用性とセマンティックエラー」の問題を防ぐためのものです。

4. スキーマと補助層: `schemas/`、`helpers/`、`templates/`

`schemas/`

ここに、OOXML / ECMA / Microsoft 拡張機能関連の XSD の完全なセットを示します。
これは、スキルの検証が頭でルールを記述することではなく、可能な限り形式的なスキーマ制約に基づいて行われることを意味します。

`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 による提案から判断すると、このスキルは次のワークフローに最適です。

シナリオ 1: 既存の DOCX の読み取りまたは分析

コンテンツを抽出し、構造を読み取り、Markdown に変換することが目的の場合は、以下を使用します。

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

基礎となる XML を表示したい場合は、以下を使用します。

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

前者は内容を読むのに適しており、後者は構造を見るのに適しています。

シナリオ 2: 新しい DOCX を作成する

スキルの提案は、OOXML を手動でロールするのではなく、docx-js を使用して以下を生成することです。

`1`	`npm install -g docx`

次に、ドキュメントを生成して検証します。

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

このルートは次のような場合に適しています。

報告
memo
letter
タイトル、目次、フッター、ページネーション、表を含む正式な文書

シナリオ 3: 既存の 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

ここで重要なのは「XML の変更」ではなく、最後のステップ --original です。
これにより、システムはパッケージを返すときに、やみくもにパッケージ化するのではなく、スキーマとレッドラインレベルの検証を実行できるようになります。

シナリオ 4: すべてのリビジョンを受け入れる

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

このステップは LibreOffice に依存します。
レビューされた文書を「クリーンなバージョン」に整理するのに適しています。

シナリオ 5: コメントを追加する

1
2

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

ここでは特別な注意を払う必要があります。スクリプトはコメントの内容と必要なコメントコンポーネントのみを追加します。実際、コメントを対応するテキスト範囲に実際に添付するには、コメントの指示に従ってコメント範囲マーカーを document.xml に追加する必要があります。

このスキルの最も注意すべき落とし穴

SKILL.md をざっと見ただけでは、その「互換性ルール」の価値を過小評価するのは簡単です。
特に以下の点は覚えておいてください。

1. `.docx` はテキストファイルではなく、Office パッケージです

最も危険な誤解は、これを「フォーマットされたテキストファイル」として扱うことです。
実際、変更には以下も含まれる場合があります。

テキスト XML
relationships
content types
comments / people / ids
スキーマ制約
リビジョンセマンティクス

そのため、このスキルでは「パッケージの開梱、編集、確認、返却」に重点が置かれています。

2. `docx-js` はドキュメントを生成できますが、デフォルトのパラメーターが目的を満たしているという保証はありません。

SKILL.md は、次のような多くのデフォルト値の落とし穴を強調表示します。

デフォルトの用紙はA4です
水平方向のページ幅と高さの処理には内部ロジックがあります
リストに箇条書き文字を直接挿入することはできません
テーブル幅を二重に宣言する必要があります
Google ドキュメントはパーセント幅との互換性が低い

これは、生成ツールが出発点にすぎず、最終的な品質を保証するものではないことを示しています。

3. コメントと修正は単一点の修正ではありません

コメントであっても、変更の追跡であっても、XML を変更するだけの問題ではありません。
複数のコンポーネント間で一貫性を維持する必要があるため、スキルはこれらのアクションをスクリプト化します。

4.「オープンできる」は「修正される」という意味ではない

文書を Word で開くことができるからといって、その構造が正しいとは限りません。
多くのエラーは、次のシナリオでのみ公開されます。

再度編集するとクラッシュする
レビューモード例外
注釈がありません
Google ドキュメントを開いた後にレイアウトが崩れる
リビジョンを再度受け入れるときにエラーが発生する

したがって、validate.py と pack.py --original は非常に重要です。

5. 外部ツールを利用する場合は事前に環境を準備する

このスキルは、いくつかの種類の外部ツールに依存しています。

pandoc
LibreOffice / soffice
docx-js
Python の依存関係 (defusedxml、lxml など)

これらのツールが環境にない場合、エージェントがプロセスを知っていても、それを完全に実行することはできません。

このスキルは何に向いていて、何が不向きなのでしょうか？

適切な

Word レポートをバッチ生成する
構造化された正式文書の生成
自動変更 .docx
追跡された変更を保存または処理する
コメントを自動的に追加する
Word ドキュメントをスクリプトまたはエージェントワークフローに組み込む

あまり適していない

PDF をエクスポートするだけの簡単なシナリオ
プレーンテキストコンテンツのみが必要で、Word 形式は気にしません
手動によるビジュアル編集に完全に依存している
依存関係や環境の準備を一切せずに、すべての Word 自動化を完了したいと考えています。

要約する

Anthropic の skills/docx の強みは、「Word を生成する」ことではなく、「Word が問題を起こしやすい理由を知り、問題を事前に分解する」ことにあります。
これは、ドキュメント生成、基礎となる XML 編集、リビジョンセマンティクス、スキーマ検証、および Office 互換性に関する元々散在していた知識を実行可能なワークフローに編成します。

単純なドキュメントを時々エクスポートするだけの場合は、少し重く感じるかもしれません。
ただし、シナリオに既存の .docx の変更、コメント、リビジョン、自動バッチ処理、または互換性要件が含まれる限り、この一連のスキルは貴重です。AI が無視する可能性が最も高く、Office ドキュメントが覆される可能性が最も高い詳細を正確に埋めるためです。

簡単な要約は次のとおりです。

SKILL.md はエージェントにどちらの方向を取るかを伝える責任があります
scripts/office/* は開梱、返品、チェック、Office の互換性を担当します。
comment.py と accept_changes.py は Word の特殊能力を担当します
schemas/ とバリデーターは、「機能しているようだ」を「構造的に信頼できる」に改善する責任があります。

コードアドレス：https://github.com/anthropics/skills/tree/main/skills/docx

Agent Skills on KnightLiブログ

eコマース商品画像の切り抜きと標準化されたエージェントスキルを共有する

このスキルはどのような問題を解決しますか?

該当するシナリオ

クイックスタート

出力ルール

主なパラメータの説明

処理の流れ

通常の切り抜きスクリプトとの違い

SKILL.md ソースコード

スクリプト/run_pipeline.py ソース コード

AI を使用して Hugo の多言語ブログを維持するエージェント スキル

このスキルはどのような問題を解決しますか?

スキルのディレクトリ構造

コアコード 1: SKILL.md

コアコード 2: エージェント/openai.yaml

実際の通話例

1) 人間指向の自然言語トリガー

2) 期待される出力

これらのルールが重要な理由

よくある落とし穴と回避策

Anthropic のエージェント スキル docx の機能、コード構成、使用法、注意事項を分析する

このスキルはどのような問題を解決しますか?

ディレクトリとコードの構成

1. 説明レイヤー: SKILL.md

2. Office パッケージ操作層: scripts/office/*

unpack.py

pack.py

validate.py

soffice.py

3. Wordの特殊能力レベル：コメント、修正、朱書き

comment.py

accept_changes.py

validators/redlining.py

4. スキーマと補助層: schemas/、helpers/、templates/

schemas/

helpers/

templates/

一般的な使用法

シナリオ 1: 既存の DOCX の読み取りまたは分析

シナリオ 2: 新しい DOCX を作成する

シナリオ 3: 既存の DOCX を編集する

シナリオ 4: すべてのリビジョンを受け入れる

シナリオ 5: コメントを追加する

このスキルの最も注意すべき落とし穴

1. .docx はテキスト ファイルではなく、Office パッケージです

2. docx-js はドキュメントを生成できますが、デフォルトのパラメーターが目的を満たしているという保証はありません。

3. コメントと修正は単一点の修正ではありません

4.「オープンできる」は「修正される」という意味ではない

5. 外部ツールを利用する場合は事前に環境を準備する

このスキルは何に向いていて、何が不向きなのでしょうか？

適切な

あまり適していない

要約する

スクリプト/run_pipeline.py ソースコード

AI を使用して Hugo の多言語ブログを維持するエージェントスキル

Anthropic のエージェントスキル docx の機能、コード構成、使用法、注意事項を分析する

1. 説明レイヤー: `SKILL.md`

2. Office パッケージ操作層: `scripts/office/*`

`unpack.py`

`pack.py`

`validate.py`

`soffice.py`

`comment.py`

`accept_changes.py`

`validators/redlining.py`

4. スキーマと補助層: `schemas/`、`helpers/`、`templates/`

`schemas/`

`helpers/`

`templates/`

1. `.docx` はテキストファイルではなく、Office パッケージです

2. `docx-js` はドキュメントを生成できますが、デフォルトのパラメーターが目的を満たしているという保証はありません。