Writing good rules and skills for Claude Code
Structure, frontmatter, choosing between a rule, a skill and an agent, keeping them short, with three generic examples (PowerShell functions, SQL scripts, pipelines).
Rules and skills are the cheapest way to make Claude Code follow your conventions, and the easiest to get wrong. After a year of tuning them on a DBA repository, here is how I structure them, how I choose between a rule, a skill and an agent, and three short generic examples.
Rule, skill or agent?
| Need | Use | Why |
|---|---|---|
| A convention that applies whenever a kind of file is touched | Rule with paths |
loaded automatically, at the right moment |
| A convention that applies in every session | CLAUDE.md |
always loaded, so keep it tiny |
| A procedure with steps, or a body of reference knowledge | Skill | loaded only when the task matches |
| Work that needs its own context, tools or a read-only stance | Agent | isolated, returns a summary |
| Something that must always happen, deterministically | Hook | code, not an instruction |
A quick test: if you would say "whenever you edit a .sql file...", write a rule. If you would say "when I ask for X, do these steps", write a skill. If you would say "go and check that for me", use an agent.
Anatomy of a rule
A rule is a Markdown file in .claude/rules/. The frontmatter lists the glob patterns that trigger it.
---
paths:
- "**/*.ps1"
---
Naming helps a lot: <domain>-<subject>.md (powershell-function.md, sql-script.md, azure-pipeline.md). One file per subject, English, kebab-case. When someone asks where a convention lives, the file name answers.
Anatomy of a skill
A skill is a folder with a SKILL.md. The frontmatter has a name and a description. The description is the part that is always in context, and it decides whether the skill is picked up, so write it like a trigger: what it does and the words a user would say.
---
name: run-triage
description: Diagnose a failed run of a scheduled job (red report mail, failed task, failed pipeline): where its status and logs are, how to group the errors, how to rerun safely. Use for "why did it fail", "rerun", "stuck".
---
# Run triage
1. Find the status store of the job (see reference/jobs.md).
2. Pull the logs of the last run, group errors by message.
3. Decide: recovers by itself, or needs a rerun, or needs a fix.
4. Never rerun a destructive job: propose the command, wait for approval.
Long reference material goes in sub-files (reference/*.md) that the skill body links to, so it is read only when needed. Skills that must never fire by themselves (an end-to-end change workflow, for instance) can be marked as manual-only.
Keep them short
- A rule is a checklist, not documentation. Ten bullets beat two pages.
- State the rule and the reason in one line; Claude generalises better from "why".
- Link, never copy. An agent says "follow rule X"; it does not paste it.
- Put decisions that were already taken in the rule ("never enable feature Y on these databases, tested, it breaks writes"), so the assistant stops proposing them.
- Review them like code: when a rule grows past a screen, split it or move detail into a skill reference.
Three generic examples
PowerShell function conventions
---
paths: ["**/*.ps1"]
---
# PowerShell functions
- Approved verb + PascalCase noun, `[CmdletBinding()]`, typed parameters.
- Return a hashtable: `@{ IsValid; Data; Reason }`. No exceptions across the public boundary.
- Log with the shared logging function, never `Write-Host`.
- `try/catch` with `-ErrorAction Stop`. Never set `$ErrorActionPreference` to SilentlyContinue.
- No credentials in code: Key Vault or managed identity.
SQL script conventions
---
paths: ["**/*.sql"]
---
# T-SQL scripts
- Header: purpose, parameters, example call.
- Templates use `{{Name}}` placeholders declared once at the top.
- `SET NOCOUNT ON`; `TRY...CATCH` that rethrows; explicit transaction for atomic DML.
- No `SELECT *`. Dynamic SQL only with `QUOTENAME`.
- DDL scripts are idempotent. Read-only queries on production are fine; DDL/DML is a change.
Pipeline conventions
---
paths: ["pipelines/**"]
---
# Pipeline YAML
- An optional string parameter gets a sentinel default (`'auto'`), not `''`.
- A new scheduled pipeline is created disabled if another scheduler runs the same work.
- Pipelines that write to production keep a dry-run default; the write is an explicit parameter.
- Internal module versions default to `latest`; pinning belongs to the release process.
Lessons learned
- Specific beats vague. "Format code nicely" does nothing; "return
@{ IsValid; Data; Reason }" is checkable. - Every rule should be verifiable by a lint, a test or a review. If you cannot check it, you will not know whether it works.
- Record the failures. Each time the assistant repeats a mistake, add one line to the right rule, then check that it stops.
- Do not duplicate between layers. Two copies will disagree within a month.
- Test a new rule by asking for a small change in a fresh session and watching whether it is applied.