build-theme

Build Theme Skill

Selects, installs, and activates a Full Site Editing (FSE) block theme from WP.org based on the user's natural language site description. This skill queries the WP.org Themes API v1.2 for FSE themes, evaluates results against the NL prompt using Claude's in-context judgment, and installs the best match. A curated fallback list provides guaranteed theme selection when the API returns poor results or is unavailable.

Critical sequencing: This skill runs AFTER build-mcp Section 2 (MCP adapter activated, DB re-exported) and BEFORE build-content (content seeding requires the theme to be active for menu location discovery).

This skill expects the following variables to already be set by the calling command:

• BUILD_DIR — absolute path to the build directory (set by build-scaffold Section 2)
• WP — the WP-CLI command prefix (e.g., wp --path=$BUILD_DIR or the Docker equivalent, set by build-scaffold Section 4)
• NL_PROMPT — the user's natural language site description string
• SITE_TITLE — site title derived from the NL prompt (set by the calling command before this skill)

Section 1: WP.org Themes API Query

Query the WP.org Themes API v1.2 for the FSE block theme pool. Use the full-site-editing tag to filter — this is the canonical public signal for FSE/block themes. Do NOT combine search and tag parameters: the API ignores tags when search is present. Claude evaluates theme relevance in-context after fetching the pool.

echo "[Build] Querying WP.org Themes API for FSE theme pool..."

# CRITICAL anti-pattern: Do NOT use ?action=query_themes&request[search]=...&request[tag][]=full-site-editing
# The API ignores tag[] when search is present. Use tag-only query; Claude evaluates relevance in-context.

FSE_THEMES_FILE="/tmp/fse_themes_$$.json"

curl -s --max-time 10 \
  "https://api.wordpress.org/themes/info/1.2/?action=query_themes&request[tag][]=full-site-editing&request[browse]=popular&request[per_page]=50&request[fields][active_installs]=true&request[fields][rating]=true&request[fields][description]=true&request[fields][tags]=true" \
  -o "$FSE_THEMES_FILE"
CURL_EXIT=$?

# Validate response — check exit code, non-empty file, and JSON structure
API_AVAILABLE=false
if [ $CURL_EXIT -eq 0 ] && [ -s "$FSE_THEMES_FILE" ]; then
  # Count themes in response — need at least 3 for Claude to evaluate properly
  THEME_COUNT=$(python3 -c "import json,sys; d=json.load(open(sys.argv[1])); print(len(d.get('themes', [])))" "$FSE_THEMES_FILE" 2>/dev/null || echo "0")
  if [ "$THEME_COUNT" -ge 3 ]; then
    API_AVAILABLE=true
    echo "[Build] WP.org API returned $THEME_COUNT FSE themes for evaluation."
  else
    echo "[Build] WP.org API returned fewer than 3 themes ($THEME_COUNT). Falling back to curated list."
  fi
else
  echo "[Build] WP.org API unavailable — using curated theme list"
fi