> ## Documentation Index
> Fetch the complete documentation index at: https://docs.straddle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot Straddle skills

> Resolve missing skills, configuration gaps, blocked plans, and incomplete evidence.

Use the skill's report and the Wizard's status to find the step that needs attention.

## Find a missing skill

For a Wizard-managed installation, inspect the cached bundle and client installation:

```bash theme={null}
npx @straddlecom/wizard@latest status --json
npx @straddlecom/wizard@latest skill list
```

`skill list` lists the skills in the Wizard's bundle and may prompt to download a release. In `status`, check the selected client's `plugin.state` and `plugin.verified` fields.

If the plugin is missing, follow [Install the Straddle plugin](/developer-tools/agent-plugin/install). For a mismatched Wizard-managed copy, update it and restart the client:

```bash theme={null}
npx @straddlecom/wizard@latest update --client claude
```

Use `--client codex` for Codex. In Cursor, refresh the team marketplace and check the installed skill names in the IDE. The Wizard's status cannot verify Cursor team-marketplace installations.

## Resolve a marketplace conflict

The Wizard stops if a marketplace named `straddle` points to a different directory from its verified plugin bundle. Choose whether to keep that installation or let the Wizard manage it.

To switch to the Wizard, remove the existing Straddle plugin and marketplace through your client, then run the [installation steps](/developer-tools/agent-plugin/install). Keep your other marketplaces in place.

## Resolve a configuration finding

Setup distinguishes missing configuration from checks that failed. Correct the named setting, then run Setup again:

```bash theme={null}
npx @straddlecom/wizard@latest setup
```

For API MCP, supply `STRADDLE_API_KEY` to the coding client's process separately from the Straddle CLI's saved credentials. Check [MCP authentication](/developer-tools/mcp/safety) and select the sandbox environment explicitly.

If discovery succeeds but an authenticated request fails, use [MCP troubleshooting](/developer-tools/mcp/troubleshooting).

## Unblock Integrate or Test

Integrate needs an approved `straddle-integration-plan.md`. Test accepts an approved integration or migration plan and needs the corresponding code.

Run Plan when the integration plan is missing. If the plan changed after approval, review the revised file and approve it again before continuing. Keep the approval attached to the current plan.

## Interpret incomplete test evidence

Read the individual rows in `straddle-test-evidence.md`. A scenario can be blocked by missing configuration, waiting for approval, or require a person to complete a browser flow. The report names what ran and what still needs evidence.

Correct the specific cause, then rerun Test. If a check found an implementation defect, return to Integrate before testing again.

## Audit an existing failure

Ask your agent to investigate with Audit:

<Prompt description="Investigate a Straddle integration failure." actions={["copy"]}>
  Use the straddle-audit skill to investigate the Straddle failure in this repository. Ask me for the sanitized error and request ID if you need them. Write the findings and recovery steps to straddle-audit-report.md.
</Prompt>

Audit checks each finding against the installed SDK and API contract. Review its proposed fix before authorizing code changes.


## Related topics

- [Troubleshoot the Straddle CLI](/developer-tools/cli/troubleshooting.md)
- [Use Straddle skills](/developer-tools/skills/use-kit.md)
- [Build with Straddle skills](/developer-tools/skills/overview.md)
- [Choose a Straddle skill](/developer-tools/skills/catalog.md)
- [Troubleshoot MCP](/developer-tools/mcp/troubleshooting.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.