The world's knowledge is in your AI. The world's practice is not.
Most people don't know which best practice applies — and AI won't enforce one unless guided. Grimoire closes both gaps.

📖 Grimoire 📖

"I'm 42, AI just took my job, I have a mortgage. What do I do?"

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. 500+ skills across 27 domains. Works with Claude, Codex, Cursor, Gemini, and OpenCode.

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

→ Read the full philosophy

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]

Law — audit a SaaS contract before signing:

User: /review-saas-contract

Claude: Red flags found.

  🔴 CRITICAL  Liability cap is $500 — your contract value is $240,000
  🔴 CRITICAL  No data processing agreement — GDPR Art.28 requires one
               before processing any EU customer data
  🟡 WARNING   Auto-renewal clause: 90-day cancellation window in §14.3
  🟡 WARNING   IP ownership of custom integrations is unassigned
  ✓  PASS      SLA 99.9% with defined service credits

  Do not sign. Renegotiate: liability cap, DPA, IP clause.
  Source: ABA model SaaS agreements

Finance — calculate how much you need to retire:

User: /calculate-fire-number

Claude: Applying Trinity Study model (Bengen 1994, 95% 30-year success rate)

  Annual expenses:       $60,000
  Safe withdrawal rate:  4.0%
  ─────────────────────────────
  FIRE number:           $1,500,000

  At $4,000/month invested + 7% real return → retire in 20.4 years
  Cut annual spend by $12,000               → retire in 16.8 years

  Next: /design-portfolio-allocation

Health — design a training program:

User: /design-training-program

Claude: Hypertrophy block — intermediate, 4 days/week

  UPPER (Mon/Thu)   Bench 4×8 · Row 4×8 · OHP 3×10 · Face pull 3×15
  LOWER (Tue/Fri)   Squat 4×6 · RDL 3×8 · Leg press 3×12

  Progressive overload: +2.5 kg when all reps completed clean
  Week 5: deload — 40% volume, same intensity

  Source: NSCA CSCS + Israetel volume landmarks (2019)

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: I signed a vendor contract and now they're saying they own my data.

Claude: Situation matches: review-saas-contract (law/contracts)
        Applying review-best-practice-fit...

        🔴 CRITICAL Data ownership clause absent — defaults to vendor jurisdiction
        → Escalate to legal counsel immediately. Request amendment to §8.2.

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.

One command. Every AI agent on your system.

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

Auto-detects Claude Code, Codex, and Gemini CLI. Installs to every agent found. Also creates a global grimoire command for future installs and upgrades.

Windows (PowerShell):

Invoke-WebRequest https://raw.githubusercontent.com/jeffreytse/grimoire/main/scripts/grimoire.ps1 -OutFile grimoire.ps1; .\grimoire.ps1

Native plugin shortcuts (Claude Code):

# Step 1: add the marketplace
/plugin marketplace add jeffreytse/grimoire

# Step 2: install (skills are namespaced, e.g. /grimoire-engineering:propose-conventional-commit)
/plugin install grimoire@grimoire                   # all domains (latest)
/plugin install grimoire-engineering@grimoire       # one domain

# For subdomain-level installs, use grimoire

Granular script installs:

./scripts/grimoire                   # interactive TUI — install/uninstall/upgrade/doctor
./scripts/grimoire --domain engineering
./scripts/grimoire --domain engineering --subdomain development
./scripts/grimoire --skill engineering/development/propose-conventional-commit
./scripts/grimoire --target all      # force install to all agents, even if not detected
./scripts/grimoire --upgrade         # pull latest (choose stable or unstable channel)
./scripts/grimoire --doctor          # health check: git repo, symlinks, config
./scripts/grimoire --version         # version info with commit and date
./scripts/grimoire --list            # list available domains and skills

Gemini CLI:

gemini extensions install https://github.com/jeffreytse/grimoire          # latest
gemini extensions install https://github.com/jeffreytse/grimoire@v1.0.0   # pin to a release
gemini extensions update grimoire                                         # update later

Cursor:

./scripts/grimoire --target cursor

OpenCode: add to opencode.json:

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

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

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

Problem spans multiple domains → plan-best-practice-solution

When a problem involves 3+ independent fields, plan-best-practice-solution decomposes it with MECE methodology and sequences skills by dependency.

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.

Adding a skill

/write-best-practice-skill    # author the skill
/review-best-practice-skill   # validate against STANDARD.md (5 criteria)
/revise-best-practice-skill   # fix any review findings
→ open PR

Maintaining a domain

/audit-best-practice-domain    # batch health check — surfaces outdated or weak-sourced skills
/revise-best-practice-skill    # update stale or under-sourced skills
/deprecate-best-practice-skill # retire skills superseded by newer practices

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/settings.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/settings.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"]

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

Project settings override 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 settings management: Use /configure-grimoire to view, edit, or validate settings without touching TOML directly. Use /apply-best-practice-profile to activate a full paradigm (OOP, TDD, clean architecture) in one command. Use /resolve-best-practice-conflict to resolve contradictions between two installed skills and record the priority automatically. Use /apply-best-practice-driven-development to run the full BPDD cycle — or see the BPDD guide for the linter, LSP output, and CI integration details.

→ Full settings 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/settings.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. Tag query — all installed skills where tags contains the name

If no file 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.

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 doubles as a best-practice linter. Encode your quality criteria once in settings.toml, then run /check-best-practice-compliance 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.

Output — dual format, always written to .grimoire/reports/:

The JSON follows the LSP Diagnostic schema — uri + range locate any finding in any text artifact, not just code. Gate CI by checking "threshold.status" in the output:

result=$(jq -r '.threshold.status' .grimoire/reports/compliance-latest.json)
[ "$result" = "pass" ] || exit 1

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

[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 500+ skills by domain

grimoire maintains an open standard for AI agent skill quality — freely adoptable by any skill library.

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

→ Read the full standard · Adopt this standard

See CONTRIBUTING.md to submit a skill.

grimoire is a framework + reference skills. The domain structure is ready — contribute to fill your domain.

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.

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.

grimoire has 500+ skills. It needs 1000. Pick a domain.

Every domain has empty sub-domains waiting for skills. If you know a field — engineering, law, finance, music, cooking, anything — add the practices you've seen work at the highest level.

Your first skill in ~30 minutes:

1. Pick a practice you've used at the highest level in your field
2. Run /write-best-practice-skill — it guides you through the format step by step
3. Open a PR — /review-best-practice-skill runs automatically and flags any gaps
4. Merge after review passes

Not sure where to start? Browse open issues for requested skills, or pick any empty sub-domain from the table below.

Skills must pass review-best-practice-skill before merge. The meta skills guide the full contribution workflow:

See CONTRIBUTING.md for the full standard and GOVERNANCE.md for how the project and standard evolve.

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.