10up Agent Skills

Teach AI coding assistants how to build WordPress the 10up way.

Agent Skills are portable bundles of instructions, checklists, and scripts that help AI assistants (Claude, Cursor, Copilot, VS Code, etc.) understand WordPress development patterns, avoid common mistakes, and follow 10up engineering best practices.

This project follows the agentskills.io specification.

Inspired by Automattic's agent-skills

This project was inspired by and builds upon the pioneering work done by Automattic in creating agent skills for WordPress development. We've adapted their approach to focus specifically on 10up's engineering patterns, tooling, and best practices. Thank you to the Automattic team for open-sourcing their work and establishing the foundation for AI-assisted WordPress development.

Why Agent Skills?

AI coding assistants are powerful, but they often:

• Generate outdated WordPress patterns (pre-Gutenberg, pre-block themes)
• Use static blocks instead of dynamic blocks with PHP rendering
• Miss critical security considerations in plugin development
• Skip proper block deprecations, causing "Invalid block" errors
• Ignore 10up tooling and conventions in your repo
• Don't know about the Interactivity API or modern block patterns

Agent Skills solve this by giving AI assistants expert-level 10up WordPress knowledge in a format they can actually use.

Available Skills

| Skill | What it teaches | |-------|-----------------| | 10up-router | Classifies WordPress repos and routes to the right 10up workflow | | 10up-project-triage | Detects project type, 10up tooling, and versions automatically | | 10up-block-development | Gutenberg blocks: block.json, dynamic rendering, attributes, deprecations | | 10up-block-themes | Block themes: theme.json, templates, patterns, style variations | | 10up-plugin-development | Plugin architecture with 10up PHP framework (ModuleInterface) | | 10up-interactivity-api | Frontend interactivity with data-wp-* directives and stores | | 10up-inner-blocks | Block composition with InnerBlocks, templates, and locking | | 10up-block-extensions | Extending core blocks with @10up/block-components | | 10up-block-patterns | Block patterns, synced patterns, and block bindings API | | 10up-toolkit | 10up-toolkit build system configuration and troubleshooting | | 10up-scaffold | WP Scaffold for theme and plugin development | | 10up-wp-framework | 10up PHP framework with ModuleInterface and auto-loading | | 10up-testing | PHPUnit, Jest, and Cypress testing strategies | | 10up-performance | Performance profiling, caching, and optimization | | 10up-commit-messages | Conventional commit messages with 10up style |

Quick Start

Option 1: Install via npx (Recommended)

# Navigate to your project
cd your-wp-project

# Install all skills to your project
npx @10up/agent-skills

# Or install specific skills only
npx @10up/agent-skills --skills=10up-router,10up-block-development

# Install for multiple editors
npx @10up/agent-skills --targets=claude,cursor,vscode

This copies skills into:

• .claude/skills/ for Claude Code (project-level)
• .cursor/rules/ for Cursor
• .github/skills/ for VS Code / GitHub Copilot

Option 2: Install globally for Claude Code

# Install all skills globally (available across all projects)
npx @10up/agent-skills --global

# Or install specific skills only
npx @10up/agent-skills --global --skills=10up-block-development,10up-interactivity-api

This installs skills to ~/.claude/skills/ where Claude Code will automatically discover them.

Option 3: Manual installation

Copy any skill folder from skills/ into your project's instructions directory:

| AI Assistant | Location | |--------------|----------| | Claude Code (global) | ~/.claude/skills/ | | Claude Code (project) | .claude/skills/ | | Cursor | .cursor/rules/ or .cursorrules file | | VS Code / Copilot | .github/skills/ | | Windsurf | .windsurfrules file |

Cursor Setup

Cursor supports custom rules through a .cursorrules file or the .cursor/rules/ directory.

Method 1: Using .cursorrules file

Create a .cursorrules file in your project root and paste the contents of the skills you want:

# Concatenate skills into a single .cursorrules file
cat skills/10up-router/SKILL.md > .cursorrules
echo "\n---\n" >> .cursorrules
cat skills/10up-block-development/SKILL.md >> .cursorrules

