Merge pull request #74 from Automattic/docs-agent/build-with-wordpress-skills

Update live agent skills

Author: chubes4

plugins/aider/skills/studio/SKILL.md

@@ -37,7 +37,7 @@ Use MCP for:
 - `wp_cli`
 - audits
 - workflow telemetry
-- `validate_html_blocks` and `validate_and_fix_blocks`
+- `validate_blocks`
 - `take_screenshot` and `inspect_design`
 
 Use the CLI for:
@@ -63,11 +63,12 @@ Use direct file edits for theme and plugin files when writing code.
 6. Use `wp_cli` for arbitrary WordPress operations instead of dropping to the shell.
 7. If MCP is unavailable or not the right tool for the task, fall back to the smallest `studio` CLI command that gets the job done.
 8. Quote and escape user-provided shell arguments when using the CLI fallback.
-9. After every file write, file edit, or `wp_cli` content update that contains serialized WordPress block markup, run `validate_html_blocks` first when the content may contain `core/html` blocks, then run `validate_and_fix_blocks`.
-10. If `validate_html_blocks` or `validate_and_fix_blocks` reports invalid blocks, treat that as a required fix step:
-   - use the reported `Expected` versus `Actual` markup to identify the serialization mismatch
-   - repair the block markup instead of leaving invalid content in place
-   - re-run `validate_html_blocks` or `validate_and_fix_blocks`, as appropriate
+9. After every file write, file edit, or `wp_cli` content update that contains serialized WordPress block markup, run `validate_blocks`. Prefer the `filePath` argument when the content lives in a template, template part, pattern, or other file.
+10. Treat every `validate_blocks` issue as a required fix step:
+   - if the static `core/html` policy reports invalid HTML blocks, rewrite those blocks as editable core or plugin blocks before calling `validate_blocks` again
+   - once the HTML policy passes, use the live-editor validation report to identify serialization mismatches
+   - when `validate_blocks` applies an auto-fix to a file, do not manually replace the file content; review the returned diff only for class, nesting, or CSS-selector follow-up
+   - for inline content, use the returned fixed block content exactly when an auto-fix is proposed
    - repeat until the report shows all blocks valid
 11. After visible site changes, use `take_screenshot` to review the result on desktop and mobile when layout or styling matters.
 12. When screenshots reveal a layout or styling issue, use `inspect_design` before editing CSS so the fix targets the element carrying the rendered style.
@@ -79,7 +80,7 @@ Use direct file edits for theme and plugin files when writing code.
 - Prefer MCP tools over shell commands when both can accomplish the task.
 - Validate theme and plugin slugs before using them in paths or commands.
 - Do not invent site paths; derive them from Studio tools or the Studio home.
-- Serialized block content must not be left unvalidated. `validate_and_fix_blocks` is mandatory after block-content writes or updates.
+- Serialized block content must not be left unvalidated. `validate_blocks` is mandatory after block-content writes or updates.
 - Keep review loops proportional to the task; do not force screenshots or validation when they add no value.
 - Do not place generated artifacts in the agent launch directory by default. Use the selected Studio site path.
 - If the user asks for performance, accessibility, or broader frontend QA, hand off to `auditing` rather than embedding that workflow here.

plugins/amp/.agents/skills/studio/SKILL.md

@@ -37,7 +37,7 @@ Use MCP for:
 - `wp_cli`
 - audits
 - workflow telemetry
-- `validate_html_blocks` and `validate_and_fix_blocks`
+- `validate_blocks`
 - `take_screenshot` and `inspect_design`
 
 Use the CLI for:
@@ -63,11 +63,12 @@ Use direct file edits for theme and plugin files when writing code.
 6. Use `wp_cli` for arbitrary WordPress operations instead of dropping to the shell.
 7. If MCP is unavailable or not the right tool for the task, fall back to the smallest `studio` CLI command that gets the job done.
 8. Quote and escape user-provided shell arguments when using the CLI fallback.
