{"id":51007567,"url":"https://github.com/siddik-web/wp-block-theme-converter","last_synced_at":"2026-06-20T22:01:51.228Z","repository":{"id":354794473,"uuid":"1214961788","full_name":"siddik-web/wp-block-theme-converter","owner":"siddik-web","description":"A Claude skill for converting any HTML/CSS/JavaScript project into a production-ready WordPress Block Theme (Full Site Editing).","archived":false,"fork":false,"pushed_at":"2026-05-30T14:59:06.000Z","size":455,"stargazers_count":31,"open_issues_count":0,"forks_count":12,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-30T16:20:57.738Z","etag":null,"topics":["claude-skills","html","wordpress","wordpress-theme"],"latest_commit_sha":null,"homepage":"","language":"Go Template","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/siddik-web.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-19T09:38:51.000Z","updated_at":"2026-05-30T14:59:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/siddik-web/wp-block-theme-converter","commit_stats":null,"previous_names":["siddik-web/wp-block-theme-converter"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/siddik-web/wp-block-theme-converter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siddik-web%2Fwp-block-theme-converter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siddik-web%2Fwp-block-theme-converter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siddik-web%2Fwp-block-theme-converter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siddik-web%2Fwp-block-theme-converter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/siddik-web","download_url":"https://codeload.github.com/siddik-web/wp-block-theme-converter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siddik-web%2Fwp-block-theme-converter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34586666,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-20T02:00:06.407Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-skills","html","wordpress","wordpress-theme"],"created_at":"2026-06-20T22:01:50.420Z","updated_at":"2026-06-20T22:01:51.221Z","avatar_url":"https://github.com/siddik-web.png","language":"Go Template","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WordPress Block Theme Converter Skill\n\nA Claude Code plugin (and standalone skill) for converting any HTML/CSS/JavaScript project into a production-ready WordPress Block Theme (Full Site Editing).\n\n**Author:** Md Siddiqur Rahman\n**Version:** 2.0.0\n**License:** MIT\n\n---\n\n## What This Skill Does\n\nConverts static HTML/CSS/JavaScript projects into complete, production-ready WordPress block themes that are:\n\n- ✅ Compatible with WordPress 6.5+\n- ✅ Full Site Editing (FSE) ready\n- ✅ Accessible (WCAG 2.1 AA)\n- ✅ Performance-optimized (Core Web Vitals)\n- ✅ Translation-ready (i18n)\n- ✅ WooCommerce-compatible (optional)\n- ✅ WordPress.org Theme Directory submission-ready\n- ✅ CI/CD pipeline ready (GitHub Actions)\n- ✅ E2E tested (Playwright)\n\n## Custom Slash Commands\n\n| Command | Purpose |\n|---------|---------|\n| `/convert-to-wp-theme` | Full conversion of HTML/CSS/JS project to complete block theme |\n| `/scaffold-wp-theme` | Create empty block theme scaffold (no source needed) |\n| `/wp-pattern` | Convert single HTML section into a registered block pattern |\n| `/wp-theme-json` | Generate theme.json from CSS custom properties / design tokens |\n| `/wp-template` | Convert single HTML page into FSE template |\n| `/wp-block` | Scaffold a custom block (block.json, edit.js, save.js/render.php, CSS) |\n| `/wp-migrate` | Migrate existing WP content (Classic Editor, ACF, widgets, CPTs, shortcodes) to block theme |\n| `/wp-plugin-theme` | Declare plugin dependencies and generate plugin-specific CSS / compatibility code |\n| `/wp-variation` | Generate a style variation (styles/*.json) — dark mode, color palette swap, font swap |\n| `/wp-classic-to-fse` | Convert an existing WordPress classic theme (PHP templates) to FSE block theme |\n| `/wp-debug` | Diagnose and fix FSE/block-theme failures — block validation errors, theme.json issues, patterns not showing, DB template overrides, PHP warnings, and more |\n\n## Installation\n\n### Option 1: Claude Code plugin (recommended)\n\nThis repository is also a Claude Code **plugin marketplace**. Install it\ndirectly from GitHub:\n\n```bash\n# Run these inside Claude Code:\n/plugin marketplace add siddik-web/wp-block-theme-converter\n/plugin install wp-block-theme-converter@siddik-web\n```\n\nInstalling the plugin registers everything at once:\n\n- All **11 slash commands** (`/convert-to-wp-theme`, `/wp-debug`, …)\n- The **`wp-block-theme-converter` skill** (auto-triggers on WordPress requests)\n- The **`wp-theme-reviewer` agent** for auditing generated themes\n- A non-blocking **`theme.json` validation hook** that runs after edits\n\nManage or disable it any time with `/plugin`.\n\n### Option 2: Claude Code skill (manual)\n\n1. Download or clone this repository\n2. Place the folder in your Claude Code skills directory:\n\n   ```bash\n   ~/.claude/skills/wp-block-theme-converter/\n   ```\n\n3. Restart Claude Code or run `claude reload`\n4. Verify: type any of the slash commands listed above\n\n### Option 3: Claude.ai (Project Skills)\n\n1. Open a Claude.ai Project\n2. Project settings → Skills → Upload Skill\n3. Upload `wp-block-theme-converter.skill`\n4. The skill will be available in all conversations within that project\n\n### Option 4: Manual (Cowork / Other Environments)\n\nPlace the `wp-block-theme-converter/` folder in your skills directory. Path varies by environment:\n\n- Cowork: `~/skills/`\n- Custom: Configure via `CLAUDE_SKILLS_DIR` environment variable\n\n## Usage\n\n### Basic Workflow\n\n1. **Open a conversation with Claude** (Code, Desktop, or Web)\n2. **Invoke a slash command** OR describe your task in natural language\n3. **Provide your source HTML/CSS/JS** (paste or attach files)\n4. **Claude generates the complete theme** following the 10-phase methodology\n5. **Download/copy the files** and install in WordPress\n\n### Example: Quick Landing Page\n\n```\n/convert-to-wp-theme\n\nI have a 3-page landing site for \"Acme Co\".\nUse Vite 6, no WooCommerce.\n\n[paste HTML/CSS/JS]\n```\n\n### Example: WooCommerce Theme\n\n```\n/convert-to-wp-theme\n\nConvert my Northaven Co. eCommerce design system to a WooCommerce block theme.\nInclude all six aesthetics as style variations.\n\n[attach HTML files]\n```\n\n### Example: Pattern Only\n\n```\n/wp-pattern\n\nConvert this hero section into a WP block pattern:\n\n\u003csection class=\"hero\"\u003e\n  \u003ch1\u003eWelcome\u003c/h1\u003e\n  \u003cp\u003eSubheading\u003c/p\u003e\n  \u003ca href=\"#\" class=\"btn\"\u003eCTA\u003c/a\u003e\n\u003c/section\u003e\n```\n\n### Example: Custom Block\n\n```\n/wp-block\n\nScaffold a \"Testimonial Slider\" custom block with server-side rendering,\nan edit.js with InspectorControls, and per-block CSS.\n```\n\n### Example: Classic Theme Migration\n\n```\n/wp-classic-to-fse\n\nConvert my existing classic PHP theme to a full FSE block theme.\nThe theme uses a custom page builder and ACF fields.\n```\n\n## Plugin Structure\n\n```\nwp-block-theme-converter/                 # Plugin root (also a marketplace)\n├── .claude-plugin/\n│   ├── plugin.json                       # Plugin manifest\n│   └── marketplace.json                  # Marketplace entry (installable)\n│\n├── SKILL.md                              # The bundled skill (auto-triggers)\n├── README.md                             # This file\n│\n├── commands/                             # 11 slash command definitions\n│   ├── convert-to-wp-theme.md\n│   ├── scaffold-wp-theme.md\n│   ├── wp-block.md\n│   ├── wp-classic-to-fse.md\n│   ├── wp-debug.md\n│   ├── wp-migrate.md\n│   ├── wp-pattern.md\n│   ├── wp-plugin-theme.md\n│   ├── wp-template.md\n│   ├── wp-theme-json.md\n│   └── wp-variation.md\n│\n├── agents/                               # Subagents\n│   └── wp-theme-reviewer.md              # Audits a generated block theme\n│\n├── hooks/\n│   └── hooks.json                        # PostToolUse theme.json validation\n│\n├── references/                           # Detailed reference docs\n│   ├── defaults.md                       # Default values for placeholders\n│   ├── methodology.md                    # 10-phase conversion methodology\n│   ├── modern-blocks.md                  # WordPress 6.5+ features (Interactivity API, Block Bindings, etc.)\n│   ├── file-structure.md                 # Required output directory layout\n│   ├── block-conversion-map.md           # HTML → WP block lookup table\n│   ├── theme-json-schema.md              # theme.json v3 reference\n│   ├── quality-rules.md                  # Non-negotiable do's and don'ts\n│   ├── multi-turn-strategy.md            # Splitting large projects\n│   ├── woocommerce.md                    # WC-specific theming\n│   ├── validation-checklist.md           # Post-generation checks\n│   ├── custom-blocks.md                  # Custom block development (block.json, edit.js, render.php)\n│   ├── content-migration.md              # Classic-to-block, WP-CLI, ACF, CPTs, page builder migration\n│   ├── asset-optimization.md             # Fonts, images, WebP, lazy load, Core Web Vitals\n│   ├── plugin-compatibility.md           # Plugin detection, CSS conflicts, caching compat\n│   ├── interactivity-api-advanced.md     # Shared store, server hydration, async, focus traps\n│   ├── accessibility.md                  # WCAG 2.1 AA, ARIA, skip links, screen reader testing\n│   ├── ci-cd.md                          # GitHub Actions, PHPCS, ESLint, Stylelint, deployment\n│   ├── backward-compatibility.md         # Feature availability by WP version, conditional loading\n│   ├── e2e-testing.md                    # Playwright, visual regression, a11y scans, CI integration\n│   └── i18n.md                           # i18n functions, plural forms, JS translations, RTL\n│\n├── templates/                            # Reusable boilerplate\n│   ├── style.css.tpl\n│   ├── theme.json.tpl\n│   ├── functions.php.tpl\n│   ├── pattern-header.php.tpl\n│   ├── template-skeleton.html.tpl\n│   ├── package.json.tpl\n│   ├── vite.config.js.tpl\n│   ├── github-actions-ci.yml.tpl\n│   └── patterns/\n│       ├── hero.php.tpl\n│       ├── features-grid.php.tpl\n│       ├── testimonials.php.tpl\n│       ├── pricing-table.php.tpl\n│       ├── cta-section.php.tpl\n│       ├── faq-accordion.php.tpl\n│       ├── team-grid.php.tpl\n│       └── stats-row.php.tpl\n│\n├── examples/                             # Worked examples\n│   ├── northaven-ecommerce.md            # Multi-aesthetic WooCommerce theme\n│   └── landing-page-simple.md            # Simple SaaS landing page\n│\n└── scripts/                              # Validation + packaging tooling\n    ├── doctor.mjs                        # Runs all four theme-quality checks\n    ├── validate-skill.mjs                # Skill integrity linter\n    ├── validate-plugin.mjs               # Plugin packaging linter\n    └── hooks/\n        └── theme-json-postwrite.mjs      # theme.json validation hook runner\n```\n\n## How It Works\n\n### Progressive Disclosure\n\nThe skill uses Claude's three-level loading:\n\n1. **SKILL.md metadata** — always in context (~100 words)\n2. **SKILL.md body** — loaded when skill triggers (~400 lines)\n3. **Reference files** — loaded on-demand as needed\n\nThis means Claude doesn't load the WooCommerce reference for a simple landing page conversion — it only loads what's relevant to the task.\n\n### 10-Phase Methodology\n\nEvery conversion follows the same proven phases:\n\n1. **Audit \u0026 Extract** — parse source, identify reusable components\n2. **theme.json** — generate schema v3 with full settings + styles (incl. Section Styles, dimensions, position)\n3. **Templates \u0026 Parts** — convert HTML pages to FSE block markup\n4. **Block Patterns** — register sections as reusable patterns\n5. **Block Styles \u0026 Variations** — register custom variants via theme.json + PHP\n6. **JavaScript Integration** — Interactivity API for interactive patterns; classic enqueue for complex libs\n7. **functions.php \u0026 inc/** — bootstrap files (WP Coding Standards)\n8. **Accessibility \u0026 Performance** — WCAG 2.1 AA + Core Web Vitals + per-block CSS + font preloading\n9. **i18n** — translation-ready strings everywhere\n10. **README \u0026 Docs** — WordPress.org-format readme.txt\n\n### Multi-Turn for Large Projects\n\nThe skill automatically detects large projects and splits delivery across 3 turns:\n\n- **Turn 1:** Foundation (theme.json, templates, parts, functions.php)\n- **Turn 2:** Patterns + Block Styles + Style Variations\n- **Turn 3:** JavaScript + Assets + Docs\n\nTriggered when source has 10+ HTML pages OR WooCommerce OR multiple style variations.\n\n### Behavioral Principles\n\nEvery output is governed by four non-negotiable principles:\n\n1. **Think Before Coding** — surface assumptions, present tradeoffs, ask before guessing\n2. **Simplicity First** — minimum code that solves the problem; no speculative features\n3. **Surgical Changes** — touch only what the task requires; don't improve adjacent code\n4. **Goal-Driven Execution** — define verifiable success criteria before writing any file\n\n## Quality Guarantees\n\nEvery theme generated follows these non-negotiable rules:\n\n- ❌ NO inline `\u003cstyle\u003e` or `\u003cscript\u003e` tags\n- ❌ NO `style=\"\"` attributes (use block attributes)\n- ❌ NO hardcoded colors/spacing in CSS (use CSS custom properties)\n- ❌ NO unescaped output\n- ❌ NO direct database queries\n- ❌ NO Alpine.js for interactions the Interactivity API can handle\n- ❌ NO physical CSS directional properties (use logical properties for RTL)\n- ❌ NO speculative features the user didn't ask for\n- ✅ All strings translation-ready\n- ✅ Semantic HTML via `tagName`\n- ✅ theme.json as single source of truth\n- ✅ WCAG 2.1 AA compliant\n- ✅ Versioned assets for cache-busting\n- ✅ Interactivity API for interactive patterns (modals, tabs, toggles)\n- ✅ Per-block CSS loading via `wp_enqueue_block_style()`\n- ✅ Font preloading for critical fonts\n- ✅ Section Styles for coordinated dark/highlight sections\n- ✅ Editor parity — all frontend CSS mirrored in editor.css\n\n## Production / Reliability\n\n### Automated Output Verification\n\nEvery theme generated by this skill can be verified using the bundled scripts:\n\n```bash\n# Run all checks at once — exits 0 only if everything passes\nnode scripts/doctor.mjs path/to/your-theme\n\n# Or run individual checks\nnode scripts/validate-theme-json.mjs path/to/your-theme   # theme.json schema + token checks\nnode scripts/lint-block-markup.mjs path/to/your-theme     # inline styles/scripts, block delimiter integrity\nnode scripts/check-patterns.mjs path/to/your-theme        # pattern headers, slugs, duplicates\nnode scripts/check-i18n.mjs path/to/your-theme            # i18n coverage + anti-patterns\n```\n\nThe skill's Step 5 (Verify) instructs Claude to run `doctor.mjs` and **loop until it passes** before declaring a theme complete. No npm install required — pure Node stdlib.\n\n### Debugging Generated Themes\n\nIf something looks wrong after generation, use `/wp-debug`:\n\n```\n/wp-debug\n\nMy pattern doesn't appear in the inserter and I can't figure out why.\n```\n\nClaude will run through a decision tree, identify the root cause (missing category registration, theme.json conflict, etc.), and offer to apply the fix. See `references/troubleshooting.md` for the full symptom → cause → fix reference.\n\n### Page Builder Migration\n\nMoving off Elementor, Divi, WPBakery, or Beaver Builder? Use `/wp-migrate` — it now includes full builder-detection and per-builder playbooks. See `references/page-builder-migration.md` for element-to-block mapping tables, WP-CLI extraction commands, and a worked Elementor example in `examples/elementor-to-block-theme.md`.\n\n### Plugin \u0026 Skill Quality\n\nThe plugin ships with:\n\n- **`evals/`** — trigger/no-trigger/ambiguous test cases per command (see `evals/README.md`)\n- **`scripts/validate-skill.mjs`** — structural linter for the skill itself (checks command files exist, no dead links, frontmatter valid)\n- **`scripts/validate-plugin.mjs`** — packaging linter for the plugin manifest, marketplace entry, and components\n- **`scripts/build-skill.sh`** — produces the distributable `.skill` zip artifact\n- **`CHANGELOG.md`** — full version history\n- **`.github/workflows/skill-ci.yml`** — CI: validate-skill, validate-plugin, lint-scripts, doctor against golden theme, markdown lint\n\n## Compatibility\n\n- **Claude Code:** ✅ Full support (all slash commands)\n- **Claude.ai (Projects):** ✅ Full support\n- **Cowork:** ✅ Full support\n- **Anthropic API:** ✅ Works as a system prompt addendum\n\n## Tips for Best Results\n\n1. **Use Claude Opus** for the full conversion (`/convert-to-wp-theme`) — provides maximum context window for large outputs\n2. **Provide design tokens upfront** if your CSS doesn't use custom properties\n3. **For 10+ page projects**, expect 3 turns and have time to \"continue\" between them\n4. **For WooCommerce themes**, ensure WooCommerce will be installed on the target site\n5. **For classic theme migrations**, use `/wp-classic-to-fse` which handles ACF, CPTs, and page builder content\n6. **Validate theme.json** at https://www.jsonschemavalidator.net/ using schema URL `https://schemas.wp.org/trunk/theme.json` before deploying\n\n## Troubleshooting\n\n### \"The skill didn't trigger\"\n\n- Check that you used one of the trigger phrases or slash commands\n- Verify the skill is installed: list available skills with `/skills`\n- For natural language, use phrases like \"convert this to a WordPress theme\" or \"make this an FSE theme\"\n\n### \"The output is incomplete\"\n\n- Likely hit context limits — large projects need multi-turn delivery\n- Reply \"continue\" to get the next batch\n- Consider using `/scaffold-wp-theme` first, then `/wp-pattern` per section\n\n### \"theme.json doesn't validate\"\n\n- Ensure no trailing commas\n- Verify `version: 3` (not 1 or 2)\n- Check that all `fontFace.src` paths actually exist\n- Validate online at https://www.jsonschemavalidator.net/ using schema URL `https://schemas.wp.org/trunk/theme.json`\n\n### \"Classic theme migration isn't picking up my ACF fields\"\n\n- Use `/wp-migrate` with the ACF field group export (JSON) attached\n- The `references/content-migration.md` documents all supported field types and Block Bindings strategies\n\n### \"My Elementor / Divi / WPBakery site won't migrate cleanly\"\n\n- Use `/wp-migrate` — it detects your page builder and applies the correct strategy\n- See `references/page-builder-migration.md` for per-builder element→block mapping tables\n- See `examples/elementor-to-block-theme.md` for a complete worked migration example\n\n### \"Something else is broken and I don't know why\"\n\n- Use `/wp-debug` — describe your symptom and Claude will identify the root cause\n- See `references/troubleshooting.md` for the full 18-symptom reference with WP-CLI cheat sheet\n\n### \"My custom block isn't showing in the editor\"\n\n- Ensure `block.json` is in the correct directory and registered via `register_block_type()`\n- Check the browser console for JS errors from `edit.js`\n- Run `npm run build` if using a build step — the editor loads the compiled assets\n\n## Contributing\n\nTo improve this skill:\n\n1. Edit the relevant files in your local copy\n2. Test changes by running a conversion\n3. Compare output quality before/after\n4. Submit improvements via the source repository\n\n## License\n\nMIT License — free to use, modify, and distribute.\n\n## Credits\n\n- Based on Md Siddiqur Rahman's master prompt for WordPress Block Theme conversion\n- Methodology distilled from 10+ years of WordPress + Joomla extension development\n- Built for the EU remote WordPress freelance community\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsiddik-web%2Fwp-block-theme-converter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsiddik-web%2Fwp-block-theme-converter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsiddik-web%2Fwp-block-theme-converter/lists"}