npm package: @10up/agent-skills
Description: Teach AI coding assistants how to build WordPress the 10up way
Author: 10up
Latest version: 0.1.3

# 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](https://10up.github.io/Engineering-Best-Practices/) and the [10up Gutenberg Best Practices](https://gutenberg.10up.com/).

This project follows the [agentskills.io specification](https://agentskills.io/specification).

> **Inspired by [Automattic's agent-skills](https://github.com/Automattic/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)

```bash
# 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

```bash
# 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:

```bash
# 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

```bash
# 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`):

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

With 10up skills, it generates:
```javascript
// Dynamic block with PHP rendering (10up standard)
save: () => null  // Render handled by markup.php
```

```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:

```bash
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](CONTRIBUTING.md) for details on how to get started.

### Quick commands

```bash
# 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](https://github.com/Automattic/agent-skills) — The original inspiration for this project
- [10up Gutenberg Best Practices](https://10up.github.io/gutenberg-best-practices/)
- [10up Engineering Best Practices](https://10up.github.io/Engineering-Best-Practices/)
- [agentskills.io Specification](https://agentskills.io/specification)
- [WordPress Block Editor Handbook](https://developer.wordpress.org/block-editor/)
- [Cursor Rules Documentation](https://docs.cursor.com/context/rules-for-ai)

## License

MIT