Agent Skills are the markdown files I’ve been waiting for

I’ve never been a big fan of Cursor rules, agents.md or claude.md files, or any of the other attempts to corral a coding agent to do things my way. Using Agent Skills, a more recent approach that’s gaining traction, makes a lot more sense to me.

What are skills?

You can think of skills like any of its predecessors: markdown files with instructions for agents. But Skills have a few advantages over the agents.md files:

1. They’re not basic instructions for a project. Often you’ll see a claude.md file with ‘This is WordPress project. Here is the file structure for my plugins,’ etc. That sort of information is already pretty easy for an agent to figure out on the fly. Meanwhile keeping some of those specifics up-to-date is a pain and a waste of time.
   The biggest issue with these files, though, is that not everything is useful for every prompt, so they can really mess things up if advice gets taken too strictly. A general agents file has your always rules, but skills take a more selective approach.
2. They’re not loaded globally. Instead a skill has a short description that lets an agent know if it would be useful. You can also specifically ask for a skill to be used by referencing it. Otherwise, all those instructions don’t muddy up the context if they don’t apply to the task at hand.
3. They’re task-oriented, not general advice. Because a skill is only loaded when it’s relevant, you can make skills that shape very specific actions or architecture decisions. Build a new block this way by following these steps. Use these specific tools from the Store API when modifying the cart. Skills can be about accomplishing a task a certain way, not just general best practices.

I’m still using a claude.md file, but I no longer use the /init command to create it. It’s just too verbose (a common AI shortcoming). Instead I only use it to store for very specific global rules: Here’s the syntax for WP-CLI commands you need to use in this environment (useful for unique or Docker-based setups). Here’s where to put new functionality. Only code for compatibility with the latest version of Woo/WP. Not a grocery list of every WordPress best practice I can think of.

I recently posted about a skill I made: when invoked, it copies Claude’s output into my Obsidian notes so I can access it later. Super handy when I want to save some ideas or analysis for later. It’s a specific workflow that’s unique to where files are on my computer, and now I can invoke it with a few words. It’s a very basic example, but the type of thing that just makes my daily work easier.

Making Skills

The best part about making skills in Claude Code is that it already has it’s own internal skill for building skills. It’s pretty good at helping you out and building the structure correctly, but remember that the actual expertise and expectations need to come from you.

Think of it this way: if Claude could write a skill for you with minimal input, it probably didn’t need a skill in the first place. Skills are most useful when you want something done a specific way that’s maybe not an LLM’s first instinct. I’m seeing a lot of skills that are just glorified docs, but I don’t think that’s the most useful way to approach them.

Just tell Claude what you want. Be specific and keep iterating until it’s actually helpful.

Skills for Woo

After seeing the Agent Skills for WordPress, I’ve been messing around with my own skills for Woo. There’s a few issues I’m still wrapping my head around, and I’d love to hear from others who are experimenting in the same space.

Woo has multiple avatars to support– merchants running stores, themes doing custom design and light customization, extensions doing heavy customization and integration, and contributors to the core software itself. I don’t think one batch of skills would apply to all of these users, so I’m focusing on my own use-case: customizing Woo stores with custom themes and lower-intensity plugins.

With a piece of software as old and omnipresent as Woo, most of the basic knowledge is in the models already. When I asked an LLM to suggest a list of skills for Woo, it recommended pretty well-documented things it already understands- like modifying product meta or a list of WP CLI commands. That’s not super helpful.

It’s mostly the newer functionality that could benefit from the skills, which means blocks and React. Extending the cart and checkout blocks, setting up product collections, extending the single product block template.

Getting AI to successfully and easily manipulate existing blocks and templates needs to be the next major focus for the AI work happening in WordPress. Custom component-based frameworks like React and Laravel have a huge advantage here. I love building custom blocks with AI, but I’d also love to use AI to design with existing blocks and core’s theme style engine.

Ultimately, where I’m landing is that skills need to be specific to the developer and the type of project. There’s definitely room for some general purpose skills, but you should also explore building your own skills for the types of code you’re regularly building. I think this approach could augment or even replace my plugin scaffolding I shared last month.

Skills (or whatever is their successor because, let’s be honest, there will be something new) remind me a lot of automation tools like AppleScript and Shortcuts. Except much more powerful and free-form. They can be applied to many aspects of your daily workload.

For now. I’m looking forward to next week when there’s a completely new thing we’re supposed to learn.