Add ExStruct CLI skill

.agents/skills/exstruct-cli/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: exstruct-cli
+description: Use ExStruct CLI to validate, inspect, create, and edit Excel workbooks safely. Trigger when an agent needs `exstruct patch`, `exstruct make`, `exstruct validate`, `exstruct ops list`, or `exstruct ops describe`, especially for create-vs-edit decisions, dry-run workflows, backend constraints, or safe workbook-edit guidance.
+---
+
+# ExStruct CLI
+
+Use the existing editing CLI as the default local operational interface for
+ExStruct workbook create/edit requests.
+
+## Select a command
+
+- Use `exstruct make` when the user wants a new workbook created and populated.
+- Use `exstruct patch` when the user wants an existing workbook edited.
+- Use `exstruct validate` when workbook readability is uncertain or before a
+  risky edit on an unfamiliar file.
+- Use `exstruct ops list` when the required operation is still unclear.
+- Use `exstruct ops describe <op>` when you know the likely op name but need
+  the exact schema or constraints.
+- Hand the workflow off to MCP when the user needs host-owned path policy,
+  transport mapping, artifact mirroring, or other server-managed behavior.
+
+## Safety rules
+
+- Do not invent unsupported patch ops.
+- Do not apply destructive edits immediately when the request is ambiguous.
+- Prefer `--dry-run` before risky edits.
+- Pin `--backend openpyxl` when the dry run and the real apply must use the
+  same engine.
+- Explain backend-specific failures directly instead of hiding them behind a
+  generic retry.
+
+## Workflow
+
+1. Decide whether the request is create, edit, or actually an MCP-hosted task.
+2. Identify the needed op or inspect the public op schema.
+3. Validate the workbook when the file, backend, or request is uncertain.
+4. Run `--dry-run` for risky edits and inspect `PatchResult`.
+5. Apply the real edit only after the planned change is acceptable.
+6. Verify the result with the lightest step that still matches the user's risk.
+
+## References
+
+- `references/command-selection.md`
+- `references/safe-editing.md`
+- `references/ops-guidance.md`
+- `references/verify-workflows.md`
+- `references/backend-constraints.md`

.agents/skills/exstruct-cli/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ExStruct CLI"
+  short_description: "Guide safe ExStruct CLI edit workflows"
+  default_prompt: "Use $exstruct-cli to choose the right ExStruct editing CLI command, follow a safe validate/dry-run workflow that inspects the PatchResult/diff before applying changes, and explain any backend constraints for this workbook task."

.agents/skills/exstruct-cli/references/backend-constraints.md

@@ -0,0 +1,37 @@
+# Backend Constraints
+
+Use this file when the workflow depends on backend selection or runtime
+capabilities.
+
+## Backend summary
+
+- `openpyxl`
+  - recommended backend to pin for ordinary workbook edits, especially when
+    you want the same engine for dry-run and apply
+  - supports `--dry-run`, `--return-inverse-ops`, and
+    `--preflight-formula-check`
+- `com`
+  - required for COM-only editing behavior such as `create_chart`
+  - required for `.xls` creation/editing
+- `auto`
+  - follows ExStruct's existing backend-selection policy
+  - can resolve to openpyxl for a dry-run request and COM for a later apply
+    request
+
+## Constraints to call out
+
+- `create_chart` is COM-only and does not support `--dry-run`,
+  `--return-inverse-ops`, or `--preflight-formula-check`.
+- `.xls` workflows require COM, are not valid with `backend=openpyxl`, and do
+  not support `--dry-run`, `--return-inverse-ops`, or
+  `--preflight-formula-check`.
+- Requests that need host-owned path restrictions, transport mapping, or
+  artifact mirroring belong to MCP, not the local CLI Skill.
+
+## Failure behavior
+
+- State clearly when the requested backend or capability is unsupported.
+- Do not pretend that `auto` guarantees the same engine across separate dry-run
+  and apply requests.
+- Redirect to MCP only for host-policy concerns, not as a generic substitute
+  for unsupported CLI behavior.

.agents/skills/exstruct-cli/references/command-selection.md