Method 2: Using .cursor/rules/ directory

# Create the rules directory
mkdir -p .cursor/rules

# Copy skill files
cp skills/10up-router/SKILL.md .cursor/rules/10up-router.md
cp skills/10up-block-development/SKILL.md .cursor/rules/10up-block-development.md
cp skills/10up-block-development/references/*.md .cursor/rules/

Method 3: Reference in Cursor settings

Add to your Cursor settings (.cursor/settings.json):

{
  "cursor.rules": {
    "include": [
      "skills/10up-*/SKILL.md",
      "skills/10up-*/references/*.md"
    ]
  }
}

Cursor with @-mentions

Once rules are loaded, you can reference them in Cursor with @rules:

@rules Create a new block called hero-section following 10up standards

How It Works

Each skill contains:

skills/10up-block-development/
├── SKILL.md              # Main instructions (when to use, procedure, verification)
├── references/           # Deep-dive docs on specific topics
│   ├── block-json.md
│   ├── deprecations.md
│   └── ...
└── scripts/              # Deterministic helpers (detection, validation)
    └── list_blocks.mjs

When you ask your AI assistant to work on WordPress code, it reads these skills and follows the documented procedures rather than guessing.

Example: What the AI learns

Without skills, an AI might generate:

// Static block with hardcoded HTML (bad for 10up projects)
save: ({ attributes }) => {
    return <div className="my-block">{attributes.content}</div>;
}

With 10up skills, it generates:

// Dynamic block with PHP rendering (10up standard)
save: () => null  // Render handled by markup.php

// markup.php
<?php
$wrapper_attributes = get_block_wrapper_attributes();
?>
<div <?php echo $wrapper_attributes; ?>>
    <?php echo wp_kses_post($attributes['content']); ?>
</div>

Usage Examples

Once installed, simply ask your AI assistant to help with WordPress development:

Block Development:

• "Create a new block called 'hero-section' with a title and background image"
• "Add a toggle setting to control whether the CTA button is displayed"
• "Fix this block deprecation error - the block shows as invalid"
• "Make this block interactive using the Interactivity API"

Theme Development:

• "Set up the theme.json with a custom color palette"
• "Create a header template part with navigation"
• "Add a card pattern with image, title, and description"

Plugin Development:

• "Create a new plugin following 10up architecture"
• "Add a settings page with a toggle option"
• "Register a custom REST endpoint"

General:

• "What type of project is this?" (triggers triage)
• "How should I structure this feature?"

Validation

Validate that all skills follow the correct structure:

node eval/harness/run.mjs

This checks:

• SKILL.md exists with valid frontmatter
• Required fields (name, description) are present
• Name format follows conventions
• File references are valid

Compatibility

• WordPress 6.4+ (PHP 8.0+)
• 10up-toolkit projects (recommended)
• Works with vanilla WordPress projects too

Contributing

We welcome contributions! This project is a great way to share your WordPress and 10up expertise.

See CONTRIBUTING.md for details on how to get started.

Quick commands

# Install skills to your project
npx @10up/agent-skills

# Install skills globally for Claude Code
npx @10up/agent-skills --global

# Validate all skills
node eval/harness/run.mjs

# Validate a specific skill
node eval/harness/run.mjs 10up-block-development

Project Structure

agent-skills/
├── skills/                    # Individual skill modules
│   ├── 10up-router/
│   ├── 10up-project-triage/
│   ├── 10up-block-development/
│   └── ...
├── shared/
│   └── scripts/               # Build and install tools
├── eval/
│   └── harness/               # Validation tools
├── docs/                      # Additional documentation
├── CONTRIBUTING.md
├── PLAN.md                    # Implementation roadmap
└── README.md

Resources

• Automattic's agent-skills — The original inspiration for this project
• 10up Gutenberg Best Practices
• 10up Engineering Best Practices
• agentskills.io Specification
• WordPress Block Editor Handbook
• Cursor Rules Documentation

License

MIT