LLI Wiki — My Digital Knowledge Base

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

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

Mastodon LLIMastodon SocialFosstodon