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