Salesflare CRM

Full Salesflare API operations skill for reading, searching, creating, and updating CRM data (accounts, contacts, opportunities, tasks, pipelines, users, tag...

Security Scan

This skill is internally consistent with its stated purpose: a Python-based Salesflare API helper that only requires a Salesflare API key and python3 and whose scripts perform discovery, requests, and optional smoke tests against api.salesflare.com.

Purpose & Capability

Name/description match the actual artifacts: the repo includes discovery, request, and smoketest scripts and the declared requirement (SALESFLARE_API_KEY) plus python3 is what you'd expect for an API client. There are no unrelated credentials or binaries requested.

Instruction Scope

SKILL.md describes safe workflow (discover → read → confirm → mutate) and instructs the agent to confirm before writes. The included scripts implement discovery (fetching an OpenAPI JSON), authenticated requests, auto-pagination, and a smoketest runner. The scripts can fetch remote OpenAPI JSON or read local files (discover accepts a local path), and request helper/smoketest accept JSON bodies from files (--data-file) which will read local files and send contents to the API. This behavior is consistent with the skill's purpose but means the agent (or user) must avoid accidentally sending arbitrary local file contents to the API; SKILL.md does not explicitly warn about that specific risk. Also, sf_request/smoketest will perform many API calls (and can perform writes/deletes when explicitly enabled) — the skill docs require explicit confirmation for writes, but that is an operational rather than programmatic enforcement.

Install Mechanism

There is no install spec — instruction-only with bundled Python scripts. No remote downloads or archive extraction are performed by an installer, which minimizes install-time risk.

Credentials

Only one required env var (SALESFLARE_API_KEY) is declared and is appropriate. The code also respects SALESFLARE_BASE_URL (documented in SKILL.md) and has an internal DEFAULT_BASE which reads SALESFLARE_DEFAULT_BASE_URL — a minor inconsistency in env var naming but not a security red flag. No unrelated secrets are requested.

Persistence & Privilege

always:false and the skill does not request persistent system-wide privileges or modify other skills. The scripts do perform network calls to Salesflare API (expected). Autonomous invocation is allowed by default (platform normal) but not combined with special persistent privileges.

Assessment

This skill appears to do what it claims, but review and use caution before giving it access to real production data. Specifically: - Only provide a SALESFLARE_API_KEY you trust; the scripts will send that key to salesflare endpoints. - The smoketest/readers can perform writes or deletes only when explicit flags are passed, but double-check that any agent using this skill asks you for confirmation before executing POST/PUT/PATCH/DELETE or running smoketest with --allow-write/--allow-delete. - Be careful with --data-file / data-file-like functionality: supplying a path will read that local file and send its contents to the API — avoid pointing it at sensitive local files. - Minor env-var inconsistency: the code reads SALESFLARE_BASE_URL (documented) and also supports SALESFLARE_DEFAULT_BASE_URL internally; if you rely on custom endpoints, verify which variable to set. - If you plan to let an autonomous agent use this skill, enforce a confirmation step in the agent policy for any write/delete operations and consider testing the scripts locally first to observe behavior.

Salesflare API

Overview

Use this skill to work with the Salesflare REST API safely and consistently.

Default approach:

1. Discover endpoint shape and required fields
2. Do a read/check request first
3. Ask confirmation before mutating data
4. Execute mutation and return compact result with IDs

Quick Start

Set API key before requests:

export SALESFLARE_API_KEY='your_key_here'

• Base URL: https://api.salesflare.com (production, default)
• Auth header: Authorization: Bearer <API_KEY>
• Optional local override: set SALESFLARE_BASE_URL to a staging URL if needed for local testing.

Core Scripts

• scripts/sf — unified CLI wrapper (subcommands: discover, request, get, post, put, patch, delete, smoketest)
• scripts/sf_discover.py — discover/list endpoints and methods from OpenAPI
• scripts/sf_request.py — execute GET/POST/PATCH/PUT/DELETE with retry handling; supports query params, JSON body, auto-pagination
• scripts/sf_smoketest.py — smoke-test OpenAPI operations in read-only mode by default; writes require --allow-write, and deletes require both --allow-write --allow-delete

Workflow

1) Discover endpoint and shape

scripts/sf discover --contains opportunities
scripts/sf discover --tag Accounts

2) Validate with read call

scripts/sf get --path /accounts --query limit=5 --query search=acme

3) Confirm before writes

Always confirm intent with the user before executing POST, PUT, PATCH, or DELETE. For DELETE operations, require explicit confirmation regardless of context — do not infer consent from prior conversation.

4) Execute write and report

Return:

• action performed
• target entity ID(s)
• key changed fields
• API response summary

5) Smoke-test safely

Default smoke test is read-only:

scripts/sf smoketest

Enable write-path testing explicitly:

scripts/sf smoketest --allow-write --safe-write

Enable delete-path testing only with dual opt-in:

scripts/sf smoketest --allow-write --allow-delete --safe-write

Mutation Safety Rules

• POST/PUT/PATCH: always require explicit user confirmation before executing. Never infer consent.
• DELETE: always require explicit user confirmation before executing. Never infer consent.
• Smoke-test defaults to read-only. Use --allow-write for write-path testing, and require both --allow-write --allow-delete for delete-path testing.
• Do not perform bulk mutations without explicit confirmation.
• Prefer single-record updates before bulk updates.
• Include IDs in all write output for traceability.
• On 429, rely on script retry/backoff. If retries exhaust, stop and report clearly.

Output Rules

• Default: concise summary + key IDs/fields
• Provide raw JSON only when user asks for full payload
• For large result sets, return top N and mention total if available

Filtering

• Direct support: simple query params via repeated --query key=value
• Advanced Salesflare query-builder filters (q object/rules): pass as raw serialized query payload when needed
• This skill does not implement a high-level DSL for composing complex q structures

Common Endpoints

/accounts       /contacts       /opportunities
/tasks          /pipelines      /users   /me
/tags           /workflows

See references/endpoints.md for concrete command examples and write patterns.

Known Endpoint Caveats

• GET /persons — bare call can return 500. Use ?search=... or ?id=... instead.
• GET /tags/{tag_id} — returns 500 with valid IDs; use GET /tags and GET /tags/{tag_id}/usage.
• GET /persons filter fields — GET /filterfields/person returns 400; use contact instead.
• See references/endpoints.md for the full list of endpoint-specific caveats.

Resources

scripts/

• sf — unified wrapper CLI
• sf_discover.py — endpoint discovery from OpenAPI
• sf_request.py — authenticated API execution helper
• sf_smoketest.py — full operation smoke-test runner

references/

• endpoints.md — practical request examples, write patterns, and endpoint-specific caveats