SmartSaaS

Install via extraDirs (not clawhub). Never auto-add items: only add when user explicitly asks; user defines what to add. Scripts: create-dataset.sh, add-to-d...

Security Scan

The skill appears to implement a coherent SmartSaaS integration, but there are multiple inconsistencies between the declared metadata, the runtime instructions (SKILL.md), and the actual scripts — the differences could be sloppy engineering or could lead to accidental credential disclosure or wrong API calls, so proceed with caution.

Purpose & Capability

The skill's purpose (SmartSaaS API client) matches the scripts' behavior: they call a base URL using an API key to manage datasets, projects, templates, webhooks, etc. However the registry metadata claims no required environment variables or binaries, while SKILL.md and almost every script require SMARTSAAS_BASE_URL and SMARTSAAS_API_KEY (and some scripts invoke python3). The missing declaration of those env vars/binaries in the registry metadata is an incoherence.

Instruction Scope

SKILL.md emphatically instructs agents to use the included shell scripts (execute_shell), never to show or run curl, and to never ask users for API tokens. The scripts themselves use curl and read SMARTSAAS_BASE_URL / SMARTSAAS_API_KEY from env, which is consistent. But there are direct contradictions: SKILL.md documents that add-to-dataset sends body wrapped as {"data":...}, while the actual scripts (add-to-dataset.sh) post the payload directly (no wrapper). add-to-dataset.sh also prints a curl example (contradicting 'never show curl'). The add-to-dataset.sh resolves folder names by listing folders and parsing JSON with python3 — this requires python3 to be present though metadata does not declare it. These inconsistencies could cause the agent to construct wrong requests or to leak guidance that includes curl examples or examples referencing env vars.

Install Mechanism

There is no remote install step or download in the skill manifest — it's instruction-only and includes scripts in the repo. No network-based install instructions from untrusted URLs are present. That reduces install-time risk.

Credentials

Requesting SMARTSAAS_BASE_URL and SMARTSAAS_API_KEY is proportionate to the skill's function (API calls). However the skill metadata failed to declare these required env vars, and some scripts assume python3 and curl behaviour. The skill does not ask for unrelated credentials. Because the API key provides broad access to a backend (data:read/write, projects, integrations, webhooks), ensure the key has minimal necessary scopes and consider using a dedicated API key for this skill.

Persistence & Privilege

The skill is not always-enabled and does not request changes to other skills or global configs. It expects to be loaded via extraDirs; that is normal and not privileged. The scripts themselves do not install persistent services or modify other skills.

Scan Findings in Context

[REQ_ENV_VARS_NOT_DECLARED] unexpected: Nearly every script requires SMARTSAAS_BASE_URL and SMARTSAAS_API_KEY, but the registry metadata lists no required environment variables. This mismatch is unexpected and should be corrected.

[USES_CURL] expected: Scripts use curl to call the SmartSaaS API; this is expected for a shell-script-based integration. SKILL.md forbids showing curl to the user, but some scripts echo curl examples on errors.

[USES_PYTHON3] expected: add-to-dataset.sh invokes python3 to parse folder lists when resolving by name. The package metadata did not list python3 as a required binary; the runtime environment must have python3 available.

[ADD_TO_DATASET_BODY_MISMATCH] unexpected: SKILL.md and some doc text suggest add-to-dataset.sh should send a body wrapper like {"data": ...}, but add-to-dataset.sh actually posts the provided JSON payload directly. This is a behavioral mismatch that could cause API errors or data inconsistencies.

[PRINTS_CURL_EXAMPLE] unexpected: When folder name resolution fails, add-to-dataset.sh prints a curl example that references SMARTSAAS_API_KEY and SMARTSAAS_BASE_URL. SKILL.md instructs 'never show curl' and 'never ask for API token' — printing curl examples may contradict that guidance and could encourage unsafe interaction patterns.

What to consider before installing

