semantics

Audit semantic contracts across code, APIs, versions, tokens, and UI signifiers.

1|Updated May 6, 2026
One-click install
npx skills add https://github.com/jacob-balslev/skill-graph --skill semantics
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: semantics
Source: https://github.com/jacob-balslev/skill-graph/tree/main/marketplace/skills/semantics
Command: npx skills add https://github.com/jacob-balslev/skill-graph --skill semantics

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

It prevents semantic drift by ensuring names and signals in code, APIs, versions, tokens, UI labels, and typed concepts consistently encode the meaning they claim to represent.

Core Features & Use Cases

  • Semantic naming audits: identify ambiguous, misleading, overly generic, or weasel-suffix identifiers (functions, variables, fields, files, database columns).
  • Compatibility signaling: apply SemVer and Conventional Commits rules so version bumps and commit types match the real impact of changes.
  • Contract correctness across surfaces: review HTTP status semantics, semantic design-token architecture, and semantic UI signifiers (including the never-color-alone rule).
  • Typed semantic boundaries: use branded/semantic types and parse-don’t-validate guidance to avoid illegal states and meaning-mixing (e.g., IDs, money, email).
  • Anti-pattern detection: catch cases where syntax is valid but the encoded meaning is wrong (e.g., misleading “200 with error body”, appearance-based token naming).

Quick Start

Ask an agent to audit your change for semantic correctness by checking naming truthfulness, version/commit impact alignment, and HTTP/status-token/UI signal meaning consistency.

Frequently Asked Questions about semantics

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I detect semantic drift in API and code naming conventions?

Semantic drift detection involves auditing naming conventions, API fields, and typed concepts to ensure identifiers consistently encode their claimed meaning. This process catches ambiguous, overly generic, or misleading identifiers across cross-domain projects before they break system contracts.

How do I decide the correct SemVer and Conventional Commits bump for my changes?

Determining the correct SemVer and Conventional Commits bump requires aligning version increments and commit types with the actual impact of changes. Applying evidence-backed rules ensures compatibility signaling matches real breaking changes, feature additions, or fixes.

What is the never-color-alone rule for semantic design tokens and UI signifiers?

The never-color-alone rule for semantic design tokens requires pairing color-based UI signifiers with secondary visual cues. Applying this rule prevents accessibility failures and misleading signals by ensuring meaning is never encoded exclusively through color.

How do I use branded types and parse-don't-validate to prevent illegal states?

Using branded semantic types and parse-don't-validate guidance prevents illegal states and meaning-mixing by enforcing strict typed boundaries. This approach catches cases where syntax is valid but encoded meaning is wrong, such as mixing IDs, money, or email values.

When should I audit HTTP status semantics for contract correctness?

Auditing HTTP status semantics is needed when reviewing API contract correctness across surfaces, especially to catch anti-patterns like valid syntax but wrong encoded meaning. Applying RFC 9110 evidence-backed rules verifies status codes match response bodies.

Can I audit semantic naming smells across database columns and UI labels simultaneously?

Auditing semantic naming smells across database columns, UI labels, and variables simultaneously is supported for cross-domain projects. This governance process identifies weasel-suffix identifiers and misleading signals, outputting deterministic verification criteria for alignment.