@10up/agent-skills

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 and the 10up Gutenberg 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-css	CSS architecture, ITCSS methodology, accessibility, specificity, naming conventions
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