write-best-practice-profile

name	write-best-practice-profile
description	Use when the user wants to create a new practice profile — e.g., "create a profile for my team", "write an OOP profile", "make a backend-defaults profile".
source	Grimoire project conventions; XDG Base Directory Specification (freedesktop.org)
tags	["profile","skill-authoring","contributor","team","preferences"]
related	["review-best-practice-profile","apply-best-practice-profile","pin-best-practice-preference"]

Write Best Practice Profile

Create a .grimoire/profiles/<name>.toml file that bundles a curated set of skills for a paradigm, team, or project context.

Why This Is Best Practice

Adopted by: Every major toolchain uses guided authoring for shared configuration — ESLint's --init, create-react-app, nx generate, and VS Code's profile export all guide users through structured configuration creation rather than expecting manual file editing. Impact: Manual TOML authoring leads to invalid skill names, missing required fields, and profiles that fail silently at activation time. A guided creation flow catches these errors before the file is written. Why best: A profile is only as good as its skill list. Guided creation ensures each skill name is validated against installed skills at write time — not discovered as a broken reference at activation time.

Sources: XDG Base Directory Specification (freedesktop.org); Grimoire docs/profiles.md

Steps

1. Gather profile identity

Ask:

• Name (slug, lowercase, hyphens): e.g. my-team, backend-defaults, frontend-strict
• Description (one sentence): when should someone activate this profile?

Profile name (slug): my-team
Description: Backend team defaults — DDD, SOLID, no framework shortcuts.

---

2. Collect skills

Two paths — offer both, user chooses:

A. Manual list — user names skills directly:

Add skills (enter names one by one, blank to finish):
  > apply-solid-principles
  > apply-domain-driven-design
  > apply-low-coupling
  >

B. Tag-assisted — run tag query, user selects subset:

Start from a tag (e.g. "oop", "tdd", "functional")? [tag or skip]:
  > oop

Found 9 skills tagged "oop":
  [x] apply-solid-principles
  [x] apply-law-of-demeter
  [ ] apply-composition-over-inheritance
  [x] apply-information-expert
  ...
Select skills to include (toggle with number, confirm with Enter)

---

3. Validate skill names

For each collected skill name, check it exists in installed grimoire skills.

• Found: mark ✓, include
• Not found: warn — ask user to confirm inclusion anyway (may be a skill they plan to install later). Use a platform-aware confirm per skill: "Include [skill-name] even though it's not installed?" (Claude Code: AskUserQuestion; OpenCode: question — same schema as AskUserQuestion; Gemini CLI: ask_user type: confirm; other: [y/n]).

Installed vs not-found distinction: When listing skills in the profile, check each against the installed skills index:

• Installed — include as-is
• Not found — flag with: [skill-name] ⚠️ not installed — users will need to install [domain] domain

Do not silently include skills that aren't installed — the profile will fail to apply for users who haven't installed those domains.

Example output (other platforms):

Validating skills...
  ✓ apply-solid-principles       — found
  ✓ apply-domain-driven-design   — found
  ⚠ apply-twelve-factor-app      — not installed. Include anyway? [y/n]

---

4. Choose save location

Use a platform-aware prompt:

• Claude Code: AskUserQuestion — options: "This project → .grimoire/profiles/ (share with team) (Recommended)", "My user level → ~/.grimoire/profiles/ (personal)"
• OpenCode: use question — same schema as AskUserQuestion
• Gemini CLI: ask_user — type: "select", same two options
• Other:

  Save to:
    [p] This project   → .grimoire/profiles/my-team.toml  (commit to repo to share with team)
    [u] My user level  → ~/.grimoire/profiles/my-team.toml (personal, applies to all projects)
  

---

5. Write the file

name = "my-team"
description = "Backend team defaults — DDD, SOLID, no framework shortcuts."

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

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

[[skills]]
name = "apply-low-coupling"

Confirm: ✓ Written to .grimoire/profiles/my-team.toml

---

6. Next steps

Auto-invoke review: After writing the profile, offer: 'Profile written. Run review-best-practice-profile now? [y/n]'

• User says n / declines: save as-is with status: draft in frontmatter. Draft profiles are not applied by suggest-best-practice or apply-best-practice-profile until status is changed to active.
• User says y, review passes: set status: active, profile is ready to use.
• User says y, review produces FAIL findings: show the findings, then offer: 'Fix now or save as draft? [fix / draft]'
  • fix: stay in this skill and apply revisions to the profile file, then re-run review
  • draft: save with status: draft, user can fix later via revise-best-practice-skill

Activate now?     profiles = ["my-team"] in grimoire.toml
Validate first?   /review-best-practice-profile my-team
Share publicly?   /share-best-practice-profile my-team

Common Mistakes

Inventing skill names. Always validate against installed skills. A profile with a typo in a skill name silently activates nothing for that entry.

One-size profiles. Profiles should be scoped — a backend-api profile is more useful than a company-wide profile that covers too many contexts.