SkillAgentSearch skills...

blueprint

Use when the deliverable is WordPress Playground Blueprint JSON or a Blueprint bundle, including creating, editing, reviewing, validating schema keys, choosing steps/resources, and debugging Blueprint files. For only running or sharing a Playground environment, use wp-playground.

Install / Use

npx skills add WordPress/agent-skills --skill blueprint

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

94/100

Supported Platforms

Universal

Our assessment of blueprint

blueprint scores 94/100 on our quality scale, 524th of 4,698 Development & Engineering skills we index (top 12%).

Its SKILL.md is 16 KB long, well organised into 33 sections with 29 code examples: a thorough specification that gives an agent plenty to work with.

With 2,162 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
30/30
Structure
20/20
Description
15/15
Adoption
14/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so blueprint is actively maintained.
  • Our last check on 2026-11-16 found the source still online.
  • No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
  • Its trust signals score 88/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-09-29. Automated pattern scan on 2026-09-29. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

blueprint compared with similar skills

All 4 of these similar skills score higher than blueprint; compare them before choosing.

SkillScoreStarsUpdatedFormat
blueprint (this skill)by WordPress942.2k54d agoSKILL.md
taste-skillby Leonxlnx100116.8k8d agoCLAUDE.md
ai-job-searchby ai-job-search-dev10072.1ktodayCLAUDE.md
claude-howtoby luongnv8910047.3k2d agoCLAUDE.md
lobehubby lobehub10085.6ktodayMCP Server

Frequently asked questions

How do I install blueprint?
Run npx skills add WordPress/agent-skills --skill blueprint. The install tabs above show the steps for each supported agent.
Which AI agents does blueprint work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is blueprint safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 88/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is blueprint still maintained?
The repository was last updated about 2 months ago, so blueprint is actively maintained.

name: blueprint description: Use when the deliverable is WordPress Playground Blueprint JSON or a Blueprint bundle, including creating, editing, reviewing, validating schema keys, choosing steps/resources, and debugging Blueprint files. For only running or sharing a Playground environment, use wp-playground. compatibility: "WordPress 7.0+, PHP 7.4.0+. Optionally Playground CLI or a browser"

WordPress Playground Blueprints

Overview

A Blueprint is a JSON file that declaratively configures a WordPress Playground instance — installing plugins/themes, setting options, running PHP/SQL, manipulating files, and more.

Core principle: Blueprints are trusted JSON-only declarations. No arbitrary JavaScript. They work on web, Node.js, and CLI.

Quick Start Template

{
  "$schema": "https://playground.wordpress.net/blueprint-schema.json",
  "landingPage": "/wp-admin/",
  "preferredVersions": { "php": "8.3", "wp": "latest" },
  "steps": [{ "step": "login" }]
}

Top-Level Properties

All optional. Only documented keys are allowed — the schema rejects unknown properties.

| Property | Type | Notes | |----------|------|-------| | $schema | string | Always "https://playground.wordpress.net/blueprint-schema.json" | | landingPage | string | Relative path, e.g. /wp-admin/ | | description | string | Deprecated optional top-level description. Prefer meta.description for new Blueprints | | meta | object | { title, author, description?, categories? } — title and author required | | preferredVersions | object | { php, wp } — both required when present | | features | object | { networking?: boolean, intl?: boolean } — only these two keys, nothing else. Networking defaults to true | | phpExtensionBundles | any | Deprecated/no longer used; the schema leaves the value unconstrained and says to remove it from Blueprints | | extraLibraries | array | ["wp-cli"] — auto-included when any wp-cli step is present | | constants | object | Shorthand for defineWpConfigConsts. Values: string/boolean/number | | plugins | array | Shorthand for installPlugin steps. Strings = wp.org slugs | | siteOptions | object | Shorthand for setSiteOptions | | login | boolean or object | true = login as admin. Object = { username?, password? } (both default to "admin"/"password") | | steps | array | Main execution pipeline. Runs after shorthands |

preferredVersions Values

  • php: Major.minor only: "7.4", "8.0", "8.1", "8.2", "8.3", "8.4", "8.5", or "latest". Patch versions like "7.4.1" are invalid. Check the schema for currently supported versions.
  • wp: Recent major versions, "latest", "beta", "nightly"/"trunk", or a URL to a custom zip. The schema also accepts false for PHP-only Playground; do not combine wp: false with WordPress-only fields such as plugins, siteOptions, login, or WordPress-only steps.