What to consider before installing or enabling this skill: - Metadata mismatch: The skill manifest claims no required environment variables or binaries, but the scripts require SMARTSAAS_BASE_URL and SMARTSAAS_API_KEY and some scripts call python3. Do not rely on the registry metadata; treat SMARTSAAS_BASE_URL and SMARTSAAS_API_KEY as required and ensure python3 is present if you will resolve folders by name. - Credential scope and placement: The API key grants broad access to the backend (create datasets, list users, remove integrations, dispatch webhooks). Use a scoped/dedicated API key with least privilege, and set it in OpenClaw's skill env (skills.entries.smartsaas.env) rather than pasting it in chat. Confirm the key's permissions before use. - Inconsistencies to fix or review: add-to-dataset behavior in the code differs from SKILL.md (wrapper vs direct payload), and the script emits a curl example on error (contradicting 'do not show curl'). These inconsistencies can lead to wrong API payloads or accidental exposure of usage patterns. Review add-to-dataset.sh and the SKILL.md guidance and test the scripts in an isolated environment to confirm expected behavior. - Source verification: The skill's source is 'unknown' and homepage is missing. If you plan to run these scripts against production data, verify the author and repository integrity (or run in a sandbox first). Consider running it in a staging environment and auditing traffic to the SMARTSAAS_BASE_URL. - Runtime safety: Because the skill issues network requests to the configured base URL, run it only with a backend you trust. If you enable cron/dispatch scripts, be careful: configure webhook targets and schedules deliberately to avoid unexpected automated actions. If you want, I can list the exact lines in add-to-dataset.sh and SKILL.md that contradict each other, or produce a recommended corrected SKILL.md / metadata snippet that declares the required env vars and binaries.

SmartSaaS Skill

When the user asks how to install or to install the smartsaas skill: Do NOT run or suggest clawhub install smartsaas or pwd then clawhub install. This skill is not installed via clawhub. Tell the user: (1) Add the path to this repo's skills folder to skills.load.extraDirs in ~/.openclaw/openclaw.json. (2) Set skills.entries.smartsaas.env with SMARTSAAS_BASE_URL and SMARTSAAS_API_KEY. (3) Restart OpenClaw. The skill is then loaded from that path. Do not run clawhub.

Create dataset + add items — WRONG vs RIGHT (no flags, use schema):

• WRONG: create-dataset.sh --name smartsaas-home (no --name; first arg is the title; dataset ends up with wrong title and empty schema). WRONG: add-to-dataset.sh --dataset <id> --name "Investor 1" --location "London" (no --dataset/--name/--location).
• RIGHT create: create-dataset.sh "investor-list" "" '{"dataTitle":"investor-list","dataSchema":{"fields":[{"name":"name","type":"string"},{"name":"notes","type":"string"}]}}' — Arg1 is always the dataset title (e.g. "investor-list"); the script sends it as dataTitle so the folder is never "untitled_folder". Arg2 = "" for no parent. Arg3 = full JSON with dataTitle and dataSchema.fields.
• RIGHT add: add-to-dataset.sh 69b66368aa4e413d0ab084b7 '{"Name":"Investor 1","City":"London"}' — first arg = folder _id, second arg = one JSON object whose keys match the dataset's dataSchema (e.g. Name, City). No flags. The script sends it as the request body {"data": <that object>}. One call per item.

