Show HN: Grimoire – Best Practices for Everyone Installed for Your AI Agents

Uh oh!

There was an error while loading. Please reload this page.

Notifications You must be signed in to change notification settings

Fork 1

Star 18

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

70 Commits

70 Commits

.github

.github

assets

assets

cmd

cmd

internal

internal

scripts

scripts

.gitignore

.gitignore

.golangci.yml

.golangci.yml

AGENTS.md

AGENTS.md

CLAUDE.md

CLAUDE.md

LICENSE

LICENSE

Makefile

Makefile

README.md

README.md

SECURITY.md

SECURITY.md

go.mod

go.mod

go.sum

go.sum

main.go

main.go

Repository files navigation

The skills package manager for AI agents — with a built-in practices linter.

Declare the practices you require. Install them in one command. Enforce them automatically,

in CI, on every save, across every domain.

Why | Features | Install | Quick Start | Domains | Contributing | Changelog | License

Built with ❤︎ by jeffreytse and contributors

🎬 Demo

"We're launching our SaaS in 48 hours. I'm terrified something will break. What do we do?"

Not an engineer? See Skills in Action for a sample, or browse all 27 domains in grimoire-core.

🤔 Why Grimoire?

Your AI knows everything — Grimoire makes it practice it.

Books gave everyone knowledge. Google gave everyone access. AI gave everyone comprehension. None of them gave everyone practice. Grimoire does.

The model knows SOLID, DDD, Google SRE, and the ABA Model Rules. Without explicit guidance, it enforces none of them. Grimoire is the enforcement layer — skills: named, citable, executable units of expert practice, one concept, one source, one set of steps.

🔍 You don't know what you don't know. Grimoire surfaces the governing standard you didn't know applied.

🤖 Knowing is not enough. Grimoire enforces. Specific steps, verifiable criteria, repeatable results. Not summaries — verdicts.

🌍 The world's best practices belong to everyone. McKinsey charges $1M. Senior lawyers bill $800/hr. The practices they follow are not proprietary. Grimoire makes them free — as executable steps, cited and verified.

🧱 Every profession. Every AI. 1000+ skills across 27 domains. Works with Claude, Copilot, Codex, Cursor, Gemini, OpenCode, OpenClaw, and Antigravity.

📦 Package-managed. Declare skills in grimoire.toml, lock versions in grimoire.lock. Reproducible skill sets across machines and teams — like Cargo or npm for best practices.

🌐 Open ecosystem. Any git repo is a grimoire package. We encourage community packages to follow the grimoire skill standard — but it's not required. Pair grimoire-core with company-internal skills, community packages, or your own library; all declared in one grimoire.toml.

🔬 Semantic compliance, not syntax checking. Other tools lint whether your CLAUDE.md is valid TOML. Grimoire checks whether your project actually follows the practices it declared — criteria by criteria, domain by domain. grimoire check is ESLint for practices. Gate CI with exit codes. Watch for changes with --live.

If you've spent 10,000 hours mastering something, your practice belongs here.

→ Read the full philosophy

📦 Skills as Packages

Every AI coding tool ships its own config format — CLAUDE.md, .cursorrules, AGENTS.md. Developers copy-paste and drift. Grimoire solves this with a package manager model: declare the practices you need in grimoire.toml, pin versions in grimoire.lock, install to every agent in one command.

Any git repo is a valid package. grimoire-core is the official one — curated, cited, peer-reviewed. Tools like Tessl distribute skills broadly. Grimoire adds the enforcement layer: curated expert practices, version-locked, with grimoire check to close the loop from declaration to compliance.

grimoire.toml — commit this to your repo

[package] name = "my-project" version = "0.1.0"

[dependencies] "jeffreytse/grimoire-core" = "*" # official package — all 1000+ skills "jeffreytse/grimoire-core:engineering" = "*" # one domain only "jeffreytse/[email protected]" = "*" # pinned to a specific release "mycompany/internal-skills" = "*" # private company package

grimoire install jeffreytse/grimoire-core # all skills from official package grimoire install "jeffreytse/grimoire-core:engineering" # engineering domain only grimoire install "jeffreytse/[email protected]" # pinned to a specific release grimoire install "jeffreytse/[email protected]:health" # pinned release + health domain grimoire install "gitlab.com/mycompany/internal-skills" # any git repo as a package grimoire install # (re-)install all from grimoire.toml grimoire update # update all packages to latest grimoire list # show installed packages and skills grimoire uninstall mycompany/internal-skills # remove a package

Ref syntax: owner/repo[@tag][:path] — the :path suffix is a Standard Glob pattern (doublestar) matched against each skill's domain path. matches any depth; * matches within one segment. Examples: engineering/ (all engineering skills), health/sleep/ (one subdomain only), /development/** (development subdomain in any domain).

Package Type Quality gate

grimoire-core Official STANDARD.md peer review required

Any git repo Community / private Owner's discretion

grimoire-core is the official package — curated, cited, and reviewed against STANDARD.md. But grimoire manages any package without restriction. Mix and match.

Community packages install identically to grimoire-core. We encourage following the grimoire skill standard for quality and interoperability — but any git repo works. Publish as grimoire- for discoverability:

Package example Focus

yourorg/grimoire-fintech fintech-specific practices

yourorg/grimoire-medical clinical protocols, FDA workflows

yourorg/grimoire-legal-us US jurisdiction guides

yourorg/internal-skills your team's private practices

