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 📖

"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.

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

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/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).

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:

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

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.

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

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/grimoire-core@v1.0.0    # 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.

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.

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"]
}

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.

→ BPDD guide — cycle, compliance linter, LSP output, suppression, CI integration

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

When top-tier orgs disagree (Google vs IBM, startup vs enterprise), pin which approach you prefer once — grimoire applies it automatically from then on.

User: I follow Google's engineering practices when there's a conflict.

Claude: Pinning preference: Google Engineering Practices → engineering domain.
        Save to: session / project / global?

User: global

Claude: Saved to ~/.config/grimoire/grimoire.toml.
        Future engineering conflicts resolve toward Google's approach automatically.

Override priority — grimoire checks preferences in this order, first match wins:

Configure manually — edit the settings files directly without going through the AI:

# ~/.config/grimoire/grimoire.toml  (global — applies everywhere)
profiles = ["oop"]                 # activate all skills tagged "oop"
# profiles = ["clean-architecture", "tdd"]  # multiple — first entry wins conflicts

[engineering]
practices = ["Google Engineering Practices"]

[finance]
practices = ["CFA Institute standards"]

# grimoire.toml  (project — overrides global for this repo)
[engineering.architecture]
practices = [
  "SOLID principles: production code",
  "KISS: prototypes, scripts"
]
fallback = "ask"

Project configuration overrides global. Session pins override both. Teams can share a global standard while individual projects deviate where needed.

practices = ["OOP"] vs profiles = ["oop"] — both signal OOP intent, but differently. practices = ["OOP"] in a domain section is a loose hint — the AI leans toward OOP conventions from its training. profiles = ["oop"] at the top level activates specific installed skills (exact steps, validated sources). Use profiles for precision; practices for domain-level style preference. → Full comparison

Guided configuration:

• /configure-grimoire — view, edit, or validate config without touching TOML directly
• /apply-best-practice-profile — activate a full paradigm (OOP, TDD, clean architecture) in one command
• /resolve-best-practice-conflict — resolve contradictions between two installed skills and record the priority automatically
• /apply-best-practice-driven-development — run the full BPDD cycle (BPDD guide)

→ Full configuration reference — all keys, override hierarchy, TOML examples

Activate a named set of skills in one line — no list to maintain, no file to create.

# grimoire.toml
profiles = ["oop"]   # activates every installed skill tagged "oop"

Grimoire resolves the name in this order, first match wins:

1. .grimoire/profiles/<name>.toml — project-level file
2. ~/.grimoire/profiles/<name>.toml — user-level file
3. .grimoire/profiles/default.toml — project-level fallback
4. ~/.grimoire/profiles/default.toml — user-level fallback
5. [profiles.<name>] in grimoire.toml — inline definition (no separate file needed)
6. Tag query — all installed skills where tags contains the name

If no file or inline definition exists, the tag query fires automatically. profiles = ["oop"] works without creating any file.

Multiple profiles — combine paradigms; first entry wins conflicts, duplicates are deduplicated:

profiles = ["clean-architecture", "tdd"]  # clean-architecture wins if both include the same skill

Custom profile — curate a team-specific subset when the tag set is too broad:

# .grimoire/profiles/my-team.toml
name = "my-team"
description = "Our backend team's default practices"

[[skills]]
name = "apply-solid-principles"

[[skills]]
name = "apply-domain-driven-design"

Commit .grimoire/profiles/ to share standards across the team. Publish as a gist or repo (grimoire-profile-<name>) for the community.

Inline profile — define directly in grimoire.toml, no separate file:

# grimoire.toml
profiles = ["my-team"]

[profiles.my-team]
description = "Our backend team's default practices"
extends = ["oop"]

[[profiles.my-team.skills]]
name = "apply-solid-principles"

[[profiles.my-team.skills]]
name = "apply-domain-driven-design"

exclude = ["apply-law-of-demeter"]

If a profiles/my-team.toml file also exists for the same name, the file wins.

profiles vs practices — profiles activates skill bundles globally; practices is a domain-scoped explicit list. → Full comparison

→ Full profiles guide — resolution order, conflict handling, sharing profiles

grimoire is a linter for best practices — same model as ESLint for code style:

# Code style linter:             │  # Best-practice linter:
npm install eslint               │  grimoire install jeffreytse/grimoire-core
eslint .                         │  grimoire check
# watch mode:                    │  # watch mode:
eslint --watch                   │  grimoire check --live

Declare which practices you require in grimoire.toml, install the packages that encode them, then run grimoire check against any artifact — a codebase, a legal contract, a business plan, a training program. Same criteria every run. Gaps that survive human review get caught by the check.

The cycle — same inversion as TDD: declare what "good" looks like first, then bring the artifact into alignment.

1. Red      — run compliance check; identify which practices FAIL or are PARTIAL
2. Green    — invoke the relevant grimoire skill; fix until the check passes
3. Refactor — clean up while keeping the check green
4. Commit   — record progress; repeat for next gap

Run /apply-best-practice-driven-development to drive the full cycle. Run /check-best-practice-compliance for a one-off check.

Two modes — choose based on how you want to run the AI:

• Independent mode (default) — grimoire runs the AI check itself; no prior AI session needed
• Report mode — an AI session skill (/check-best-practice-compliance) generates the JSON report; grimoire check --from-report reads it and enforces thresholds

grimoire init                        # one-time project setup
grimoire check                       # independent mode: auto-selects local CLI or API provider
grimoire check --via claude          # force a specific local agent
grimoire check --live                       # file watcher + browser report — like eslint --watch
grimoire check --live --port 8080           # custom port (default 7890)
grimoire check --live --host 127.0.0.1     # localhost-only (default: all interfaces)
grimoire check --ci                  # + GitHub Actions annotations
grimoire check --junit report.xml    # + JUnit XML for CI reporters
grimoire check --from-report         # report mode: reads .grimoire/reports/compliance-latest.json

