taxonomist

A blog that has run for years ends up with overlapping and half-empty categories — this reads every post and works out the tidier set they should have been in all along.

WHEN TO USE

SCOPE

USE FOR

Give every category a written description so readers know what belongs in it.
Merge duplicate categories together and retire the ones with zero posts.
Re-categorize every post on a site based on its actual content, not just its title.
Preview every proposed category change before anything touches the live site.
Undo every category change afterward from a timestamped backup if the result isn't right.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (15)

AI-powered WordPress category taxonomy optimizer. Analyzes every post on a WordPress site and suggests an improved category structure — merging duplicates, retiring dead categories, creating missing ones, and re-categorizing posts.

Based on Taxonomist by Matt Mullenweg.

On Startup

When the user invokes this skill, introduce yourself:

Welcome to Taxonomist! I'll analyze your WordPress categories and suggest improvements — merging duplicates, retiring dead categories, creating missing ones, and re-categorizing your posts using AI.

Everything is safe: I'll preview all changes before doing anything, and log every modification so it can be reversed. Nothing touches your site until you approve it.

Then identify the target site. If there's only one local Studio site, use it automatically. If there are multiple, ask which one to analyze.

Before anything else, call the install_taxonomy_scripts tool with the target site to set up the PHP scripts.

How It Works

This skill operates through an interactive, step-by-step process on a local Studio site:

Connect — Identify the target local site and verify it's running
Export — Download all posts (full content) and categories to local JSON
Backup — Snapshot current taxonomy state before any changes
Analyze — Use parallel sub-agents to analyze every post's content and suggest optimal categories
Plan — Present a comprehensive category plan with descriptions
Review — Iterate with the user until the plan is approved
Apply descriptions — Update category descriptions first
Apply categories — Execute post re-categorization, logging every change
Verify — Confirm site integrity

Steps 1-6 require NO write access to the site. The site is only modified after explicit user approval.

Working Directory

All data files go in a taxonomist-data/ directory inside the site root:

{site_path}/taxonomist-data/
├── export/
│   ├── posts.json          # Exported posts with full content
│   └── categories.json     # Current category list
├── batches/
│   ├── batch-000.json      # Posts split into analysis batches
│   ├── batch-001.json
│   └── ...
├── results/
│   ├── batch-000-results.json
│   └── ...
├── backups/
│   └── pre-analysis-{timestamp}.json
└── logs/
    └── changes-{timestamp}.tsv

Step 1: Connect

Use site_list to find available sites
If multiple sites exist, ask the user which one to analyze
Use site_info to verify the site is running
If the site is stopped, start it with site_start
Verify WordPress is working: wp_cli with eval 'echo "OK";'

Step 2: Export

Create the working directory structure, then export posts and categories.

Export categories

Use wp_cli:

term list category --format=json --fields=term_id,name,slug,description,count,parent

Save the output to taxonomist-data/export/categories.json.

Export posts

Use wp_cli:

eval-file tmp/taxonomist/export-posts.php

With the environment variable:

TAXONOMIST_OUTPUT={site_path}/taxonomist-data/export/posts.json

Post-export summary

Report to the user:

Total posts exported
Total categories found
Top 20 categories by post count
Any categories with 0 posts (candidates for retirement)
The default category (cannot be deleted without changing the setting first)

Step 3: Backup

Create a full taxonomy snapshot before any analysis.

Use wp_cli:

eval-file tmp/taxonomist/backup.php

With the environment variable:

TAXONOMIST_OUTPUT={site_path}/taxonomist-data/backups/pre-analysis-{timestamp}.json

Step 4: Analyze

Split exported posts into batches and analyze each batch with a sub-agent.

Batch splitting

Read taxonomist-data/export/posts.json and split into batch files of ~20-50 posts each (adjust based on average post length — aim for batches that fit within a single agent context). Write each batch to taxonomist-data/batches/batch-NNN.json.

Parallel analysis

For each batch, spawn a sub-agent (use the Agent tool with model "haiku" for efficiency) with this prompt:

Analyze these blog posts and suggest optimal category assignments.

Existing categories: {list from categories.json with slugs}

Instructions:

Read the FULL content of each post, not just the title

Suggest 1-3 categories per post using category slugs (not display names)

Prefer existing categories over creating new ones

Only propose a new category if the topic is genuinely unserved AND would apply to multiple posts

Avoid generic catch-alls like "Uncategorized" or "General"

For each post, provide a confidence level: "high", "medium", or "low"

Output format (JSON array):
[
  {
    "post_id": 123,
    "cats": ["wordpress", "ai"],
    "new_cats": [],
    "confidence": "high"
  }
]
If proposing a new category, add it to new_cats with a suggested slug and name:
"new_cats": [{"slug": "machine-learning", "name": "Machine Learning"}]
Batch data: {batch JSON content}