-9. After every file write, file edit, or `wp_cli` content update that contains serialized WordPress block markup, run `validate_html_blocks` first when the content may contain `core/html` blocks, then run `validate_and_fix_blocks`.
-10. If `validate_html_blocks` or `validate_and_fix_blocks` reports invalid blocks, treat that as a required fix step:
-   - use the reported `Expected` versus `Actual` markup to identify the serialization mismatch
-   - repair the block markup instead of leaving invalid content in place
-   - re-run `validate_html_blocks` or `validate_and_fix_blocks`, as appropriate
+9. After every file write, file edit, or `wp_cli` content update that contains serialized WordPress block markup, run `validate_blocks`. Prefer the `filePath` argument when the content lives in a template, template part, pattern, or other file.
+10. Treat every `validate_blocks` issue as a required fix step:
+   - if the static `core/html` policy reports invalid HTML blocks, rewrite those blocks as editable core or plugin blocks before calling `validate_blocks` again
+   - once the HTML policy passes, use the live-editor validation report to identify serialization mismatches
+   - when `validate_blocks` applies an auto-fix to a file, do not manually replace the file content; review the returned diff only for class, nesting, or CSS-selector follow-up
+   - for inline content, use the returned fixed block content exactly when an auto-fix is proposed
    - repeat until the report shows all blocks valid
 11. After visible site changes, use `take_screenshot` to review the result on desktop and mobile when layout or styling matters.
 12. When screenshots reveal a layout or styling issue, use `inspect_design` before editing CSS so the fix targets the element carrying the rendered style.
@@ -79,7 +80,7 @@ Use direct file edits for theme and plugin files when writing code.
 - Prefer MCP tools over shell commands when both can accomplish the task.
 - Validate theme and plugin slugs before using them in paths or commands.
 - Do not invent site paths; derive them from Studio tools or the Studio home.
-- Serialized block content must not be left unvalidated. `validate_and_fix_blocks` is mandatory after block-content writes or updates.
+- Serialized block content must not be left unvalidated. `validate_blocks` is mandatory after block-content writes or updates.
 - Keep review loops proportional to the task; do not force screenshots or validation when they add no value.
 - Do not place generated artifacts in the agent launch directory by default. Use the selected Studio site path.
 - If the user asks for performance, accessibility, or broader frontend QA, hand off to `auditing` rather than embedding that workflow here.

plugins/claude-code/skills/studio/SKILL.md

@@ -37,7 +37,7 @@ Use MCP for:
 - `wp_cli`
 - audits
 - workflow telemetry
-- `validate_html_blocks` and `validate_and_fix_blocks`
+- `validate_blocks`
 - `take_screenshot` and `inspect_design`
 
 Use the CLI for:
@@ -63,11 +63,12 @@ Use direct file edits for theme and plugin files when writing code.
 6. Use `wp_cli` for arbitrary WordPress operations instead of dropping to the shell.
 7. If MCP is unavailable or not the right tool for the task, fall back to the smallest `studio` CLI command that gets the job done.
 8. Quote and escape user-provided shell arguments when using the CLI fallback.
-9. After every file write, file edit, or `wp_cli` content update that contains serialized WordPress block markup, run `validate_html_blocks` first when the content may contain `core/html` blocks, then run `validate_and_fix_blocks`.
-10. If `validate_html_blocks` or `validate_and_fix_blocks` reports invalid blocks, treat that as a required fix step:
-   - use the reported `Expected` versus `Actual` markup to identify the serialization mismatch
-   - repair the block markup instead of leaving invalid content in place
-   - re-run `validate_html_blocks` or `validate_and_fix_blocks`, as appropriate
+9. After every file write, file edit, or `wp_cli` content update that contains serialized WordPress block markup, run `validate_blocks`. Prefer the `filePath` argument when the content lives in a template, template part, pattern, or other file.
+10. Treat every `validate_blocks` issue as a required fix step:
+   - if the static `core/html` policy reports invalid HTML blocks, rewrite those blocks as editable core or plugin blocks before calling `validate_blocks` again
+   - once the HTML policy passes, use the live-editor validation report to identify serialization mismatches
+   - when `validate_blocks` applies an auto-fix to a file, do not manually replace the file content; review the returned diff only for class, nesting, or CSS-selector follow-up
+   - for inline content, use the returned fixed block content exactly when an auto-fix is proposed
    - repeat until the report shows all blocks valid
 11. After visible site changes, use `take_screenshot` to review the result on desktop and mobile when layout or styling matters.
 12. When screenshots reveal a layout or styling issue, use `inspect_design` before editing CSS so the fix targets the element carrying the rendered style.
@@ -79,7 +80,7 @@ Use direct file edits for theme and plugin files when writing code.
 - Prefer MCP tools over shell commands when both can accomplish the task.
 - Validate theme and plugin slugs before using them in paths or commands.
 - Do not invent site paths; derive them from Studio tools or the Studio home.
-- Serialized block content must not be left unvalidated. `validate_and_fix_blocks` is mandatory after block-content writes or updates.
+- Serialized block content must not be left unvalidated. `validate_blocks` is mandatory after block-content writes or updates.
 - Keep review loops proportional to the task; do not force screenshots or validation when they add no value.
 - Do not place generated artifacts in the agent launch directory by default. Use the selected Studio site path.
 - If the user asks for performance, accessibility, or broader frontend QA, hand off to `auditing` rather than embedding that workflow here.

