Claude manages my blog content - the drafts, the scheduled posts, the whole backlog of article ideas. The problem was that every time I asked “what’s in the backlog?”, Claude would confidently list items we’d already published, or miss new ideas we’d just added. The recollection was stale, the answers burned through tokens, and I kept having to correct things manually. I wanted to just say “backlog” and have Claude figure out it should check the actual files - not a slash command I have to remember to type, but something that kicks in automatically when the context is right.

WHERE SKILLS FIT Claude Code has a bunch of extension points now. Commands you invoke explicitly (/command). Hooks run automatically before/after Claude acts. MCPs connect Claude to external tools and APIs. Skills are different - they’re instructions that Claude decides to load based on what you’re doing. Think of skills as recipes Claude pulls off the shelf when relevant, vs commands you have to explicitly ask for.

So I had Claude make a project-level skill - a SKILL.md file in .claude/skills/content-pipeline/ with a description and instructions for managing my content pipeline. After some fumbling, here’s what I learned about making skills that actually work.

What makes a good skill

  • Write descriptions in third person with WHAT + WHEN. The official docs are clear: descriptions get injected into Claude’s system prompt, so third person works best. Lead with what it does, then when to use it:
Manages blog content pipeline including drafts, scheduled posts, and backlog. Use when discussing content status, scheduling, or asking what to write next.
  • Include trigger contexts, not just trigger words. Rather than listing words like “backlog, pipeline, status”, describe the situations: “Use when discussing content status, scheduling, or asking what to write next.”
  • Keep conditionals out of descriptions. Put conditional logic in the skill body, not the description. The description should just tell Claude when to load it.
  • After changes, restart the session. /clear or new terminal - skills load at startup.

By the way, Anthropic provides a skill-creator skill that walks you through building skills interactively. You can get it via /plugin marketplace add anthropics/skills, then install it from there. There are community marketplaces too - claudecodeplugin.com has a directory, and the plugin marketplace docs explain how it all works.

That said, I’m glad I built mine manually first - it’s how I figured out the stuff below.

Where I got stuck when building my Claude skill

  1. The description vanished. Claude used YAML’s multi-line syntax (description: >) which is technically valid, but Claude Code’s skill parser wasn’t reading it correctly. The skill showed up as just (project) with no description. Fix: put the description on one line in quotes.

  2. The description didn’t include my trigger words. Even with a visible description, Claude wasn’t using the skill when I said “backlog.” The description said “Use after pushing/deploying blog content” - so Claude decided my request didn’t match. Skills are model-invoked, meaning Claude reads the description and makes a judgment call. If your trigger words aren’t literally in the description, Claude might skip it.