Shorthands vs Steps

Shorthands (login, plugins, siteOptions, constants) are expanded and prepended to steps in an unspecified order. Use explicit steps when execution order matters.

Resource References

Resources tell Playground where to find files. Used by installPlugin, installTheme, writeFile, writeFiles, importWxr, etc.

| Resource Type | Required Fields | Example | |--------------|----------------|---------| | wordpress.org/plugins | slug | { "resource": "wordpress.org/plugins", "slug": "woocommerce" } | | wordpress.org/themes | slug | { "resource": "wordpress.org/themes", "slug": "astra" } | | url | url | { "resource": "url", "url": "https://example.com/plugin.zip" } | | git:directory | url, ref | See below | | literal | name, contents | { "resource": "literal", "name": "file.txt", "contents": "hello" } | | literal:directory | name, files | See below | | bundled | path | References a file within a blueprint bundle (e.g. { "resource": "bundled", "path": "/plugin.zip" }) | | zip | inner | Wraps another resource in a ZIP — use when a step expects a zip but your source isn't one (e.g. wrapping a url resource pointing to a raw directory) |

git:directory — Installing from GitHub

{
  "resource": "git:directory",
  "url": "https://github.com/WordPress/gutenberg",
  "ref": "trunk",
  "refType": "branch",
  "path": "/"
}
  • When using a branch or tag name for ref, you must set refType ("branch" | "tag" | "commit" | "refname"). Without it, only "HEAD" resolves reliably.
  • path selects a subdirectory (defaults to repo root).

literal:directory — Inline File Trees

{
  "resource": "literal:directory",
  "name": "my-plugin",
  "files": {
    "plugin.php": "<?php /* Plugin Name: My Plugin */ ?>",
    "includes": {
      "helper.php": "<?php // helper code ?>"
    }
  }
}
  • files uses nested objects for subdirectories — keys are filenames or directory names, values are plain strings (file content) or objects (subdirectories). Never use resource references as values.
  • Do NOT use path separators in keys (e.g. "includes/helper.php" is wrong — use a nested "includes": { "helper.php": "..." } object).

Steps Reference

Every step requires "step": "<name>". Any step can optionally include "progress": { "weight": 1, "caption": "Installing..." } for UI feedback.

Plugin & Theme Installation

{
  "step": "installPlugin",
  "pluginData": { "resource": "wordpress.org/plugins", "slug": "gutenberg" },
  "options": { "activate": true, "targetFolderName": "gutenberg" },
  "ifAlreadyInstalled": "overwrite"
}
{
  "step": "installTheme",
  "themeData": { "resource": "wordpress.org/themes", "slug": "twentytwentyfour" },
  "options": { "activate": true, "importStarterContent": true },
  "ifAlreadyInstalled": "overwrite"
}
  • Use pluginData / themeData — NOT the deprecated pluginZipFile / themeZipFile.
  • pluginData / themeData accept any FileReference or DirectoryReference — a zip URL, a wordpress.org/plugins slug, a git:directory, or a literal:directory (no zip wrapper needed).
  • options.activate controls activation. No need for a separate activatePlugin/activateTheme step when using installPlugin/installTheme.
  • ifAlreadyInstalled: "overwrite" | "skip" | "error"

Activation (standalone)

Only needed for plugins/themes already on disk (e.g. after writeFile/writeFiles):

{ "step": "activatePlugin", "pluginPath": "my-plugin/my-plugin.php" }
{ "step": "activateTheme", "themeFolderName": "twentytwentyfour" }

File Operations

{ "step": "writeFile", "path": "/wordpress/wp-content/mu-plugins/custom.php", "data": "<?php // code" }

data accepts a plain string (as shown above) or a resource reference (e.g. { "resource": "url", "url": "https://..." }).

{
  "step": "writeFiles",
  "writeToPath": "/wordpress/wp-content/plugins/",
  "filesTree": {
    "resource": "literal:directory",
    "name": "my-plugin",
    "files": {
      "plugin.php": "<?php\n/*\nPlugin Name: My Plugin\n*/",
      "includes": {
        "helpers.php": "<?php // helpers"
      }
    }
  }
}

writeFiles requires a DirectoryReference (literal:directory or git:directory) as filesTree — not a plain object.

Other file operations: mkdir, cp, mv, rm, rmdir, unzip.

Running Code

runPHP:

{ "step": "runPHP", "code": "<?php require '/wordpress/wp-load.php'; update_option('key', 'value');" }

