Wordpress Sage Theme Agent Skill

Provides WordPress theme development patterns using Sage (roots/sage) framework. Use when creating, modifying, or debugging WordPress themes with Sage, including (1): creating new Sage themes from scratch, (2): setting up Blade templates and components, (3): configuring build tools (Vite, Bud), (4): working with WordPress theme templates and hierarchy, (5): implementing ACF fields integration, (6): theme customization and asset management.

9k tokens

context cost

the whole folder, loaded on every use

files

instructions only

copies elsewhere

how many repositories repackaged it

316

stars on the repo

on the repository, not the skill itself

Install

one command, takes just this skill from the repository

npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill wordpress-sage-theme

The instruction itself

34 sections, as written by the author

WordPress Sage Theme Development

Overview

Sage is a WordPress theme framework by Roots that provides modern development practices including Blade templates, dependency management with Composer, and build tools with Vite/Bud.

When to Use

Creating new Sage themes from scratch or from composer templates
Setting up Blade templates, layouts, and reusable components
Configuring build tools (Bud/Vite) for asset compilation
Working with WordPress template hierarchy in Blade format
Integrating Advanced Custom Fields (ACF) with Blade templates
Debugging theme rendering, asset loading, or build issues

Instructions

Set up the environment: Install PHP 8.0+, Node.js 18+, Composer, and create a new Sage theme with composer create-project roots/sage
Configure build tools: Run npm install && composer install, then configure bud.config.js for asset entries and Tailwind
Create Blade templates: Place templates in resources/views/, using layouts in layouts/, components in components/
Wire up WordPress templates: Map WordPress template hierarchy to Blade files (e.g., page.blade.php for page templates)
Integrate ACF fields: Use get_field() for basic fields, have_rows() loops for repeaters and flexible content
Build and verify: Run npm run build, verify public/manifest.json exists, check browser console for asset errors
Deploy: Ensure the production build step (npm run build) runs during deployment; raw source files cannot be served directly

Examples

Create a new Sage theme:

composer create-project roots/sage my-theme
cd my-theme
npm install && composer install
npm run dev

Blade page template:

@extends('layouts.app')

@section('content')
  <main class="content">
    <h1>{{ the_title() }}</h1>
    <div class="entry-content">
      {{ the_content() }}
    </div>
  </main>
@endsection

ACF flexible content in Blade:

@if (have_rows('flexible_content'))
  @while (have_rows('flexible_content'))
    @php the_row() @endphp
    @switch(get_row_layout())
      @case('hero_section')
        @include('components.hero')
        @break
    @endswitch
  @endwhile
@endif

Quick Start

Creating a New Sage Theme

Prerequisites: PHP 8.0+, Node.js 18+, Composer

# Create new Sage theme
wp scaffold theme-theme my-theme --theme_name="My Theme" --author="Your Name" --activate

# Or install Sage directly via Composer
composer create-project roots/sage my-theme
cd my-theme

# Install dependencies
npm install
composer install

# Build for development
npm run dev

# Build for production
npm run build

Directory Structure

resources/
├── views/           # Blade templates
│   ├── layouts/     # Base layouts (app.blade.php)
│   ├── components/  # Reusable components
│   └── partials/    # Template partials
├── styles/          # CSS/SASS files
│   └── main.scss    # Main stylesheet
└── scripts/         # JavaScript files
    └── main.js      # Main JavaScript

Blade Templates

Layouts

Base Layout (resources/views/layouts/app.blade.php):

<!DOCTYPE html>
<html {{ site_html_language_attributes() }}>
  <head>
    {{ wp_head() }}
  </head>
  <body {{ body_class() }}>
    @yield('content')
    {{ wp_footer() }}
  </body>
</html>

Template Hierarchy Mapping

| WordPress Template | Sage Blade File |

|-------------------|-----------------|

| front-page.php | views/front-page.blade.php |

| single.php | views/single.blade.php |

| page.php | views/page.blade.php |

| archive.php | views/archive.blade.php |

| index.php | views/index.blade.php |

Example Page Template (resources/views/page.blade.php):

@extends('layouts.app')