plugins/cline/.cline/skills/studio/SKILL.md

@@ -37,7 +37,7 @@ Use MCP for:
 - `wp_cli`
 - audits
 - workflow telemetry
-- `validate_html_blocks` and `validate_and_fix_blocks`
+- `validate_blocks`
 - `take_screenshot` and `inspect_design`
 
 Use the CLI for:
@@ -63,11 +63,12 @@ Use direct file edits for theme and plugin files when writing code.
 6. Use `wp_cli` for arbitrary WordPress operations instead of dropping to the shell.
 7. If MCP is unavailable or not the right tool for the task, fall back to the smallest `studio` CLI command that gets the job done.
 8. Quote and escape user-provided shell arguments when using the CLI fallback.
-9. After every file write, file edit, or `wp_cli` content update that contains serialized WordPress block markup, run `validate_html_blocks` first when the content may contain `core/html` blocks, then run `validate_and_fix_blocks`.
-10. If `validate_html_blocks` or `validate_and_fix_blocks` reports invalid blocks, treat that as a required fix step:
-   - use the reported `Expected` versus `Actual` markup to identify the serialization mismatch
-   - repair the block markup instead of leaving invalid content in place
-   - re-run `validate_html_blocks` or `validate_and_fix_blocks`, as appropriate
+9. After every file write, file edit, or `wp_cli` content update that contains serialized WordPress block markup, run `validate_blocks`. Prefer the `filePath` argument when the content lives in a template, template part, pattern, or other file.
+10. Treat every `validate_blocks` issue as a required fix step:
+   - if the static `core/html` policy reports invalid HTML blocks, rewrite those blocks as editable core or plugin blocks before calling `validate_blocks` again
+   - once the HTML policy passes, use the live-editor validation report to identify serialization mismatches
+   - when `validate_blocks` applies an auto-fix to a file, do not manually replace the file content; review the returned diff only for class, nesting, or CSS-selector follow-up
+   - for inline content, use the returned fixed block content exactly when an auto-fix is proposed
    - repeat until the report shows all blocks valid
 11. After visible site changes, use `take_screenshot` to review the result on desktop and mobile when layout or styling matters.
 12. When screenshots reveal a layout or styling issue, use `inspect_design` before editing CSS so the fix targets the element carrying the rendered style.
@@ -79,7 +80,7 @@ Use direct file edits for theme and plugin files when writing code.
 - Prefer MCP tools over shell commands when both can accomplish the task.
 - Validate theme and plugin slugs before using them in paths or commands.
 - Do not invent site paths; derive them from Studio tools or the Studio home.
-- Serialized block content must not be left unvalidated. `validate_and_fix_blocks` is mandatory after block-content writes or updates.
+- Serialized block content must not be left unvalidated. `validate_blocks` is mandatory after block-content writes or updates.
 - Keep review loops proportional to the task; do not force screenshots or validation when they add no value.
 - Do not place generated artifacts in the agent launch directory by default. Use the selected Studio site path.
 - If the user asks for performance, accessibility, or broader frontend QA, hand off to `auditing` rather than embedding that workflow here.

plugins/codex/plugins/wordpress-studio/skills/studio/SKILL.md

@@ -37,7 +37,7 @@ Use MCP for:
 - `wp_cli`
 - audits
 - workflow telemetry
-- `validate_html_blocks` and `validate_and_fix_blocks`
+- `validate_blocks`
 - `take_screenshot` and `inspect_design`
 
 Use the CLI for:
@@ -63,11 +63,12 @@ Use direct file edits for theme and plugin files when writing code.
 6. Use `wp_cli` for arbitrary WordPress operations instead of dropping to the shell.
 7. If MCP is unavailable or not the right tool for the task, fall back to the smallest `studio` CLI command that gets the job done.
 8. Quote and escape user-provided shell arguments when using the CLI fallback.
