SOTA Engineering Skills

Make your AI coding assistant build and audit like your most senior engineer.

Your assistant is brilliant — it just doesn't know your standards, and it forgets the ones it does know as the task grows long. SOTA-skills fixes both, and the fix is measured: from a bare "build X" prompt, best-practice coverage climbs from ~59% to ~98% (+0.39) — the model stops silently dropping tests, rate limiting, structured logging, and TLS (see every number →).

It works by being a loop, not a prompt dump: route in only the rules a task needs, re-state them every turn, and re-check them last before shipping — so the guidance survives a long context instead of fading into it. That's why it beats a bigger prompt instead of becoming one. Native on Claude Code; works with Gemini CLI, Codex, and any agent that reads AGENTS.md.

Under the hood: 41 skills (297 files, ~61k lines) of state-of-the-art 2026 practice, each instruction file under 500 lines so only the matching rules load — the cap applies to skills/** alone, never to README/CHANGELOG/docs/ — every fast-moving claim web-verified against a primary source.

Two commands to install:

/plugin marketplace add martinholovsky/SOTA-skills
/plugin install sota-skills@sota-skills

Or clone + link (best if you want a local checkout to read, hack on, or pin). Skills are discovered from .claude/skills/ (per project) or ~/.claude/skills/ (personal, all projects). Clone the repo, then run the installer — it symlinks every skill (and your profile, if you have one):

git clone https://github.com/martinholovsky/SOTA-skills && cd SOTA-skills
./scripts/install.sh                 # personal: ~/.claude/skills (all projects)
./scripts/install.sh --project DIR   # one project: DIR/.claude/skills
./scripts/install.sh --copy          # copy instead of symlink (pin a snapshot)

The installer colour-codes what it did (✓ done · ↻ changed or act on this · · no-op) and drops to plain ASCII when the output is not a terminal, on a non-UTF-8 locale, on TERM=dumb, or with NO_COLOR set — --color=always|never|auto (or --no-color) overrides the detection either way.

Then describe the task in plain language — routing loads the right skills; the stack comes from your profile or the skills' defaults (naming one is optional):

Design a multi-tenant invoicing service.

Run a full audit of this repo — severity, effort, and fix on every finding.

More install options: Installation · more prompts: Using it.

Contents

• Standards & practices baked in · What the audit hunts that a scanner can't · How the numbers are kept honest
• Skills · Coverage & non-goals
• Installation · Always-on routing · Updating
• Using it
• Optional setup & integrations — badge, gates, other agents, status line, plugin extras
• Structure · How it works · Conventions
• Found a gap? Tell us · Contributing · License

Deeper docs: Find it fast (docs index) · Does it work? (measured results) · Why it works · Keeping rules applied as context fills · Roadmap

Standards & practices baked in

Findings name the control they violate — not just "this looks wrong":

• Security — OWASP Top 10 (2025), ASVS, API & LLM Top 10; findings cite CWE IDs
• Languages — all 9 language skills (Rust → Ruby, below) get the same rigor; formal standards where they exist: SEI CERT (C, C++, Java), MISRA C/C++, ANSSI Rust
• Supply chain — SLSA, Sigstore, in-toto, SBOM (CycloneDX/SPDX), NIST SSDF
• Cloud & identity — CIS Benchmarks, NIST 800-207 zero trust, NIST 800-63-4, OAuth 2.1, FAPI 2.0, passkeys, SPIFFE
• Privacy & compliance — GDPR, CCPA/CPRA, HIPAA, PCI DSS 4.x, SOC 2, ISO 27001, EU AI Act, NIS2, DORA
• Government & regulated — NIST CSF 2.0, 800-53, 800-171/CMMC, FedRAMP, EU Cyber Resilience Act, IEC 62443
• Threats, detection & AI/ML — STRIDE, LINDDUN, MITRE ATT&CK & ATLAS, NIST 800-61, NIST AI RMF
• Frontend, mobile & testing — WCAG 2.2 AA, Core Web Vitals, OWASP MASVS & WSTG

Named standards are the floor. Most of the library is the practice layer no regulation writes down: cancellation & backpressure, retries with jitter, circuit breakers, outbox/saga, zero-downtime migrations, measure-first performance, API evolvability, per-language idioms, SLOs, test-suite health.

Measured, not asserted — library vs. an unguided model (same model, no library); clean, blind-judged, stable across samples (results & method →):

• Completeness +0.39 — from a bare "build X" prompt, best-practice coverage goes ~59% → ~98% (7 tasks): the model stops silently dropping tests, rate limiting, structured logging, and TLS. Web search likely can't recover this (an agent won't search "should I add rate limiting"). Not model-specific: a different-family frontier model (openai/gpt-5.1) shows +0.44 on the same tasks (cross-model →).
• Freshness +0.53 — current-2026 facts (RFCs, CVEs, EOLs) 0.44 → 0.97, where an unguided model is confidently wrong.
• Routing +0.10 — the right skills load for the task (0.90 → 1.00), even ones a keyword read misses; with the library, results barely move run-to-run.

And not just vs. an unguided model — head-to-head against the most popular guidance libraries on backend build tasks, SOTA-skills leads on completeness (content-only, blind-judged; wins or ties all 21 cases, loses none):

A five-domain breadth test shows when this edge holds: SOTA-skills leads the field wherever a base model ships incomplete code — production backend in any language and complex/security-sensitive frontend (~+10 pts) — and ties where the base model is already near-complete (simple UI, templated infra). The lead tracks task difficulty, not the domain — we measure it and say so. Full breadth result, consolidated table, method & honest limits →

What the audit hunts that a scanner can't

Eight classes of defect survive every linter, SAST rule, and CVE scanner, because in each one the code isn't wrong. The library hunts them as explicit passes:

• Controls that are inert — a safeguard whose success and whose total failure look identical from outside: a swallowed enforcement exception, a ruleset that loads zero rules, presence decided by exists() rather than a loaded artifact, a CI gate whose every run is skipped, a test that still passes when the control's body is replaced with a no-op. (rules/10)
• Layers that were never layers — the same test applied to an architecture diagram rather than a function. A second-opinion classifier drawn from the same model family as the system it guards shares its blind spots by construction (common-cause failure), and one that only ever sees what the primary already flagged uncertain cannot, even in principle, catch what the primary got confidently wrong. A TEE bought to fix records that were never emitted is answering a liveness question no hardware guarantee covers. Both are counted in a threat model and neither reaches the case it is counted for. (rules/08 §1, rules/04 §8)
• Stages that report success while doing nothing — found by the cheap signals rather than by reading every line: a step returning "nothing found" far faster than its claimed work allows, a gate that never prints how many items it examined (0 checked, 0 failed, exit 0), a size-gated branch no fixture crosses, a cache key narrower than the behaviour it gates, a control written as an assert that -O/NDEBUG/a missing -ea deletes in production. (rules/11)
• Your own scorer, gate or benchmark doing none of the above — the same file ends by turning the lens around: anything whose output decides whether something is OK is a control too. A broken feature produces a complaint; a broken instrument produces a number, and numbers get quoted. So give it a known-bad input it must fail and a known-good one it must pass, bound what it reads, and never trust a number from an instrument you haven't watched produce a wrong answer on purpose. (rules/11 §7)

Where this is not backed by a number: the measured lift is in BUILD (completeness, freshness). Seven audit instruments across three designs all sit at +0.00 — recognition (snippets, cross-file repo, precision), procedure (does the model actually mutate the control and re-run the build), and question-set (an unscoped "audit this repository", with defect classes outside the standard repertoire). A frontier model handed the code is already at ceiling, and it stays at ceiling when you stop telling it what to look for. The audit half is justified by gap analysis and by real defects it found in this repo — not by a measured lift, and it is reported that way rather than implied. Every null, the retraction, and the pre-registered predictions that were wrong →

How the numbers are kept honest

The measurement discipline is the part that is hard to copy, so it is worth stating plainly. Every item below is in the repo, not a claim about it:

• Nulls are published, not buried. Seven +0.00 rows sit on the scoreboard next to the +0.39 — including the four that say the audit half of this library adds nothing a good model doesn't already do.
• A lift was retracted. An early +0.07 on inert-control detection did not reproduce when the sample grew from 15 to 49 cases. It was withdrawn and the retraction is documented rather than quietly dropped.
• Predictions are pre-registered. Before the 2026-07-30 audit experiments ran, the expected numbers and ranges were committed and pushed (PRE-REGISTRATION.md). Both predictions turned out wrong — one by three times its own lower bound — and are reported as wrong.
• The scorers are themselves tested. A mutation probe once replaced a scoring function with return 1.0 and nothing noticed; the golden tests that now run in CI were watched to fail against that exact mutation first.
• The eval runners carry a duration baseline. Each run records to a local ledger and the next run of the same runner prints the delta — [run-completeness elapsed 12.3s over 7 cases | previous 380.0s — 30.9x faster] — because "finished far faster than the work allows" is a comparison, and a duration without its denominator says nothing. A swing over 5× is flagged for a human; nothing is gated on time.
• The library is applied to itself, and it finds things. Its own dead-path rules caught this repo's CI gates passing over zero files — green, exit 0, examining nothing — and the fix was verified by re-running the mutation. The same lens later caught this repo's secret scan: gitleaks prints 179 commits scanned, and nobody read it. In a shallow clone it scans 1 of 179, prints no leaks found, and exits 0 — a green scan over 0.5% of history, with one CI setting the only thing preventing it. CI now asserts the scope.

The point is not that every number is flattering. It is that you can tell which ones are load-bearing, because the ones that aren't are labelled.

Skills

Skill	Covers
sota	Master router: operating principles, task→skill routing, full-audit workflow + audit methodology (tool matrix, evidence standard, report template)
sota-architecture	Styles & ADRs, DDD, distributed systems, resilience, scalability, cloud-native, anti-patterns
sota-code-security	Injection, authn/authz, crypto, web security, resource safety, data exposure, LLM appsec
sota-threat-modeling	STRIDE/LINDDUN, DFDs & trust boundaries, threat catalogs, risk rating, model reconstruction
sota-secrets-management	Lifecycle & workload identity, storage backends, app patterns, leak detection, credential types
sota-sandboxing	Isolation boundaries, seccomp/Landlock/capabilities, containers/microVMs, parsers, AI-agent sandboxing
sota-performance	Measure-first methodology, algorithms, memory, I/O & network, caching, Web Vitals
sota-async-concurrency	Concurrency models, races/deadlocks, primitives, event-loop hygiene, cancellation, backpressure
sota-api-design	REST/HTTP, versioning, GraphQL, gRPC, websockets/SSE/realtime, webhooks, API security & ops
sota-devsecops	Pipeline hardening, SLSA/Sigstore provenance, dependencies/SBOM, container builds, IaC, admission control
sota-databases	Modeling & engine choice, zero-downtime migrations, indexes, transactions, reliability, security, pgvector/Qdrant, SurrealDB
sota-frontend-design	Typography/color, layout, design systems, UX patterns, WCAG 2.2 accessibility, motion design, visual craft
sota-web-frameworks	React 19/Next.js + Vue 3/Nuxt 4: Server Components & Server Actions, RSC/client boundary, caching (use cache/PPR/ISR), hydration correctness, SSR state serialization, Nitro routes, framework CVEs
sota-observability	Structured logging, metrics, OpenTelemetry tracing, SLOs & alerting, operational readiness
sota-testing	Test strategy & design, doubles/test data, contract testing, e2e, property/fuzzing/mutation, suite health

Coverage & non-goals

Deliberately not covered: Scala/Elixir, standalone C (inside sota-c-cpp), platform-engineering/IDP depth. File a skill request issue.

Installation

Both commands are shown at the top — the plugin (/plugin, auto-updates on version bump) or clone + link (./scripts/install.sh, a local checkout to read, hack on, or pin). A few details on the clone path:

• Skills are discovered from .claude/skills/ (per project) or ~/.claude/skills/ (personal, all projects); install.sh symlinks every skill and your profile.
• --project DIR scopes to one repo; --copy pins a snapshot instead of linking.
• Prefer no script? It only symlinks skills/*/ into ~/.claude/skills/ — do that by hand if you'd rather.

