write-detection-rule

Skill: write-detection-rule

This skill teaches Claude Code how to write detection rules for the AI Traffic Control rule engine. Read this before creating or modifying anything in rules/. The full rule schema is Rule in packages/schema/src/zod/rule.ts — it is the source of truth for every field below.

Rule file format (specVersion 1)

Every rule is a JSON file named <rule-name>.json inside a pack directory:

{
  "specVersion": 1,
  "id": "<pack-id>/<rule-name>",
  "name": "Human-readable name",
  "category": "pii|financial|secret|phi|code_context|code_flaw|custom|config",
  "severity": "critical|high|medium|low",
  "matcher": { ... },
  "postValidators": ["luhn"],
  "examples": ["example matching string"]
}

A misspelled key fails the parse — it is not dropped

Every object in the rule tree is strict: an unrecognized key is a parse error naming the key, at whatever depth it sits. This holds for the rule itself, for matcher, appliesTo, requiresNearby, the object form of a postValidators entry, and for fixture files including each entry of expectedSpans.

The reason is that the old behaviour was to strip the key and carry on, which is the worst outcome available: the rule still parses, still loads and still fires, with whatever the key was meant to configure simply gone. postValidator for postValidators dropped a false-positive guard. capture_group for captureGroup widened the redacted span from the value to the whole match. windowChar for windowChars left a proximity gate at the 160-character default while the author believed they had narrowed it. None of these produce a failing fixture, so nothing caught them.

So a rule that parses is a rule whose every key was understood. If you get Unrecognized key, check the spelling against Rule in packages/schema/src/zod/rule.ts — the field is real but named something else, or it belongs one level up or down.

Matcher types

keyword — fast literal or phrase match, good for high-recall low-precision terms: