Move AI instruction files to a dedicated folder structure

[sejas]

Related issues

• Fixes STU-1397 and STU-1396

Proposed Changes

Create a folder under the skills root directory containing the static AGENTS.md, CLAUDE.md, STUDIO.md, and custom Studio skills folders.
It unifies the logic to bundle these files inside the binary and then copy them on site creation
Having the skills folder it opens the door to install them using npx skills command. E.g npx skills add https://github.com/Automattic/studio --skill studio-cli

It also adds getWpFilesPath function which points to the correct wp-files root folder. That was broken becuase Studio was moved to a subdirectory when we created the mono repo.

graph TD
      subgraph "Source (repo)"
          S1["skills/<br/>├── AGENTS.md<br/>├── CLAUDE.md<br/>├── STUDIO.md<br/>└──
  studio-cli/SKILL.md"]
          S2["GitHub: WordPress/agent-skills<br/>├── wp-plugin-development/<br/>├──
  wp-block-development/<br/>├── wp-block-themes/<br/>├── wp-rest-api/<br/>└──
  wp-wpcli-and-ops/"]
      end

      subgraph "Build Time (npm install)"
          WP["wp-files/skills/<br/>├── AGENTS.md<br/>├── CLAUDE.md<br/>├── STUDIO.md<br/>├──
  studio-cli/<br/>├── wp-plugin-development/<br/>├── wp-block-development/<br/>├──
  wp-block-themes/<br/>├── wp-rest-api/<br/>└── wp-wpcli-and-ops/"]
      end

      subgraph "App Startup"
          SF["server-files/skills/<br/>(app data directory)"]
      end

      subgraph "Site Creation"
          ROOT["~/Studio/my-site/<br/>├── AGENTS.md<br/>├── CLAUDE.md<br/>└── STUDIO.md"]
          AGENTS["~/Studio/my-site/.agents/skills/<br/>├── studio-cli/<br/>├──
  wp-plugin-development/<br/>└── ..."]
          CLAUDE["~/Studio/my-site/.claude/skills/<br/>├── studio-cli →
  ../../.agents/skills/studio-cli<br/>└── ... (symlinks)"]
      end

      S1 -->|"copyLocalContent()"| WP
      S2 -->|"downloadRemoteSkills()"| WP
      WP -->|"copyBundledAiInstructions()<br/>setup-wp-server-files.ts"| SF
      SF -->|"installAiInstructionsToSite()<br/>.md files → copyFile"| ROOT
      SF -->|"installSkillToSite()<br/>directories → copyDir"| AGENTS
      AGENTS -->|"ensureSkillSymlink()<br/>symlink"| CLAUDE

Loading

Testing Instructions

1. Run nvm use && npm i to download and merge remote and local skills
2. Confirm the skills folder exist under wp-files
3. Run ENABLE_AGENT_SUITE=true npm start
4. Confirm the skill folder is moved under server-files
5. Create a site
6. Confirm that AGENTS.md, CLAUDE.md, and STUDIO.md are added to the new site
7. Confirm that skills are also added to the new site
8. Stop and restart the site — verify STUDIO.md and CLAUDE.md are kept up-to-date

agents-skills.mp4

Pre-merge Checklist

• Have you checked for TypeScript, React or other console errors?

[epeicher]

Thanks @sejas for iterating on this! I have early reviewed the changes, and they look great. I much prefer to have the AI files as external resources that can be updated easily; this will help with maintenance and quick updates. I have tested the installation, and I can see the files generated as expected (thanks for adding the diagram!).

Installation script	Created site

I have left a couple of minor comments, but overall changes look good to me, please ping once the PR is Ready to review, and I will be happy to have another 👀

[sejas]

@epeicher , this PR is ready for a review! 🤞

[wpmobilebot]

📊 Performance Test Results

Comparing 8856b6e vs trunk

app-size

Metric	trunk	8856b6e	Diff	Change
App Size (Mac)	1236.43 MB	1236.41 MB	0.02 MB	⚪ 0.0%

site-editor

Metric	trunk	8856b6e	Diff	Change
load	1670 ms	1892 ms	+222 ms	🔴 13.3%

site-startup

Metric	trunk	8856b6e	Diff	Change
siteCreation	7121 ms	6116 ms	1005 ms	🟢 -14.1%
siteStartup	3931 ms	3925 ms	6 ms	⚪ 0.0%

---

Results are median values from multiple test runs.

Legend: 🟢 Improvement (faster) | 🔴 Regression (slower) | ⚪ No change (<50ms diff)

[epeicher]

Thanks Antonio for adding this! I have tested it, and it works great! I have created a site and confirmed the skills are copied as expected. I have also removed and edited, and confirmed that Reinstall works fine too. I have reviewed the code and it LGTM! I have left a couple of minor comments, but approving this, as it can progress as is.

After creating a site	Install skills modal

[epeicher]

Great approach 👍

[nightnei]

@sejas Overall, this looks awesome 👍 One thing I’d like to discuss is the root directory name skills. AGENTS.md isn’t really a “skill” by definition — it’s more like instructions that get loaded during initialization, while skills are loaded on demand. Because of that, I wonder if it’d be better to rename the root folder to something like ai-instructions (or similar). WDYT?

[sejas]

@sejas Overall, this looks awesome 👍 One thing I’d like to discuss is the root directory name skills. AGENTS.md isn’t really a “skill” by definition — it’s more like instructions that get loaded during initialization, while skills are loaded on demand. Because of that, I wonder if it’d be better to rename the root folder to something like ai-instructions (or similar). WDYT?

This is a good point, and thought about that when creating the folder. The main reason to have the skills under a root top folder is to expose them to https://skills.sh/ , so users will be able to install them by running a similar command to npx skills add https://github.com/Automattic/studio --skill studio-cli. I agree AGENTS.md is not a skill but I think it makes sense to keep it there as simplification, and avoid having many folders related to AI.

[sejas]

Example of installing a Studio skill using npx skills add

studio-cli-skill.mp4