Add-item shape: The second argument to add-to-dataset.sh is the item content object (keys = field names from the dataset's dataSchema). Before adding items, run get-dataset.sh <folderId> to get the folder's dataSchema and use it to build itemJson. Example: if dataSchema has name, notes, use '{"name":"John","notes":"Investor"}'. The script wraps it in {"data": ...} for the API. No flags.

Do NOT auto-add items. Only add items when the user explicitly asks to add specific items. If the user only asked to create a dataset (e.g. "create a dataset called X"), create it and stop — do not proceed to add items or suggest "shall I add investors?" or add example data. The user defines what to add (if anything). "Investor-list" / "investors from London" in this doc are syntax examples only, not a directive to add that content.

Skill summary (for explain / reference)

What it does: Interact with SmartSaaS via shell scripts: create datasets, add items, manage projects/tasks, knowledge, campaigns, templates, webhooks. Run scripts with execute_shell; do not run or show curl. Do not ask for an API token — the key is in the environment.

Environment: Scripts read SMARTSAAS_BASE_URL and SMARTSAAS_API_KEY (not SMARTSAAS_API_TOKEN). Both are required; set in OpenClaw config or system env. Never ask the user to provide the key in chat.

Scripts (positional args only — no --name, --dataset, --location):

• create-dataset.sh — Arg1: dataTitle. Arg2: use "" for no parent (not the word "parentId"). Arg3: bodyJson with dataTitle and dataSchema: {"fields":[...]} (dataSchema must be object with "fields", not a string). Example: create-dataset.sh "investor-list" "" '{"dataTitle":"investor-list","dataSchema":{"fields":[{"name":"Name","type":"string"},{"name":"City","type":"string"}]}}'
• add-to-dataset.sh — add-to-dataset.sh <folderId> '<itemJson>'. No flags. itemJson = one object with keys matching the dataset's dataSchema (script sends body {"data": itemJson}). Example: add-to-dataset.sh 507f1f77bcf86cd799439011 '{"Name":"John Doe","City":"London"}'

Example flow: (1) Run create-dataset.sh with dataTitle and dataSchema. (2) From the response, take the top-level _id. (3) Only if the user asked to add items: run get-dataset.sh <folderId> to get dataSchema, then run add-to-dataset.sh with that _id and each item (itemJson keys match dataSchema.fields). Scripts in skills/smartsaas/scripts/; use full path if needed.

Is the skill installed? This skill is loaded from extraDirs (local path in openclaw.json). Do NOT suggest clawhub install smartsaas when scripts or ls skills/ appear missing — the shell CWD is often not the repo root. Still run the scripts using the full path (e.g. <workspace_root>/skills/smartsaas/scripts/create-dataset.sh). Do not conclude "skill not installed" and suggest clawhub install.

When the user asks to create a dataset: If they only asked to create (e.g. "create a dataset called X"), run create-dataset.sh and stop; do not add items unless they explicitly asked to add something. If they asked to create and add items, only add what they specified — the user defines what to add (if anything). Do NOT reply with "we need your API token". Do NOT output curl. Run scripts via execute_shell; the key is in the environment.

NEVER ask for "API token" or "YOUR_API_TOKEN". NEVER output curl or api.smartsaas.co.uk. ONLY run the scripts via execute_shell. The key is in env.

MANDATORY — read first. You must NOT: use curl; use api.smartsaas.co.uk or api.smartsaas.com; send body {"name":"investor-list"} (API expects dataTitle + dataSchema); ask the user for "API token" or "YOUR_API_TOKEN". The only way to create a dataset and add items is to call execute_shell with the scripts: create-dataset.sh (args: title, "", bodyJson with dataTitle+dataSchema), then add-to-dataset.sh (args: the _id from the create response, itemJson). Base URL and API key come from env (openclaw.json); never ask for them in chat.

---

Quick reference (32k window: read this first)
Installation: This skill is loaded locally via extraDirs in openclaw.json (this repo’s skills folder). Never run clawhub install smartsaas . If ls skills/ shows nothing or scripts are "not found", do NOT suggest clawhub install; use the full path to the script (e.g. <workspace_root>/skills/smartsaas/scripts/create-dataset.sh) or run from workspace root. Do NOT search the web for SmartSaaS API docs.

You MUST run the scripts via execute_shell — do NOT run or output curl. Do NOT put the API key in chat. Scripts need env: SMARTSAAS_BASE_URL, SMARTSAAS_API_KEY (openclaw.json or system env). Wrong: curl, body {"name":"..."}, /folders/investor-list/items (use folder _id). Right: (1) create-dataset.sh "title" "" '{"dataTitle":"...","dataSchema":{...}}' — no --name (2) get _id (3) only if user asked to add items: add-to-dataset.sh <_id> '<itemJson>' — no --dataset/--name/--location. Do NOT auto-add items; user defines what to add.

---

Use this skill when the user asks to create or list datasets, create projects, work packages, tasks, assign tasks, add team members, sync or manage integrations, refresh user data, get favourites, companies, users, calendar, research knowledge (list/get/create knowledge articles, post research saved as knowledge), look up data entries (contacts, investors, companies, etc.) to add to datasets — find or validate entries then add via add-to-dataset.sh — start or create campaigns, create or update email templates, create or update website (webpage) templates, post events / configure cron jobs and dispatch to the SmartSaaS OpenClaw webhook.

Never ask the user for an API key. The scripts read SMARTSAAS_BASE_URL and SMARTSAAS_API_KEY from the environment. If a script fails with "must be set", tell the user to set these in OpenClaw config or in the system env (see Environment below) — not to paste the key in chat.

You have direct access to the API via the scripts. Do NOT say "we don't have direct access" or "I will provide you with the API calls". You MUST run the shell scripts yourself via execute_shell. Do NOT output curl for the user to run.

Wrong (do not do this):

• Do NOT run or output curl at all — not even with the correct URL or a real API key. You MUST call execute_shell with the script; the scripts read URL and key from env. Never put the API key in the chat.
• Do NOT use body {"name":"investor-list"}. The API expects dataTitle and dataSchema (for adding items), not "name". A 500 or error often means wrong body — use the scripts.
• Do NOT use the dataset name in the add-items path. Wrong: /folders/investor-list/items. The path must use the folder _id (the ObjectId returned from the create call), e.g. /folders/507f1f77bcf86cd799439011/items. Run create-dataset.sh first, take the top-level _id from the response, then call add-to-dataset.sh with that _id.

Right: (1) Create: create-dataset.sh "title" "" '{"dataTitle":"...","dataSchema":{...}}'. (2) From the output, copy the top-level _id. (3) Only if the user asked to add items: for each item they specified, run add-to-dataset.sh <that_id> '<itemJson>'. Do not add items the user did not ask for. Do not use curl.

Scripts use positional args only — no flags.

• create-dataset.sh has no --name. Usage: create-dataset.sh "<dataTitle>" [parentId] [bodyJson]. Example: create-dataset.sh "investor-list" "" '{"dataTitle":"investor-list","dataSchema":{"fields":[...]}}'.
• add-to-dataset.sh has no --dataset, --name, or --location. Usage: add-to-dataset.sh <folderId> '<itemJson>'. Second arg = one JSON object whose keys match the dataset's dataSchema (script sends {"data": itemJson} to the API). Example: add-to-dataset.sh 507f1f77bcf86cd799439011 '{"Name":"John Doe","City":"London"}'.

Required behavior (must follow)

• Do NOT auto-add items. Only run add-to-dataset.sh when the user has explicitly asked to add specific items. If they only asked to create a dataset, create it and stop; the user defines what to add (if anything).
• Run the scripts, never curl. You MUST use execute_shell to run the scripts in skills/smartsaas/scripts/. Do NOT run or output curl (even with the right URL or key). Creating datasets and adding items is done ONLY by calling create-dataset.sh and add-to-dataset.sh via execute_shell. Do not ask for an API key; do not put the API key in your message.
• Do NOT create local files as a substitute. Do not create a JSON file or any file in the workspace and claim it is "the dataset" — that does not call the API. That does not create anything in SmartSaaS. Only the scripts (create-dataset.sh, add-to-dataset.sh, etc.) create or update data in SmartSaaS. If the scripts are "not in the expected location", run from the workspace root (the directory containing skills/) or use the full path to the script; do not fall back to writing a local file. If script execution is blocked ("not allowed for spawning sub-agents"), tell the user to enable it in OpenClaw; do not use web_fetch or create local files.
• Do NOT ask the user for the API key. Never say "If you have an API key, please provide it" or "Do you have an API key?". The API key is configured in OpenClaw (skills.entries.smartsaas.env.SMARTSAAS_API_KEY). Run the scripts; they get the key from the environment. If the scripts report "SMARTSAAS_API_KEY must be set", tell the user to add it to their OpenClaw skill config (openclaw.json), not to paste it here.
• If script execution is disabled or "not allowed for spawning sub-agents": If you get an error that execute_shell is not supported, the tool is not available, or the "smartsaas agent ID is not allowed for spawning sub-agents", tell the user: "The SmartSaaS skill requires script execution (execute_shell) to be enabled for this skill in OpenClaw. Please enable it in your OpenClaw settings so I can run create-dataset.sh and add-to-dataset.sh. See TROUBLESHOOTING.md in the skill repo for 'Agent ID not allowed for spawning sub-agents'." Do not fall back to web_fetch for documentation or to creating local files or directories — that does not create a dataset in SmartSaaS.

Do NOT (common mistakes)

• Do NOT ask for the API key. Do not say "please provide your API key", "do you have an API key?", or "if you have an API key we can proceed". Just run the scripts. The key is in OpenClaw config; only if a script fails with "must be set" tell the user to add it to openclaw.json.
• Do NOT suggest clawhub install smartsaas when the skill or scripts appear missing. The skill is loaded from extraDirs. If ls skills/ returns nothing or the scripts dir "does not exist", the CWD is likely wrong — use the full path to the script and still run the scripts.
• Do NOT use a generic "action" JSON. There is no API that accepts {"action":"create-dataset", "dataset":"...", "fields":[...]} or {"action":"create-records", "dataset":"...", "records":[...]}. You MUST run the shell scripts: create-dataset.sh and add-to-dataset.sh via execute_shell.
• Do NOT create or run invented script names (e.g. create_dataset.sh, add_investors.sh) — they do not exist. Use only the scripts in skills/smartsaas/scripts/ (create-dataset.sh, add-to-dataset.sh, etc.).
• Do NOT use flags like --name, --dataset, --location with these scripts. They take positional arguments only: create-dataset.sh <dataTitle> [parentId] [bodyJson]; add-to-dataset.sh <folderId> <itemJson> (one JSON object as second arg).
• Do NOT use wrong endpoints. The API is not at POST /datasets or POST /datasets/<name>/records. It is at POST /api/protected/data/folders (create dataset) and POST /api/protected/data/folders/:folderId/items (add items). Base URL is SMARTSAAS_BASE_URL (set in env), not api.smartsaas.co.uk.
• Do NOT suggest clawhub install smartsaas to fix "skill not found" — the skill is installed via extraDirs; when scripts appear missing, use full path to scripts.
• Do NOT search the web for "SmartSaaS API documentation" or open smartsaas.com for API docs — that is a different product or public site. This skill’s endpoints and flow are in this SKILL.md; use the scripts only.
• Do NOT skip running the scripts. If the scripts "are not in the expected location", run from the workspace root (the directory that contains skills/) so that ./skills/smartsaas/scripts/create-dataset.sh works, or use the full path to the script. Do not fall back to "API calls directly" with made-up endpoints, curl to the wrong host, or creating a local JSON file instead of calling the API.
• Do NOT run or output curl. Do not run curl yourself or give the user curl commands to run. You MUST call execute_shell with the script path and args. Do not put the API key in the message (scripts use env). Do NOT prefix the script with placeholder env (e.g. SMARTSAAS_BASE_URL=https://your-smartsaas-url.com SMARTSAAS_API_KEY=your-api-key); run the script alone so it uses the process environment. If scripts fail (env missing, HTTP 000), tell the user to set vars in ~/.openclaw/.env and restart OpenClaw; do not fall back to curl.

Environment (env) — required for scripts

The scripts read SMARTSAAS_BASE_URL and SMARTSAAS_API_KEY from the environment. Without them, scripts exit with "SMARTSAAS_BASE_URL and SMARTSAAS_API_KEY must be set."

NEVER run the script with placeholder values. Do NOT prefix the command with SMARTSAAS_BASE_URL=https://your-smartsaas-url.com SMARTSAAS_API_KEY=your-api-key or any fake URL/key. Run the script alone (e.g. ./skills/smartsaas/scripts/create-dataset.sh "investor-list" "" '{"dataTitle":"investor-list","dataSchema":{...}}') so it uses the process environment. If the script then fails with "must be set" or connection errors, the sub-agent/shell is not receiving the vars — tell the user to set them in ~/.openclaw/.env or export them before starting OpenClaw (see BLOCKED_ENV_FIX.md / TROUBLESHOOTING "Sub-agent not receiving env vars").

Where env can be set (so sub-agents get them):

1. ~/.openclaw/.env — OpenClaw loads this; best so the process (and any sub-agent shell) has the vars.
2. Export before starting OpenClaw in the same shell: export SMARTSAAS_BASE_URL=... SMARTSAAS_API_KEY=... then start OpenClaw.
3. OpenClaw skill config: ~/.openclaw/openclaw.json → skills.entries.smartsaas.env — may not be passed to sub-agent shells; if scripts fail with "must be set", use (1) or (2).

If a script fails with "must be set" or HTTP 000 / connection errors: Tell the user the sub-agent is likely not receiving env vars. Have them add SMARTSAAS_BASE_URL and SMARTSAAS_API_KEY to ~/.openclaw/.env and restart OpenClaw. Do not ask the user to paste the API key in chat.

Prerequisites

• SMARTSAAS_BASE_URL and SMARTSAAS_API_KEY must be available to the scripts (see Environment above). The API key is created in SmartSaaS APIScreen. You do not ask the user for it.

Schema chain (retrieve schema before posting)

Before any create or POST request, retrieve the expected shape so the request body matches backend expectations.

1. Run scripts/get-schema.sh <resource> to get the schema for that resource. Resources: dataset, data-item, project, work-package, task, campaign, email-template, webpage-template.
2. Use the script output (JSON with fields, endpoint, createScript) to build the POST body. Include all required fields and only optional fields you need.
3. Then run the corresponding create script with the built body (e.g. scripts/create-dataset.sh with bodyJson, or scripts/add-to-dataset.sh with itemJson).

Example chain for creating a dataset that can hold content:
get-schema.sh dataset → read dataTitle (required), dataSchema (required when adding content) →
create-dataset.sh "My Dataset" "" '{"dataTitle":"My Dataset","dataSchema":{"fields":[{"name":"name","type":"string"}]}}'

If you skip the schema step and the backend returns 400 (e.g. missing field or wrong shape), run get-schema.sh <resource> and retry with a body that matches.

Creating a dataset and adding items (two-step flow)

Only add items when the user explicitly asked to add something; they define what to add (if anything). Do not assume or add example data (e.g. "investors") unless the user asked for it.

Adding items to a dataset requires the dataset id from the create step. Follow this order:

1. Create the dataset (with dataSchema so items can be added):

   • Run scripts/create-dataset.sh "<dataTitle>" "" '<bodyJson>' where bodyJson includes dataTitle and dataSchema.fields for the fields the user wants. Use get-schema.sh dataset first if needed to build the body.
   • The script prints the API response. Response shape: { "success": true, "message": "Data posted", "data": { "_id": "...", "dataTitle": "...", ... }, "_id": "<folderId>" }. Use the top-level _id as the dataset id (folderId) for add-to-dataset.sh.

2. Before adding items (recommended): Run scripts/get-dataset.sh <folderId> to fetch the folder; the response includes dataSchema so you can build itemJson with matching field names. If get-dataset.sh returns 404, the backend may not expose GET /folders/:id yet — use the dataSchema you used when creating the dataset, or list-datasets.sh and find the folder in the list by _id to read its dataSchema.

3. Add each item:

   • Run scripts/add-to-dataset.sh <folderId> '<itemJson>' for each item. <itemJson> must match the dataset's dataSchema (same field names as in dataSchema.fields). If you didn't create the dataset in this session, run get-dataset.sh first to get the structure.

Looking up data entries: You may look up contacts, investors, companies, or other entities (e.g. via web search or other tools) to find or validate data to add as dataset items. That is separate from research/knowledge: use whatever tools you have to gather entries, then add them via add-to-dataset.sh. Research / knowledge is different: use list-knowledge.sh, create-knowledge.sh, and post-research.sh to work with knowledge articles and save research as knowledge — that does not populate dataset items; it saves findings as knowledge content.

You cannot add items until the dataset exists and you have its id. Always use the top-level _id from the create-dataset.sh response as folderId.

Where to run / why "scripts directory doesn't exist": The shell used by execute_shell often does not start in the repo root. So ./skills/smartsaas/scripts/ or ls skills/smartsaas/scripts/ may fail with "no such file" or "directory does not exist" because the current working directory is elsewhere. Fix: use the full absolute path to the script. The scripts live at <repo_root>/skills/smartsaas/scripts/ where <repo_root> is the directory that contains the skills folder (e.g. the smartsaas-openclaw-tools repo). Example: /Users/sarfrazhussain/smartsaas-openclaw-tools/skills/smartsaas/scripts/create-dataset.sh (adjust if the user's repo is elsewhere). Or run cd <repo_root> && ./skills/smartsaas/scripts/create-dataset.sh ... with the real path to the repo. Do not conclude the scripts are missing; use the full path.

Do NOT: Invent script names (e.g. create_dataset.sh, add_investors.sh) or use api.smartsaas.co.uk or /datasets. Run only the existing scripts from skills/smartsaas/scripts/.

Example: dataset + items (e.g. "Investor-List" with name/email/phone/city/country)

For "create dataset X" only: create and stop. For "create dataset X and add [specific items]": create then add only what the user specified. Example syntax for adding (when user asked) — dataset with fields Name, Email, Phone, City, Country:

1. Create: create-dataset.sh "<Title>" "" '{"dataTitle":"<Title>","dataSchema":{"fields":[...]}}' (replace with user's dataset name and desired fields).
2. From the output, take the top-level _id as folderId.
3. Before adding items: run get-dataset.sh <folderId> to get the folder's dataSchema so itemJson keys match.
4. For each item the user asked to add: add-to-dataset.sh <folderId> '<itemJson>' with itemJson keys matching dataSchema.fields.

Do not ask for an API key. Do not create a local file instead of running the scripts.

Scripts (run via execute_shell)

Run scripts from this skill's scripts/ directory (or use the full path to each script). All scripts use SMARTSAAS_BASE_URL and SMARTSAAS_API_KEY from the environment (except get-schema.sh, which needs no env). Always report the script's full stdout and stderr to the user so they can see success messages or errors. For dataset/project names with spaces, pass the title as a single quoted argument (e.g. scripts/create-dataset.sh "hello world").

Action	Script	Arguments / usage
Get schema (run first before create/post)	scripts/get-schema.sh	1) resource (dataset | data-item | project | work-package | task | campaign | email-template | webpage-template). No arg = list resources.
Create dataset	scripts/create-dataset.sh	1) dataTitle (required) 2) parentId (optional) 3) bodyJson (optional: full JSON per Data.mjs—dataTitle, dataSchema for content, dataTags, dataType, description, shared, etc.)
Get dataset (folder) by id	scripts/get-dataset.sh	1) folderId. Returns folder including dataSchema; run before adding items to get correct structure for itemJson.
Add item to dataset	scripts/add-to-dataset.sh	1) folderId 2) itemJson (keys match dataSchema.fields; use get-dataset.sh first if unsure of structure)
Get dataset content	scripts/get-data-content.sh	1) folderId 2) type (optional: document | invoice; omit for dataset + dataContent items). Backend: getDataContent.mjs.
List datasets	scripts/list-datasets.sh	1) parentId (optional)
Create project	scripts/create-project.sh	1) title 2) description (optional). Shape: Projects.mjs
List projects	scripts/list-projects.sh	(no args)
Create work package	scripts/create-work-package.sh	1) projectId 2) work_package_title 3) description (optional). Shape: Projects.mjs WorkPackageSchema
Create task	scripts/create-task.sh	1) projectId 2) workPackageId 3) task_title 4) description (optional). Shape: Projects.mjs TaskSchema
Assign task	scripts/assign-task.sh	1) projectId 2) taskId 3) assignedTo (optional)
Add team member	scripts/add-team-member.sh	1) projectId 2) userId 3) role (optional)