@@ -0,0 +1,35 @@
+# Command Selection
+
+Use this file when the user intent is clear enough to route to one CLI command
+but the exact command is still undecided.
+
+## Primary routing
+
+- New workbook output requested: use `exstruct make`.
+- Existing workbook path provided and the request changes it: use
+  `exstruct patch`.
+- Readability or file-health check requested: use `exstruct validate`.
+- Unknown capability or op name: use `exstruct ops list` first, then
+  `exstruct ops describe <op>`.
+- Host-owned path restrictions, transport, approval-aware execution, or
+  artifact mirroring requested: use MCP guidance instead of this Skill.
+
+## Request patterns
+
+- "Create a workbook with these starter sheets and values."
+  - `make`
+- "Edit this workbook and set/update/merge/style cells."
+  - `patch`
+- "I do not know which op supports this change."
+  - `ops list` or `ops describe`
+- "Check whether this workbook is readable before we touch it."
+  - `validate`
+- "Do this through the MCP server / Claude Desktop / host-managed policy."
+  - MCP docs, not the local CLI Skill
+
+## Escalate instead of guessing
+
+- Clarify the request before applying edits when the sheet, range, output path,
+  or intended effect is underspecified.
+- If the user requests behavior outside the published op schema, say so and
+  offer the nearest supported workflow or a manual alternative.

.agents/skills/exstruct-cli/references/ops-guidance.md

@@ -0,0 +1,34 @@
+# Ops Guidance
+
+Use this file when the user knows the desired workbook outcome but the exact
+patch op is unclear.
+
+## How to inspect ops
+
+- Run `exstruct ops list` when you need the supported op names and one-line
+  descriptions.
+- Run `exstruct ops describe <op>` when you need exact fields, aliases,
+  backend constraints, or examples.
+
+## Common patterns
+
+- Single cell value/formula updates:
+  - inspect `set_value`, `set_formula`, and the conditional variants
+- New worksheet creation:
+  - inspect `add_sheet`
+- Rectangular data loads:
+  - inspect `set_range_values`
+- Styling and layout:
+  - inspect `set_style`, `set_alignment`, `set_fill_color`, `set_bold`,
+    `auto_fit_columns`, `set_dimensions`
+- Table or chart workflows:
+  - inspect `apply_table_style` and `create_chart`
+
+## Rules
+
+- Never invent an op name that `ops list` does not expose.
+- Never guess required fields when `ops describe` can answer the question.
+- Treat `create_chart` and `.xls` workflows as backend-sensitive and confirm the
+  backend before apply.
+- If the user asks for behavior outside the op schema, say it is unsupported
+  and offer the closest supported path.

.agents/skills/exstruct-cli/references/safe-editing.md

@@ -0,0 +1,49 @@
+# Safe Editing
+
+Use this file for risky edits, unfamiliar workbooks, or any request where a
+wrong apply would be expensive.
+
+## Standard flow
+
+1. Determine whether the request creates a new workbook or edits an existing
+   one.
+2. Validate the input workbook when readability is uncertain for an existing
+   workbook edit.
+3. Build or inspect the patch-op JSON.
+4. Run `exstruct patch --dry-run` for risky edits to an existing workbook.
+5. Run `exstruct make --dry-run` for risky new-workbook requests when the
+   chosen ops and output format support dry-run.
+6. Inspect `PatchResult`, warnings, `patch_diff`, and `engine`.
+7. Re-run without `--dry-run` only after the plan is acceptable.
+8. Perform lightweight verification or deeper verification based on risk.
+
+## Ambiguity rules
+
+- Ask for clarification before apply when sheet names, target cells/ranges,
+  output naming, or overwrite policy are unclear.
+- If the user only states a goal, inspect the op schema before inventing a
+  payload shape.
+
+## Risk checks
+
+- Treat destructive or broad edits as risky:
+  - overwrite/rename conflict decisions
+  - merge / unmerge operations
+  - range-wide formula fills
+  - style changes across large regions
+  - chart creation or COM-only workflows
+- `create_chart` requests and `.xls` create/edit workflows do not support
+  `--dry-run`, `--return-inverse-ops`, or `--preflight-formula-check`;
+  inspect ops, run only supported validation, and explain the backend
+  constraint before any non-dry-run apply.
+- Prefer `--backend openpyxl` when you want the dry run and the later apply run
+  to use the same engine.
+- Explain that `--backend auto` can resolve to openpyxl for a dry-run request
+  and COM for a later non-dry-run request on COM-capable hosts.
+
+## Failure behavior
+
+- Surface schema or validation failures directly.
+- Do not silently retry with a different conceptual operation.
+- If the request depends on unsupported runtime features, explain the
+  constraint and route to the correct backend or MCP workflow.

.agents/skills/exstruct-cli/references/verify-workflows.md