-9. After every file write, file edit, or `wp_cli` content update that contains serialized WordPress block markup, run `validate_html_blocks` first when the content may contain `core/html` blocks, then run `validate_and_fix_blocks`.
-10. If `validate_html_blocks` or `validate_and_fix_blocks` reports invalid blocks, treat that as a required fix step:
-   - use the reported `Expected` versus `Actual` markup to identify the serialization mismatch
-   - repair the block markup instead of leaving invalid content in place
-   - re-run `validate_html_blocks` or `validate_and_fix_blocks`, as appropriate
+9. After every file write, file edit, or `wp_cli` content update that contains serialized WordPress block markup, run `validate_blocks`. Prefer the `filePath` argument when the content lives in a template, template part, pattern, or other file.
+10. Treat every `validate_blocks` issue as a required fix step:
+   - if the static `core/html` policy reports invalid HTML blocks, rewrite those blocks as editable core or plugin blocks before calling `validate_blocks` again
+   - once the HTML policy passes, use the live-editor validation report to identify serialization mismatches
+   - when `validate_blocks` applies an auto-fix to a file, do not manually replace the file content; review the returned diff only for class, nesting, or CSS-selector follow-up
+   - for inline content, use the returned fixed block content exactly when an auto-fix is proposed
    - repeat until the report shows all blocks valid
 11. After visible site changes, use `take_screenshot` to review the result on desktop and mobile when layout or styling matters.
 12. When screenshots reveal a layout or styling issue, use `inspect_design` before editing CSS so the fix targets the element carrying the rendered style.
@@ -79,7 +80,7 @@ Use direct file edits for theme and plugin files when writing code.
 - Prefer MCP tools over shell commands when both can accomplish the task.
 - Validate theme and plugin slugs before using them in paths or commands.
 - Do not invent site paths; derive them from Studio tools or the Studio home.
-- Serialized block content must not be left unvalidated. `validate_and_fix_blocks` is mandatory after block-content writes or updates.
+- Serialized block content must not be left unvalidated. `validate_blocks` is mandatory after block-content writes or updates.
 - Keep review loops proportional to the task; do not force screenshots or validation when they add no value.
 - Do not place generated artifacts in the agent launch directory by default. Use the selected Studio site path.
 - If the user asks for performance, accessibility, or broader frontend QA, hand off to `auditing` rather than embedding that workflow here.

plugins/copilot/skills/studio/SKILL.md

@@ -37,7 +37,7 @@ Use MCP for:
 - `wp_cli`
 - audits
 - workflow telemetry
-- `validate_html_blocks` and `validate_and_fix_blocks`
+- `validate_blocks`
 - `take_screenshot` and `inspect_design`
 
 Use the CLI for:
@@ -63,11 +63,12 @@ Use direct file edits for theme and plugin files when writing code.
 6. Use `wp_cli` for arbitrary WordPress operations instead of dropping to the shell.
 7. If MCP is unavailable or not the right tool for the task, fall back to the smallest `studio` CLI command that gets the job done.
 8. Quote and escape user-provided shell arguments when using the CLI fallback.
-9. After every file write, file edit, or `wp_cli` content update that contains serialized WordPress block markup, run `validate_html_blocks` first when the content may contain `core/html` blocks, then run `validate_and_fix_blocks`.
-10. If `validate_html_blocks` or `validate_and_fix_blocks` reports invalid blocks, treat that as a required fix step:
-   - use the reported `Expected` versus `Actual` markup to identify the serialization mismatch
-   - repair the block markup instead of leaving invalid content in place
-   - re-run `validate_html_blocks` or `validate_and_fix_blocks`, as appropriate
+9. After every file write, file edit, or `wp_cli` content update that contains serialized WordPress block markup, run `validate_blocks`. Prefer the `filePath` argument when the content lives in a template, template part, pattern, or other file.
+10. Treat every `validate_blocks` issue as a required fix step:
+   - if the static `core/html` policy reports invalid HTML blocks, rewrite those blocks as editable core or plugin blocks before calling `validate_blocks` again
+   - once the HTML policy passes, use the live-editor validation report to identify serialization mismatches
+   - when `validate_blocks` applies an auto-fix to a file, do not manually replace the file content; review the returned diff only for class, nesting, or CSS-selector follow-up
+   - for inline content, use the returned fixed block content exactly when an auto-fix is proposed
    - repeat until the report shows all blocks valid
 11. After visible site changes, use `take_screenshot` to review the result on desktop and mobile when layout or styling matters.
 12. When screenshots reveal a layout or styling issue, use `inspect_design` before editing CSS so the fix targets the element carrying the rendered style.
@@ -79,7 +80,7 @@ Use direct file edits for theme and plugin files when writing code.
 - Prefer MCP tools over shell commands when both can accomplish the task.
 - Validate theme and plugin slugs before using them in paths or commands.
 - Do not invent site paths; derive them from Studio tools or the Studio home.
-- Serialized block content must not be left unvalidated. `validate_and_fix_blocks` is mandatory after block-content writes or updates.
+- Serialized block content must not be left unvalidated. `validate_blocks` is mandatory after block-content writes or updates.
 - Keep review loops proportional to the task; do not force screenshots or validation when they add no value.
 - Do not place generated artifacts in the agent launch directory by default. Use the selected Studio site path.
 - If the user asks for performance, accessibility, or broader frontend QA, hand off to `auditing` rather than embedding that workflow here.