The practices in your installed packages define what grimoire check validates against — declare the package, get the linter rules for free.

🔬 Linting for Practices

Declare which practices your project follows. grimoire check enforces them — CI gate, watch mode, or on-demand.

grimoire check # run compliance check against declared practices grimoire check --live # watch mode — re-check on every file save grimoire check --live --port 8080 # custom port (default 7890) grimoire check --live --host 127.0.0.1 # localhost-only (default: all interfaces) grimoire check --junit report.xml # JUnit XML output for CI systems grimoire check --scope changed # check only changed files (incremental)

Sample output:

✓ propose-conventional-commit 100% all 4 criteria passing ✓ apply-solid 88% 7/8 criteria passing ✗ review-pull-request 62% below threshold (80%) └─ missing: security-checklist, breaking-change-annotation

2 passed · 1 failed · exit 1

Gate any PR: grimoire check --junit report.xml exits non-zero when coverage drops below the configured threshold. No other tool checks whether your project follows its declared practices — only whether the config file is valid.

✨ Skills in Action

Engineering — propose a commit message from staged diff:

User: /propose-conventional-commit

Claude: Inspecting staged changes...

feat(auth): add OAuth2 PKCE flow for mobile clients

Replaces implicit grant with PKCE to address RFC 6749 §10.16 implicit flow vulnerabilities in native apps.

Approve? [y/n]

Every skill is structured: triggering condition, verified source, numbered steps, no freeform guessing.

Or describe the situation in plain language — you don't need to know which skill applies:

User: My team keeps missing sprint goals and I don't know why.

Claude: Situation matches: plan-retrospective (engineering/project-management)

Run a blameless retrospective (Amazon format):

1. Timeline reconstruction — what actually happened
2. Five whys — surface root causes, not symptoms
3. Action items with owners and deadlines

→ /plan-retrospective to run the session now

suggest-best-practice auto-classifies any situation, routes to the matching skill, or tells you exactly what to install if the skill isn't in your library yet.

→ See skills across all 27 domains — law, finance, health, cooking, and more

⚒️ Install

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/jeffreytse/grimoire/main/scripts/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/jeffreytse/grimoire/main/scripts/install.ps1 | iex

Go:

go install github.com/jeffreytse/grimoire@latest

Then run the interactive wizard (all platforms):

grimoire wizard # guided setup: registry, domains, agents — no config editing required

Or set up manually:

grimoire update # fetch the official skill library grimoire install # install to all detected AI agents

Auto-detects Claude Code, Codex, Gemini CLI, OpenClaw, and OpenCode.

Native plugin shortcuts (Claude Code):

Step 1: add the marketplace

/plugin marketplace add jeffreytse/grimoire-core

Step 2: install (skills are namespaced, e.g. /grimoire-engineering:propose-conventional-commit)

/plugin install grimoire@grimoire-core # all domains (latest) /plugin install grimoire-engineering@grimoire-core # one domain

For subdomain-level installs, use grimoire

Package management:

grimoire install jeffreytse/grimoire-core # add + install official package grimoire install myorg/my-skills # add + install any git repo as a package grimoire uninstall myorg/my-skills # remove + unlink a package grimoire update # update all packages to latest grimoire update --force # update, discarding any local package modifications grimoire list # list installed packages and skill counts

Granular installs (within a package):

grimoire install # install all packages grimoire install --domain engineering grimoire install --domain engineering --subdomain development grimoire install --skill engineering/development/propose-conventional-commit grimoire install --target all # install to all agents, even if not detected grimoire doctor # health check: git repo, symlinks, config grimoire version # version info with commit and date

Gemini CLI:

gemini extensions install https://github.com/jeffreytse/grimoire-core # latest gemini extensions install https://github.com/jeffreytse/[email protected] # pin to a release gemini extensions update grimoire # update later

Cursor:

grimoire install --target cursor

OpenCode:

grimoire install --target opencode

Or via plugin in opencode.json:

{ "plugin": ["grimoire@git+https://github.com/jeffreytse/grimoire-core"] }

OpenClaw: see .openclaw/INSTALL.md or run grimoire install --target openclaw.

Antigravity CLI (agy):

grimoire install --target antigravity

Or natively via agy plugin install https://github.com/jeffreytse/grimoire-core. Skills land in ~/.gemini/config/skills (global) or .agent/skills (project-scoped); the trigger line is written to ~/.gemini/AGENTS.md.

🤖 Agent Support

Agent Plugin install Script install

Claude Code /plugin marketplace add jeffreytse/grimoire-core then /plugin install grimoire@grimoire-core grimoire install --target claude

GitHub Copilot CLI copilot plugin marketplace add jeffreytse/grimoire-core then copilot plugin install grimoire@grimoire-core grimoire install --target all

Gemini CLI gemini extensions install https://github.com/jeffreytse/grimoire-core grimoire install --target gemini

OpenCode See .opencode/INSTALL.md grimoire install --target opencode

OpenClaw See .openclaw/INSTALL.md grimoire install --target openclaw

Codex CLI AGENTS.md auto-loaded; browse /plugins in CLI grimoire install --target codex

Cursor AGENTS.md context injection grimoire install --target cursor

Antigravity CLI (agy) agy plugin install https://github.com/jeffreytse/grimoire-core grimoire install --target antigravity

🖥️ Editor Integration (LSP)

grimoire lsp implements the Language Server Protocol over stdio. Any LSP-capable editor gets comp

[truncated for AI cost control]