@@ -0,0 +1,35 @@
+# Verify Workflows
+
+Use this file after `patch` or `make`, or after a `--dry-run` when the result
+must be inspected before apply.
+
+## Always check
+
+- CLI exit code
+- `PatchResult.error`
+- `PatchResult.warnings`
+- `PatchResult.engine`
+- `PatchResult.patch_diff`
+- `PatchResult.out_path`
+
+## After `--dry-run`
+
+- Confirm that `patch_diff` matches the intended change.
+- Confirm that warnings and formula issues are acceptable.
+- If the user needs same-engine confidence, ensure the command pinned
+  `--backend openpyxl`.
+
+## After real apply
+
+- Re-run `exstruct validate` when the workbook was unfamiliar or the change was
+  operationally sensitive.
+- Re-run extraction or another downstream read step when the workbook feeds a
+  larger pipeline and the user needs output-level confirmation.
+- Prefer lightweight verification for small, low-risk edits and deeper
+  verification for wide-range, formula, chart, or backend-sensitive changes.
+
+## When lightweight verification is enough
+
+- The change is narrow and the `patch_diff` is easy to inspect.
+- No backend-sensitive features were used.
+- The user did not request stronger confirmation or downstream artifacts.

README.ja.md

@@ -121,6 +121,34 @@ exstruct validate --input book.xlsx --pretty
 4. `--backend auto` を使う場合は `PatchResult.engine` を確認する。Windows/Excel 環境では実適用時に COM へ切り替わることがある。
 5. 問題がなければ `--dry-run` なしで再実行する。
 
+## ExStruct CLI Skill
+
+ExStruct には、editing CLI を安全に使うための repo 管理 Skill も 1 つ含めています。
+
+repo 上の正本:
+
+- `.agents/skills/exstruct-cli/`
+
+次の 1 コマンドでインストールできます。
+
+```bash
+npx skills add harumiWeb/exstruct/.agents/skills --skill exstruct-cli
+```
+
+このコマンドは、このリポジトリで公開される Skill ディレクトリから
+`exstruct-cli` を直接追加する想定です。まだ未公開ブランチで作業している場合や、
+`npx skills add` を使えない実行環境では、従来どおり `SKILL.md` ベースの Skill が
+検出されるローカルディレクトリへ同じフォルダを手動配置してください。
+
+この Skill は、`patch` / `make` / `validate` / `ops list` /
+`ops describe` の使い分けや、安全な
+`validate -> dry-run -> PatchResult/diff を確認 -> apply -> verify`
+フローが必要なときに使います。
+
+エージェント向けの最小プロンプト例:
+
+> `$exstruct-cli` を使って適切な ExStruct editing CLI コマンドを選び、PatchResult/diff の確認を含む validate/dry-run の安全なフローと、このワークブック作業に関係する backend 制約を説明してください。
+
 ## MCPサーバー (標準入出力)
 
 MCP は同じ editing core を包む integration / compatibility layer です。

README.md

@@ -133,6 +133,35 @@ Recommended edit flow:
 4. If you keep `--backend auto`, inspect `PatchResult.engine`; on Windows/Excel hosts the real apply may switch to COM.
 5. Re-run without `--dry-run` only after the result is acceptable.
 
+## ExStruct CLI Skill
+
+ExStruct also ships one repo-owned Skill for agents that should follow the
+editing CLI safely instead of rediscovering the workflow each time.
+
+Canonical repo source:
+
+- `.agents/skills/exstruct-cli/`
+
+You can install it with the following single command:
+
+```bash
+npx skills add harumiWeb/exstruct/.agents/skills --skill exstruct-cli
+```
+
+That command should install `exstruct-cli` directly from this repository's
+published Skill directory. If you are working from an unpublished branch or a
+runtime that does not support `npx skills add`, fall back to copying the same
+folder into the equivalent local skill directory that discovers
+`SKILL.md`-based skills.
+
+Use this Skill when the agent needs help choosing between `patch`, `make`,
+`validate`, `ops list`, and `ops describe`, or when it should follow the safe
+`validate -> dry-run -> inspect -> apply -> verify` workflow.
+
+Example prompt for agents:
+
+> Use `$exstruct-cli` to choose the right ExStruct editing CLI command, follow a safe validate/dry-run/inspect workflow, and explain any backend constraints for this workbook task.
+
 ## MCP Server (stdio)
 
 MCP is the integration / compatibility layer around the same editing core. Use