Skip to content
Browse documentation
skills

Installation and agent-host setup

Plan and install retained Framework skills for Codex or Claude Code, then confirm discovery in the chosen host.

Use the application's retained release

First install the CLI and create an application, or select packages in an existing project. Replace /absolute/my-product below with the absolute application root containing smoothie.toml. Check the installed command grammar before proceeding:

bash
smoothie help skills install --format json

Installation reads the selection recorded in vendor/smoothie/application.json and its hash-listed framework/skills/ files. It is offline and needs neither GitHub access nor installed application dependencies. An older release without retained skills cannot supply them through this command; see troubleshooting.

Review and apply installation

bash
smoothie skills install --project /absolute/my-product --host codex --format json
smoothie skills install --project /absolute/my-product --host codex \
  --run --expect-plan <data.planId> --format json

The first command returns a plan without writing. Review its release, destination, and skill actions; replace the plan placeholder in the second command with the returned data.planId. Keep the project, host, and inputs unchanged. The CLI installs all complete skills supplied by the selection, not a separately downloaded latest batch.

--host codex.agents/skills/<skill-name>/
--host claude.claude/skills/<skill-name>/

Each installed skill includes a .smoothie-install.json provenance receipt. Identical managed copies are unchanged; conflicting copies are refused. Review results and diagnostics, not only the process exit. Installation does not execute skill instructions, install dependencies, configure MCP, or change host permissions. See versions and conflicts before replacing copies.

Keep release-managed skill files unchanged. Updated Starters exclude the six distributed Smoothie skill directories from application formatting and linting, for both hosts; custom skills remain checked. If an older Starter reports errors inside these installed directories, add only their exact paths to biome.jsonc exclusions, using the installation receipts to identify them. Package updates do not overwrite your application configuration.

Confirm host discovery

Open a fresh Codex or Claude Code session in the application and check that the host lists the installed skill names. Ask it to use the selected skill explicitly for your task. Installation, discovery, and successful task execution are three separate checks; data.hostDiscoveryVerified remains false in the installation result.

For another host, use its documented project-local registration mechanism with complete skill directories from the entitled source release. Preserve names, companion files, release identity, and local configuration. If it has no skill discovery, explicitly ask it to read the relevant SKILL.md. A generic skills/ directory is not automatically discovered, and these manual paths are not additional CLI host support.