Teaching Claude Code Your House Style with Agent Skills

Every team has house rules. The blog never uses em-dashes, API errors always come back in the same envelope, and database migrations always get a rollback script. The trouble is where they live, often in a senior developer's head, in a wiki page nobody opens, or in a prompt you find yourself retyping every Monday morning. Agent Skills give Claude Code a place to keep those rules and a good reason to follow them.

The Re-Prompting Problem

If you've used Claude Code for more than a week, you'll recognise the loop. You ask for something routine: a blog post, a new endpoint, a release. The first draft ignores half your conventions, so you paste in the checklist you keep in a notes file somewhere. The output gets better, but then the session ends and all that knowledge goes with it, so next week you do the same thing again.

The obvious fix is CLAUDE.md, the project memory file that loads at the start of every session. It works well for short, universal facts: which package manager to use, which port the dev server runs on, what never to touch. But CLAUDE.md has a cost that grows with every line you add. The whole file loads in every session, whether the task needs it or not, and a 400-line procedures manual sat at the top of your context window crowds out the code you're actually working on. We've written before about why context is a budget worth guarding, and a bloated memory file spends that budget before you've typed a word.

Anthropic's documentation draws the line neatly: create a skill "when a section of CLAUDE.md has grown into a procedure rather than a fact". So facts stay in CLAUDE.md, and procedures, checklists and reference material move into skills, where they cost almost nothing until they're needed.

What a Skill Actually Is

A skill is just a folder with a SKILL.md file in it, and that's the whole format. The file opens with YAML frontmatter, typically a name and a description, followed by ordinary markdown instructions:

---
name: api-conventions
description: API design rules for this codebase. Use when writing or
  reviewing REST endpoints, error responses, or request validation.
---

When writing API endpoints:

- Use RESTful resource naming: plural nouns, no verbs
- Return errors in the standard envelope (see errors.md)
- Validate request bodies with zod schemas from src/schemas/

Anthropic shipped Agent Skills in October 2025 and later published the format as an open standard at agentskills.io, since adopted by a growing list of agent tools, so a skill you write for Claude Code isn't tied to Claude Code. The anthropics/skills repository on GitHub collects worked examples, the specification and a starter template, including the document skills Claude itself uses to produce spreadsheets and presentations.

The folder can hold more than one file. Scripts, templates, reference docs and example outputs all sit alongside SKILL.md, and the agent reads or executes them only when the instructions point that way. If you'd previously set up custom slash commands, the two concepts have merged: a skill at .claude/skills/deploy/SKILL.md and a command file at .claude/commands/deploy.md both give you /deploy, but skills add the supporting-files directory and finer control over who can invoke them.

Progressive Disclosure, or Why Skills Scale

Skills stay cheap through what Anthropic calls progressive disclosure. The mental model is a library card catalogue: you don't read every book to find the one you need, you skim the index cards and pull a single drawer. Skills load in three stages:

1. Discovery. At startup, Claude sees only each skill's name and description. Dozens of skills cost only their summaries, a small fraction of what the full bodies would.
2. Activation. When your request matches a description, the full SKILL.md body loads into context.
3. Execution. Supporting files load, and bundled scripts run, only if the instructions call for them.

Anthropic's engineering team compares the structure to a well-organised manual: a table of contents first, then specific chapters, then a detailed appendix you consult only when you must. The practical consequence is that a 3,000-word image-sourcing procedure costs you nothing during a refactoring session, because Claude never opens that drawer. CLAUDE.md can't do that, because everything in it loads every time.

One detail worth knowing: once a skill activates, its body stays in your context for the rest of the session. That's usually what you want, since you'd want the instructions to keep applying, but it means every line in the body is a recurring token cost. So it's worth writing skills like a good runbook, which says what to do without a long essay on why.

Where Skills Live

Three locations matter day to day:

Personal skills suit private habits: your preferred commit format, your note-taking workflow. Project skills are the more useful ones for teams, because they live in the repo and come down with every git clone. A new starter gets the house style on day one without anyone having to explain it, and so does every CI agent and background session that touches the repo, which matters more each year as more of the commits come from unattended runs.

When names collide across levels, enterprise-managed skills win over personal ones, and personal skills win over project ones. You also don't have to wait for Claude to pick a skill by itself, because typing /skill-name runs any user-invocable skill directly, with the directory name doubling as the command name.

The Description Field Is the Trigger

So how does Claude decide to load a skill? It reads the description, because nothing else about the skill is visible at that point. The description does the whole routing job, so write it for the model more than for a colleague browsing the repo.

A description written for people tends to read like a label, such as "Article helper." One written for the model reads more like a matching rule, saying what the skill does and when to use it, in the words a user would actually type:

description: Create, edit, and manage blog articles for the company
  website. Use when the user says "write an article", "new blog post",
  "add an article", or references content for the /articles section.

Those quoted trigger phrases do real work, so if you'd say "draft a post" rather than "write an article", put that phrase in. Claude Code caps each skill's listing entry at 1,536 characters, so lead with the key use case and trim the rest.

