Claude Code skills: teach your AI agent your real workflows

Full disclosure first: this very site is built and maintained with Claude Code, Anthropic’s terminal-based AI agent. Not “AI-assisted” in the marketing sense — the agent writes code, runs builds, deploys to Cloudflare, and gets code-reviewed like any colleague. Doing that daily teaches you what actually separates a gimmick from a tool. The biggest separator has a name: skills.

What a skill is

A skill is a folder containing a SKILL.md file: a short frontmatter (name + description of when to use it) and then instructions, optionally with scripts and reference files alongside. You drop it in .claude/skills/ in your project (or your home directory), and the agent loads it on demand — only when a task matches the description.

That last part matters. The agent doesn’t carry your entire wiki in its head on every request; it discovers that a skill exists, and pulls in the full instructions only when relevant. Anthropic calls this progressive disclosure. In practice it means you can accumulate dozens of playbooks without drowning the model.

Why this beats “just prompt better”

A prompt is a conversation; a skill is infrastructure:

• Repeatable. The migration checklist executes the same way in March as in November, whoever is typing.
• Versioned. Skills live in git, next to the code they operate on. They get reviewed in PRs like anything else.
• Shared. A junior with your team’s skills inherits your team’s way of working — and so does the agent.
• Composable. One skill can invoke your scripts; scripts don’t hallucinate.

If you have ever written a CONTRIBUTING.md that nobody reads, skills are that document — except something finally reads it, every time.

What I encode as skills (Drupal edition)

Concrete examples from my own practice:

1. The Drupal 10 → 11 migration method. The exact sequence from my migration guide — Upgrade Status audit, environment checks, cleanup before upgrade, Rector, contrib triage, the SEO cut-over checklist. The agent follows the same steps I bill for, and flags what needs a human decision.
2. Code-review conventions. What “done” means in my projects: cache tags on every custom block, no \Drupal:: calls in services, accessibility semantics, update-path hygiene. The agent reviews diffs against the list before I ever look.
3. Deployment runbooks. The order of operations for a given client’s stack — build, config import, smoke tests, rollback path. Runbooks in a drawer save nobody; runbooks as skills execute.
4. Content rules for this site. Meta title/description length limits, hreflang pairing rules, tone. The blog post you are reading passed through them.

A minimal example

---
name: drupal-security-update
description: Apply Drupal core/contrib security updates the safe way.
  Use when a security advisory needs to be applied to a client site.
---

1. Check the advisory severity; critical + remote = same-day window.
2. `composer update` the affected packages only — never blanket-update.
3. `drush updb && drush cr`, then run the smoke-test script (./scripts/smoke.sh).
4. Deploy through CI like any release. Never bypass the pipeline.
5. Post the diff and the advisory link in the PR description.

Twelve lines, and the agent now handles security Wednesdays the way I do — including the part where it refuses to skip CI.

The honest caveats

Skills don’t make the agent infallible; they make it consistent. You still review the diffs. You still keep secrets out of reach and permissions minimal. And a skill encoding a bad process just executes the bad process faster — the value of the tool is exactly the value of the practice you feed it.

That is also why this is a senior developer’s game, not a replacement for one: the skills worth writing are the judgement you already have.

Curious what this looks like applied to a Drupal team — or want your own playbooks turned into something an agent can run? Let’s talk.