Bundle WordPress agent skills into Studio binary (#2741)

* Bundle WordPress agent skills into Studio binary

Add support for bundling 5 curated WordPress skills from the WordPress/agent-skills
repository into Studio's binary distribution. Skills are downloaded on-demand via
`npm run download-agent-skills`, bundled as extra resources, and copied to appdata
server-files at app startup following the existing pattern.

- Add download script for fetching skills from GitHub
- Add skills installation logic with symlink creation for .agents/ and .claude/ dirs
- Add IPC handlers and UI row in AI settings modal for manual install/reinstall
- Auto-install skills on site creation (desktop + CLI), behind ENABLE_AGENT_SUITE flag
- Add 9 unit tests for skills module

* Address PR review: shared skill constants, translations, deduplicate install logic

- Move BUNDLED_SKILL_IDS and installSkillsToSite to @studio/common/lib/agent-skills
  so both Studio and CLI share a single source of truth
- Add __() translations to skill display names and descriptions
- Remove duplicated installAgentSkills from CLI create.ts, use shared function
- Simplify skills.ts by delegating to shared installSkillsToSite
- Add 7 tests for the shared agent-skills module

* Address code review: shared skill IDs, symlink fix, Windows compat

1. Use BUNDLED_SKILL_IDS from shared module in download script (single source of truth)
3. Fix symlink early-return bug: create .claude symlink even when .agents copy exists
4. Add Windows symlink fallback: fall back to junction on EPERM

* Revert formatting change in forge.config.ts to match trunk

* Trigger E2E tests

* Fix blank screen caused by Node.js imports leaking into renderer bundle

skills-constants.ts re-exported from @studio/common/lib/agent-skills,
which imports fs/promises and path. Since ai-settings-modal.tsx imports
skills-constants.ts, this pulled Node.js modules into the renderer
bundle, crashing it silently. Removed the unused re-export.

* Download WordPress skills as a postinstall step

---------

Co-authored-by: Antonio Sejas <antonio.sejas@automattic.com>

Author: epeicher

apps/cli/commands/site/create.ts

@@ -9,6 +9,7 @@ import {
 	DEFAULT_WORDPRESS_VERSION,
 	MINIMUM_WORDPRESS_VERSION,
 } from '@studio/common/constants';
+import { installSkillsToSite } from '@studio/common/lib/agent-skills';
 import { extractFormValuesFromBlueprint } from '@studio/common/lib/blueprint-settings';
 import {
 	filterUnsupportedBlueprintFeatures,
@@ -62,7 +63,7 @@ import {
 import { connectToDaemon, disconnectFromDaemon, emitSiteEvent } from 'cli/lib/daemon-client';
 import { generateSiteName, getDefaultSitePath } from 'cli/lib/generate-site-name';
 import { copyLanguagePackToSite } from 'cli/lib/language-packs';
-import { getServerFilesPath } from 'cli/lib/server-files';
+import { getAgentSkillsPath, getServerFilesPath } from 'cli/lib/server-files';
 import { getPreferredSiteLanguage } from 'cli/lib/site-language';
 import { logSiteDetails, openSiteInBrowser, setupCustomDomain } from 'cli/lib/site-utils';
 import { writeSkillMd } from 'cli/lib/skill-md';
@@ -442,6 +443,11 @@ export async function runCommand(
 			console.log( __( 'Run "studio site start" to start the site.' ) );
 		}
 
+		// Install bundled WordPress agent skills
+		if ( process.env.ENABLE_AGENT_SUITE === 'true' ) {
+			await installSkillsToSite( sitePath, getAgentSkillsPath() );
+		}
+
 		logger.reportKeyValuePair( 'id', siteDetails.id );
 		logger.reportKeyValuePair( 'running', String( siteDetails.running ) );
 		await emitSiteEvent( SITE_EVENTS.CREATED, { siteId: siteDetails.id } );

apps/cli/lib/server-files.ts

@@ -19,3 +19,7 @@ export function getSqliteCommandPath(): string {
 export function getLanguagePacksPath(): string {
 	return path.join( getServerFilesPath(), 'language-packs' );
 }
+
+export function getAgentSkillsPath(): string {
+	return path.join( getServerFilesPath(), 'agent-skills' );
+}

apps/studio/src/components/ai-settings-modal.tsx

@@ -10,6 +10,10 @@ import {
 	type InstructionFileType,
 } from 'src/modules/agent-instructions/constants';
 import { type InstructionFileStatus } from 'src/modules/agent-instructions/lib/instructions';
+import {
+	BUNDLED_SKILLS,
+	type SkillStatus,
+} from 'src/modules/agent-instructions/lib/skills-constants';
 
 interface AiSettingsModalProps {
 	isOpen: boolean;
@@ -161,6 +165,110 @@ function AgentInstructionsPanel( { siteId }: { siteId: string } ) {
 	);
 }
 
+function WordPressSkillsPanel( { siteId }: { siteId: string } ) {
+	const { __ } = useI18n();
+	const [ statuses, setStatuses ] = useState< SkillStatus[] >( [] );
+	const [ error, setError ] = useState< string | null >( null );
+	const [ installing, setInstalling ] = useState( false );
+
+	const refreshStatus = useCallback( async () => {
+		try {
+			const result = await getIpcApi().getWordPressSkillsStatus( siteId );
+			setStatuses( result as SkillStatus[] );
+			setError( null );
+		} catch ( err ) {
+			const errorMessage = err instanceof Error ? err.message : String( err );
+			setError( errorMessage );
+		}
+	}, [ siteId ] );
+
+	useEffect( () => {
+		void refreshStatus();
+		const handleFocus = () => void refreshStatus();
+		window.addEventListener( 'focus', handleFocus );
+		return () => window.removeEventListener( 'focus', handleFocus );
+	}, [ refreshStatus ] );
+
+	const handleInstall = useCallback(
+		async ( overwrite: boolean = false ) => {
+			setInstalling( true );
+			setError( null );
+			try {
+				await getIpcApi().installWordPressSkills( siteId, { overwrite } );
+				await refreshStatus();
+			} catch ( err ) {
+				const errorMessage = err instanceof Error ? err.message : String( err );
+				setError( errorMessage );
+			} finally {
+				setInstalling( false );
+			}
+		},
+		[ siteId, refreshStatus ]
+	);
+
+	const allInstalled = statuses.length > 0 && statuses.every( ( s ) => s.installed );
+	const installedCount = statuses.filter( ( s ) => s.installed ).length;
+
+	return (
+		<div className="flex flex-col gap-4">
+			<div className="flex items-center justify-between">
+				<div>
+					<h3 className="text-sm font-medium text-gray-900">{ __( 'WordPress skills' ) }</h3>
+					<p className="text-xs text-gray-500 mt-0.5">
+						{ __( 'WordPress development skills for AI agents' ) }
+					</p>
+				</div>
+			</div>
+
+			{ error && (
+				<div className="bg-red-50 border border-red-200 text-red-700 px-3 py-2 rounded text-sm">
+					{ error }
+				</div>
+			) }
+
+			<div className="border border-gray-200 rounded-md overflow-hidden">
+				<div className="flex items-center justify-between px-3 py-2.5">
+					<div className="flex-1 min-w-0 pr-3">
+						<div className="flex items-center gap-2">
+							<span className="text-sm font-medium text-gray-900">
+								{ __( 'WordPress Skills' ) }
+							</span>
+							{ allInstalled && (
+								<span className="inline-flex items-center gap-1 text-[11px] text-green-700 bg-green-50 px-2 py-0.5 rounded-full">
+									<Icon icon={ check } size={ 12 } />
+									{ __( 'Installed' ) }
+								</span>
+							) }
+							{ ! allInstalled && installedCount > 0 && (
+								<span className="inline-flex items-center gap-1 text-[11px] text-orange-700 bg-orange-50 px-2 py-0.5 rounded-full">
+									{ `${ installedCount }/${ BUNDLED_SKILLS.length }` }
+								</span>
+							) }
+						</div>
+						<div className="text-xs text-gray-500">
+							{ __( 'Plugins, blocks, themes, REST API, and WP-CLI skills' ) }
+						</div>
+					</div>
+					<div className="flex items-center gap-2 flex-shrink-0">
+						<Button
+							variant="secondary"
+							onClick={ () => handleInstall( allInstalled ) }
+							disabled={ installing }
+							className="text-xs py-1 px-2"
+						>
+							{ installing
+								? __( 'Installing...' )
+								: allInstalled
+								? __( 'Reinstall' )
+								: __( 'Install' ) }
+						</Button>
+					</div>
+				</div>
+			</div>
+		</div>
+	);
+}
+
 export function AiSettingsModal( { isOpen, onClose, siteId }: AiSettingsModalProps ) {
 	const { __ } = useI18n();
 
@@ -176,8 +284,9 @@ export function AiSettingsModal( { isOpen, onClose, siteId }: AiSettingsModalPro
 			size="medium"
 			className="min-h-[350px] app-no-drag-region"
 		>
-			<div className="px-2 pb-4 flex gap-4 flex-col">
+			<div className="px-2 pb-4 flex gap-6 flex-col">
 				<AgentInstructionsPanel siteId={ siteId } />
+				<WordPressSkillsPanel siteId={ siteId } />
 			</div>
 		</Modal>
 	);

apps/studio/src/ipc-handlers.ts

@@ -49,7 +49,7 @@ import {
 	trustRootCA,
 } from 'src/lib/certificate-manager';
 import { simplifyErrorForDisplay } from 'src/lib/error-formatting';
-import { buildFeatureFlags } from 'src/lib/feature-flags';
+import { buildFeatureFlags, getFeatureFlagFromEnv } from 'src/lib/feature-flags';
 import { getImageData } from 'src/lib/get-image-data';
 import { exportBackup } from 'src/lib/import-export/export/export-manager';
 import { ExportOptions } from 'src/lib/import-export/export/types';
@@ -74,6 +74,11 @@ import {
 	installInstructionFile,
 	type InstructionFileStatus,
 } from 'src/modules/agent-instructions/lib/instructions';
+import {
+	getSkillsStatus,
+	installAllSkills,
+	type SkillStatus,
+} from 'src/modules/agent-instructions/lib/skills';
 import { editSiteViaCli, EditSiteOptions } from 'src/modules/cli/lib/cli-site-editor';
 import { isStudioCliInstalled } from 'src/modules/cli/lib/ipc-handlers';
 import { STABLE_BIN_DIR_PATH } from 'src/modules/cli/lib/windows-installation-manager';
@@ -164,6 +169,30 @@ export async function installAgentInstructions(
 	);
 }
 
+export async function getWordPressSkillsStatus(
+	_event: IpcMainInvokeEvent,
+	siteId: string
+): Promise< SkillStatus[] > {
+	const server = SiteServer.get( siteId );
+	if ( ! server ) {
+		throw new Error( `Site not found: ${ siteId }` );
+	}
+	return getSkillsStatus( server.details.path );
+}
+
+export async function installWordPressSkills(
+	_event: IpcMainInvokeEvent,
+	siteId: string,
+	options?: { overwrite?: boolean }
+): Promise< void > {
+	const server = SiteServer.get( siteId );
+	if ( ! server ) {
+		throw new Error( `Site not found: ${ siteId }` );
+	}
+	const overwrite = options?.overwrite ?? false;
+	await installAllSkills( server.details.path, overwrite );
+}
+
 const DEBUG_LOG_MAX_LINES = 50;
 const PM2_HOME = nodePath.join( os.homedir(), '.studio', 'pm2' );
 const DEFAULT_ENCODED_PASSWORD = encodePassword( 'password' );
@@ -337,6 +366,14 @@ export async function createSite(
 			void loadThemeDetails( event, server.details.id );
 		}
 
+		// Install agent instructions and WordPress skills into the new site
+		if ( getFeatureFlagFromEnv( 'enableAgentSuite' ) ) {
+			void installInstructionFile( path, 'agents', DEFAULT_AGENT_INSTRUCTIONS, false ).catch(
+				() => {}
+			);
+			void installAllSkills( path, false ).catch( () => {} );
+		}
+
 		return server.details;
 	} catch ( error ) {
 		// Skip WASM memory errors - they're user system issues, not bugs

apps/studio/src/lib/server-files-paths.ts

@@ -71,3 +71,10 @@ export function getWpCliPath(): string {
 export function getLanguagePacksPath(): string {
 	return path.join( getBasePath(), 'language-packs' );
 }
+
+/**
+ * The path where bundled agent skills are stored.
+ */
+export function getAgentSkillsPath(): string {
+	return path.join( getBasePath(), 'agent-skills' );
+}

apps/studio/src/modules/agent-instructions/lib/skills-constants.ts

@@ -0,0 +1,39 @@
+import { __ } from '@wordpress/i18n';
+
+export interface SkillConfig {
+	id: string;
+	displayName: string;
+	description: string;
+}
+
+export interface SkillStatus extends SkillConfig {
+	installed: boolean;
+}
+
+export const BUNDLED_SKILLS: SkillConfig[] = [
+	{
+		id: 'wp-plugin-development',
+		displayName: __( 'Plugin Development' ),
+		description: __( 'Hooks, settings API, security, and packaging' ),
+	},
+	{
+		id: 'wp-block-development',
+		displayName: __( 'Block Development' ),
+		description: __( 'Block.json, attributes, rendering, and deprecations' ),
+	},
+	{
+		id: 'wp-block-themes',
+		displayName: __( 'Block Themes' ),
+		description: __( 'Theme.json, templates, patterns, and style variations' ),
+	},
+	{
+		id: 'wp-rest-api',
+		displayName: __( 'REST API' ),
+		description: __( 'Routes, endpoints, schema, and authentication' ),
+	},
+	{
+		id: 'wp-wpcli-and-ops',
+		displayName: __( 'WP-CLI & Ops' ),
+		description: __( 'CLI commands, automation, and search-replace' ),
+	},
+];

apps/studio/src/modules/agent-instructions/lib/skills.ts

@@ -0,0 +1,34 @@
+import fs from 'fs/promises';
+import nodePath from 'path';
+import { installSkillsToSite } from '@studio/common/lib/agent-skills';
+import { getAgentSkillsPath } from 'src/lib/server-files-paths';
+import { BUNDLED_SKILLS, type SkillStatus } from './skills-constants';
+
+export { BUNDLED_SKILLS, type SkillConfig, type SkillStatus } from './skills-constants';
+
+export function getBundledSkillsPath(): string {
+	return getAgentSkillsPath();
+}
+
+export async function getSkillsStatus( sitePath: string ): Promise< SkillStatus[] > {
+	return Promise.all(
+		BUNDLED_SKILLS.map( async ( skill ) => {
+			const skillMdPath = nodePath.join( sitePath, '.agents', 'skills', skill.id, 'SKILL.md' );
+			let installed = false;
+			try {
+				await fs.access( skillMdPath );
+				installed = true;
+			} catch {
+				// Skill not installed or incomplete
+			}
+			return { ...skill, installed };
+		} )
+	);
+}
+
+export async function installAllSkills(
+	sitePath: string,
+	overwrite: boolean = false
+): Promise< void > {
+	await installSkillsToSite( sitePath, getBundledSkillsPath(), overwrite );
+}