Output — always written to .grimoire/reports/:

The JSON follows the LSP Diagnostic schema — uri + range locate any finding in any text artifact, not just code.

Coverage thresholds — set in grimoire.toml, enforced on every check:

[standards.engineering]
compliance-threshold = 80        # fail if overall criteria coverage < 80%
compliance-threshold-error = 0   # fail if any error-severity violations remain

Use /fix-best-practice-finding to fix one specific compliance finding — targeted, location-aware, verified. Use /apply-best-practice-driven-development to fix everything systematically.

→ Full BPDD guide — cycle, linter, LSP schema, false positive suppression, incremental mode

→ Browse all skills by domain

grimoire-core maintains an open standard for AI agent skill quality — freely adoptable by any skill library. Community packages are encouraged to follow it; grimoire installs any git repo regardless. This quality gate applies to grimoire-core contributions only.

Every skill must pass review-best-practice-skill before merge:

grimoire validate is the reference implementation of the standard — a static linter for SKILL.md files:

grimoire validate                        # validate all skills in current directory
grimoire validate skills/                # validate a specific skills tree
grimoire validate skills/engineering/    # validate one domain
grimoire validate path/to/SKILL.md       # validate a single skill
grimoire validate skills/ --fix          # fix errors via AI (requires local agent or API key)
grimoire validate skills/ --strict       # treat warnings as errors (CI gate)
grimoire validate skills/ --no-duplicates  # skip semantic near-duplicate detection
grimoire validate --test-schema schema/tests  # run conformance test suite

Checks run on every skill: required frontmatter fields, tag format, description quality, name uniqueness, and semantic near-duplicate detection across the library.

→ Read the full standard · Adopt this standard

See CONTRIBUTING.md to submit a skill.

Domains below are from grimoire-core, the official package. Community packages may cover any domain structure — grimoire imposes no layout.

📦 Official package: github.com/jeffreytse/grimoire-core

Isn't this already in the model's training data?

Yes — and no. Models know about best practices. Skills make models do them, reliably.

The difference:

For simple tasks (write a test, fix a bug), the skeptic is right — the model doesn't need a skill. For complex, multi-step workflows — an SLO design, a post-mortem, an incident response — skills measurably change what you get. The model knows Google's engineering review process exists. It does not reliably know which question to ask first, what the output format is, or when to stop. That's what a skill encodes.

These are just textbook practices the model already knows. Why bother?

Knowing a practice and reliably executing it are different things. Ask any model "I just had a production incident" — you'll get a generic write-up. Run write-post-mortem and you get: blameless framing, 5-whys, timeline, contributing factors, action items with owners, and a detection section. The model knew all of that before the skill existed. The skill is what makes it happen consistently, in the right format, every time.

The "textbook" objection gets it backwards. Established practices are ideal for skills precisely because they're falsifiable — you can verify whether the output matches what Google's SRE book, Amazon's mechanisms, or the WHO protocol actually prescribes. If you find a skill that adds nothing over a bare prompt, that's a quality failure. File an issue.

Some frameworks here are universally known — isn't the value already in the model?

The question isn't whether the model knows the framework name. It's whether the skill encodes what practitioners who already know the name still get wrong.

A framework qualifies when the skill has substantial content beyond the acronym or label — the step most people skip, the failure mode they don't avoid, the discipline that separates expert application from surface-level application. SWOT, for example, is universally known, but most practitioners stop at the 4-quadrant list and never derive the TOWS cross-matrix (SO/WO/ST/WT strategies) — the step that converts a diagnosis into actionable options. The skill encodes that gap.

A framework doesn't qualify when the full implementation reduces to restating the framework name. If a skill's entire content would be "follow the acronym," it adds nothing — the model already knows the letters.

The test: "What would this skill contain beyond the framework name?" If the answer is "the step practitioners skip + the failure mode they don't avoid" — it qualifies. If the answer is "the letters, explained" — it doesn't.

Does grimoire conflict with my team's existing conventions?

Skills describe what the world's top institutions do. Your team may do things differently — and be right to. Two ways to handle it:

Pin your preference. Tell grimoire which approach to follow when practices conflict:

User: We follow Google's engineering practices, not IBM's.
→ Claude pins this via `pin-best-practice-preference` — applies automatically from now on.

Override or fork. A skill is a starting point, not a mandate. Adapt any skill to your context, or ignore it entirely. The format is plain Markdown and the license is MIT.

Two ways to contribute:

Add a skill — share expert knowledge across law, finance, engineering, cooking, or any of the 27 domains. First skill takes ~30 minutes.

→ Contributing guide in grimoire-core

Improve the CLI — bug fixes, new commands, performance, documentation.

1. Fork and clone this repo
2. make build to compile, make test to run tests
3. Open a PR — describe the problem it solves

→ Open issues · CONTRIBUTING.md

grimoire is free. It replaces $500/hr lawyers, $300 doctor visits, and $1M McKinsey engagements — at zero cost, forever.

If it saved you time, money, or a bad decision:

• ⭐ Star this repo — takes 2 seconds, helps thousands of people find it
• 💖 Sponsor on GitHub — keeps the maintainer funded to add more skills across more domains
• ☕ Ko-fi · Patreon · Liberapay — one-time or recurring

Every star makes grimoire more visible. Every sponsorship funds one more domain.

This project is licensed under the MIT license © Jeffrey Tse.