A Claude Code / Agent Skill that adds rich, intent-focused comments to your code — in Hebrew or English — without changing any logic.
SaferSkills independently audited code-annotator (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
Add explanatory comments to code without changing a single line of logic. The goal is comments that a new developer could read to understand what the code does, why it does it that way, and how it connects to the rest of the codebase — not comments that merely restate the syntax.
i++ // increment i is noise. Comment intent, contracts, and non-obvious decisions — not self-evident syntax.// for Dart/TS/JS/PHP/C++, # for Python/Ruby/shell, <!-- --> for HTML, /// for Dart doc comments where appropriate.Decide per file, in this order:
Keep code identifiers, API names, and error strings exactly as they are — only the prose of the comments is translated.
Before commenting anything, build a mental map:
Only once you understand how the file fits into the whole do you start writing comments. This is what separates this skill from line-by-line description.
At the top of each file, add a header block:
// ─── <filename> — <one-line purpose in chosen language> ──────────────────────
// <1–3 lines: what this file is responsible for>
// <connections: who calls it / what it calls — e.g. "נקרא על ידי updateTicketStatus() ב-admin_dashboard.js">Use box-drawing dashes (─, U+2500) to pad the divider to a consistent width (~78 cols). Keep it tidy and aligned.
Split the file into logical scopes and label each one with a named divider:
// ─── <scope name> ───────────────────────────────────────────────────────────
// <why this scope exists / what it groups>Examples of scopes: "בדיקת method", "איסוף פרמטרים", "עדכון בDB", "Helpers", "State setup", "Render". Name them by intent, not by mechanics.
Above every function/method, explain:
// נקרא על ידי TaskRepository.submit() — מצפה ל-userId כבר מאומת.Inside functions, add short comments only where a decision is non-obvious or load-bearing. Prioritize:
After commenting, re-read the file as if you were new to it. Remove any comment that just echoes the code. Confirm: did you touch any logic? If yes, revert it.
This is the level of quality to aim for. The key thing to notice: the comments make the cross-file integration explicit. Each file's header names who it talks to, and the contract notes name the exact function or class on the other side — so a reader never has to guess how the pieces connect. The example below is three files of a small shopping cart: a shared helper, the code that uses it, and the stylesheet that shares a class-name contract with that code.
File 1 — `format-price.js` (a shared utility other files depend on):
// ─── format-price.js — currency formatting helper ──────────────────────────
// Pure function, no side effects. Turns an integer amount of minor units
// (cents / agorot) into a localized price string.
// Used by: cart.js → renderTotal(). If you change the return shape here,
// update the assertion in cart.test.js too.
export function formatPrice(minorUnits, currency = 'USD') {
// Work in minor units (integers) to avoid floating-point rounding errors.
// Callers MUST pass whole cents — passing 9.99 instead of 999 is wrong by 100x.
const major = minorUnits / 100;
return new Intl.NumberFormat('en-US', { style: 'currency', currency }).format(major);
}File 2 — `cart.js` (consumes the helper above, and shares a contract with the CSS):
// ─── cart.js — shopping cart rendering ─────────────────────────────────────
// Owns the cart DOM: reads cart state, renders rows, paints the total.
// Depends on: format-price.js (formatPrice).
// Shares a contract with cart.css: toggles the .cart--empty class — the class
// name must stay identical in both files or the empty-state styling breaks.
import { formatPrice } from './format-price.js';
// ─── total ─────────────────────────────────────────────────────────────────
function renderTotal(items) {
// sum stays in cents — formatPrice expects minor units, so we never divide here.
const sum = items.reduce((acc, item) => acc + item.priceCents * item.qty, 0);
// formatPrice() lives in format-price.js — we pass raw cents, not dollars.
totalEl.textContent = formatPrice(sum);
// .cart--empty is consumed by cart.css to hide the checkout button.
// Rename it here and you must rename it there too — silent breakage otherwise.
cartEl.classList.toggle('cart--empty', items.length === 0);
}File 3 — `cart.css` (annotating a non-code file: the skill understands the whole project, not just logic):
/* ─── cart.css — shopping cart styles ───────────────────────────────────────
Styles the DOM built by cart.js. Class names here are a contract with the JS:
cart.js toggles .cart--empty at runtime, so renaming it here silently breaks
the empty-state behavior. Keep the two files in sync. */
/* ─── empty state ─────────────────────────────────────────────────────────── */
/* Applied when cart.js sets .cart--empty (items.length === 0).
Hides the checkout button so an empty cart can't be submitted. */
.cart--empty .checkout-btn {
display: none;
}/// doc comments above public classes, widgets, and providers so they show up in IDE tooltips; use // for internal scope dividers and inline notes. For Riverpod providers, note what the provider exposes and who watches it.# comments for scopes; consider a short module docstring """...""" for the file header instead of a # block.~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.