README.md
July 19, 2026 · View on GitHub
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
🎬 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 ingrimoire.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-corewith company-internal skills, community packages, or your own library; all declared in onegrimoire.toml. - 🔬 Semantic compliance, not syntax checking. Other tools lint whether your
CLAUDE.mdis valid TOML. Grimoire checks whether your project actually follows the practices it declared — criteria by criteria, domain by domain.grimoire checkis 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.
📦 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/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
/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.
🤖 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 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
⚙️ Configuration
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:
| Priority | Level | Stored in | Scope |
|---|---|---|---|
| 1st | Session | In-memory | Current session only — resets when session ends |
| 2nd | Project | grimoire.toml | Current project, committed to repo |
| 3rd | Global | ~/.config/grimoire/grimoire.toml | All projects on this machine |
| 4th | System | /etc/grimoire/grimoire.toml | All users on this machine |
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
🎭 Profiles
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:
.grimoire/profiles/<name>.toml— project-level file~/.grimoire/profiles/<name>.toml— user-level file.grimoire/profiles/default.toml— project-level fallback~/.grimoire/profiles/default.toml— user-level fallback[profiles.<name>]ingrimoire.toml— inline definition (no separate file needed)- Tag query — all installed skills where
tagscontains 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
📏 BPDD — Best Practice Driven Development
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-reportreads 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/:
| File | Format | Use |
|---|---|---|
compliance-<timestamp>.json | LSP-compatible JSON | editors, CI pipelines, LSP servers, dashboards |
compliance-latest.json | JSON (symlink) | Always points to most recent run — use in CI |
compliance-<timestamp>.html | HTML | browser or CI artifact upload |
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
🌟 Featured Skills
| Skill | Domain | Source methodology | Verified |
|---|---|---|---|
review-saas-contract | law/contracts | ABA model SaaS agreements | ✓ |
calculate-fire-number | finance/personal-finance | Bengen (1994) / Trinity Study | ✓ |
negotiate-salary | finance/personal-finance | Fisher & Ury "Getting to Yes" / BLS data | ✓ |
design-sleep-protocol | health/sleep | Matthew Walker "Why We Sleep" / AASM | ✓ |
apply-mise-en-place | cooking/techniques | Culinary Institute of America | ✓ |
apply-five-whys | engineering/reliability | Toyota Production System / Google SRE | ✓ |
design-training-program | sports/training | NSCA CSCS curriculum | ✓ |
apply-acceptance-commitment-therapy | psychology/cognitive | Hayes / ACBS meta-analyses | ✓ |
write-value-proposition | writing/copywriting | Osterwalder "Value Proposition Design" | ✓ |
design-training-periodization-plan | sports/training | Bompa "Periodization" / NSCA | ✓ |
📐 The Grimoire Skill Standard
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:
| Criterion | Requirement | Rejection example |
|---|---|---|
| Adopted by | Named organizations or institutions | "Many top companies" |
| Impact | Cited study or % number | "Significantly improves quality" |
| Steps | Immediately executable | Abstract theory or advice |
| Scope | One concept per skill | "Nutrition and training program" |
| Source | External institution or standard body | Internal opinion |
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
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
❓ FAQ
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:
| Without a skill | With a skill |
|---|---|
| Model improvises a version of the practice | Model follows the exact steps from the source institution |
| Output varies every run | Same process, same structure, every time |
| Practice applied only if you know to ask | Skill triggers automatically when the situation matches |
| Generic advice | Specific: the right gate, the right question, the right output format |
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.
🤝 Contributing
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.
- Fork and clone this repo
make buildto compile,make testto run tests- Open a PR — describe the problem it solves
→ Open issues · CONTRIBUTING.md
❤️ Support
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.
📄 License
This project is licensed under the MIT license © Jeffrey Tse.