The plugin (or --copy) installs the skills; a few extras (routing reminder, status line, pre-commit gates, AGENTS.md) aren't auto-enabled — see Optional extras for plugin users. On first run the plugin shows a one-time notice pointing there.

An install is personal, not repo-resident

Installing once makes the skills apply in every project you open, new ones included — there is nothing to run per repo, and a brand-new repo is covered the moment you start work in it. But the install resolves against your home directory: a teammate's clone and a CI runner see none of it.

So for a repo shared with anyone, decide explicitly:

./scripts/install.sh --project .   # repo-resident: .claude/skills/ in the repo
./scripts/install.sh --project . --copy   # ...pinned snapshot, not symlinks to your paths

— or leave it personal and put the install step in CONTRIBUTING.md so a contributor can reproduce it. What must not stay personal is the gates: a secret scan that lives only in your shell doesn't run on anyone else's commit. Wire those into the repo with init-gates.sh.

And the things no install can supply per repo — gates, LICENSE, .gitignore, an agent file, and the order to create them in — are the day-zero list in sota-docs-workflow rules/01 §10. The router raises it once, unprompted, the first time it meets a repo that has none of them.

Updating

Plugin install: updates ship when the version bumps — /plugin update sota-skills@sota-skills (or /plugin marketplace update sota-skills).

