hush
Self-documenting naming and minimal, high-signal comments for AI coding agents.
Open source Open in the app JSON README (API)
About
Self-documenting naming and minimal, high-signal comments for AI coding agents.
Details
- Kind
- Plugins
- Topic
- No topic detected
- Publisher
- ro80t
- Origin
- gemini
- Category
- ferramentas
- Version
- 1.0.0
- Stars
- 1
- Last push
- 2026-09-12T15:04:50Z
- Repository state
- ativo
- Language
- JavaScript
- License
- MIT
- Added
- 2026-09-12 17:04:37
- Updated
- 2026-09-12 17:04:37
- Origin id
ro80t/hush
README
# Hush
An [Agent Skill](https://github.com/vercel-labs/skills) 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`](skills/hush/SKILL.md) for the full ruleset.
## Install
With the [skills CLI](https://github.com/vercel-labs/skills) (`npx skills`):
```bash
npx skills add ro80t/hush
```
Update later with:
```bash
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:
```bash
/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):
```bash
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).
## 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`](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
```tree
hush/
skills/
hush/
SKILL.md # the skill itself — name + description frontmatter, then the full ruleset + examples
.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 a sibling skill later (e.g. a `hush-review` that audits an existing diff for comment-noise) just means a new `skills/<name>/SKILL.md` directory — no other changes needed.
## License
MIT — see [`LICENSE`](LICENSE).