@section('content')
  <main class="content">
    <h1>{{ the_title() }}</h1>
    <div class="entry-content">
      {{ the_content() }}
    </div>
  </main>
@endsection

Components

Reusable Button Component (resources/views/components/button.blade.php):

@props(['url' => '#', 'text' => 'Click', 'variant' => 'primary'])

<a href="{{ $url }}" class="btn btn-{{ $variant }}">
  {{ $text }}
</a>

Usage:

<x-button url="/contact" text="Contact Us" variant="secondary" />

ACF Integration

Displaying ACF Fields

Basic Field:

@while(the_post())
  <h1>{{ get_field('hero_title') ?? the_title() }}</h1>
  <p>{{ get_field('hero_description') }}</p>
@endwhile

Flexible Content:

@if (have_rows('flexible_content'))
  @while (have_rows('flexible_content'))
    @php the_row() @endphp

    @switch(get_row_layout())
      @case('hero_section')
        @include('components.hero')
        @break

      @case('features_grid')
        @include('components.features-grid')
        @break
    @endswitch
  @endwhile
@endif

Repeater Field:

@if (have_rows('testimonials'))
  <div class="testimonials">
    @while (have_rows('testimonials'))
      @php the_row() @endphp
      <blockquote>
        <p>{{ get_sub_field('testimonial_text') }}</p>
        <cite>{{ get_sub_field('author_name') }}</cite>
      </blockquote>
    @endwhile
  </div>
@endif

Build Configuration (Bud)

Tailwind CSS Setup

Install Tailwind:

npm install -D tailwindcss
npx tailwindcss init -p

Configure (bud.config.js):

export default async (app) => {
  app
    .entry({
      app: ['@/scripts/main.js', '@styles/main.css'],
      editor: ['@scripts/editor.js', '@styles/editor.css'],
    })
    .assets('images', 'fonts')
    .tailwind()
    .runtime()
};

Tailwind CSS (resources/styles/main.css):

@tailwind base;
@tailwind components;
@tailwind utilities;

@layer components {
  .btn {
    @apply px-4 py-2 rounded font-semibold transition;
  }

  .btn-primary {
    @apply bg-blue-600 text-white hover:bg-blue-700;
  }
}

Advanced Patterns

Conditional Logic

@if (is_front_page())
  @include('components.hero')
@elseif (is_singular('post'))
  @include('components.post-meta')
@endif

Custom Queries

@php
  $args = [
    'post_type' => 'service',
    'posts_per_page' => 6,
  ];
  $query = new WP_Query($args);
@endphp

@if ($query->have_posts())
  @while ($query->have_posts())
    @php $query->the_post() @endphp
    <article>
      <h2>{{ the_title() }}</h2>
    </article>
  @endwhile
  @php wp_reset_postdata() @endphp
@endif

Theme Customization

functions.php additions:

// Custom image sizes
add_image_size('hero-lg', 1920, 1080, true);

// Custom post types
add_action('init', function() {
  register_post_type('service', [
    'label' => 'Services',
    'public' => true,
    'has_archive' => true,
    'supports' => ['title', 'editor', 'thumbnail'],
  ]);
});

References

Sage Documentation: See sage.md for complete framework reference
Blade Templates: See blade.md for advanced Blade patterns
Bud Configuration: See bud.md for build tool configuration
ACF Integration: See acf.md for ACF field examples

Troubleshooting

Build workflow validation (always run in order):

npm run build completes without errors
Verify public/manifest.json exists and contains asset entries
Test locally in browser before production push
Check browser console for asset 404 errors

Build issues:

# Clear cache
npm run clean

# Rebuild
rm -rf node_modules public
npm install
npm run build

# Validate build output
ls -la public/
cat public/manifest.json | head -20

Blade not compiling: Check public/manifest.json exists after build

AC fields not showing: Verify field names match exactly (case-sensitive)

Best Practices

Blade Template Organization

Use components for reusable UI elements: Create blade components in resources/views/components/ for buttons, cards, and other repeated elements
Keep layouts minimal: Base layouts should only contain structural HTML; delegate styling to components
Leverage Blade directives: Use @include, @each, and @component for better code organization
Avoid inline PHP: Use @php blocks sparingly; move complex logic to Composers or service classes