Integrations (sync with user integrations)

Action	Script	Arguments / usage
List integrations	scripts/list-integrations.sh	(no args)
Remove integration	scripts/remove-integration.sh	1) integration name (e.g. gmail, shopify)
Sync Shopify products	scripts/sync-shopify-products.sh	(no args)
Get product sync status	scripts/get-product-sync-status.sh	1) dataId
Pull products from integration	scripts/pull-products-from-integration.sh	1) dataId 2) integrationType (e.g. shopify)
Push products to integration	scripts/push-products-to-integration.sh	1) dataId 2) integrationType
Get available integrations	scripts/get-available-integrations.sh	(no args)

Core tasks (user, favourites, companies, calendar)

Action	Script	Arguments / usage
Refresh user	scripts/refresh-user.sh	(no args)
Get data favourites	scripts/get-data-favourites.sh	(no args)
Get project favourites	scripts/get-project-favourites.sh	(no args)
Get user companies	scripts/get-user-companies.sh	(no args)
Get users	scripts/get-users.sh	1) page (optional) 2) pageSize (optional)
Get user hierarchy	scripts/get-user-hierarchy.sh	(no args)
Get calendar schema	scripts/get-calendar-schema.sh	(no args)
Get calendar content	scripts/get-calendar-content.sh	1) date (e.g. 2025-03-15)

