Convention

Apply the Iceberg Convention — an asymmetric complexity management framework in which senior-authored code absorbs system complexity below an architectural airgap, exposing a frictionless, hard-to-misuse surface above it for juniors and AI agents. This is a language- and framework-agnostic convention; Claude applies the rules as patterns and picks the idiomatic enforcement mechanism for whatever ecosystem the target code lives in. Use this skill whenever writing, reviewing, or auditing code in a codebase that follows the Iceberg Convention (or should); when setting up a new project's architectural guardrails; when authoring module-boundary rules, AST-level linters, branded/nominal type scaffolding, finite state machines for async workflows, or Architectural Decision Records; when making design-review decisions about API boundaries, state management, type systems, purity, or how to make code hard to misuse. Trigger whenever the user mentions 'iceberg convention,' 'airgap,' 'asymmetric complexity,' 'junior-friendly architecture,' 'compiler-driven mentorship,' 'defensive type engineering,' 'state-machine dictatorship,' 'observability as documentation,' or the five pillars. Also trigger — even without those phrases — when the user asks to reduce cognitive load for less-experienced teammates, make an API hard to misuse, replace ad-hoc boolean flags with a state machine, brand scalar primitives to prevent ID mix-ups, enforce a layered architecture at compile time, build guardrails for AI coding agents, or audit an existing codebase for maintainability and mentorship-quality issues. Do not skip this skill just because the user didn't use the exact name — if the task is about making senior-authored code safe for juniors or AI agents to consume, this skill applies.

mkdir -p ~/.claude/skills/convention
curl -L https://claudskills.com/skills/convention/SKILL.md \
  -o ~/.claude/skills/convention/SKILL.md

@misc{convention-2026,
  author    = {ziadoz},
  title     = {Convention [Claude Code skill]},
  year      = {2026},
  publisher = {ClaudSkills},
  url       = {https://claudskills.com/skills/convention/}
}