feat: Add WordPress block theme development skills and utilities

.github/changelog.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this repository are documented in this file.
+
+## [0.1.0] - 2026-04-08
+
+### Added
+- Initial skills toolkit under `.github/skills/` with shared usage guidance and docs.
+- Spacing migration tooling and documentation:
+  - `spacing-mapper.cjs`
+  - `SPACING-MIGRATION.md`
+  - `SPACING-MAPPER-USAGE.md`
+- Inc folder formatter tooling and documentation:
+  - `inc-formatter.cjs`
+  - `INC-FORMATTER.md`
+  - `INC-FORMATTER-BUGFIX-REPORT.md`
+- WordPress Block Pattern Generator skill documentation and guide:
+  - `wordpress-block-pattern-generator.md`
+  - `wordpress-block-pattern-generator/SKILL.md`
+- WordPress Block Pattern Validator skill, validator script, and docs:
+  - `wordpress-block-pattern-validator/SKILL.md`
+  - `wordpress-block-pattern-validator/README.md`
+  - `wordpress-block-pattern-validator/validate-patterns.cjs`
+- WordPress Theme JSON Mapper skill and reference docs:
+  - `wordpress-theme-json-mapper/SKILL.md`
+  - `wordpress-theme-json-mapper/README.md`
+- New skill for modularising WordPress theme JSON into preset folders:
+  - `theme-json-to-preset-folders/SKILL.md`
+- Refactor report artifact:
+  - `bin/footer-sections-refactor-report.md`
+
+### Changed
+- Updated `.github/skills/README.md` to include the new Theme JSON to Preset Folders skill.
+- Enhanced WordPress Block Pattern Validator rules and documentation to cover:
+  - font family validation behaviour
+  - font size class validation
+  - non-WordPress comment detection
+  - navigation-related checks
+  - background image attribute handling
+  - button style class placement checks

.github/skills/PHASE-1-COMPLETION-REPORT.md

