功能描述

shell-native spreadsheet CLI for agent work. Use it for workbook inspection, sheet/range reads, precise writes, import/export handoff, review-table construct...

使用说明 (SKILL.md)

agent-sheet

Name: Agent Sheet
Author: yangluoshen

agent-sheet is a local spreadsheet CLI for agents. Prefer it when the task needs real workbook structure, formulas, sheet lifecycle, import/export handoff, or a safe shell roundtrip instead of plain CSV cleanup or ad-hoc xlsx library use.

Use it for

resolving a workbook and keeping the target explicit with --entry-id
inspecting workbook structure, sheets, ranges, formulas, and search hits
writing sparse cells, bounded ranges, anchored review tables, or formula fills
importing a local workbook, continuing edits, and exporting a final file
streaming workbook data through shell tools, then writing verified results back
using bounded script js only when built-in commands do not express the workbook change cleanly

Do not default to

reopening the workbook with a local workbook library for reads or writes that agent-sheet already covers
using shell transforms when a direct write cells, write range, write table, write fill, or sheet ... command is clearer
trusting metadata-only surfaces such as file info as proof of workbook structure
finishing after a write without a task-specific verification pass

First path

Run playbooks/00-preflight.md.
Resolve the workbook and keep using --entry-id.
Choose the smallest matching command via references/command-selection-matrix.md.
Verify with playbooks/15-verify.md before finishing.

Hard defaults

prefer entryId over unitId for local workbooks and imports
treat write range as a full bounded rectangle replacement
treat write table --sheet \x3Cname> as an A1-anchored table write with header semantics
verify shell roundtrips with structure plus sample rows, not row count alone
use sheet list or inspect workbook for sheet existence and handoff verification

Highest-signal gotchas

imported local entries can be healthy even when later file info shows unitId: null; keep operating on entryId
file info is metadata only; it does not prove sheet count, sheet names, or formula state
do not run init inside an already initialized workspace tree; nested workspace refusal is expected
non-English sheet names work, but quote the full A1 range string in the shell
shell pipelines can preserve the expected row count while still shifting headers or keys; verify the first rows and key columns after writeback

Read references/gotchas.md when the task looks routine but has import/handoff, shell roundtrip, or workspace ambiguity.

Task routing

Task	Read next
workspace root, CLI resolution, or workbook target is unclear	playbooks/00-preflight.md
inspect workbook state, extract data, search, or review formulas	playbooks/10-read-analyze.md
plan the smallest safe mutation path	references/command-selection-matrix.md
make data-visible edits or structural workbook changes	playbooks/20-write-safe.md
verify a mutation, shell roundtrip, or handoff	playbooks/15-verify.md
create, import, open, or export a local workbook	playbooks/30-file-lifecycle.md
stream workbook data through shell tools	references/shell-patterns.md
formatting, layout, or other built-in command gaps	playbooks/40-script-fallback.md
import/handoff, `entryId` targeting, `file info`, or shell verification edge cases	references/gotchas.md

Output style

prefer bounded previews, file paths, or stream output over oversized inline dumps
use --to-stdout for shell pipelines
use --to-file --output \x3Cpath> for large reusable extracts
when reporting success, include the verification surface you actually used

Ready-made assets

Use these before improvising shell snippets:

Asset	Use when
examples/roundtrip-awk-write-table.md	building a review sheet through shell roundtrip
examples/handoff-verify.md	exporting, importing, and proving handoff structure
examples/template-import-anchor-check.md	importing a template workbook and checking anchor cells
scripts/verify_csv_preview.py	comparing header, head sample rows, and a key column
scripts/check_csv_cells.py	asserting anchor values or non-empty cells from a CSV snippet

File	Use when
playbooks/00-preflight.md	workspace or workbook context is not yet resolved
playbooks/10-read-analyze.md	inspecting workbook state, extracting data, searching, or reviewing formulas
references/command-selection-matrix.md	picking the smallest correct command before writing
playbooks/15-verify.md	proving a mutation or handoff actually succeeded
playbooks/20-write-safe.md	choosing the smallest safe mutation path
playbooks/30-file-lifecycle.md	creating, importing, opening, or exporting a local workbook
playbooks/40-script-fallback.md	built-in commands cannot express the requested workbook change
references/shell-patterns.md	the task is naturally a shell pipeline
references/gotchas.md	the task involves common real-world failure modes
references/js-api-minimal.md	`script js` is necessary and must stay tightly bounded
examples/roundtrip-awk-write-table.md	you need a concrete shell roundtrip example
examples/handoff-verify.md	you need a concrete export/import handoff example
examples/template-import-anchor-check.md	you need a concrete non-English template import example

安全使用建议

This skill is coherent for local spreadsheet work, but before installing: (1) verify the npm package name/author (inspect the package on the registry or the linked GitHub repo) rather than blindly installing '@latest'; (2) consider pinning a specific reviewed version instead of installing 'latest'; (3) review or sandbox the agent-sheet binary if you run it in environments with sensitive files; (4) avoid running unreviewed 'script js' code that could abuse an engine exposing more than the documented API; and (5) the included Python scripts are small and safe (they only check CSV contents). If you need stronger assurance, request the upstream package source or a checksum for the binary/package before installation.

功能分析

