salesforce

Files (5)

• SKILL.md
• openai.yaml · agents/
• scenarios.json · evals/
• metadata-and-queries.md · references/
• salesforce_query.py · scripts/

SKILL.md (first lines)

# Salesforce

Use this skill for Salesforce CRM work from an org you can access with stored OAuth credentials.

## Scope

- global object discovery
- object describe / DDL-style metadata inspection
- relationship discovery for lookup, master-detail, and child links
- SOQL row queries
- Tooling API metadata queries
- lead, contact, and opportunity lookup
- opportunity stage/probability updates
- activity logging for calls, emails, and meetings on the right CRM record
- opinionated natural-language commands for common CRM workflows
- credential setup guidance using HybridClaw stored secrets

## Default Workflow

1. Start with read/plan commands. Do not mutate CRM state unless the user explicitly asks.
2. Run the bundled helper directly via bash in the current session:
   ```bash
   python3 skills/salesforce/scripts/salesforce_query.py ...
   ```
3. Use `plan` for natural-language requests when you need to inspect the API actions before execution.
4. Use `run` for supported opinionated workflows, for example "Move the Acme deal to Closed Won and log a call from today".
5. Use `find leads|contacts|opportunities` for business-row reads before a write target is ambiguous.
6. Use `objects`, `describe`, or `relations` before writing SOQL against an unfamiliar object.
7. Use `query` for row reads. Add a SOQL `LIMIT` unless the user explicitly needs a larger fetch.
8. Use `tooling-query` for metadata objects such as `CustomObject`, `FieldDefinition`, `ApexClass`, and flow metadata.
9. If login fails, confirm that `SF_FULL_PASSWORD` already includes any required Salesforce security token.

## Secret Refs

The helper routes all HTTP traffic through the HybridClaw gateway proxy.
OAuth credentials are sent as `<secret:NAME>` placeholders that the gateway
resolves server-side — real secret values never enter the Python process or
the agent context.

Required stored secrets:

- `SF_FULL_USERNAME`
- `SF_FULL_PASSWORD`
- `SF_FULL_CLIENTID`
- `SF_FULL_SECRET`
- `SF_DOMAIN` — `login` for production, `test` for sandbox

The gateway automatically captures the OAuth `access_token` from the login
response and stores it as `SF_ACCESS_TOKEN`; it also captures
`instance_url` as `SF_INSTANCE_URL`. The token never enters the Python process
or the agent context. Subsequent API calls reference it via `bearerSecretName`,
so the gateway injects the bearer token server-side.

Ask the user to set them once in this order:

1. Browser admin: open the active HybridClaw admin URL ending in `/admin/secrets` and set the
   `SF_*` secrets.
2. Browser `/chat` or TUI fallback:

```text
/secret set SF_FULL_USERNAME you@example.com
/secret set SF_FULL_PASSWORD <password-plus-token>
/secret set SF_FULL_CLIENTID <connected-app-client-id>
/secret set SF_FULL_SECRET <connected-app-client-secret>
/secret set SF_DOMAIN login
```

3. Local console fallback:

```bash
hybridclaw secret set SF_FULL_USERNAME you@example.com
hybridclaw secret set SF_FULL_PASSWORD '<password-plus-token>'
hybridclaw secret set SF_FULL_CLIENTID '<connected-app-client-id>'
hybridclaw secret set SF_FULL_SECRET '<connected-app-client-secret>'
hybridclaw secret set SF_DOMAIN login
```

## Command Contract

Plan a natural-language CRM request without authentication:

```bash
python3 skills/salesforce/scripts/salesforce_query.py --format json plan "Move the Acme deal to Closed Won and log a call from today"
```

Execute a supported natural-language CRM request:

```bash
python3 skills/salesforce/scripts/salesforce_query.py run "Move the Acme deal to Closed Won and log a call from today"
```

List objects:

```bash
python3 skills/salesforce/scripts/salesforce_query.py objects --search Account
```

Describe an object:

```bash
python3 skills/salesforce/scripts/salesforce_query.py describe Account
```

Show parent and child relationships:

```bash
python3 skills/salesforce/scripts/salesforce_query.py relations Opportunity
```

Query rows:

```bash
python3 skills/salesforce/scripts/salesforce_query.py query "SELECT Id, Name FROM Account LIMIT 10"
```

Query Tooling API metadata:

```bash
python3 skills/salesforce/scripts/salesforce_query.py tooling-query "SELECT Id, DeveloperName FROM CustomObject LIMIT 20"

From HybridAIOne/hybridclaw, MIT.

More from HybridAIOne/hybridclaw