Auto-install the Shopify skill in the background on CLI runs

[alfonso-noriega]

WHY are these changes introduced?

Fixes #0000

WHAT is this pull request doing?

How to test your changes?

Post-release steps

Checklist

• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've considered possible documentation changes
• I've considered analytics changes to measure impact
• The change is user-facing — I've identified the correct bump type (patch for bug fixes · minor for new features · major for breaking changes) and added a changeset with pnpm changeset add

[alfonso-noriega]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• Auto-install the Shopify skill in the background on CLI runs #8160 👈 (View in Graphite)
• Add Shopify skill install command #8140
• Add shopify validate command for offline validation #8142
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[alfonso-noriega]

/snapit

[github-actions]

Differences in type declarations

We detected differences in the type declarations generated by Typescript for this branch compared to the baseline ('main' branch). Please, review them to ensure they are backward-compatible. Here are some important things to keep in mind:

• Some seemingly private modules might be re-exported through public modules.
• If the branch is behind main you might see odd diffs, rebase main into this branch.

New type declarations

packages/cli-kit/dist/public/node/skills.d.ts

import { LocalStorage } from './local-storage.js';
import { ConfSchema } from '../../private/node/conf-store.js';
/**
 * Options for {@link installShopifySkillInBackground}.
 */
export interface InstallShopifySkillInBackgroundOptions {
    /** The command being run, used to avoid recursive installs from `skill` commands. */
    currentCommand: string;
    /** The process argv, used to re-invoke the current CLI binary. */
    argv?: string[];
    /** The process environment. */
    env?: NodeJS.ProcessEnv;
    /** The cli-kit local storage, injectable for testing. */
    config?: LocalStorage<ConfSchema>;
    /** The user's home directory, injectable for testing. */
    homeDir?: string;
}
/**
 * Checks whether the Shopify skill for coding agents is installed globally.
 *
 * The skills CLI installs universal skills under `~/.agents/skills` (older versions)
 * or `$XDG_CONFIG_HOME/agents/skills` (newer versions), so both locations are checked.
 *
 * @param env - The process environment.
 * @param homeDir - The user's home directory.
 * @returns Whether the Shopify skill is installed in any known global location.
 */
export declare function shopifySkillIsInstalled(env?: NodeJS.ProcessEnv, homeDir?: string): boolean;
/**
 * Installs the Shopify skill for coding agents by running `shopify skill install`
 * in a detached background process, so the current command is never delayed.
 *
 * The install is attempted at most once per day until it succeeds. Once the skill
 * is detected as installed, a completion flag is recorded and the check becomes a
 * no-op forever, so deliberately uninstalling the skill won't trigger a re-install.
 *
 * Skipped for `skill` commands (to avoid recursion), in CI, in unit tests, in
 * development mode, and when `SHOPIFY_CLI_NO_SKILL_AUTO_INSTALL` is set.
 *
 * @param options - See {@link InstallShopifySkillInBackgroundOptions}.
 */
export declare function installShopifySkillInBackground(options: InstallShopifySkillInBackgroundOptions): Promise<void>;

Existing type declarations

packages/cli-kit/dist/private/node/conf-store.d.ts

@@ -25,6 +25,7 @@ export interface ConfSchema {
     currentDevSessionId?: string;
     cache?: Cache;
     autoUpgradeEnabled?: boolean;
+    skillAutoInstallCompleted?: boolean;
 }
 /**
  * Get session.
@@ -139,6 +140,19 @@ export declare function getAutoUpgradeEnabled(config?: LocalStorage<ConfSchema>)
  * @param enabled - Whether auto-upgrade should be enabled.
  */
 export declare function setAutoUpgradeEnabled(enabled: boolean, config?: LocalStorage<ConfSchema>): void;
+/**
+ * Get whether the Shopify skill auto-install has already completed.
+ *
+ * @param config - The cli-kit local storage.
+ * @returns Whether the skill was detected as installed at some point.
+ */
+export declare function getSkillAutoInstallCompleted(config?: LocalStorage<ConfSchema>): boolean;
+/**
+ * Record that the Shopify skill auto-install has completed, so it is never attempted again.
+ *
+ * @param config - The cli-kit local storage.
+ */
+export declare function setSkillAutoInstallCompleted(config?: LocalStorage<ConfSchema>): void;
 export declare function getConfigStoreForPartnerStatus(): LocalStorage<Record<string, {
     status: true;
     checkedAt: string;

packages/cli-kit/dist/public/node/metadata.d.ts

@@ -34,7 +34,7 @@ export type SensitiveSchema<T> = T extends RuntimeMetadataManager<infer _TPublic
  * @returns A container for the metadata.
  */
 export declare function createRuntimeMetadataContainer<TPublic extends AnyJson, TSensitive extends AnyJson = Record<string, never>>(defaultPublicMetadata?: Partial<TPublic>): RuntimeMetadataManager<TPublic, TSensitive>;
-type CmdFieldsFromMonorail = PickByPrefix<MonorailEventPublic, 'cmd_all_'> & PickByPrefix<MonorailEventPublic, 'cmd_app_'> & PickByPrefix<MonorailEventPublic, 'cmd_create_app_'> & PickByPrefix<MonorailEventPublic, 'cmd_theme_'> & PickByPrefix<MonorailEventPublic, 'store_'> & PickByPrefix<MonorailEventPublic, 'env_auto_upgrade_'>;
+type CmdFieldsFromMonorail = PickByPrefix<MonorailEventPublic, 'cmd_all_'> & PickByPrefix<MonorailEventPublic, 'cmd_app_'> & PickByPrefix<MonorailEventPublic, 'cmd_create_app_'> & PickByPrefix<MonorailEventPublic, 'cmd_theme_'> & PickByPrefix<MonorailEventPublic, 'cmd_validate_'> & PickByPrefix<MonorailEventPublic, 'store_'> & PickByPrefix<MonorailEventPublic, 'env_auto_upgrade_'>;
 declare const coreData: RuntimeMetadataManager<CmdFieldsFromMonorail, {
     commandStartOptions: {
         startTime: number;

packages/cli-kit/dist/public/node/monorail.d.ts

@@ -77,6 +77,11 @@ export interface Schemas {
             cmd_app_validate_valid?: Optional<boolean>;
             cmd_app_validate_issue_count?: Optional<number>;
             cmd_app_validate_file_count?: Optional<number>;
+            cmd_validate_subcommand?: Optional<string>;
+            cmd_validate_result?: Optional<string>;
+            cmd_validate_api?: Optional<string>;
+            cmd_validate_api_version?: Optional<string>;
+            cmd_validate_json?: Optional<boolean>;
             cmd_dev_tunnel_type?: Optional<string>;
             cmd_dev_tunnel_custom_hash?: Optional<string>;
             cmd_dev_urls_updated?: Optional<boolean>;

[github-actions]

🫰✨ Thanks @alfonso-noriega! Your snapshot has been published to npm.

Test the snapshot by installing your package globally:

pnpm i -g --@shopify:registry=https://registry.npmjs.org @shopify/cli@0.0.0-snapshot-20260722210655

Caution

After installing, validate the version by running shopify version in your terminal.
If the versions don't match, you might have multiple global instances installed.
Use which shopify to find out which one you are running and uninstall it.