ACF Field Management

Group related fields: Use ACF field groups to organize fields logically by content type
Use field keys for references: When referencing fields programmatically, use field keys (e.g., field_12345678) for reliability
Implement fallback values: Always provide default values for optional fields to prevent empty output
Cache expensive queries: Use WordPress transients for complex ACF queries on high-traffic pages

Asset Management

Use Bud for asset compilation: Let Bud handle versioning and optimization instead of manual asset management
Minimize HTTP requests: Combine CSS/JS files where appropriate using Bud's entry points
Optimize images: Use WordPress image sizes and lazy loading; consider WebP conversion
Cache busting: Bud automatically handles cache busting via manifest.json

Code Organization

Use Composers for data: Move data retrieval logic from templates to Sage Composers (app/View/Composers/)
Separate concerns: Keep business logic in service classes, presentation in Blade templates
Follow WordPress coding standards: Maintain consistency with WordPress PHP coding standards
Use type declarations: PHP 8.0+ allows typed properties and arguments for better code quality

Security Considerations

Escape all output: Use {{ }} (Blade auto-escapes) or WordPress functions like esc_html(), esc_url()
Validate ACF input: Sanitize and validate custom field inputs on the backend
Nonce verification: Always verify nonces for form submissions
Capability checks: Use current_user_can() before privileged operations

Constraints and Warnings

Version Requirements

PHP 8.0+ required: Sage 10 requires PHP 8.0 or higher; earlier versions are not supported
Node.js 18+ required: Build tools require modern Node.js; older versions may cause compilation errors
WordPress 6.0+ recommended: While Sage works with WordPress 5.x, version 6.0+ is recommended for full feature support
Composer required: Dependency management requires Composer; manual installation is not supported

Build Tool Limitations

Hot reload limitations: Bud's hot reload may not work correctly with some WordPress multisite configurations
Production builds required for testing: Some features work differently in development vs production; always test with npm run build before deployment
Manifest.json dependency: Theme relies on public/manifest.json; missing this file breaks asset loading

Common Pitfalls

Template hierarchy confusion: Sage uses Blade files but follows WordPress template hierarchy; ensure file names match WordPress expectations
Direct file access: Do not access Blade files directly via URL; they must be rendered through WordPress
Plugin conflicts: Some caching and security plugins may interfere with Bud's hot reload or asset serving
Theme updates: Updating Sage via Composer may overwrite customizations; use child themes for extensive modifications

Performance Considerations

ACF Repeater performance: Large repeater fields can impact page load; consider pagination or alternative storage for large datasets
Blade compilation overhead: First load after cache clear compiles all templates; use OPcache in production
Asset bundle size: Monitor compiled asset sizes; large bundles affect page load performance
Database queries: Use Query Monitor plugin to identify and optimize expensive queries in theme templates

Deployment Constraints

Build step required: Production deployments must run npm run build; raw source files cannot be served
Environment-specific configuration: Bud configuration may need adjustment for different deployment environments
File permissions: Ensure public/ directory is writable during builds; incorrect permissions cause build failures

Other skills for the same job

different authors, same section of the catalogue

Theme Factory

by anthropics

vendor ×16

Toolkit for styling artifacts with a theme. These artifacts can be slides, docs, reportings, HTML landing pages, etc. There are 10 pre-set themes with colors/fonts that you can apply to any artifact that has been creating, or can generate a new theme on-the-fly.

Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.

Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts.

11k tokens scripts

Web Artifacts Builder

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.

Set up Tailwind CSS v4 in Expo with react-native-css and NativeWind v5 for universal styling

Use Expo DOM components to run web code in a webview on native and as-is on web. Migrate web code to native incrementally.

3k tokens

How to use it

Copy the folder

Take giuseppe-trisciuoglio/wordpress-sage-theme from the repository into ~/.claude/skills for personal use, or into .claude/skills inside a project.

Check the name does not clash

The agent identifies a skill by the name field in its header. Two skills with the same name cannot sit side by side — one of them will be ignored.

Install what it needs

The instructions reference npm, npx. Without those the skill loads but fails at the first command.