Creating Skills and Tools

This skill provides guidelines for extending the WordPress MCP Server with new Agent Skills and MCP tools.

Core Principle: Minimal Tools, Maximum Flexibility

Before creating anything new, ask yourself:

Can this be done with wp_cli? → If yes, don't create a new tool
Is this WordPress-specific? → Use WP-CLI commands via wp_cli
Is this a reusable workflow? → Create an Agent Skill, not a tool

When to Create What

| Need | Solution | |------|----------| | Run a WordPress command | Use existing wp_cli tool | | Complex multi-step workflow | Create an Agent Skill | | Non-WordPress SSH operation | Evaluate if executeSshCommand suffices | | Truly new capability | Create a new MCP tool (rare) |

Creating Agent Skills

Skill Structure

.github/skills/
└── your-skill-name/
    ├── SKILL.md           # Required: Main instructions
    ├── reference.md       # Optional: Detailed reference
    └── scripts/           # Optional: Utility scripts
        └── helper.py

SKILL.md Template

See skill-template.md for the full template.

Key requirements:

YAML frontmatter with name and description
Name: lowercase, hyphens only, max 64 chars
Description: What it does AND when to use it

Progressive Disclosure

Keep SKILL.md lean (<500 lines). Split into separate files:

Put detailed references in separate .md files
Link with: See [reference.md](reference.md) for details
Claude loads files only when needed

Best Practices

Be concise: Claude is smart, don't over-explain
One level deep: Don't nest references (SKILL.md → file.md, not SKILL.md → a.md → b.md)
Use examples: Input/output pairs are clearer than descriptions
Forward slashes: Always use / in paths, never \

Creating MCP Tools (Use Sparingly!)

When to Create a Tool

Only create a new MCP tool when:

It cannot be done via wp_cli or existing tools
It provides significant value that justifies the context cost
It's a fundamental capability, not a convenience wrapper

Tool Registration Pattern

server.registerTool(
  "tool_name",
  {
    description: "Clear description of what the tool does",
    inputSchema: {
      param1: z.string().describe("What this parameter is for"),
      param2: z.number().optional().describe("Optional parameter"),
    },
  },
  async ({ param1, param2 }) => {
    // Implementation
    return {
      content: [{ type: "text", text: "Result message" }],
    };
  }
);

Tool Naming

Use snake_case for tool names
Be descriptive: test_ssh_connection not test_ssh
Prefix related tools: wp_* for WordPress tools

Updating the Skills Catalog

After creating a skill, update .github/copilot-instructions.md:

| Skill Name | Description | Path |
|------------|-------------|------|
| your-skill-name | Brief description | `.github/skills/your-skill-name/SKILL.md` |

Anti-Patterns to Avoid

❌ Don't create specialized WordPress tools

// BAD - Creates context bloat
server.registerTool("get_plugins", ...)
server.registerTool("activate_plugin", ...)
server.registerTool("update_plugin", ...)

✅ Use the generic wp_cli tool instead

// GOOD - One tool, infinite commands
wp_cli({ domain: "example.com", command: "plugin list" })
wp_cli({ domain: "example.com", command: "plugin activate akismet" })
wp_cli({ domain: "example.com", command: "plugin update --all" })

❌ Don't duplicate WP-CLI documentation

Claude already knows WP-CLI
Link to official docs instead

❌ Don't create deeply nested skill files

Keep references one level deep from SKILL.md

creating-skills-and-tools