Save each sub-agent's output to taxonomist-data/results/batch-NNN-results.json.

Aggregate results

After all batches complete:

Merge all result files, de-duplicating by post_id
Collect all proposed new categories across batches
Compute category frequency statistics
Save aggregated results to taxonomist-data/results/aggregated.json

Step 5: Plan

Present a single comprehensive table showing the recommended action for every category:

Category	Posts	Action	Description
WordPress	142	Keep	Articles about WordPress development, plugins, and the WordPress ecosystem
Tech	89	Keep	Technology industry news, trends, and analysis
Asides	34	Retire → merge into "Notes"	Short-form posts and quick thoughts
Uncategorised	23	Retire → re-categorize	Posts to be assigned proper categories
Machine Learning	—	Create	Posts about ML, neural networks, and AI model training

Include:

Every existing category with its current post count and recommended action (Keep / Rename / Merge / Retire)
Every proposed new category with expected post count
Proposed descriptions for all categories (new and existing)
A summary of how many posts would be re-categorized

Then show the full dry run — a table of every post that would change, showing old categories → new categories.

Step 6: Review

CRITICAL: You MUST use the AskUserQuestion tool here to get explicit approval before proceeding. Do NOT continue to Step 7 without the user's explicit "yes" or approval.

Present the plan, then use AskUserQuestion with options like:

"Approve and apply changes"
"I want to adjust some categories first"
"Cancel — don't make any changes"

If the user wants adjustments, iterate on the plan and use AskUserQuestion again for each revision until they approve.

Step 7: Apply Descriptions

After approval, first create any new categories and update descriptions using wp_cli:

# Create new categories
term create category "Category Name" --slug=category-slug --description="Description here"

# Update existing category descriptions
term update category {term_id} --description="Updated description"

Step 8: Apply Categories

Prepare the suggestions JSON file from the approved plan, then run the apply script.

First, do a preview (dry run) using wp_cli:

eval-file tmp/taxonomist/apply-changes.php

With environment variables:

TAXONOMIST_SUGGESTIONS={site_path}/taxonomist-data/results/suggestions.json
TAXONOMIST_LOG={site_path}/taxonomist-data/logs/changes-{timestamp}.tsv
TAXONOMIST_MODE=preview

Show the user the preview results. Use AskUserQuestion to confirm before applying. After they confirm, run again with:

TAXONOMIST_SUGGESTIONS={site_path}/taxonomist-data/results/suggestions.json
TAXONOMIST_LOG={site_path}/taxonomist-data/logs/changes-{timestamp}.tsv
TAXONOMIST_MODE=apply
TAXONOMIST_REMOVE_CATS=uncategorized

Step 9: Verify

After applying changes:

List categories with counts using wp_cli: term list category --format=table --fields=term_id,name,slug,count
Check for posts with no categories: eval 'echo count(get_posts(["posts_per_page" => -1, "category__in" => [get_option("default_category")]]));'
Report the change log location to the user
Remind them that a full backup exists and can be restored

Restoring from Backup

If the user wants to undo all changes, use wp_cli:

eval-file tmp/taxonomist/restore.php

With environment variable:

TAXONOMIST_BACKUP={site_path}/taxonomist-data/backups/pre-analysis-{timestamp}.json

Important Notes

Use the Studio tools (site_list, site_info, site_start, wp_cli, etc.) — not shell commands
Category slugs are the stable identifier — always use slugs (not names or IDs) when referencing categories across steps
Never modify WordPress core files — all changes go through WP-CLI commands
The default category cannot be deleted — change it first via wp_cli: option update default_category {new_id} if needed
All data stays local — exported posts, analysis results, and backups remain in the site's taxonomist-data/ directory

Built into Studio Code, the AI agent in WordPress Studio. Nothing to install there: it comes with the Studio app and the Studio CLI. Studio Code is in beta and needs a WordPress.com login with a payment method on file. The npx skills add command copies the same instructions into another agent, but each one calls tools built into Studio, such as site_info or validate_blocks.

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add automattic/studio --skill "taxonomist" --full-depth

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

View on GitHub

taxonomist

Taxonomist

On Startup

How It Works

Working Directory

Step 1: Connect

Step 2: Export

Export categories

Export posts

Post-export summary

Step 3: Backup

Step 4: Analyze

Batch splitting

Parallel analysis

Aggregate results

Step 5: Plan

Step 6: Review

Step 7: Apply Descriptions

Step 8: Apply Categories

Step 9: Verify

Restoring from Backup

Important Notes

Local tool required

More skills

annotate

block-content

hosting-plans-helper

imagery

liberate

need-for-speed