Hush

An Agent Skill that enforces self-documenting naming and minimal, high-signal comments in AI-generated and AI-edited code.

What it does

• Prefers a rename over a comment whenever a name alone can carry the meaning.
• Caps ordinary comments at ~3 lines, breaking lines at clause boundaries — clarity of the break outranks the line count.
• Writes full doc comments with usage examples for public/exported API surfaces (library boundaries), with no length cap there.
• Always comments non-obvious behavior — invariants, workarounds, gotchas — regardless of public/private visibility.
• Comments a branch (if/for/while/switch) only when its condition or body can't be inferred from the names involved.

See skills/hush/SKILL.md for the full ruleset.

Two sibling skills apply that same ladder to code that already exists:

• hush-review — audits comments in the current diff (or a given path/branch/PR) and reports findings, read-only.
• hush-fix — runs the same audit and applies the fixes: renames to drop redundant comments, adds missing public API docs, trims oversized comments, updates or removes stale ones.

Install

With the skills CLI (npx skills):

npx skills add ro80t/hush

Update later with:

npx skills update hush

This installs skills/hush/SKILL.md into the right directory for your agent (.claude/skills/, ~/.codex/skills/, .cursor/rules/, etc.) — the skill file itself is agent-agnostic.

Claude Code plugin marketplace

This repo self-hosts a Claude Code marketplace (.claude-plugin/marketplace.json + plugin.json). Add it as a marketplace source, then install:

/plugin marketplace add ro80t/hush
/plugin install hush@hush

Codex plugin marketplace

Same pattern for Codex (.codex-plugin/marketplace.json + plugin.json, pointing at the same skills/ directory):

codex plugin marketplace add ro80t/hush
codex plugin install hush

Manual install

Copy skills/hush/ into whichever directory your agent scans for skills (e.g. ~/.claude/skills/hush/, ~/.codex/skills/hush/).

Everyone else

Agents that don't support a skills/plugin system read plain instruction files. skills/hush/SKILL.md is the single source of truth — the block between <!-- RULE-SUMMARY:START --> and <!-- RULE-SUMMARY:END --> is extracted verbatim into every file below by npm run sync (node scripts/sync-rules.mjs). Edit SKILL.md, run npm run sync, and every adapter updates together — no hand-copying, and no symlinks (a symlink would drag SKILL.md's YAML frontmatter and worked Examples into files that must stay plain instructions, and breaks on a GitHub zip download or a Windows checkout without symlink support). npm run check reruns the sync and fails if anything is out of date — wire it into CI to catch drift.

Agent / editor	File
GitHub Copilot	.github/copilot-instructions.md
Cursor	.cursor/rules/hush.mdc
Windsurf	.windsurf/rules/hush.md
Cline	.clinerules/hush.md
Kiro	.kiro/steering/hush.md
Qoder	.qoder/rules/hush.md
Generic .agents/ convention (OpenCode, Devin, etc.)	.agents/rules/hush.md
Gemini CLI	GEMINI.md, referenced by gemini-extension.json's contextFileName

Root-level AGENTS.md and CLAUDE.md are not part of this list — see Developing this repo.

Developing this repo

skills/hush/SKILL.md is the only file you hand-edit; everything else in this section is generated by npm run sync. See AGENTS.md for the full dev guide (this is what an agent working on hush itself should read — CLAUDE.md just points here with one Claude-specific note).

This repo also dogfoods its own skill: .claude/skills/hush/SKILL.md and .agents/skills/hush/SKILL.md are full copies of skills/hush/SKILL.md, placed where Claude Code and other .agents/skills/-aware agents auto-discover project-local skills — so opening this repo directly loads Hush for the session.

Repo layout

hush/
  skills/
    hush/
      SKILL.md              # the skill itself — name + description frontmatter, then the full ruleset + examples
    hush-review/
      SKILL.md              # read-only audit of existing comments against the hush ladder
    hush-fix/
      SKILL.md              # same audit, but applies the fixes
  .claude/
    skills/hush/SKILL.md     # generated full copy — Claude Code project-local dogfood
  .agents/
    skills/hush/SKILL.md     # generated full copy — generic .agents/skills/ dogfood
    rules/hush.md            # generated condensed copy — distributed to consumer projects
  .claude-plugin/
    plugin.json              # Claude Code plugin manifest
    marketplace.json         # self-hosted Claude Code marketplace listing
  .codex-plugin/
    plugin.json              # Codex plugin manifest (points "skills" at ./skills/)
    marketplace.json         # self-hosted Codex marketplace listing
  scripts/
    sync-rules.mjs           # generates every file below from SKILL.md
  AGENTS.md                 # hand-maintained — dev guide for people working on hush itself
  CLAUDE.md                 # hand-maintained — points at AGENTS.md, Claude-specific note
  GEMINI.md                 # generated — Gemini CLI context file
  gemini-extension.json     # Gemini CLI extension manifest, contextFileName: GEMINI.md
  .github/copilot-instructions.md
  .cursor/rules/hush.mdc
  .windsurf/rules/hush.md
  .clinerules/hush.md
  .kiro/steering/hush.md
  .qoder/rules/hush.md
  README.md
  LICENSE

Adding another sibling skill later just means a new skills/<name>/SKILL.md directory — no other changes needed, same as hush-review and hush-fix above.

License

MIT — see LICENSE.