grounding-rules
initialneil/grounding-rules
A Claude Code skill: distill a system into a short, human-readable set of grounding rules — the load-bearing invariants that teach it in minutes and settle design questions.
Instalação
npx convez-ai initialneil/grounding-rules1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Grounding Rules
A Claude Code skill that distills a system or subsystem into a short, human-readable set of grounding rules — the minimal load-bearing invariants and design decisions that let a reader gain confidence in a system in minutes and settle future design questions, instead of reading a full spec for hours.
It follows the Agent Skills SKILL.md format, so it works in any skills-compatible agent (Claude Code, Codex CLI, …).
What it does
/grounding-rules produces a tight rules doc — the constitution of a module:
- a one-line mental model and a tl;dr of foundation rules,
- the one diagram (the entity skeleton),
- 8–15 numbered, load-bearing rules — each a one-line claim + why + a light
file:symbolanchor, - "Using these rules" — worked design questions each settled by citing a rule.
Three actions:
| Command | What it does |
|---|---|
/grounding-rules | A fresh grounding pass over the system you point it at. |
/grounding-rules update <facts> | Re-ground an existing doc when the system changed — not append; it re-runs the whole doc. |
/grounding-rules ask <question> | Answer a question from the real code, in the grounding voice. |
The guiding bar: a rule is for a human acting in good faith — its plain reading should make the right choice obvious. Optimize for fast confidence, not completeness; the moment you add clauses to fence edge cases, you're writing a spec, not a rule.
Install (Claude Code)
/plugin marketplace add initialneil/grounding-rules
/plugin install grounding-rules@grounding-rules
Then type /grounding-rules in any project.
Update to the latest version
/plugin update grounding-rules
Manual install
Copy skills/grounding-rules/ into ~/.claude/skills/ (global) or your project's .claude/skills/.
Optional: Obsidian
When you point the skill at a path inside an Obsidian vault, it invokes the
obsidian-markdown skill (if
installed) to format with frontmatter + callouts. It's a soft dependency —
plain Markdown is used everywhere else, and nothing breaks if it isn't installed.
Publishing a new version (maintainer)
Edit skills/grounding-rules/SKILL.md, then in this repo run:
/release [patch|minor|major | X.Y.Z] ["what changed"]
The /release skill (.claude/skills/release/, maintainer-only — not shipped to
consumers) runs the whole pipeline: it publishes (bumps both manifests,
prepends CHANGELOG.md, commits, tags v<version>, pushes — via
scripts/publish.sh) and refreshes your local install
(claude plugin marketplace update grounding-rules). Everyone else picks up the
new version with /plugin update grounding-rules.
Prefer the raw script? scripts/publish.sh patch "what changed" does the publish
half (no local refresh).
License
MIT — see LICENSE.