A few years ago I started doing something embarrassing: making a list of software engineering best practices I actually knew well enough to apply.
SOLID principles. Conventional commits. Blameless retrospectives. The Google SRE handbook. A handful of others.
The list was shorter than I expected.
Not because I was lazy. I'd read plenty. But reading about a practice and having it available when you need it — at 11pm debugging a production incident, or mid-PR-review when you're already context-switched — are completely different things. The gap between knowing a practice exists and applying it consistently in daily work is enormous, and most of us just quietly accept it.
Then I started wondering how many practices I'd never even heard of. Architectural decision records. Pre-mortems. The Five Whys. The ABA Model Rules for legal review. Different domains — engineering, finance, law, medicine, leadership — each have decades of accumulated wisdom. Most of it is documented, cited, and public. None of it is particularly accessible.
What I wanted was a master. Someone who knew every relevant practice, could surface the right one for my exact situation, and would hold me accountable for actually following it. That used to cost $800/hr. I decided to build it instead.
I called it grimoire 🧙 — a wizard's book of spells.
📦 What is grimoire?
Think npm, but for AI agent best practices.
You declare which skill libraries you want in a grimoire.toml. Grimoire clones them from a git registry and symlinks the individual skill files into each AI agent's context directory. Skills show up as slash commands in Claude, tab-completable commands in Codex, and equivalently in other agents.
Then grimoire check audits your project against those installed practices — like ESLint, but for how you work, not just how you code.
# Install grimoire
curl -fsSL https://raw.githubusercontent.com/jeffreytse/grimoire/main/scripts/install.sh | bash
# Guided setup
grimoire wizard
# Install skills to all detected agents
grimoire install
# Run your first compliance check
grimoire check
That's the full loop.
🚀 From install to first wow
After grimoire install, skills appear immediately as slash commands. Here's what code review looks like after installing the engineering skill library:
User: /conduct-code-review
Claude: Reviewing staged changes against declared engineering standards...
VERDICT: REQUEST CHANGES
1. Missing test for the new token refresh path (auth/refresh.go:34)
→ coverage drops to 61%; your threshold is 80%
2. Secret potentially exposed in error message (api/handler.go:89)
→ raw token value in error string; wrap before logging
3. Breaking change undocumented
→ removeImplicitGrant() is public; needs BREAKING CHANGE footer
File a review comment? [y/n]
Not five bullet points. A structured verdict, with file locations and criteria, every time.
🧠 You don't need to know which skill to invoke
This is my favorite part. You don't need to memorize skill names. Just describe the situation and grimoire routes to the right practice:
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 — root causes, not symptoms
3. Action items with owners and deadlines
→ /plan-retrospective to run the session now
User: We're launching in 48 hours and I'm terrified something will break.
Claude: Situation matches: apply-premortem (engineering/reliability)
Followed by: design-slo → plan-incident-response
→ /apply-premortem to begin
suggest-best-practice auto-classifies any situation and routes it. If the relevant skill isn't installed, it tells you exactly what to add to your grimoire.toml.
🗂️ How skills actually work
A skill is a single markdown file — not a prompt, more like a runbook:
---
name: conduct-code-review
tags: [engineering, review]
description: Run a structured code review against declared standards.
source: https://google.github.io/eng-practices/review/reviewer/
---
## Steps
1. Identify the scope — what problem does this change solve?
2. Check test coverage: new code paths must have tests.
3. Review naming: does it match established project conventions?
4. Check for security implications: auth, input validation, secrets.
5. Identify breaking changes — flag with BREAKING CHANGE if present.
6. Issue a verdict: APPROVE / REQUEST CHANGES / COMMENT.
Every skill has a triggering condition, a cited source, numbered steps, and a verdict form. Not a suggestion — a procedure.
Here's the part I think is clever: the same file that teaches the AI how to do a code review is what grimoire check reads when auditing whether your project actually ran one. No separate compliance schema to maintain. Update the skill and both the guidance and the compliance criteria update in one step.
🔍 The compliance engine — grimoire check
grimoire check is where things get interesting.
grimoire check # full project audit
grimoire check --live # watch mode: re-checks on every file save
grimoire check --scope changed # incremental — changed files only (great for large repos)
grimoire check --junit report.xml # JUnit XML for GitHub Actions / GitLab CI
Result page:
Sample output:
$ grimoire check
✓ propose-conventional-commit 100% all 4 criteria passing
✓ apply-solid 88% 7/8 criteria passing
✗ conduct-code-review 62% below threshold (80%)
└─ missing: security-checklist, breaking-change-annotation
2 passed · 1 failed · exit 1
You can gate CI on this. Declare a threshold in grimoire.toml:
[standards]
threshold = 80 # fail CI below 80% compliance
The difference from other linters: ESLint checks whether your code is valid JavaScript. grimoire check checks whether your project actually follows the practices you declared. Did the last five commits use conventional commit format? Does the new auth module have adequate test coverage against your standards? Did the PR include a security checklist? Those are semantic questions — existing linters don't answer them.
🖥️ Editor integration (LSP)
grimoire lsp implements the Language Server Protocol. Point any LSP-capable editor at it and you get compliance diagnostics in the gutter on every file save.
Neovim:
if not configs.grimoire then
configs.grimoire = {
default_config = {
cmd = { 'grimoire', 'lsp' },
filetypes = { 'go', 'python', 'javascript', 'typescript', 'rust' },
root_dir = lspconfig.util.root_pattern('grimoire.toml', '.git'),
},
}
end
lspconfig.grimoire.setup {}
Helix:
[[language-server]]
name = "grimoire"
command = "grimoire"
args = ["lsp"]
No plugin required beyond a one-time language client config. VSCode is supported too.
🤖 MCP server — let the AI manage itself
grimoire mcp serve exposes all grimoire operations as MCP tools. Claude Desktop, Cursor, or Windsurf can manage their own skill library mid-conversation:
grimoire mcp serve # start the MCP server
grimoire mcp config # write config file to your editor
The AI can call grimoire_install, grimoire_update, grimoire_check as tool calls — detect a missing skill, install it, and immediately apply it, without you touching the terminal.
🌍 It's not just for engineering
This is the thing I keep having to say out loud: grimoire-core ships 1000+ skills across 27 domains.
Engineering. Architecture. Product management. Technical writing. Legal review. Financial analysis. Health. Leadership. Sales. Cooking.
The same infrastructure that enforces code review standards can enforce legal document review, financial due diligence, clinical protocol compliance, or onboarding documentation quality. The mechanism is identical — only the skills change.
That's the bigger bet: AI gives everyone comprehension. Grimoire gives everyone practice. The senior lawyer's review checklist, the experienced engineer's PR process, the McKinsey consultant's structuring framework — not proprietary, just previously inaccessible. Grimoire makes them installable.
📦 Declaring dependencies
# grimoire.toml — commit this to your repo
[package]
name = "my-project"
version = "0.1.0"
[dependencies]
"jeffreytse/grimoire-core" = "*" # all 1000+ skills
"jeffreytse/grimoire-core:engineering" = "*" # one domain only
"jeffreytse/grimoire-core@0.1.0" = "*" # pinned release
"mycompany/internal-skills" = "*" # your team's private practices
Any git repo is a valid package. Your company's internal engineering standards, a fintech-specific library, a jurisdiction-specific legal practices set — all install identically. Versions are locked in grimoire.lock (yes, it's exactly what you think it is).
✍️ Publish your own skills
If you've spent years mastering something, your practice belongs here.
# Validate your skill files
grimoire validate
# AI-powered auto-fix for conformance issues
grimoire validate --fix
# Preview before writing
grimoire validate --fix --dry-run
- Write skill markdown files (name, tags, description, source, steps)
- Push to any git repo
- Others install with
grimoire install yourgithub/yourpackage
Naming convention: yourorg/grimoire-fintech, yourorg/grimoire-legal-us, yourorg/grimoire-medical. Private repos work fine — install is identical.
🏁 Try it
curl -fsSL https://raw.githubusercontent.com/jeffreytse/grimoire/main/scripts/install.sh | bash
grimoire wizard
grimoire check
- GitHub: https://github.com/jeffreytse/grimoire ⭐
- Skills library: https://github.com/jeffreytse/grimoire-core
- Website: https://grimoire.jeffreytse.net
It's free, open source (MIT), and the wizard gets you to a first compliance check in about two minutes.
I'd love to know: what practices does your team currently enforce through system prompts or manual checklists? That's exactly the kind of thing that should probably be a grimoire skill.
Drop a comment or open an issue — especially if you want to contribute skills from your domain. 👇