@@ -0,0 +1,338 @@
+# Phase 1 Completion Report: Structural Alignment
+
+**Date**: 2026-04-30  
+**Status**: ✅ **COMPLETED**
+
+---
+
+## Summary
+
+Successfully completed Phase 1: Structural Alignment with agentskills.io specification. All skills now follow the proper directory structure with YAML frontmatter, organized scripts, and reference documentation.
+
+---
+
+## Changes Implemented
+
+### 1. New Skill Directories Created ✅
+
+#### inc-formatter/
+```
+inc-formatter/
+├── SKILL.md (with frontmatter)
+├── scripts/
+│   └── inc-formatter.cjs
+└── references/
+    └── BUGFIX-REPORT.md
+```
+- **Migrated from**: `INC-FORMATTER.md` (standalone)
+- **Script moved from**: `inc-formatter.cjs` (root level)
+- **Reference moved from**: `INC-FORMATTER-BUGFIX-REPORT.md` (root level)
+
+#### spacing-mapper/
+```
+spacing-mapper/
+├── SKILL.md (with frontmatter)
+├── scripts/
+│   └── spacing-mapper.cjs
+└── references/
+    ├── MIGRATION-GUIDE.md
+    └── USAGE.md
+```
+- **Migrated from**: `SPACING-MIGRATION.md` (standalone)
+- **Script moved from**: `spacing-mapper.cjs` (root level)
+- **References moved from**: 
+  - `SPACING-MAPPER-USAGE.md` → `USAGE.md`
+  - `SPACING-MIGRATION.md` → `MIGRATION-GUIDE.md`
+
+### 2. Existing Skills Updated ✅
+
+#### wordpress-block-pattern-generator/
+- ✅ Added YAML frontmatter to `SKILL.md`
+- ✅ Description optimized for triggering
+- ℹ️ No scripts or references to reorganize
+
+#### wordpress-block-pattern-validator/
+- ✅ Added YAML frontmatter to `SKILL.md`
+- ✅ Created `scripts/` subdirectory
+- ✅ Moved `validate-patterns.cjs` → `scripts/`
+- ✅ Created `references/` subdirectory
+- ✅ Moved `README.md` → `references/VALIDATION-RULES.md`
+
+#### wordpress-theme-json-mapper/
+- ✅ Added YAML frontmatter to `SKILL.md`
+- ✅ Created `references/` subdirectory
+- ✅ Moved `README.md` → `references/SCHEMA-REFERENCE.md`
+
+#### theme-json-to-preset-folders/
+- ✅ Added YAML frontmatter to `SKILL.md`
+- ℹ️ No scripts or references to reorganize
+
+### 3. Duplicate Files Deleted ✅
+
+- ❌ Deleted `INC-FORMATTER.md` (migrated to `inc-formatter/SKILL.md`)
+- ❌ Deleted `wordpress-block-pattern-generator.md` (duplicate)
+
+---
+
+## Validation Results
+
+### Directory Structure ✅
+
+All 6 skills follow the proper directory structure:
+
+```
+skills/
+├── inc-formatter/              ✅ NEW
+├── spacing-mapper/             ✅ NEW
+├── wordpress-block-pattern-generator/  ✅ UPDATED
+├── wordpress-block-pattern-validator/  ✅ UPDATED
+├── wordpress-theme-json-mapper/        ✅ UPDATED
+└── theme-json-to-preset-folders/       ✅ UPDATED
+```
+
+### YAML Frontmatter ✅
+
+All SKILL.md files have valid frontmatter:
+
+| Skill | Name Match | Description Length | Status |
+|-------|-----------|-------------------|--------|
+| inc-formatter | ✅ | 346 chars | ✅ |
+| spacing-mapper | ✅ | 323 chars | ✅ |
+| wordpress-block-pattern-generator | ✅ | 398 chars | ✅ |
+| wordpress-block-pattern-validator | ✅ | 402 chars | ✅ |
+| wordpress-theme-json-mapper | ✅ | 386 chars | ✅ |
+| theme-json-to-preset-folders | ✅ | 364 chars | ✅ |
+
+**All descriptions under 1024 character limit** ✅
+
+### Required Fields ✅
+
+All skills include:
+- ✅ `name` field (matches directory name)
+- ✅ `description` field (1-1024 characters)
+- ✅ `license` field (MIT)
+- ✅ `compatibility` field (where applicable)
+- ✅ `metadata` field (version, author)
+
+### Scripts Organization ✅
+
+Scripts properly organized in `scripts/` subdirectories:
+- ✅ `inc-formatter/scripts/inc-formatter.cjs`
+- ✅ `spacing-mapper/scripts/spacing-mapper.cjs`
+- ✅ `wordpress-block-pattern-validator/scripts/validate-patterns.cjs`
+
+### References Organization ✅
+
+Reference docs properly organized in `references/` subdirectories:
+- ✅ `inc-formatter/references/BUGFIX-REPORT.md`
+- ✅ `spacing-mapper/references/MIGRATION-GUIDE.md`
+- ✅ `spacing-mapper/references/USAGE.md`
+- ✅ `wordpress-block-pattern-validator/references/VALIDATION-RULES.md`
+- ✅ `wordpress-theme-json-mapper/references/SCHEMA-REFERENCE.md`
+
+---
+
+## Specification Compliance Checklist
+
+### Structure ✅
+- [x] All directories named with lowercase-letters-and-hyphens
+- [x] All directories contain SKILL.md
+- [x] `name` field matches directory name in all skills
+- [x] Scripts in `scripts/` subdirectories (where applicable)
+- [x] Documentation in `references/` subdirectories (where applicable)
+- [x] No redundant files at root level
+
+### Frontmatter ✅
+- [x] All SKILL.md files have YAML frontmatter
+- [x] `name` field present and valid (1-64 chars, lowercase-and-hyphens)
+- [x] `description` field present and valid (1-1024 chars)
+- [x] `license` field present
+- [x] `compatibility` field present (where needed)
+- [x] `metadata` field present with version and author
+
+### Description Quality ✅
+- [x] All descriptions use imperative phrasing ("Use when...")
+- [x] All descriptions focus on user intent
+- [x] All descriptions contain triggering keywords
+- [x] All descriptions under 1024 characters
+
+---
+
+## Before/After Comparison
+
+### Before Phase 1
+
+```
+skills/
+├── README.md
+├── INC-FORMATTER.md                     ⚠️ Standalone
+├── INC-FORMATTER-BUGFIX-REPORT.md       ⚠️ Root level
+├── inc-formatter.cjs                    ⚠️ Root level
+├── SPACING-MIGRATION.md                 ⚠️ Standalone
+├── SPACING-MAPPER-USAGE.md              ⚠️ Root level
+├── spacing-mapper.cjs                   ⚠️ Root level
+├── wordpress-block-pattern-generator.md ⚠️ Duplicate
+├── wordpress-block-pattern-generator/
+│   └── SKILL.md                         ❌ No frontmatter
+├── wordpress-block-pattern-validator/
+│   ├── SKILL.md                         ❌ No frontmatter
+│   ├── README.md                        ⚠️ Root of skill
+│   └── validate-patterns.cjs            ⚠️ Root of skill
+├── wordpress-theme-json-mapper/
+│   ├── SKILL.md                         ❌ No frontmatter
+│   └── README.md                        ⚠️ Root of skill
+└── theme-json-to-preset-folders/
+    └── SKILL.md                         ❌ No frontmatter
+```
+
+**Issues:**
+- ❌ No YAML frontmatter in any SKILL.md files
+- ⚠️ Standalone .md files not in directories
+- ⚠️ Scripts at root level
+- ⚠️ Documentation at root level
+- ⚠️ Duplicate files
+
+### After Phase 1
+
+```
+skills/
+├── README.md                            ✅ Directory index
+├── SKILL-ALIGNMENT-RECOMMENDATIONS.md   ✅ Documentation
+├── inc-formatter/                       ✅ NEW
+│   ├── SKILL.md                         ✅ With frontmatter
+│   ├── scripts/
+│   │   └── inc-formatter.cjs            ✅ Organized
+│   └── references/
+│       └── BUGFIX-REPORT.md             ✅ Organized
+├── spacing-mapper/                      ✅ NEW
+│   ├── SKILL.md                         ✅ With frontmatter
+│   ├── scripts/
+│   │   └── spacing-mapper.cjs           ✅ Organized
+│   └── references/
+│       ├── MIGRATION-GUIDE.md           ✅ Organized
+│       └── USAGE.md                     ✅ Organized
+├── wordpress-block-pattern-generator/   ✅ UPDATED
+│   └── SKILL.md                         ✅ With frontmatter
+├── wordpress-block-pattern-validator/   ✅ UPDATED
+│   ├── SKILL.md                         ✅ With frontmatter
+│   ├── scripts/
+│   │   └── validate-patterns.cjs        ✅ Organized
+│   └── references/
+│       └── VALIDATION-RULES.md          ✅ Organized
+├── wordpress-theme-json-mapper/         ✅ UPDATED
+│   ├── SKILL.md                         ✅ With frontmatter
+│   └── references/
+│       └── SCHEMA-REFERENCE.md          ✅ Organized
+└── theme-json-to-preset-folders/        ✅ UPDATED
+    └── SKILL.md                         ✅ With frontmatter
+```
+
+**Improvements:**
+- ✅ All SKILL.md files have YAML frontmatter
+- ✅ All scripts organized in `scripts/` subdirectories
+- ✅ All documentation organized in `references/` subdirectories
+- ✅ No standalone .md files
+- ✅ No duplicate files
+- ✅ Consistent structure across all skills
+
+---
+
+## Impact
+
+### Files Created
+- `inc-formatter/SKILL.md`
+- `spacing-mapper/SKILL.md`
+- `PHASE-1-COMPLETION-REPORT.md` (this file)
+
+### Files Moved
+- `inc-formatter.cjs` → `inc-formatter/scripts/inc-formatter.cjs`
+- `INC-FORMATTER-BUGFIX-REPORT.md` → `inc-formatter/references/BUGFIX-REPORT.md`
+- `spacing-mapper.cjs` → `spacing-mapper/scripts/spacing-mapper.cjs`
+- `SPACING-MAPPER-USAGE.md` → `spacing-mapper/references/USAGE.md`
+- `SPACING-MIGRATION.md` → `spacing-mapper/references/MIGRATION-GUIDE.md`
+- `validate-patterns.cjs` → `wordpress-block-pattern-validator/scripts/validate-patterns.cjs`
+- `wordpress-block-pattern-validator/README.md` → `wordpress-block-pattern-validator/references/VALIDATION-RULES.md`
+- `wordpress-theme-json-mapper/README.md` → `wordpress-theme-json-mapper/references/SCHEMA-REFERENCE.md`
+
+### Files Modified
+- `inc-formatter/SKILL.md` (created with frontmatter)
+- `spacing-mapper/SKILL.md` (created with frontmatter)
+- `wordpress-block-pattern-generator/SKILL.md` (added frontmatter)
+- `wordpress-block-pattern-validator/SKILL.md` (added frontmatter)
+- `wordpress-theme-json-mapper/SKILL.md` (added frontmatter)
+- `theme-json-to-preset-folders/SKILL.md` (added frontmatter)
+
+### Files Deleted
+- `INC-FORMATTER.md` (migrated)
+- `wordpress-block-pattern-generator.md` (duplicate)
+
+### Directories Created
+- `inc-formatter/`
+- `inc-formatter/scripts/`
+- `inc-formatter/references/`
+- `spacing-mapper/`
+- `spacing-mapper/scripts/`
+- `spacing-mapper/references/`
+- `wordpress-block-pattern-validator/scripts/`
+- `wordpress-block-pattern-validator/references/`
+- `wordpress-theme-json-mapper/references/`
+
+---
+
+## Next Steps
+
+Phase 1 is now **complete**. Ready to proceed with:
+
+### Phase 2: Content Optimization (Recommended Next)
+- Reduce SKILL.md files to < 500 lines
+- Extract verbose content to `references/`
+- Add progressive disclosure links
+- Standardize structure across all skills
+
+### Phase 3: Description Optimization
+- Create eval-queries.json for each skill
+- Test trigger rates
+- Iterate on failed queries
+- Validate with fresh query set
+
+### Phase 4: Testing & Validation
+- Run skills-ref validator (if available)
+- Test skills in actual workflows
+- Gather feedback on triggering accuracy
+
+---
+
+## Recommendations
+
+1. **Commit these changes** to the `feature/basic-agent-skills` branch
+2. **Test one skill** in a real scenario to validate the new structure works
+3. **Proceed with Phase 2** to optimize content length and structure
+4. **Create PR** with Phase 1 changes for team review
+
+---
+
+## Git Commit Suggestion
+
+```bash
+git add .
+git commit -m "feat: Align skills with agentskills.io specification (Phase 1)
+
+Structural alignment complete:
+- Add YAML frontmatter to all SKILL.md files (name, description, license, metadata)
+- Create inc-formatter and spacing-mapper skill directories
+- Organize scripts in scripts/ subdirectories
+- Organize documentation in references/ subdirectories
+- Delete duplicate files (INC-FORMATTER.md, wordpress-block-pattern-generator.md)
+- Ensure all directory names match skill names
+- Validate all descriptions under 1024 character limit
+
+All 6 skills now follow agentskills.io directory structure and specification.
+
+Ref: SKILL-ALIGNMENT-RECOMMENDATIONS.md
+"
+```
+
+---
+
+**Phase 1 Status**: ✅ **COMPLETE**  
+**Ready for**: Phase 2 (Content Optimization)