Two frontmatter fields change who's allowed to run a skill. disable-model-invocation: true means only you can run it, which is right for anything with side effects, such as deploys, releases or sending messages, since you don't want Claude deciding to ship just because the code looks done. The opposite, user-invocable: false, hides a skill from the / menu while letting Claude load it as background knowledge, useful for context like "how the legacy billing system works" that isn't a command anyone would run.

A Worked Example: The Skill That Runs This Blog

We'll use ourselves as the case study, because this very article was written under a skill. The LibraBit blog has a house style that took months to settle: British English, contractions, a hard ban on em-dashes and a list of thirty-odd marketing buzzwords we never want to see, every statistic attributed inline, every Unsplash photo credited on a dedicated page. None of that is something a model could guess, so early drafts kept drifting off-style and we kept re-explaining the same rules at the start of every writing session.

So the rules moved into a project skill at .claude/skills/librabit-articles/SKILL.md. Here's an abbreviated version of the real thing:

---
name: librabit-articles
description: Create, edit, and manage blog articles for the LibraBit
  website. Use when the user says "write an article", "new blog post",
  "add an article", "edit article", or references creating content for
  the /articles section. Handles research, writing, Unsplash image
  sourcing, and articles.json updates.
---

# LibraBit Article Writer

## Project structure

- Article markdown: src/content/blog/posts/{slug}.md
- Article index: src/content/blog/articles.json
- Image credits: src/lib/image-credits.ts

## BlogPostMeta schema (articles.json)

slug, title, excerpt, publishedAt (YYYY-MM-DD), published,
tags (2-4, title case), authorName ("LibraBit Team"),
coverImage (?w=1600&q=80), coverImageAlt

## Voice rules (non-negotiable)

- British English spelling throughout
- Use contractions; mix sentence lengths
- Never use em-dashes; use a comma, full stop, or restructure
- No exclamation points; no marketing buzzwords (full list below)
- Every statistic attributed inline to a named, linked source

## Images (Unsplash)

Cover image plus in-content mood images at natural breaks. Skip
premium photos. Verify the photographer's username, then add every
image to src/lib/image-credits.ts.

## Validation checklist

- [ ] articles.json entry matches the schema above
- [ ] Cover image URL returns 200 (check with curl -sI)
- [ ] All image credits added, usernames verified
- [ ] grep for em-dashes and banned words returns zero hits
- [ ] References section with real, linked sources

The full version runs to about 250 lines, with the buzzword list, the article structure template and the image-sourcing commands spelled out. Once it existed, the prompt changed. "Write an article about Claude Code hooks" is now enough, because the skill carries the file paths, the schema, the voice rules and the checklist. We've argued before that vague prompts produce vague software, and the fix is to put the detail somewhere it'll stay, so the prompt can be short.

The validation checklist helps a lot here, because voice rules ask the model to use judgement, while a checklist gives it concrete, mechanical checks to run before declaring the job done: grep for the banned characters, curl the image URL, diff the schema. And where a check absolutely must happen regardless of what the model decides, pair the skill with a hook. The skill tells the model what you want, and the hook makes sure it actually happens. Our em-dash grep could run as a PostToolUse hook on every write, and the model couldn't choose to skip it.

Keeping Skills Sharp

A few practices we've settled on, all consistent with Anthropic's guidance:

• Keep SKILL.md under 500 lines. That's the limit Anthropic's docs recommend. When a section outgrows the file, move it to a supporting file (image-workflow.md, schema-reference.md) and link it from the main file with a note on when to read it. It then loads only when relevant.
• Spend your words on the description. A so-so body with a clear description does better than the other way round, because a skill that never triggers is no use to anyone. If a skill isn't firing, add the phrases people actually say. If it fires too eagerly, narrow the description or switch it to manual invocation.
• Treat skills as code. Commit project skills, review changes to them in pull requests, and ask of every line whether it earns its recurring token cost. A skill encodes how your team works, which is exactly the kind of change that deserves a second pair of eyes.
• Iterate from observed behaviour. Anthropic's engineers build skills by watching where the agent falls short on real tasks, then patching that gap, instead of guessing at problems and writing manuals up front, so start with the mistakes Claude actually makes in your repo.

The Documentation You Didn't Know You Owed

Writing the skill also improved how we work as people, as well as what the agent produces, which we hadn't expected. Forcing tacit knowledge into a file an agent can follow exposes how much of your "house style" was never actually written down, and how much of it gets ignored in practice. Our em-dash ban entered the skill with the annotation "past articles have failed on these" because they had: we once spent an entire commit scrubbing them out of already-published copy. The skill ended up as the official document, because it has a reader that goes through it on every task and drifts visibly when it's unclear, which a wiki page doesn't.

Onboarding used to be something you did for each person, and re-prompting was really onboarding you did every session. With a committed skill you do it once and then version it like everything else in the repo, so the next contributor who clones the project, human or not, finds the house rules already written down. If you keep pasting the same checklist into Claude, that checklist is a good first skill to write.

---

References

• Extend Claude with skills, Claude Code Documentation, Anthropic
• Equipping agents for the real world with Agent Skills, Anthropic Engineering
• Introducing Agent Skills, Claude Blog
• Agent Skills: an open format for extending AI agents, Agent Skills Standard
• anthropics/skills: examples, specification and template, GitHub