Meta Skills
Meta skills run the grimoire framework itself. Unlike domain skills (which encode best practices in engineering, health, finance, etc.), meta skills are how you find, apply, contribute, and maintain those domain skills.
There are two audiences: users who want to apply best practices, and contributors who manage the library.
User-facing skills
These skills cover every stage of the user journey: defining the problem, finding the right practice, planning multi-domain work, evaluating existing solutions, and going deeper on any practice.
suggest-best-practice
When to use: Any time a user describes a situation, problem, goal, or question — including when they don’t know which domain applies or don’t know a best practice exists for their situation.
What it produces: Either applies the best-matching skill directly, or presents a ranked list of candidates for the user to choose from. If no installed skill matches, it identifies which domain to install.
Example invocation:
User: "Our API response times have been spiking for two days and we can't figure out why."
→ suggest-best-practice classifies this as engineering/debugging, routes to the appropriate skillUser: "I need to write a performance review for a direct report."
→ suggest-best-practice: no installed skill matches — suggests installing a management domainplan-best-practice-solution
When to use: When the problem spans multiple domains, requires coordinating several best practices in sequence, or is too complex for a single skill — e.g., launching a startup, handling a compliance audit, building a hiring process from scratch.
What it produces: A sequenced plan — sub-problems identified, each matched to the best skill, ordered by dependency. Executes one skill at a time through the plan.
Example invocation:
User: "We're a 12-person startup about to raise Series A. What do we need to get right?"
→ plan-best-practice-solution decomposes: legal entity structure → cap table clean-up →
unit economics → pitch narrative → data room — each mapped to a skill, sequencedreview-best-practice-fit
When to use: When the user already has a solution, plan, design, or approach and wants to know how well it aligns with best practices — what’s missing, what’s wrong, what to fix first.
What it produces: ALIGNED / PARTIAL / MISSING verdict per applicable practice, with a prioritized fix list.
Example invocation:
User: "Here's our API design doc — does it follow REST best practices?"
→ review-best-practice-fit evaluates against applicable skills:
ALIGNED: resource naming, HTTP verbs
PARTIAL: error response format (missing error codes)
MISSING: pagination contract, versioning strategy
→ fix list ordered by impactanalyze-best-practice-problem
When to use: When the user’s problem isn’t clearly defined — goal is unclear, scope is unstated, or what’s described looks like a symptom rather than a root cause.
What it produces: A clarification loop (one question at a time), then a structured problem space map (problem statement / scope / constraints / root cause) and 2–4 possible solution routes before handing off to solution skills.
Example invocation:
User: "My team isn't performing well."
→ analyze-best-practice-problem asks: "What outcome are you trying to achieve — better output, faster delivery, or fewer conflicts?"
→ After answers: Problem statement, scope, routes A/B/C, handoff to suggest-best-practicediscover-best-practices
When to use: When the user mentions a domain, role, or field without a specific problem — or wants to know what best practices exist before encountering a problem.
What it produces: A grouped list of available practices by subdomain, framed as “what goes wrong without each one,” with 1–3 “most commonly discovered too late” highlights.
Example invocation:
User: "What best practices exist for contract negotiation?"
→ discover-best-practices lists practices by subdomain, surfaces the 2 most commonly skipped
→ Offers to apply any or learn morestart-best-practice
When to use: When the user signals they are about to begin a task — “I’m going to write X”, “starting to build Y”, “planning to do Z” — before they have started.
What it produces: A proactive surface of the most relevant practice for that task, with the key gaps it would prevent, and an offer to apply it before they begin.
Example invocation:
User: "I'm about to refactor our auth module."
→ start-best-practice: "Before you start: review-security-posture applies here.
Common gaps at this stage: token expiry strategy, rate limiting, audit logging.
Apply now, or continue without? [y/n]"apply-best-practice-tree
When to use: When a problem is complex but stays within one domain — requiring recursive decomposition into sub-problems, each matched to the best installed skill.
What it produces: A recursive skill tree — the top-level problem matched to a skill, which surfaces sub-problems, each matched and applied in turn until the full problem is covered.
Example invocation:
User: "Our production incident response is a mess."
→ apply-best-practice-tree: top match design-incident-response-process →
sub-problems: Detection (apply-alerting-strategy), Escalation (design-on-call-rotation),
Communication (write-status-page-update), Post-incident (apply-five-whys)
→ Apply each sub-skill in orderaudit-applied-best-practices
When to use: When the user has existing work — code, a document, a design, a plan — and wants to know which best practices were applied, which are missing, and what gaps to address.
What it produces: An audit of the existing work against applicable practices (APPLIED / PARTIAL / MISSING), with a prioritized list of gaps to close.
Example invocation:
User: "Here's our current incident response runbook."
→ audit-applied-best-practices: identifies domain (engineering/reliability),
scores runbook against applicable practices, surfaces MISSING: blameless framing,
contributing factors section, PARTIAL: timeline structure
→ Fix list ordered by impactcompare-best-practices
When to use: When the user needs to choose between two or more practices that could apply to the same problem — or when suggest-best-practice surfaces multiple close matches.
What it produces: A side-by-side table (approach / evidence / best for / trade-off / adoption cost) and a clear recommendation with reasoning.
Example invocation:
User: "Should I use Kanban or Scrum for my 4-person team?"
→ compare-best-practices: side-by-side table, then:
Recommendation: Kanban
Reason: 4-person teams with mixed work types benefit from flow-based prioritization;
Scrum's sprint ceremonies add overhead that benefits larger teams more.explain-best-practice
When to use: When the user wants to understand WHY a practice works, not just apply it — or asks “what’s the evidence for X?”, “why do we do Y?”.
What it produces: A structured explanation with six sections: the problem, the origin, the evidence, the mechanism, failure modes, and common misconceptions — plus a real-world failure example.
Example invocation:
User: "Why do code reviews matter? Can't we just rely on tests?"
→ explain-best-practice: covers problem (bugs tests miss), origin (Fagan 1976),
evidence (Google 50% defect reduction), mechanism (second reader catches assumptions),
failure modes (review fatigue, rubber-stamping), misconceptions (it's about finding bugs)learn-best-practice
When to use: When the user wants to actually internalize a specific installed practice — not just understand or apply it once, but build durable recall so they can use it correctly later without an AI assistant present.
What it produces: A baseline self-explanation check, a compressed memorable “trigger → core steps → trip-up” card, a scenario-based active-recall test (with a correction-and-retest loop if the answer reveals a real gap), a 3–5 item portable memory aid, and a recommended spaced-review schedule. Works even if the practice isn’t installed but exists in a cloned repo on disk — and offers to install it afterward.
Example invocation:
User: "I want to actually learn the margin-of-safety concept, not just apply it once."
→ learn-best-practice: asks for a self-explanation first, presents a compressed card,
poses a stock-valuation scenario and checks the answer against calculate-margin-of-safety's
actual steps, produces a 4-item memory checklist, recommends re-testing in 3 dayslearn-grimoire
When to use: When a new user wants to get oriented on grimoire itself — what it is, why it exists, and how to actually use it — or an existing user has been using it without understanding the system underneath.
What it produces: A one-paragraph explanation of what grimoire is, why it exists (an AI that knows expert standards won’t enforce them without an explicit trigger), a brief map of core concepts (domains/skills/meta layer/profiles), how to use it day to day, and a close inviting a first real task.
Example invocation:
User: "I just installed this. What even is grimoire?"
→ learn-grimoire: one-paragraph explanation, the "why" (trigger + verified steps
an AI won't enforce unprompted), a brief map of domains/skills/meta-layer/profiles,
then: "Bring me a real problem you're working on right now."adapt-best-practice
When to use: When the user wants to apply a practice but has constraints that differ from the canonical case — team size, regulation, budget, maturity, or tech stack.
What it produces: An adapted version of the practice with each step labeled ✓ unchanged / adapted: / ✗ skipped, plus a trade-off summary. Core steps are never silently removed.
Example invocation:
User: "Apply design-api-architecture, but we're a 2-person startup — we don't have time for full API governance."
→ adapt-best-practice: classifies each step Core/Adjustable/Optional,
skips Optional governance steps, adapts versioning to lightweight URL convention,
warns: "Rate limiting is a Core step — skipping it is a risk."teach-best-practice
When to use: When the user wants to explain or advocate for a practice with others — a team, manager, client, or stakeholder.
What it produces: Audience-tailored talking points, a written brief, or a slide outline — with a hook framed around what the audience cares about losing, anticipated objections, and concrete responses.
Example invocation:
User: "Help me convince my manager to adopt blameless post-mortems."
→ teach-best-practice: detects audience (non-technical manager, cares about risk/cost),
produces: hook (without this, incidents repeat and cost 3× more), what it is (one sentence),
why it works (incentivizes reporting over blame), evidence (Google SRE data),
objections: "We don't have time" → responsepin-best-practice-preference
When to use: When the user wants to save a practice preference for a domain or subdomain — so future sessions automatically apply it without re-matching.
What it produces: A saved preference at session level, project level (<root>/.grimoire/preferences.md), or global level (~/.grimoire/preferences.md), depending on user choice.
Example invocation:
User: "Always use Kanban for project management, not Scrum."
→ pin-best-practice-preference: saves preference at user-chosen scope,
future suggest-best-practice calls skip matching for this subdomainresolve-best-practice-conflict
When to use: When two or more installed skills give contradictory guidance for the same situation, or to proactively scan preferences and rank conflicts before one arises.
What it produces: A recorded precedence decision — which skill wins — saved so the same conflict never has to be re-resolved.
Example invocation:
User: "design-api-versioning-strategy says use URL versioning, but our pinned REST skill says header versioning. Which wins?"
→ resolve-best-practice-conflict: surfaces both positions, asks which the user prefers,
saves the decision as a pinned preference for this subdomainconfigure-grimoire
When to use: When the user wants to view, edit, remove, or validate grimoire.toml — reading current preferences, changing or deleting a setting, switching a profile, or checking for contradictions and expired entries.
What it produces: A guided read/write interface over grimoire.toml, with confirmation before destructive edits and validation of the resulting file.
Example invocation:
User: "What profile am I currently using for engineering?"
→ configure-grimoire: reads grimoire.toml, reports the resolved profile and its source fileinstall-grimoire
When to use: When the user wants to install or uninstall skills by domain or individual skill, upgrade grimoire, clean up broken symlinks, list available skills, or health-check the installation.
What it produces: A guided interface over the grimoire CLI — shows the command, confirms before destructive operations, reports exactly what changed.
Example invocation:
User: "Uninstall the cooking domain, I don't need it."
→ install-grimoire: confirms target, runs the uninstall, reports which paths were removedapply-best-practice-driven-development
When to use: When the user wants to systematically align a project or artifact to their stated best-practice preferences — “apply BPDD”, “align this project to our settings”, “enforce our best practices like TDD.”
What it produces: A Red-Green-Refactor style compliance cycle driven by grimoire.toml and profiles — check, fix, re-check — applicable to codebases, legal documents, business plans, or any work product with declared practices.
Example invocation:
User: "Apply BPDD to this repo using our pinned engineering profile."
→ apply-best-practice-driven-development: checks compliance, fixes findings one at a time,
re-checks until the artifact matches the declared standardcheck-best-practice-compliance
When to use: When the user wants to check whether an artifact aligns with their pinned preferences — “check compliance”, “linter for best practices,” “are we following our pinned practices?”
What it produces: A compliance report against the resolved effective preferences — LSP-compatible JSON plus an HTML coverage report. The “linter for best practices.”
Example invocation:
User: "Check this PR against our pinned standards before I merge."
→ check-best-practice-compliance: runs the resolved preference set against the diff,
reports pass/fail per rule with file:line locationsfix-best-practice-finding
When to use: When the user wants to fix one specific finding from a check-best-practice-compliance report — “fix this finding”, “resolve violation #3.”
What it produces: A targeted, location-aware fix for exactly the cited finding — no unrelated changes.
Example invocation:
User: "Fix finding #3 — the SRP violation in UserService."
→ fix-best-practice-finding: loads the finding's location, applies the minimal fix,
re-runs the specific check to confirm it now passesapply-best-practice-profile
When to use: When the user wants to activate a named set of best practices for a paradigm or methodology — “use OOP”, “set profile to clean-architecture”, “switch to functional style.”
What it produces: The named profile’s skills pinned as preferences for the current scope (session, project, or global).
Example invocation:
User: "Switch this project to the clean-architecture profile."
→ apply-best-practice-profile: resolves the profile, pins its skill set as project preferenceswrite-best-practice-profile
When to use: When the user wants to create a new practice profile — “create a profile for my team”, “write an OOP profile.”
What it produces: A .grimoire/profiles/<name>.toml file bundling a curated skill set for a paradigm, team, or project context.
Example invocation:
User: "Make a backend-defaults profile from our current pinned preferences."
→ write-best-practice-profile: scaffolds the profile file, populates it from current pinsreview-best-practice-profile
When to use: When the user wants to validate a profile before using or sharing it — “review my profile”, “validate my-team.toml.”
What it produces: A validation pass — format check, verifies every referenced skill exists, surfaces internal conflicts — before the profile is trusted or shared.
Example invocation:
User: "Validate my-team.toml before I share it."
→ review-best-practice-profile: checks format and skill references, flags 1 conflicting entryshare-best-practice-profile
When to use: When the user wants to publish or share a practice profile — “share my team profile”, “open-source my backend-defaults profile.”
What it produces: A published, installable profile others can adopt directly, following the same “one shareable file replaces manual selection” pattern as eslint-config-* packages.
Example invocation:
User: "Publish my backend-defaults profile so the rest of the team can use it."
→ share-best-practice-profile: runs review-best-practice-profile first, then publishesContributor skills
These six skills manage the library: authoring, reviewing, fixing, auditing, retiring, and designing new domains.
write-best-practice-skill
When to use: When authoring a new SKILL.md — whether starting from scratch, adapting existing knowledge, or encoding a domain best practice.
What it produces: A complete SKILL.md with all required sections: frontmatter, Why This Is Best Practice (Adopted by / Impact / Why best / Sources), and Steps. Structured to pass review-best-practice-skill.
Example invocation:
User: "I want to add a skill for conducting blameless post-mortems."
→ write-best-practice-skill guides: qualify the practice → name it → write frontmatter →
find credible sources → write Why section → write Steps → self-reviewreview-best-practice-skill
When to use: When evaluating whether a SKILL.md meets grimoire standards — for self-review before submitting a PR, for maintainer PR review, or for auditing existing skills.
What it produces: A structured verdict — PASS, NEEDS-REVISION, or REJECT — with a per-criterion findings table. REJECT blocks merge. NEEDS-REVISION lists exactly what to fix.
Example invocation:
Applying review-best-practice-skill to skills/engineering/development/skills/review-pull-request/SKILL.md
→ verdict table: name ✅, description ✅, tags ⚠️ (missing outcome axis), Impact ⚠️ (vague)
→ Overall: NEEDS-REVISION — 2 required fixes before mergerevise-best-practice-skill
When to use: When an existing SKILL.md has review-best-practice-skill findings to address, a citation has become inaccurate, steps reference an outdated tool, or scope needs adjusting.
What it produces: Targeted changes to the specific failing sections only. Passing sections are left untouched.
Example invocation:
review-best-practice-skill found: Impact line says "significantly improves" — no number or study
→ revise-best-practice-skill: load the Impact finding → find the specific sentence →
replace with causal argument or cited number → re-run review-best-practice-skill → PASSaudit-best-practice-domain
When to use: When assessing the quality of all skills in a domain — before a release, after a bulk contribution, when adopting a domain for the first time, or on a weekly maintenance schedule.
What it produces: Per-skill verdicts (PASS/NEEDS-REVISION/REJECT) for every SKILL.md in the domain, plus summary counts. REJECT findings trigger deprecation or revision.
Example invocation:
Applying audit-best-practice-domain to skills/engineering/
→ engineering/development: 8 PASS, 1 NEEDS-REVISION (propose-conventional-commit)
→ engineering/testing: 5 PASS, 0 findings
→ Action items: open issue for propose-conventional-commit revisiondeprecate-best-practice-skill
When to use: When a skill has become outdated — the referenced tool no longer exists at scale, the source institution revised its position, a newer practice has achieved majority top-tier adoption that supersedes it, or the skill fails criteria it once passed.
What it produces: A two-step PR process: (1) deprecation notice added to the skill file + deprecated: true in marketplace.json; (2) after one release cycle, a removal PR deleting the directory.
Example invocation:
User: "The skill references a tool that was sunset two years ago."
→ deprecate-best-practice-skill: add notice → point to replacement skill →
merge deprecation PR → wait one release cycle → open removal PRdesign-best-practice-domain
When to use: When adding a new domain or sub-domain to grimoire — whether starting a brand-new domain (health, law, cooking), adding a new sub-domain to an existing domain, or deciding whether a new sub-domain is needed at all.
What it produces: A complete domain scaffold: directory structure, domain plugin.json, sub-domain plugin.json files, marketplace.json entries, README table update, and minimum 2 seed skills — all verified by audit-best-practice-domain before PR.
Example invocation:
User: "I want to add a 'leadership' domain with skills for 1:1s, performance reviews, team structure."
→ design-best-practice-domain: qualify (3+ separable subdomains?) → choose flat vs hierarchical →
create dirs → write plugin.json → write 2 seed skills → audit-best-practice-domain → open PRLifecycle: how meta skills connect
The meta skills form a complete workflow. No step is orphaned.
Finding and applying practices (users)
Browse before a problem
→ discover-best-practices
→ grouped list by subdomain with gap framing
→ highlights most commonly discovered too late
→ offer to apply or learn more
About to start a task
→ start-best-practice
→ proactive match before work begins
→ key gaps identified
→ apply now or continue
Problem isn't clear yet
→ analyze-best-practice-problem
→ clarification loop (one question at a time)
→ problem statement + space map + possible routes
→ hands off to suggest-best-practice or plan-best-practice-solution
Describe situation
→ suggest-best-practice (or analyze-best-practice-problem if vague)
→ single skill match: apply it directly
→ multiple matches: ranked list with ★ recommendation
→ no match: identify domain to install
→ multi-domain problem: hand off to plan-best-practice-solution
Complex single-domain problem
→ apply-best-practice-tree
→ recursive decomposition into sub-problems
→ each sub-problem matched and applied in turn
Existing solution to evaluate
→ review-best-practice-fit
→ ALIGNED / PARTIAL / MISSING per practice
→ prioritized fix list
Audit what was applied to existing work
→ audit-applied-best-practices
→ identifies which practices were applied, which are missing
→ fix list ordered by impact
Choosing between practices
→ compare-best-practices
→ side-by-side table: approach / evidence / best for / trade-offs
→ clear recommendation with reasoning
Deep understanding of a practice
→ explain-best-practice
→ problem → origin → evidence → mechanism → failure modes → misconceptions
Applying under constraints
→ adapt-best-practice
→ Core / Adjustable / Optional classification per step
→ adapted version with labeled changes
Sharing with others
→ teach-best-practice
→ audience analysis → tailored hook → talking points / brief / slide outline
Save a preference
→ pin-best-practice-preference
→ session / project / global scopeContributing a new skill
suggest-best-practice ← check no duplicate exists
└→ design-best-practice-domain ← if new domain needed
└→ write-best-practice-skill ← author SKILL.md
└→ review-best-practice-skill ← self-review
└→ revise-best-practice-skill ← fix NEEDS-REVISION findings
└→ review-best-practice-skill ← re-verify → PASS
└→ open PRMaintaining the library
audit-best-practice-domain ← weekly or pre-release
└→ NEEDS-REVISION found → revise-best-practice-skill → re-run review-best-practice-skill
└→ REJECT found
→ outdated practice: deprecate-best-practice-skill
→ fixable: revise-best-practice-skill
→ replaced by new domain: design-best-practice-domainQuick reference
| Skill | Audience | Trigger | Output |
|---|---|---|---|
analyze-best-practice-problem | User | problem isn’t clearly defined | problem statement + space map + possible routes |
discover-best-practices | User | user mentions a domain, no specific problem | grouped practice list with gap framing |
start-best-practice | User | about to begin a task | proactive practice match + apply offer |
suggest-best-practice | User | any situation or question | matching skill, ranked list, or install recommendation |
plan-best-practice-solution | User | multi-domain or complex problem | sequenced skill application plan |
apply-best-practice-tree | User | complex single-domain problem | recursive skill tree applied in sequence |
review-best-practice-fit | User | existing solution to evaluate | ALIGNED/PARTIAL/MISSING per practice + fix list |
audit-applied-best-practices | User | existing work to audit | APPLIED/PARTIAL/MISSING per practice + fix list |
compare-best-practices | User | multiple practices could apply | side-by-side table + recommendation |
explain-best-practice | User | wants to understand WHY a practice works | 6-section explanation + failure example |
adapt-best-practice | User | practice has constraint conflicts | adapted version with labeled step changes |
teach-best-practice | User | wants to share practice with others | audience-tailored talking points/brief/outline |
pin-best-practice-preference | User | wants to save a practice preference | saved preference at session/project/global scope |
write-best-practice-skill | Contributor | new practice to encode | complete SKILL.md |
review-best-practice-skill | Contributor | SKILL.md to evaluate | PASS/NEEDS-REVISION/REJECT verdict with findings |
revise-best-practice-skill | Contributor | review findings to address | targeted fixes to existing SKILL.md |
audit-best-practice-domain | Contributor | domain to assess | per-skill verdicts + summary counts |
deprecate-best-practice-skill | Contributor | outdated skill | deprecation notice + removal PR |
design-best-practice-domain | Contributor | new domain concept | directory scaffold + plugin files + seed skills |
For contributor workflow detail, see authoring-skills.md and maintaining.md.