Do not assume auto-update covers you. Per the Claude Code docs (checked 2026-07-30): "Third-party and local development marketplaces have auto-update disabled by default" — this is a third-party marketplace, so unless you turned it on (/plugin → Marketplaces → the entry → Enable auto-update), nothing updates on its own. Even with it enabled, the check runs after your session starts "with a random delay of up to ten minutes", and the running session keeps the versions it loaded at launch, so a refresh lands on /reload-plugins or your next launch — never mid-turn. Run /plugin update when you want a known-current library.

An occasional nudge, with no telemetry. Nothing pushes updates on either path, so a SessionStart hook (scripts/update-reminder.sh) mentions — at most once every 14 days — that your copy has been sitting for a while, and how to check. It makes no network request. It cannot tell whether a new version exists, only how long since it last spoke: the useful part was the reminder, and a real check from every session start would turn a documentation library into something that reports when and how often you work. You run the check. Installed by install.sh (clone) and by the plugin's own hook; silence it with SOTA_UPDATE_REMINDER_DAYS=0, or set your own interval in days.

Which version am I on? scripts/install.sh --version reports the release, the checkout (git describe), whether your remote is ahead as of the last fetch, and whether the skills are symlinked (update live) or a pinned --copy snapshot. Quote it in a bug report — otherwise a report about a rule's behaviour can't be tied to the release that produced it.

