Summary

The ExStruct CLI editing feature is now largely implemented, and practical Excel editing through the CLI has become possible.
The next step is to provide a dedicated Skill so AI agents can use the ExStruct CLI reliably and effectively.

This issue proposes introducing a single Skill + detailed reference documents under references/, following the general structure expected by skill-creator / Agent Skills.

Background

The ExStruct CLI already supports operations such as:

• Editing existing workbooks with exstruct patch
• Creating new workbooks and applying ops with exstruct make
• Discovering supported operations with exstruct ops list / ops describe
• Validating inputs with exstruct validate
• Inspecting workbook structure through extraction commands

However, for AI agents to use the CLI in real workflows, having commands alone is not enough. The agent also needs operational knowledge such as:

• Which command should be used for which user request
• How to distinguish between editing an existing workbook and creating a new one
• When to use ops list / ops describe
• Safe workflows using validate and --dry-run
• How to handle backend-specific constraints
• How to verify results after editing
• What to do when the request is ambiguous or the requested op is unsupported

This operational knowledge should be packaged as a single Skill, while the details should be moved into references/ inside the Skill directory.

Why a single skill

At the current stage, a single Skill is preferable to splitting the functionality across multiple Skills.

Reasons:

• ExStruct users can install it more easily
• The agent does not need to choose between multiple similar Skills
• For ExStruct CLI editing, teaching a safe workflow is more important than exposing individual feature-specific Skills
• Keeping SKILL.md lightweight and moving details into references/ avoids bloat

Goal

Make it possible for AI agents to use the ExStruct CLI with a consistent, safe workflow for:

• Safely editing existing Excel workbooks
• Creating new Excel workbooks
• Discovering supported operations before editing
• Validating workbooks before editing
• Running safe edits with --dry-run
• Verifying results after editing
• Failing appropriately and suggesting alternatives when needed

Non-Goals

This issue does not aim to cover:

• Splitting the Skill into multiple smaller Skills
• GUI-oriented editing workflows
• A dedicated MCP-only Skill
• Fully abstracting all backend differences
• Product-specific optimization for every agent runtime

Proposed design

1. Create a single Skill following the skill-creator structure

The Skill should live in a single directory, with SKILL.md as the core file.
Detailed guidance should live under references/ inside the same Skill directory.

Proposed structure:

.claude/
  skills/
    exstruct-cli/
      SKILL.md
      references/
        command-selection.md
        safe-editing.md
        ops-guidance.md
        verify-workflows.md
        backend-constraints.md
      scripts/
        # optional helper scripts
      assets/
        # optional templates, constants, etc.

Alternatively, the repository may keep the Skill source in an equivalent internal layout, as long as it can be distributed into .claude/skills/exstruct-cli/.

2. Keep SKILL.md short and focused on decision rules

SKILL.md should contain only:

• The purpose of the Skill
• When to use it
• Command selection rules
• Safety rules
• The standard workflow
• Minimal concrete examples
• Pointers to the detailed files in references/

The following should not be overloaded into SKILL.md:

• Large enumerations of ops
• Detailed backend differences
• Long recipe collections
• Exhaustive failure case documentation
• Deep implementation background

3. Use minimal frontmatter

Under the skill-creator convention, the frontmatter in SKILL.md should be minimal.
At minimum it should define:

---
name: exstruct-cli
description: Use ExStruct CLI to inspect, validate, create, and edit Excel workbooks safely. Choose between patch and make, consult ops metadata when needed, and prefer validate/dry-run before risky edits.
---

The description should help the agent decide when to activate the Skill, so it should include concepts such as:

• Excel workbook editing
• create / patch
• validate / dry-run
• ops discovery
• safe workflow

4. The Skill’s responsibility is “safe operational knowledge for ExStruct CLI”

This Skill should not be just a command catalog. It should teach the agent:

• Use make for creating a new workbook
• Use patch for editing an existing workbook
• Use ops list / ops describe if the required op is unclear
• Use validate for risky or uncertain inputs
• Use --dry-run before destructive changes
• Verify results when necessary
• Never invent unsupported ops

