Skip to content
Browse documentation
skills

Troubleshoot Framework skills

Distinguish CLI installation, retained skill inputs, host discovery, and agent execution failures.

Installation did not complete

If skills install is missing from help, verify the executable selected by your host; installing a newer CLI elsewhere does not change that path. Use Install the CLI to check the binary. Do not guess replacement flags or download a different Framework release to conceal a mismatch.

Check that the explicit project path is absolute and contains smoothie.toml and a valid vendor/smoothie/application.json. The recorded selection must contain intact retained skills. For an older release without them, use complete skill directories from that entitled source through the host's documented registration mechanism; do not manufacture retained metadata or copy instructions from an unrelated release.

Read status, diagnostics, and completed/pending entries in the JSON result. A stale plan requires a fresh review; conflicts and interrupted batches follow versions, updates, and conflicts. Do not treat partial output or missing final output as a successful batch.

The host cannot find a skill

Confirm the chosen host and actual destination from the installation result, then open a fresh session in the application root. Check the host's own skill listing. A file present on disk, a successful installation result, or a context-search hit does not prove host discovery. Follow agent-host setup for manual registration or explicit reading; do not configure MCP just to activate a skill.

A discovered skill cannot finish its task

Separate instruction discovery from command access and task prerequisites. The host may use a different executable or lack shell permissions, dependencies, a browser, service credentials, provider consent, or authority for the requested effect. Ask for the exact blocked step and evidence; never put credentials into the conversation or broaden access automatically. Unsupported deployment profiles remain unsupported.

If execution starts but the application fails, use the owning CI and troubleshooting guide. For missing release context or an optional MCP connection, use coding-agent context and MCP. Report skipped checks and unresolved outcomes separately from work that actually passed.