From 8e7db692f806d15a6dfd83edf17daf6992900a9b Mon Sep 17 00:00:00 2001 From: Vikhyath Mondreti Date: Wed, 2 Sep 2026 15:38:25 -0700 Subject: [PATCH] feat: add workspace files skill --- README.md | 4 + scripts/validate-skills.ts | 1 + skills/files/SKILL.md | 154 +++++++++++++++++++++++++++++++++++++ 3 files changed, 159 insertions(+) create mode 100644 skills/files/SKILL.md diff --git a/README.md b/README.md index d2d55de..8304088 100644 --- a/README.md +++ b/README.md @@ -73,8 +73,10 @@ Native plugin installs expose the skills under the `sim` namespace: - `sim:build-workflow` - `sim:run-workflow` - `sim:deploy-workflow` +- `sim:files` - `sim:table` - `sim:knowledge-base` +- `sim:run-tool` Direct installs through `bunx sim-skills` install the selected skills without the plugin prefix. @@ -83,7 +85,9 @@ Direct installs through `bunx sim-skills` install the selected skills without th - `build-workflow` — discover blocks and author a draft graph with atomic workflow operations. - `run-workflow` — test saved state, exercise triggers, resume from a block, and diagnose runs. - `deploy-workflow` — publish and manage workflows as APIs, chats, or MCP tools. +- `files` — organize workspace files and folders, read and search text, and apply targeted edits. - `table` — design typed tables, load and query rows, import data, and run workflow groups. - `knowledge-base` — ingest and index documents, configure connectors and tags, and verify retrieval. +- `run-tool` — call one integration tool directly with Sim-managed credentials. The skills assume the `sim` CLI is installed and authenticated. They never store or print API keys. diff --git a/scripts/validate-skills.ts b/scripts/validate-skills.ts index 02419d8..7e4a1a3 100644 --- a/scripts/validate-skills.ts +++ b/scripts/validate-skills.ts @@ -13,6 +13,7 @@ const pluginName = "sim"; const expectedSkillNames = [ "build-workflow", "deploy-workflow", + "files", "knowledge-base", "run-tool", "run-workflow", diff --git a/skills/files/SKILL.md b/skills/files/SKILL.md new file mode 100644 index 0000000..94c9359 --- /dev/null +++ b/skills/files/SKILL.md @@ -0,0 +1,154 @@ +--- +name: files +description: Manage Sim workspace files and folders through the sim CLI. Use when listing, uploading, reading, searching, moving, renaming, sharing, restoring, or making exact or anchor-based edits to workspace files; not for knowledge-base ingestion or local filesystem edits. +--- + +# Manage Sim Workspace Files + +Use server-side folder, search, and edit operations instead of downloading a workspace tree or +rewriting a whole file when a narrower operation expresses the request. + +## Establish context + +- Use the profile the user named. If none was named, inspect configured profiles and current + context; do not silently switch accounts, workspaces, or API origins. +- Start with `sim --output json files ls [path]` when navigating files and child folders together. + Use `files list` for file-only filtering and `files folders list` for folder-only traversal. +- Keep file ids returned by list, upload, and create operations. File mutations use the id, not a + name or path that could identify several files. +- Read `sim files --help` and the relevant subcommand help when the installed CLI may differ from + these instructions. Do not guess a newly introduced flag. + +Folder paths use the same slash-delimited form shown in the app; the leading slash is optional. The +CLI encodes individual path segments, so pass the displayed path rather than percent-encoding it. + +## Scope discovery on the server + +List one folder without descendants: + +```bash +sim --output json files list --folder "Reports/2026" --no-recursive +``` + +Add `--recursive` when descendants belong in the result. With `files list`, recursion defaults to +false for an ordinary folder listing and true when `--search` is present. With no `--folder`, the +list already spans the workspace and a recursion flag has no effect. + +Search file names with `files list --search`. Search text contents with `files search`: + +```bash +sim --output json files search \ + --query "invoice_[0-9]+" --mode regex \ + --folder "Reports" "Exports" --include-subfolders +``` + +`--folder` on `files search` accepts several folder paths. Omit it to search the whole workspace. +Use `--mode exact` for literal text and `--no-include-subfolders` when only the selected folders +should be searched. Do not fetch every file and search locally when the server-side query suffices. + +## Create and organize deliberately + +Upload a local file or create textual content directly: + +```bash +sim --output json files upload ./report.csv --folder "Reports/2026" +sim --output json files create --name notes.md --folder "Reports/2026" --content "# Notes" +``` + +Create nested folders with `files mkdir ` or `files folders create `. Move or rename a +folder atomically with `files folders move `. Move known files with +`files move --file-ids --to `; omit `--to` to move them to the workspace root. + +File names are leaf names, not paths. Use `files rename --name ` to change one and +`files move` to change its folder. Do not place path separators or dot segments in a file name. + +## Read before editing + +For textual work, inspect only the needed lines: + +```bash +sim --output json files read --offset 1 --limit 200 +``` + +`files read` extracts text and supports line windows. Use `files get --output-file ` +when the original bytes are needed. Use `files describe ` for metadata and sharing status. + +Apply one targeted edit with `files edit --edit `. Prefer `@path` or `@-` for +multiline content or payloads that are awkward to shell-quote. + +### Exact replacement + +```json +{ + "mode": "search_replace", + "search": "old text", + "content": "new text", + "replaceAll": false +} +``` + +Without `replaceAll`, the search must occur exactly once. Set `replaceAll` to true only when every +exact occurrence should change. An empty `content` deletes the matched text. + +### Anchor-based edits + +Anchors match complete lines after trimming surrounding whitespace. They are not substrings or +regular expressions. `occurrence`, when supplied, is 1-based and selects among repeated valid +matches. + +Replace the lines between two retained anchors: + +```json +{ + "mode": "replace_between", + "beforeAnchor": "BEGIN GENERATED", + "afterAnchor": "END GENERATED", + "content": "replacement lines", + "occurrence": 1 +} +``` + +Insert immediately after a retained anchor: + +```json +{ + "mode": "insert_after", + "anchor": "## Changelog", + "content": "- Added workspace file editing", + "occurrence": 1 +} +``` + +Delete from the start anchor through the line before the retained end anchor: + +```json +{ + "mode": "delete_between", + "startAnchor": "BEGIN OBSOLETE", + "endAnchor": "END OBSOLETE", + "occurrence": 1 +} +``` + +Use `files set-content` only when complete replacement is intentional. A targeted edit preserves +unrelated content and reduces stale-read overwrites. If an edit is rejected because the source +changed concurrently, read the current file and recompute the edit; do not replay the stale write. + +## Treat deletion and sharing as explicit effects + +File and folder deletion requires `--yes` and is soft-delete where the surface supports restore. +Use `files list --scope archived` or `files folders list --scope archived` to find deleted items, +then restore by exact file id or folder path. A recursive folder delete affects descendants, so use +it only when the requested scope is clear. + +Before changing a share, inspect it with `files share get `. `files share set` requires a +personal API-key profile. Do not expose share passwords, profile credentials, or unrelated file +content in output. + +## Verify and report + +After a mutation, read the exact file, folder listing, metadata, or share state that proves the +requested outcome. For edits, verify the affected region and enough surrounding lines to confirm +the anchors and unrelated content remain correct. Report the file id, folder path, and operation +performed, plus any concurrency or authorization error. Do not claim an accepted upload, move, or +edit succeeded without checking the returned result.