5. references/ should be structured for agent navigation, not just human notes

references/ should be split by responsibility.

references/command-selection.md

• How to choose between patch, make, validate, ops list, and ops describe
• Example request patterns and the appropriate command choice

references/safe-editing.md

• The standard flow: validate → dry-run → apply → verify
• Conflict handling policies
• Precautions for destructive changes

references/ops-guidance.md

• Fundamentals of ops design
• Common ops patterns
• What to do when a requested op is unknown

references/verify-workflows.md

• What should be checked after editing
• When to re-extract / re-validate
• Criteria for deciding whether verification is required

references/backend-constraints.md

• Backend-specific differences
• COM-dependent features
• Constraints in openpyxl / LibreOffice-based workflows
• Appropriate failure behavior when a requested feature is unsupported

Example SKILL.md outline

---
name: exstruct-cli
description: Use ExStruct CLI to inspect, validate, create, and edit Excel workbooks safely. Choose between patch and make, consult ops metadata when needed, and prefer validate/dry-run before risky edits.
---

# ExStruct CLI

Use this skill when the user wants to create, inspect, validate, or edit Excel workbooks with ExStruct CLI.

## Command selection
- Use `exstruct make` for creating a new workbook.
- Use `exstruct patch` for editing an existing workbook.
- Use `exstruct ops list` or `exstruct ops describe` when the required operation is unclear.
- Use `exstruct validate` when workbook validity is uncertain or before risky edits.

## Safety rules
- Do not apply destructive edits immediately when requirements are ambiguous.
- Prefer `--dry-run` before risky edits.
- Do not invent unsupported ops.
- Check backend constraints when environment-specific features may matter.
- Verify results after editing when the request is confirmation-sensitive.

## Workflow
1. Determine whether the task is create or edit.
2. Identify the required operation(s).
3. Validate if needed.
4. Run dry-run if the change is risky.
5. Apply the change.
6. Verify the result if needed.

## References
- references/command-selection.md
- references/safe-editing.md
- references/ops-guidance.md
- references/verify-workflows.md
- references/backend-constraints.md

Deliverables

• Add .claude/skills/exstruct-cli/SKILL.md
• Add .claude/skills/exstruct-cli/references/
• Add scripts/ and/or assets/ if needed
• Add Skill installation instructions to the README
• Provide minimal usage examples
• Define a basic regression-check workflow for the Skill

Acceptance criteria

• ExStruct users can enable the workflow by installing one Skill
• SKILL.md stays focused on core decision rules and does not become bloated
• Detailed documentation is separated into references/
• The roles of patch, make, validate, ops list, and ops describe are clearly defined
• A safe editing flow using validate and --dry-run is documented for destructive edits
• Backend constraints and unsupported operations have explicit failure rules
• The README explains how to install and use the Skill

Implementation plan

Phase 1

• Finalize the single-Skill structure
• Draft the first version of SKILL.md
• Define the responsibilities of each file under references/

Phase 2

• Write command-selection, safe-editing, ops-guidance, verify-workflows, and backend-constraints
• Add Skill installation instructions to the README

Phase 3

• Validate the Skill behavior against representative use cases
• Refine wording where the guidance is missing or too verbose

Phase 4

• Add scripts/ or support assets if needed later
• Improve description and reference files based on real usage feedback

Open questions

• Should the canonical source live directly under .claude/skills/, or in a separate internal source directory and then be synced?
• Should we introduce scripts/ from the beginning, or start with only SKILL.md + references/?
• Should Skill evaluation be done with pytest-based checks, or with a more agent-oriented eval setup?
• Where should the boundary be drawn between this CLI Skill and future MCP-oriented documentation?

Notes

The important thing is not to create more Skills.
The important thing is to make ExStruct CLI usable by AI agents in a safe, reproducible, low-friction way.

For that reason, this issue prioritizes:

• a single installable Skill
• a description that makes activation easy
• a lean SKILL.md
• detailed documentation separated into references/
• a structure aligned with skill-creator so it can scale later