Knowledge & research

Action	Script	Arguments / usage
List knowledge	scripts/list-knowledge.sh	1) page (optional) 2) limit (optional) 3) sortBy (optional) 4) sortOrder (optional). Permission: knowledge:read.
Get knowledge article	scripts/get-knowledge.sh	1) id. Permission: knowledge:read.
Create knowledge article	scripts/create-knowledge.sh	1) articleJson (title, content, featuredImage, …). Permission: knowledge:write.
Post research (saved as knowledge)	scripts/post-research.sh	1) researchJson (title, findings/content/summary, source, url, …). Adapter maps to knowledge. Permission: knowledge:write.

Campaigns

Action	Script	Arguments / usage
List active campaigns	scripts/list-active-campaigns.sh	(no args)
Create campaign	scripts/create-campaign.sh	1) campaignJson (campaign_title, stages, etc.) 2) userId (optional). Shape: SalesSchemas/Campaign.mjs
Start campaign	scripts/start-campaign.sh	1) campaignId

Email templates

Action	Script	Arguments / usage
List email templates	scripts/list-email-templates.sh	(no args)
Create email template	scripts/create-email-template.sh	1) templateJson (title required; content, description, tags). Shape: TemplateModels/Email.mjs
Update email template	scripts/update-email-template.sh	1) templateJson (_id required; title, content, description, etc.)
Send test email	scripts/send-test-email.sh	1) templateId 2) toEmail 3) subject (optional)

