Claude Code skills

This repository ships a suite of repository-specific Claude Code skills under .claude/skills/. Each skill is a focused audit that compares one surface of the codebase against its source of truth — the OpenAPI spec, the cobra command tree, the bounded-context map, the design-system spec, the observability conventions, the documentation corpus — and reports drift before it reaches a release.

The skills complement the CI gates documented in CI pipeline — jobs, triggers, and reproducing failures. CI is the authoritative gate; the skills give a contributor (or an agent acting on the contributor's behalf) a structured, repeatable way to walk a surface and explain the findings in prose.

When to use a skill

• After changing a surface the skill audits (an OpenAPI operation, a plexctl command, a bounded context, a doc page, a metric or span attribute, …).
• Before opening a release PR, as a final sweep across every surface.
• When a CI gate is red and you want a per-surface diagnostic that goes deeper than the gate's failure message.

The check-* audit skills are read-only by design: each one runs a deterministic bash script and walks the relevant sources, then produces a findings report grouped by severity. Fixes are a separate, explicitly-scoped task — either hand-driven, or delegated to the resolve-checks orchestrator, the one write-capable skill in the suite.

How to invoke a skill

The skills are loaded automatically by Claude Code when it sees the repository's .claude/ directory. There are two ways to run one:

• Explicit slash command. Type /<skill-name> in the Claude Code prompt — for example /check-doc-drift — and Claude follows the procedure in the skill's SKILL.md.
• Implicit trigger. Each skill's description names the situations where it should be used proactively ("after adding or changing an API operation", "before a release", …). Claude Code may invoke the skill on its own when it recognises the trigger.

Every skill ships a scripts/audit-<name>.sh companion that runs the deterministic part of the audit and exits non-zero on a [FAIL]. The script is safe to run by hand from a shell — it reads files and prints inventories; it never writes to the tree.

bash .claude/skills/check-doc-drift/scripts/audit-doc-drift.sh

The skill's SKILL.md describes the prose-level checks the script cannot do (cross-referencing the doc to the source of truth, judging severity), the gate commands to run alongside the audit (make check-rendered-identifiers, make docs-check, go test ./tests/docs/..., …), and the report format.

Catalogue

The eleven audit skills are grouped by the surface they audit; a twelfth skill, resolve-checks, orchestrates them. Each entry links to the skill's SKILL.md (the procedure) and the bash script (the deterministic part of the audit).

Domain and architecture

Skill	Audits	Use when
check-ddd-boundaries	Bounded-context layering — domain free of framework / persistence / transport imports, no cross-context domain coupling, application layers not reaching into a sibling context's persistence, repository and domain-event idioms present where they should be.	After introducing a new aggregate or context, before a release.
check-context-lockstep	Bounded-context registration surfaces — Go workspace, depguard cross-context deny lists, root Dockerfile, the dependabot module list, CODEOWNERS, and the layout reference.	After adding, renaming, or removing an internal/<ctx>/ package.
check-test-pyramid-coverage	Per-context coverage matrix against internal/, tests/integration/, tests/e2e/, and docs/contexts/ — the four-aspect rule (unit + integration + e2e + docs).	After adding or changing a bounded context, before a release.

API, CLI, and codegen

Skill	Audits	Use when
check-api-wiring	Every /v1 HTTP operation end to end — OpenAPI spec, generated ServerInterface, handler, transport Deps, wiring bundle, composition-root seam, and mountV1.	After adding or changing an API operation, before a release.
check-cli-wiring	Every plexctl command end to end — root constructor declared, registered via registerSubcommands, Short/Long help present, sub-command tree matches its reference page, reaches a real application service.	After adding or changing a plexctl command, before a release.
check-codegen-drift	Every code generator (OpenAPI server, OpenAPI Go client, OpenAPI Go types, OpenAPI TypeScript client, sqlc, buf / gRPC) — artefacts present, matched to a live config, regenerable from a clean tree, free of orphans.	After editing an OpenAPI / proto / SQL spec, before a release.
check-config-surface	Configuration surface — code defaults and ENV bindings in cmd/plexsphere/*_factory_prod.go and the signer binary, CLI flag bindings in cmd/plexctl/commands/, and the operator-facing docs that describe them.	After adding or changing a PLEXSPHERE_* env var or a plexctl flag, before a release.

Dashboard, observability, docs, traceability

Skill	Audits	Use when
check-design-system-drift	Dashboard drift against the binding design system — raw hex literals, ad-hoc Tailwind colour utilities, off-scale pixel values, missing empty / loading / error state triplets, missing aria-label on icon-only buttons, per-component theme conditionals, ground-up panels that should wrap a catalogued primitive.	After adding or changing a view under web/, before a release.
check-observability-conventions	Observability surfaces — structured slog logs, Prometheus metrics, OpenTelemetry trace spans — for naming-convention drift and cardinality risks.	After adding or changing a log field, a metric, or a span attribute.
check-doc-drift	Documentation against the implementation — API reference vs the OpenAPI spec and wired handlers, CLI reference vs the plexctl command tree, bounded-context docs vs internal/ domain code, architecture and contributing docs vs the repo layout.	After adding or changing a feature, before a release.
check-traceability-orphans	Internal traceability identifiers that live inside source comments — bare TODO markers missing the parenthesised reference, malformed TODO blocks, code references to a planwerk id the inventory does not claim, inventory entries with no code reference, DECISION blocks too short to carry the rejected-alternative rationale, retired-suffix patterns in production strings.	After adding or changing a TODO / DECISION block, before a release.

Orchestration

Skill	Does	Use when
resolve-checks	Runs every check-* audit in one sweep (the set is discovered dynamically from the directory layout), triages the combined findings into fix / intentional / defer, and resolves the fixable ones on a fresh branch — one commit per improvement, each re-verified against the originating audit and the relevant CI gates. Commit trailers (attribution plus sign-off) are derived at runtime from the repository's commit conventions and the active git config identity, never hardcoded. Unlike the audit skills it edits the tree — but only in its fix phase, only on the sweep branch, never on main. Its companion script run-all-audits.sh stays read-only: it executes every audit script and prints a per-skill PASS/FAIL summary.	When you want all checks run and their findings worked down into reviewable commits — typically as a pre-release cleanup pass.

What a skill is, structurally

Every skill in this suite follows the same layout:

.claude/skills/<name>/
├── SKILL.md                 # the procedure Claude follows
└── scripts/
    └── audit-<name>.sh      # the deterministic, read-only audit

The resolve-checks orchestrator follows the same layout, with scripts/run-all-audits.sh as its deterministic entry point instead of an audit-*.sh.

SKILL.md opens with a YAML frontmatter block carrying name and description — the description is what Claude Code matches the user's prompt against when deciding whether to load the skill. The body documents the audit's procedure, the drift patterns that recur on the surface, and the reporting format (severity grouping, file:line citations on both the doc and the source-of-truth side).

The bash script is the deterministic part of the audit. It performs no build, writes nothing, and reads from a fixed list of source-of-truth files. Exit code 0 means no [FAIL]; 1 means at least one mechanically-checkable assertion failed; 2 means the script could not run (not a repo, missing inputs).

Authoring or modifying a skill

When you add a new skill or modify an existing one, keep the suite internally consistent:

• Frontmatter. Every SKILL.md carries name and description. The description is the discoverability surface — write it as a single sentence in the form "Audit … — … . Use when …".
• Read-only. The companion script reads files and prints reports; it never writes to the tree, never invokes go generate, never triggers a build. This holds for resolve-checks too — its script only runs the audits; the edits happen in the skill's fix phase, as commits on a dedicated branch.
• Findings report. The report groups findings by severity (HIGH / MEDIUM / LOW) with one line per finding and a file:line reference on both sides of the drift.
• Pair with CI. If the audit overlaps a CI gate, name the gate in SKILL.md and tell the reader to trust the gate's verdict over the script's. The script is a debugging aid; the gate is the source of truth.
• No private-repo links. Like every tracked file, a skill body must not link to private GitHub artifacts. Inline the rationale instead (see Docs authoring conventions).
• Stay in English. Skill bodies, frontmatter, and script comments follow the repository-wide English-only rule.

The skills are not a substitute for CI gates — they are an aid for the contributor (or the agent) who has to read a surface deeply and explain what changed. When in doubt, run the gate listed in the skill's SKILL.md and trust its verdict.