Clone install: because linking is symlink-based, existing skills update the moment you pull — the symlinks already point at the live files:

git -C /path/to/SOTA-skills pull

To also pick up newly added skills (a pull alone won't link a brand-new skill directory) and prune links to removed ones — pull and re-link at once:

./scripts/update.sh                  # git pull --ff-only, then re-link
./scripts/install.sh --update        # the same thing — update.sh is a thin alias

It's idempotent: re-running only links what's new and prunes what's gone, and never touches symlinks it didn't create (--copy snapshots don't auto-update — re-run to refresh). With always-on routing enabled, a re-run also refreshes the managed routing directive and reminder hook in place when their wording changes upstream — prompting first, backing up, touching only the managed block; a hook you customized is left untouched.

Always-on routing (recommended)

Skill descriptions are matched per prompt, so routing is opt-in and depends on how you phrase the request. To make the skills apply to every session regardless of wording, pin the routing instruction where Claude Code always sees it.

The quick path: ./scripts/install.sh offers to set this up for you after linking the skills — interactive and dotfiles-aware: it detects an existing or symlinked ~/.claude/CLAUDE.md / settings.json, asks before touching anything (recommended answer pre-filled), backs up first, writes through a symlink so dotfiles stay in charge, and uses managed markers so re-runs refresh the managed block in place and never duplicate it. Use --routing to force, --no-routing to skip, --yes for non-interactive. Or wire the three layers by hand:

Three layers, strongest last:

1. A stack profile. Copy the template, fill in your stack, and symlink it into ~/.claude/ so the router finds it in every project (not just this repo):

cp profiles/example.md.template profiles/<you>.md   # edit it — profiles/*.md is git-ignored
mkdir -p ~/.claude/profiles
ln -sfn "$(pwd)/profiles/<you>.md" ~/.claude/profiles/<you>.md

2. A global directive. ~/.claude/CLAUDE.md is loaded into every session, every project. Add a routing mandate so the skills apply without trigger words:

# Global engineering directive

Always, on every answer: (1) **validate before you assert** — verify any claim
about code, system state, config, versions, or facts against a primary source
(read the file / run the command / fetch official docs) before answering or
proposing, and label anything unverified as such; (2) **keep docs current** —
when you change code/behavior/config, update the affected docs (README,
CHANGELOG, comments, runbooks, AGENTS.md) in the same change, unprompted.

For any task that builds, designs, refactors, debugs, reviews, or audits code —
in any language or repo — consult the `sota` router skill first, load the
matching `sota-*` skills, and apply their rules before acting. This holds even
when I never say "SOTA" or "audit". Treat `~/.claude/profiles/<you>.md` as the
BUILD default and AUDIT baseline, and stop-and-ask on security-relevant choices.

3. (Optional) A per-prompt reminder. A directive read many turns ago can fade from a long context; a UserPromptSubmit hook in ~/.claude/settings.json re-injects it on every prompt:

{
  "hooks": {
    "UserPromptSubmit": [
      { "hooks": [ { "type": "command",
        "command": "echo 'Route code tasks through the sota router and apply the matching sota-* skills; the profile is the stack baseline.'" } ] }
    ]
  }
}

No mechanism forces a model to run a skill — the three layers feed it instructions it chooses to follow, making routing reliable, not phrasing-dependent.

Using it

With always-on routing set up (above), you don't name anything — describe the task in plain language and the right skills load automatically (see How it works). Name a skill or rule only to force a specific skill, scope to one rule file, or stack an exact combo.

Building — plain prompts; routing picks the skills:

Design a multi-tenant invoicing service — stack from my profile, or propose one.

Add a RAG search feature over our docs, and write the evals first.

Scaffold the GitHub Actions pipeline for this repo: SHA-pinned actions, OIDC, SBOM + signing.

We handle CUI on this service — what does that require of the architecture and data stores?

Auditing — say the mode ("audit", "review", "harden"):

Run a full audit of this repo. Static analysis only, current commit, report with a prioritized roadmap.

Audit this PR before I merge it.

Sweep the repo and git history for secrets — rotate-first recommendations.

Threat-model this service from the code: DFD, trust boundaries, STRIDE.

Audit our Kubernetes manifests and Dockerfiles. Severity + effort on every finding.

Why is checkout slow? Profile first — no guessing.

Review our agent's MCP setup for tool poisoning, rug pulls, and shadowing.

Naming a skill or rule (optional — to force or scope):

Add a websocket endpoint per sota-api-design rules/05 (auth-at-upgrade, backpressure).

Is this migration zero-downtime safe? Check sota-databases rules/02 (expand/contract, lock-aware DDL).

Review test-suite health against sota-testing rules/07 (flaky policy, coverage ratchets, speed budgets).

Audit this PR against sota-code-security + sota-golang before merge.

Maintaining the library:

Refresh the library — re-verify fast-moving claims against current primary sources, apply fixes, and update the root LAST-VERIFIED stamp.

Create profiles/.md for my stack: <stores, auth, platform, policies>.

Add a new skill for , same structure: SKILL.md + rules/ under 500 lines each, claims web-verified.

Tips:

• Say the mode if ambiguous — "audit/review/harden" vs "build/add/design"; skills key off those verbs.
• Scope audits explicitly — which commit/branch, static-only or may-run-tools, time budget ("crown jewels only"). The methodology file asks otherwise.
• Ask for the report format — default audit output is executive summary → findings by severity → roadmap by risk-reduction-per-effort → positive notes.
• Re-verify version-sensitive facts — web-check before pinning any version.

Optional setup & integrations

Beyond the skills themselves — all opt-in, none required to use the library.

Badge

Built or audited a project with the library? Ship the attribution :

[![Built with SOTA Skills](https://img.shields.io/badge/Built%20with-SOTA%20Skills-2fa45f)](https://github.com/martinholovsky/SOTA-skills)

Enforcing the gates

Routing makes the model apply the rules; to make them stick regardless of who (or what) commits, wire them as git hooks. scripts/init-gates.sh generates a SOTA-aligned .pre-commit-config.yaml for whatever languages it finds in the target repo:

cd /path/to/your/project
/path/to/SOTA-skills/scripts/init-gates.sh        # add --dry-run to preview first

It detects Python / Go / Rust / JS-TS / shell by manifest and extension, then writes the exact tools each skill prescribes — ruff·mypy·pytest·pip-audit, gofumpt·golangci-lint·govulncheck, clippy·cargo-audit, eslint·tsc·<pm> audit, shellcheck·shfmt, plus gitleaks everywhere. Fast checks (lint, format, secrets) run on commit; heavy ones (type-check, tests, vuln scans) run on push — the split sota-python rules/01 §6 and sota-devsecops rules/05 require, so commits stay quick.

It is idempotent: re-run it after adding a language and it rewrites only the block between its # >>> sota-gates >>> markers, leaving any hooks you added yourself in place. The hooks call your project's own toolchain, so install the per-language tools it lists on exit (and pre-commit install if the script couldn't).

Then check it actually took. init-gates.sh sets things up; nothing verifies the result, and "configured" and "working" render identically — a config file with no installed hook is not a control, and a CI job whose every run is skipped is a gate on paper.

/path/to/SOTA-skills/scripts/verify-setup.sh     # read-only; --runs N widens the CI sample

It reports skills reachability, the routing hook, the profile symlink, a licence under any name, which gates exist, whether a hook is installed rather than merely configured, and — from real run conclusions — whether CI has ever executed and ever rejected anything. It changes nothing and exits 1 on any FAIL. Anything it could not observe is marked UNVERIFIED, never passed: on this repo the reject-history check reads UNVERIFIED at the default sample and turns up a real rejection at --runs 200, which is why the sample size is printed. docs/VERIFY-SETUP.md carries the other half — a paste-in prompt for the judgement calls a script can't make: whether the agent file's content is meaningful and whether its claims are still true.

Add --docs-gate to also install a pre-commit hook that blocks a commit which changes code but updates no docs (README/CHANGELOG/docs//*.md) — so docs stay current without you having to ask. It writes a small helper to .sota/docs-gate.sh; it's heuristic (a docstring-only edit inside a code file will trip it) and bypassable with SKIP=sota-docs-gate git commit, which is why it's opt-in.

Other AI agents (Codex, Copilot, Gemini, …)

The skill content is plain Markdown — any model reads it. To route a non-Claude agent through the library, generate an AGENTS.md (the cross-tool open standard read by Codex, Cursor, Copilot, Gemini CLI, Windsurf, Zed, and more):

cd /path/to/your/project
/path/to/SOTA-skills/scripts/gen-agents-md.sh        # add --dry-run to preview

It writes a thin AGENTS.md that carries the operating principles and points the agent at the installed skills/ tree — the index is built from each skill's frontmatter so it stays in sync, and the agent reads the relevant rules/*.md on demand (no rule text is duplicated). Idempotent via a managed block, like the others; --skills-dir/--output override the defaults. Claude Code keeps using the native Skills install above. This repo itself follows the standard: AGENTS.md is canonical; CLAUDE.md/GEMINI.md are symlinks.

Status line (optional)

scripts/statusline.sh is a Claude Code status line that shows which skills you've actually used this session — not just how many are installed:

Opus 4.8 │ ctx 63% │ my-service ⎇ main │ skills▸ code-security, testing (2)

Claude Code's status-line input doesn't expose loaded skills, but it passes the transcript path; the script reads back the Skill invocations recorded there, falling back to a count of installed skills before any are used. Wire it up in settings.json (requires jq):

"statusLine": { "type": "command", "command": "/path/to/SOTA-skills/scripts/statusline.sh" }

Optional extras (for plugin users)

The plugin installs the skills; it deliberately does not touch your global config or status line — plugins are sandboxed by design, so the imperative setup the clone installer does can't be automated. To match the clone experience, opt in to any of these (the scripts ship with the plugin, under its cache dir):

• Always-on routing — add the UserPromptSubmit hook from Always-on routing so the skills apply without trigger words.
• Status line — point settings.json statusLine at the bundled scripts/statusline.sh (see Status line).
• Pre-commit gates / AGENTS.md — run the bundled scripts/init-gates.sh or scripts/gen-agents-md.sh against a project (see Enforcing the gates and Other AI agents).

The quickest path: just ask Claude to "set up the SOTA optional extras" — the first-run notice prompts for exactly this, and Claude will walk you through them.

Structure

skills/
  sota/                          # master router — start here
    SKILL.md                     # routing, operating principles, workflows
    rules/
      01-audit-methodology.md    # how to audit: tooling, evidence, reporting
  sota-<domain>/
    SKILL.md                     # when to use, BUILD/AUDIT workflows,
                                 # severity conventions, rules index, top-10
    rules/
      NN-<topic>.md              # ~80–350 lines each, ends with an Audit checklist
      ...
profiles/
  <user>.md                      # personal stack defaults consulted by router

Every skill works in two modes:

• BUILD — apply the rules while designing/writing code.
• AUDIT — review existing code; findings are emitted as file:line | rule violated | severity (Critical/High/Medium/Low/Info) | effort (trivial/small/medium/large) | fix.

Two cross-cutting pieces live outside the domain skills:

• skills/sota/rules/01-audit-methodology.md — how to run an audit: scoping, a verified static-analysis tool matrix, the evidence standard, and the report template (executive summary → findings → roadmap by risk-reduction-per-effort).
• profiles/ — per-user stack profiles: the default in BUILD mode, the expected baseline in AUDIT mode — keeping the library generic and shareable.

How it works

Claude Code matches your prompt against each skill's frontmatter description and loads what's relevant automatically — you don't have to name a skill. Naming one (or the sota router) just makes the routing explicit. From there:

1. The skill's SKILL.md loads first (workflows, severity conventions, an index of its rules/ files). Only the rules files matching your task are read — never the whole library.
2. BUILD mode applies the rules while writing code and self-checks the diff against each loaded rules file's Audit checklist before presenting it.
3. AUDIT mode hunts violations and reports findings as file:line | rule | severity | effort | fix. A full audit runs seven passes: recon → threat model → per-domain passes → silent-control pass (does each control confirmed to exist actually do anything?) → decision-ledger review → findings → refute before reporting. Scoping, evidence standard, severity model and report structure come from sota/rules/01-audit-methodology.md; the report ends in a roadmap sequenced by risk-reduction-per-effort.
4. If profiles/<you>.md exists, its stack choices are BUILD defaults and the AUDIT baseline (deviations get flagged).

Conventions

• Every rules file ends with an Audit checklist (yes/no questions, often with grep/lint patterns to hunt violations).
• Severity scale everywhere: Critical (exploitable/data loss) · High (fix this sprint) · Medium (bounded impact) · Low (hygiene) · Info (observations, no direct risk). Each finding also carries an effort estimate (trivial/small/medium/large) so remediation can be sequenced by risk-reduction-per-effort.
• Each SKILL.md carries a top-10 non-negotiables list — apply these unconditionally; load detailed rules files only as the task demands.
• Borderline severities state the deciding assumption; unconfirmed findings are marked "needs verification", never asserted.
• A negative claim needs more proof than a positive one. "No instances of X" and "I only looked one way" are indistinguishable from the outside, so an absence claim requires a widened search plus a second independent method, and the search actually run is stated.
• A positive observation must show effect, not existence — the request it rejected, the log line it emitted, the test that fails when it's disabled. An inert control praised as a strength is the worst reporting error available.

Found a gap? Tell us — it's the only signal we get

This library has no telemetry. Nothing reports back, by design. That also means a wrong rule, a stale version claim, or a task with no owning skill stays in the library for everyone until a human says so.

If a skill was wrong, outdated, or missing when you needed it: open an issue (bad-guidance / skill-request templates — both take about a minute). Dangerous or security-sensitive guidance goes to a private advisory instead.

The assistant will usually flag these itself: the router tells it to surface a one-line note when the library lets you down, rather than papering over it.

If it saved you time, a ⭐ helps other engineers find it.

Contributing

See CONTRIBUTING.md. The short version: keep skills generic, verify fast-moving claims against primary sources, keep skill files (skills/**) ≤ 500 lines — that cap keeps incremental rule loading working and does not apply to README/CHANGELOG/docs/, which are read by humans — and end each rules file with an audit checklist. Fourteen invariants enforce this in scripts/check-invariants.sh (pre-commit + CI), covering line caps, checklist placement, description limits, version and count drift, router completeness, internal link resolution, every rules file being reachable from its skill's index, a single [Unreleased] CHANGELOG entry, the LAST-VERIFIED stamp moving only with a sweep, a rendered assets/*.png never being older than the *.html it comes from, every scoreboard row declaring its sample size, and a release declaring the front door terms its new capabilities landed on — plus gitleaks (full-history scan in CI; per-commit via the pre-commit hook). Ideas taken from outside the repo are recorded with a verdict and reason in docs/ADOPTION-LOG.md, so a rejection isn't re-litigated. Security issues and conduct: SECURITY.md, CODE_OF_CONDUCT.md.

License

© 2026 Martin Holovsky. Licensed under CC BY 4.0 — Creative Commons Attribution 4.0 International. Use, adapt, and share freely (including commercially); just give attribution: "SOTA Engineering Skills by Martin Holovsky, CC BY 4.0."

profiles/ holds personal stack profiles and is git-ignored except profiles/example.md.template — copy that to profiles/<you>.md and edit it; your real profile stays local and is never committed.