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 blueprintInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
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.
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 foundOur 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.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| blueprint (this skill)by WordPress | 94 | 2.2k | 54d ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.1k | today | CLAUDE.md |
| claude-howtoby luongnv89 | 100 | 47.3k | 2d ago | CLAUDE.md |
| lobehubby lobehub | 100 | 85.6k | today | MCP 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.
Skill content
View source on GitHubname: 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 acceptsfalsefor PHP-only Playground; do not combinewp: falsewith WordPress-only fields such asplugins,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 setrefType("branch"|"tag"|"commit"|"refname"). Without it, only"HEAD"resolves reliably. pathselects 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 ?>"
}
}
}
filesuses 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 deprecatedpluginZipFile/themeZipFile. pluginData/themeDataaccept any FileReference or DirectoryReference — a zip URL, awordpress.org/pluginsslug, agit:directory, or aliteral:directory(nozipwrapper needed).options.activatecontrols activation. No need for a separateactivatePlugin/activateThemestep when usinginstallPlugin/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
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
ai-job-search
72.1kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
claude-howto
47.3kA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
lobehub
85.6k🤯 LobeHub - Super-Agents on Your Team. Add super-agents to the chats your team already uses.They take on work by themselves and get better every week.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