GOTCHA: You must require '/wordpress/wp-load.php'; to use any WordPress functions.

wp-cli:

{ "step": "wp-cli", "command": "wp post create --post_type=page --post_title='Hello' --post_status=publish" }

The step name is wp-cli (with hyphen), NOT cli or wpcli.

runSql:

{ "step": "runSql", "sql": { "resource": "literal", "name": "q.sql", "contents": "UPDATE wp_options SET option_value='val' WHERE option_name='key';" } }

Site Configuration

{ "step": "setSiteOptions", "options": { "blogname": "My Site", "blogdescription": "A tagline" } }
{ "step": "defineWpConfigConsts", "consts": { "WP_DEBUG": true } }
{ "step": "setSiteLanguage", "language": "en_US" }
{ "step": "defineSiteUrl", "siteUrl": "https://example.com" }

Other Steps

| Step | Key Properties | |------|---------------| | login | username?, password? (default "admin" / "password") | | enableMultisite | (no required props) | | importWxr | file (FileReference) | | importThemeStarterContent | themeSlug? | | importWordPressFiles | wordPressFilesZip, pathInZip? — imports a full WordPress directory from a zip | | request | request: { url, method?, headers?, body? } | | updateUserMeta | userId, meta | | runWpInstallationWizard | options? — runs the WP install wizard with given options | | resetData | (no props) |

Common Patterns

Inline mu-plugin (quick custom code)

{
  "step": "writeFile",
  "path": "/wordpress/wp-content/mu-plugins/custom.php",
  "data": "<?php\n// mu-plugins load automatically — no activation needed, no require wp-load.php\nadd_filter('show_admin_bar', '__return_false');"
}

Inline plugin with multiple files

{
  "step": "writeFiles",
  "writeToPath": "/wordpress/wp-content/plugins/",
  "filesTree": {
    "resource": "literal:directory",
    "name": "my-plugin",
    "files": {
      "my-plugin.php": "<?php\n/*\nPlugin Name: My Plugin\n*/\nrequire __DIR__ . '/includes/main.php';",
      "includes": {
        "main.php": "<?php // main logic"
      }
    }
  }
}

Then activate it with a separate step:

{ "step": "activatePlugin", "pluginPath": "my-plugin/my-plugin.php" }

Plugin from a GitHub branch

{
  "step": "installPlugin",
  "pluginData": {
    "resource": "git:directory",
    "url": "https://github.com/user/repo",
    "ref": "feature-branch",
    "refType": "branch",
    "path": "/"
  }
}

Common Mistakes

| Mistake | Correct | |---------|---------| | pluginZipFile / themeZipFile | pluginData / themeData | | "step": "cli" | "step": "wp-cli" | | Flat object as writeFiles.filesTree | Must be a literal:directory or git:directory resource | | Path separators in files keys | Use nested objects for subdirectories | | runPHP without wp-load.php | Always require '/wordpress/wp-load.php'; for WP functions | | Invented top-level keys | Only documented keys work — schema rejects unknown properties | | Inventing proxy URLs for GitHub | Use git:directory resource type | | Omitting refType with branch/tag ref | Required — only "HEAD" works without it | | Resource references in literal:directory files values | Values must be plain strings (content) or objects (subdirectories) — never resource refs | | features.debug or other invented feature keys | features only supports networking and intl — use constants: { "WP_DEBUG": true } for debug mode | | require wp-load.php in mu-plugin code | Only needed in runPHP steps — mu-plugins already run within WordPress | | Schema URL with .org domain | Must be playground.wordpress.net, not playground.wordpress.org |

Full Reference

This skill covers the most common steps and patterns. For the complete API, see:

  • Blueprint docs: https://wordpress.github.io/wordpress-playground/blueprints
  • JSON schema: https://playground.wordpress.net/blueprint-schema.json

Additional steps not covered above: runPHPWithOptions (run PHP with custom ini settings), runWpInstallationWizard, and resource types vfs and bundled (for advanced embedding scenarios).

Blueprint Bundles

Bundles are self-contained packages that include a blueprint.json along with all the resources it references (plugins, themes, WXR files, etc.). Instead of hosting assets externally, bundle them

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars2.2k
CategoryDevelopment
Updated1mo ago
Forks322

Languages

JavaScript

Trust signals

88/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 medium
blueprint — Universal Skill: Install & Safety Check | SkillAgent