Type: OpenClaw Skill Name: agent-sheet Version: 0.1.6 The agent-sheet skill bundle provides a comprehensive CLI and set of playbooks for managing spreadsheets. It includes utility scripts (scripts/check_csv_cells.py and scripts/verify_csv_preview.py) designed for data verification and detailed documentation that emphasizes safety, such as the 'Write Safe' and 'Verification' playbooks. While the tool includes a 'script js' command for executing JavaScript within a spreadsheet engine, the documentation (references/js-api-minimal.md) explicitly mandates scoped, side-effect-free execution and provides clear safety guidelines. No evidence of data exfiltration, malicious execution, or harmful prompt injection was found; the bundle appears to be a legitimate tool for agent-based spreadsheet tasks.

能力评估

✓ Purpose & Capability

Name/description claim a shell-native spreadsheet CLI and all declared requirements align: the skill requires the agent-sheet binary and optionally awk/sed/python for shell pipelines and verification. The two included Python scripts are directly relevant (CSV checks). No unrelated credentials, system paths, or unrelated binaries are requested.

✓ Instruction Scope

SKILL.md instructs the agent to use the agent-sheet CLI, standard shell tools, and the included helper scripts to read/export/import workbook files and verify results. The instructions do not direct the agent to read unrelated system files, environment secrets, or to contact external endpoints. The only potential risk area is the documented 'script js' fallback (it runs JS inside the workbook engine) — the docs repeatedly warn to avoid network/filesystem/process side effects, but that is guidance rather than an enforcement mechanism.

ℹ Install Mechanism

Install uses a node package spec 'agent-sheet@latest' which is a normal distribution mechanism. Using the '@latest' tag means the installed code can change over time; the package likely publishes the agent-sheet binary. This is moderate risk compared with no-install skills — verify the npm package source and consider pinning a specific, reviewed version before installation.

✓ Credentials

The skill declares no required environment variables, no credentials, and no config paths. This is proportional to its stated purpose: local file and CLI-based workbook manipulation. The included scripts only operate on local artifact files and do not access secrets.

✓ Persistence & Privilege

The skill does not request always:true or other elevated persistent privileges; it is user-invocable and allows autonomous invocation by default (the platform standard). It does not attempt to modify other skills or system-wide agent settings.

版本历史

v0.1.6

**Introduces ready-made examples, task-specific scripts, and practical verification playbooks for workbook handoff and shell roundtrips.** - Added new reference playbooks, usage examples, and gotchas docs to cover workbook import/export, handoff, and verification scenarios. - Included examples for handoff verification, shell roundtrip review-table creation, and template import anchor checks. - Added scripts for verifying CSV structure and cell values after shell processing. - Clarified task routing, verification requirements, and the use of entryId vs. unitId throughout. - Updated documentation to highlight safest shell-native paths and verification best practices.

v0.1.5

- Clarified when to use bounded script JS for workbook-native operations versus standard commands. - Updated guidance to avoid reopening workbooks with external libraries when agent-sheet commands or bounded script JS suffice. - Added detail on using file import/export and output file selection. - Strengthened defaults and best practices for task routing and output handling. - Enhanced examples and explanations for workbook processing flows.

v0.1.4

No user-visible changes in this version. - No file changes detected between this and the previous version.

v0.1.3

- Removed sample file: evals/evals.json. - No functional or user-facing changes; this is a minor clean-up of unused or sample content.

v0.1.2

No user-facing changes in this release. - No file changes detected between versions 0.1.1 and 0.1.2. - All documentation and metadata remain unchanged.

v0.1.1

- Simplified and streamlined documentation and skill description for easier onboarding. - Removed multiple redundant policy, reference, and template files; added an example `evals.json`. - Updated usage instructions and defaults for clarity and conciseness. - Added explicit metadata for system compatibility, dependencies, and install instructions. - Clarified task scope, command routing, and recommended usage patterns.

v0.1.0

agent-sheet 0.1.0 — Initial release - Introduces the `agent-sheet` protocol for operating on spreadsheet workbooks via CLI. - Supports workbook inspection, editing, import/export, remote attach/push, sheet tab management, A1 range operations, formulas, formatting, and precise cell/range mutations. - Provides detailed workflow guidance, output contracts, and strict repo-local guardrails. - Emphasizes explicit workbook context, verifiable mutations, and minimal, composable commands. - Includes canonical usage patterns and fallback strategies for advanced operations.

元数据

Slug agent-sheet

版本 0.1.6

许可证 MIT-0

累计安装 1

当前安装数 1

历史版本数 7

常见问题

Agent Sheet 是什么？

shell-native spreadsheet CLI for agent work. Use it for workbook inspection, sheet/range reads, precise writes, import/export handoff, review-table construct... 它是一个面向 Claude Code / OpenClaw 的 AI Agent Skill 插件，目前累计下载 204 次。

如何安装 Agent Sheet？

在 OpenClaw 或 Claude Code 对话框中运行命令「/install agent-sheet」即可一键安装，无需额外配置。

Agent Sheet 是免费的吗？

是的，Agent Sheet 完全免费，采用 MIT-0 许可证，可自由下载、安装和使用。

Agent Sheet 支持哪些平台？

Agent Sheet 跨平台运行，可在任意部署了 OpenClaw / Claude Code 的环境中使用（linux, macos）。

谁开发了 Agent Sheet？

由 yangluoshen（@yangluoshen）开发并维护，当前版本 v0.1.6。

Agent Sheet