jeffreytse/grimoire

🧙 Grimoire is a free, open-source package manager for best practices — 1000+ skills across 26 domains (engineering, law, finance, design, health, and more), each sourced from a real institution or ...

18 stars · 1 forks · Go Topics: productivity, best-practices, opencode, gemini, developer-tools, cursor, knowledge-base, multi-domain, copilot, codex, expert-system, ai-agents, claude, cli-tool, lsp-server, open-standard, compliance-as-code, ai-tools, skills-manager, openclaw

README

The world's knowledge is in your AI. The world's practice is not.A modern skills manager for AI agents — install, manage, and enforce best practices the way npm manages packages. 📖 Grimoire 📖

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

[dependencies] "jeffreytse/grimoire-core" = "*" # official package — all 1000+ skills "jeffreytse/grimoire-core:engineering" = "*" # one domain only "jeffreytse/grimoire-core@0.1.0" = "*" # 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/grimoire-core@0.1.0" # pinned to a specific release grimoire install "jeffreytse/grimoire-core@0.1.0: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-<name> 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

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

For subdomain-level installs, use grimoire

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 compliance diagnostics in the gutter in real time — no plugin required beyond a one-time language-client config. How it works: on every file save the server runs grimoire check in the background and pushes findings as LSP diagnostics to your editor. Pass/hint items are suppressed; only errors, warnings, and info appear.

Editor Setup

Neovim lspconfig custom server (see below)

VSCode grimoire extension, or tasks.json with a custom server entry

Helix languages.toml custom language server entry

Any LSP client Point cmd at grimoire lsp

Neovim (nvim-lspconfig): local lspconfig = require('lspconfig') local configs = require('lspconfig.configs')

if not configs.grimoire then configs.grimoire = { default_config = { cmd = { 'grimoire', 'lsp' }, filetypes = { 'go', 'python', 'javascript', 'typescript', 'rust', 'ruby' }, root_dir = lspconfig.util.root_pattern('grimoire.toml', '.git'), single_file_support = true, }, } end

lspconfig.grimoire.setup {} Helix (languages.toml): [[language-server]] name = "grimoire" command = "grimoire" args = ["lsp"]

[[language]] name = "go" language-servers = ["gopls", "grimoire"] VSCode (settings.json — requires grimoire extension or a custom extension): { "grimoire.lsp.enable": true, "grimoire.lsp.command": "grimoire", "grimoire.lsp.args": ["lsp"] } 🚀 Quick Start New to grimoire? Run the interactive wizard: grimoire wizard The wizard walks you through registry selection, domain choice, and agent linking — no manual config editing. It detects your installed AI agents and installs the right skills automatically.

After install, describe any problem in plain language: User: I need to raise a Series A but don't know how to pitch investors.

Claude: Situation matches: write-value-proposition + design-go-to-market + apply-pyramid-principle Applying suggest-best-practice... → Start with your value prop. /write-value-proposition

Or invoke a skill directly: /suggest-best-practice # describe any problem — auto-routes to the right skill /review-pull-request # engineering code review /calculate-fire-number # how much do I need to retire? /review-saas-contract # flag dangerous clauses before signing /design-training-program # build a training program

For CI enforcement, initialize once per project and gate PRs with the grimoire CLI: grimoire init # creates grimoire.toml with auto-detected profile grimoire check # exits 0 (pass) or 1 (fail) New to grimoire? Start with /suggest-best-practice. Describe any professional or life situation — it reads your context and routes you to the matching skill, or tells you exactly what to install if the skill isn't in your library yet. 🎯 Workflows

Your situation Start here

Know exactly which skill you need /skill-name directly

Have a problem, unsure which skill /suggest-best-practice

Already have a plan, want gaps checked /review-best-practice-fit

Needs 2+ practices coordinated — within one domain or across many — and sub-problems are identifiable upfront /plan-best-practice-solution

Complex problem where sub-problems are opaque and emerge through execution /apply-best-practice-tree

Don't know what practices exist for a topic /discover-best-practices

About to start a task — want to catch gaps before you begin /start-best-practice

Problem isn't clear yet — need to define it before solving /analyze-best-practice-problem

Activate a paradigm's best practices (OOP, TDD, etc.) /apply-best-practice-profile

Align any project or artifact to stated best practice preferences (BPDD) /apply-best-practice-driven-development

Check if any artifact aligns with stated best practice preferences /check-best-practice-compliance

Have a specific compliance finding to fix /fix-best-practice-finding

Two practices exist — want side-by-side comparison /compare-best-practices

Two practices conflict — want to reason through which fits /resolve-best-practice-conflict

Resolved a conflict — want to save the decision for future sessions /pin-best-practice-preference

Get oriented on grimoire itself — what it is, why, how to use it /learn-grimoire

Actually internalize a practice — active recall, spaced review, so you can use it without AI /learn-best-practice

Understand what a skill does and why it exists /explain-best-practice

Adapt a skill to a different context or constraint /adapt-best-practice

Teach a practice to someone else (structured walkthrough) /teach-best-practice

→ BPDD guide — cycle, compliance linter, LSP output, suppression, CI integration Common paths Describe any problem → suggest-best-practice Describe any situation. suggest-best-practice reads it, finds the best-matching skill(s), and routes you there. User: My senior engineer just quit and the team is losing confidence.

Claude: Situation matches: design-onboarding-program + write-leadership-principles → /design-onboarding-program to rebuild team structure → /write-leadership-principles to establish decision-making clarity

Multiple practices needed → plan-best-practice-solution When a problem needs 2+ practices coordinated in sequence — within one domain or across many — plan-best-practice-solution decomposes it with MECE methodology, sequences skills by dependency, and recursively plans complex sub-problems. User: I want to leave my job and launch a SaaS startup.

Claude: Situation spans 4 domains. Solution plan: 1. design-business-model — validate the idea before building 2. calculate-unit-economics — confirm revenue model is viable 3. review-saas-contract — legal structure before hiring 4. design-go-to-market — growth strategy before launch

Apply in order? I'll pause for confirmation after each step.

Catching gaps before you start → start-best-practice Before any task begins, start-best-practice intercepts, surfaces the relevant practices you should apply, and applies them — so you enter the work already aligned instead of discovering gaps mid-execution. User: I'm about to write performance reviews for my team.

Claude: Applying start-best-practice... Relevant practices: conduct-performance-review + write-developmental-feedback → Running /conduct-performance-review to establish evaluation structure → Running /write-developmental-feedback for written output format Ready to proceed.

Opaque complex problem → apply-best-practice-tree When sub-problems are unknown until you start solving — apply-best-practice-tree builds a dynamic execution tree, discovering and applying practices as the structure emerges. User: My product is losing users and I don't know why.

Claude: Applying apply-best-practice-tree... Root: diagnose-user-churn ├─ run-exit-survey-analysis → reveals: onboarding drop-off │ └─ audit-activation-funnel → reveals: Day 3 aha-moment missing │ └─ redesign-onboarding-sequence └─ analyze-retention-cohorts → reveals: power users staying; casual dropping └─ segment-engagement-model

Internalizing a practice → learn-best-practice When you want to actually own a practice — not just apply it once — learn-best-practice runs active recall, spaced-repetition review, and scenario drilling so you can use it without AI in the future. User: I want to actually learn MECE decomposition, not just use it.

Claude: Starting learn-best-practice: mece-decomposition Round 1 — concept + example Round 2 — you decompose this problem (I'll score it) Round 3 — harder variant, novel domain Review scheduled: +3 days, +10 days, +30 days

source