Troubleshooting skills

When to use: Your agent isn’t picking up an OutboundSync skill, preflight fails on credentials, or you’re getting the wrong skill for the job.

Skill pages stay linked from the catalog. This page is for when something doesn’t work as expected.

The agent never runs the skill

Skills are selected from each skill’s description metadata after install — you don’t need a long always-on rule that pastes the whole workflow.

1. Confirm the skill (or full pack) is installed — see Install skills.
2. Ask in plain language that matches the skill (examples live on each skill page under Try saying this).
3. Restart or open a new agent session after install so the harness reloads skills.
4. In Cursor / Claude Code / Codex, check the skill appears in that tool’s skills list (/skills, skill picker, or project .agents / .claude/skills folders).

Optional hooks are not required for discovery. If you added hooks, make sure they aren’t blocking the shell or HTTP calls the skill needs.

API skill says it’s blocked or asks for a key

Preflight, API, and Sync monitoring need an OutboundSync API key.

1. Create a key: Creating API keys.
2. Put it in the environment as OUTBOUNDSYNC_API_KEY (shell export, gitignored .env, or CI secret) — see Install → Credentials.
3. Never paste the key into the chat. Agents should load it from the environment.
4. Prefer a connection-scoped key for preflight when you only need one CRM connection. Sync Monitoring /webhooks* needs an account-scoped key; mutations need write and explicit confirmation.

If a preflight report is Not ready, read the Next steps — missing inbound Sources (SEP paste URLs), inactive mailboxes, and CRM disconnects are the usual blockers, not a broken skill install. For OutboundSync-emitted Sync Monitoring Webhooks, use the Sync monitoring skill or OutboundSync webhooks.

CRM analysis won’t run or looks incomplete

CRM analysis does not use an OutboundSync API key. It needs OutboundSync engagement fields already present in HubSpot or Salesforce.

• If fields are missing, expect PARTIAL / UNSUPPORTED with a short list of what’s absent — not invented metrics.
• Social-only HeyReach questions usually need an explicit exploratory mode; say so in the ask.
• Don’t confuse CRM analysis with Preflight (launch wiring vs engagement in the CRM).

Wrong skill for the ask

Use the catalog “Use when” column, or:

You want…	Skill
How to use the API / key scope / vocabulary	API
Ready to launch / inbound Sources wiring / sync	Preflight
Sync Monitoring webhooks / deliveries / sync.failed	Sync monitoring
Replies, follow-up, attribution in CRM	CRM analysis
Offer / CTA copy	Outbound offer
Full cold email body	Cold email body
Subject lines	Cold email subject lines
Social invite notes	Connection requests
Email + social sequence structure	Omnichannel campaigns
Mailbox naming	Email aliases
SPF / DKIM / DMARC	Email authentication
Is this sending domain any good?	Sending domain quality
Which agency to hire	Agencies
Does OutboundSync connect tool X?	Integrations

Install or harness quirks

• Try without installing: npx skills use outboundsync/skills --skill <name> (see Install).
• OpenClaw + CRM analysis: use the OpenClaw install flag or ClawHub path on the Install page — the skill files are the same pack.
• Stale copy: Source of truth is outboundsync/skills; re-run npx skills add after pack updates.

Still stuck?

• Re-check Install skills for your agent tool.
• Open the specific skill page from the catalog and try the sample prompt.
• Contact support if account or API access looks wrong after the steps above.