Website (webpage) templates

Action	Script	Arguments / usage
List webpage templates	scripts/list-webpage-templates.sh	(no args)
Create webpage template	scripts/create-webpage-template.sh	1) templateJson (title required; description, content, urlSlug, isPublished). Shape: TemplateModels/Webpage.mjs
Update webpage template	scripts/update-webpage-template.sh	1) templateJson (_id required; title, description, content, isPublished, urlSlug)

Events & webhook (cron, dispatch)

Action	Script	Arguments / usage
Dispatch to OpenClaw webhook	scripts/dispatch-openclaw-webhook.sh	1) optional JSON payload (default: ping event)
Post event to webhook	scripts/post-openclaw-event.sh	1) eventType (e.g. cron, daily_sync) 2) optional JSON payload
Configure cron / schedule	scripts/configure-openclaw-cron.sh	1) config JSON (schedule, payload, enabled, etc.)

Webhook URL: {SMARTSAAS_BASE_URL}/api/protected/openclaw/webhook. Use for cron jobs, scheduled tasks, or custom event dispatch.

Examples

• Create dataset then add items: (1) Create with scripts/create-dataset.sh "<title>" "" '<bodyJson>' (bodyJson includes dataTitle and dataSchema.fields). (2) Parse the response: use the top-level _id as folderId. (3) Add each item: scripts/add-to-dataset.sh <folderId> '<itemJson>' (itemJson matches schema). (4) Fetch: scripts/get-data-content.sh <folderId>.
• Schema chain: Run scripts/get-schema.sh dataset first to see required/optional fields, then build the body and run scripts/create-dataset.sh "My Dataset" "" '<bodyJson>'.
• Create a dataset (no items): scripts/create-dataset.sh "My Dataset". To allow adding content later, include dataSchema: scripts/create-dataset.sh "My Dataset" "" '{"dataTitle":"My Dataset","dataSchema":{"fields":[{"name":"name","type":"string"}]}}'.
• List datasets: run scripts/list-datasets.sh.
• Create a project: run scripts/create-project.sh "Project Alpha" "Description".
• Create a task: run scripts/create-task.sh "<projectId>" "<workPackageId>" "Task title".
• Assign a task: run scripts/assign-task.sh "<projectId>" "<taskId>" "<userId>".
• List user integrations: run scripts/list-integrations.sh.
• Sync Shopify products: run scripts/sync-shopify-products.sh.
• Refresh user: run scripts/refresh-user.sh.
• Get calendar for a date: run scripts/get-calendar-content.sh "2025-03-15".
• List campaigns: run scripts/list-active-campaigns.sh.
• Start a campaign: run scripts/start-campaign.sh "<campaignId>".
• Create email template: run scripts/create-email-template.sh '{"title":"Welcome","subject":"Hi","content":"..."}'.
• Create webpage template: run scripts/create-webpage-template.sh '{"title":"Landing","description":"..."}'.
• Send test email: run scripts/send-test-email.sh "<templateId>" "[e-mail]" "Test".
• List knowledge: scripts/list-knowledge.sh or scripts/list-knowledge.sh 1 10 createdAt desc. Get one: scripts/get-knowledge.sh "<id>". Create: scripts/create-knowledge.sh '{"title":"My article","content":"..."}'. Post research: scripts/post-research.sh '{"title":"Market study","findings":"..."}'.
• Dispatch to webhook: run scripts/dispatch-openclaw-webhook.sh or scripts/dispatch-openclaw-webhook.sh '{"event":"cron","job":"daily"}'.
• Post event: run scripts/post-openclaw-event.sh cron '{"schedule":"daily"}'.
• Configure cron: run scripts/configure-openclaw-cron.sh '{"schedule":"0 9 * * *","payload":{},"enabled":true}'.

Schema requirements (valid posts): Use the schema chain: run get-schema.sh <resource> before any create/post to retrieve the expected shape, then build the request from that output. Schemas are in this skill's schemas/ (JSON per resource); they mirror smartsaas-backend/src/schema/ and repo SCHEMA_REQUIREMENTS.md. Use the correct field names (e.g. task_title, campaign_title, dataSchema) when sending full JSON; scripts may accept friendly names and the API may map them.

Do not log or echo the API key. Never ask the user to provide the API key in chat. If the scripts report missing config, tell the user to set SMARTSAAS_BASE_URL and SMARTSAAS_API_KEY in OpenClaw (e.g. in skills.entries.smartsaas.env in ~/.openclaw/openclaw.json).