How the Client Profile System Works with Project Markers in diagram-design

The client profile system in diagram-design uses a hidden .diagram-design marker file in a project's root to determine which client-specific profile to load from ~/.diagram-design/profiles/, bypassing the shared working copy when a valid marker is present.

The cathrynlavery/diagram-design repository implements a flexible client profile system that separates shared style guides from client-specific configurations. This article explains how the client profile system interacts with project markers to load customized diagram styles based on the presence of a .diagram-design file.

Profile Storage and the Default Profile

According to skills/diagram-design/references/profiles.md (lines 9-23), the system maintains a strict separation between the installed working copy and user-defined profiles.

The Profile Library Layout

Each client profile exists as a single markdown file stored in ~/.diagram-design/profiles/<slug>.md. The system ships with a built-in default profile that users can load or reset to, but cannot overwrite, update, or delete. This ensures baseline functionality remains available even when user profiles are corrupted or missing.

Slug Naming Constraints

Profile identifiers (slugs) must adhere to strict validation rules defined in the source at lines 30-33 of profiles.md. Slugs are limited to 64 ASCII characters consisting only of letters, digits, or hyphens. The system rejects spaces, dots, slashes, and other special characters to prevent path traversal and ensure valid filenames across operating systems.

Project Markers and Profile Resolution

The core mechanism connecting a project to a specific client profile is the project marker file.

The .diagram-design Marker File

A hidden file named .diagram-design placed in a project's root directory controls profile selection. When this file contains exactly profile: <slug>, the skill directly reads the corresponding profile from ~/.diagram-design/profiles/ and skips the installed working copy entirely. The marker may also specify profile: default to force use of the shipped default without creating a snapshot.

Critically, as documented in profiles.md (lines 132-135), markers are only honored after the user explicitly consents to write or replace them, preventing accidental project configuration changes.

Resolution Order and Fallback Behavior

The resolution logic implemented in skills/diagram-design/SKILL.md (lines 23-31) follows this strict hierarchy:

1. Check for marker: If .diagram-design exists and references a valid profile slug, the skill loads that profile as-is without copying it to the working copy.
2. Validate marker: If the marker is malformed or points to a non-existent profile, the skill reports the error and offers profile list to select a valid alternative.
3. Fallback to working copy: If no marker exists (or it specifies default with no snapshot), the skill falls back to the installed working copy. If the working copy contains only shipped defaults, the system presents the style-guide gate for onboarding.

Managing Profiles via CLI Commands

The profile command, defined in commands/profile.md, implements verbs that interact with both the profile library and project markers.

Listing and Loading Profiles

The profile list command displays all available profiles, marking the active one—either the profile selected via project marker or the working copy header. When using profile load <slug> in a project with an existing marker, the skill reads the named profile but does not copy it over the working copy, preserving the separation between client configurations.

Saving Profiles and Creating Markers

The profile save <slug> command writes the current effective style guide as a new profile file to ~/.diagram-design/profiles/. After saving, the skill may offer to write the project marker, but this occurs only with explicit user consent (profiles.md lines 123-130). If the project directory is unwritable, the profile saves successfully to the home library, and the user receives a prompt to manually create the marker file containing profile: <slug>.

Practical Examples

Listing Available Profiles

$ diagram-design profile list
✔ default            # built-in (read-only)

✔ blue-brand         # user-saved profile

✔ red-client         # user-saved profile ← active (project marker)

Creating a Profile and Project Marker

$ diagram-design profile save my-new-profile
✔ Saved profile to ~/.diagram-design/profiles/my-new-profile.md
? Write a project marker to use this profile for the current project? (y/N) y
✔ Wrote .diagram-design marker with `profile: my-new-profile`

Loading a Profile Without Altering the Working Copy

$ cat .diagram-design
profile: blue-brand

$ diagram-design profile load blue-brand
✔ Loaded profile "blue-brand" (no copy-over, marker used)

Resetting to the Default Profile

$ diagram-design profile reset default
✔ Reset to shipped default; marker removed if present

Summary

• Client profiles are stored as individual markdown files in ~/.diagram-design/profiles/<slug>.md, separate from the shared working copy.
• Project markers (.diagram-design files) contain a single line profile: <slug> that directs the skill to load a specific client configuration.
• Resolution priority checks for markers first, loading profiles as-is without copying, then falls back to the installed working copy if no valid marker exists.
• User consent is mandatory for creating or replacing project markers, preventing accidental configuration changes.
• The profile command provides verbs (list, load, save, update, reset, delete) to manage the library and interact with markers.

Frequently Asked Questions

What is the purpose of the .diagram-design project marker?

The .diagram-design file acts as a project marker that tells the skill which client profile to load from ~/.diagram-design/profiles/. When present in a project's root directory with content profile: <slug>, it causes the skill to bypass the shared working copy and use the specified client-specific style guide directly.

Can I override the default profile in diagram-design?

Yes, you can create custom profiles using profile save <slug> and activate them via project markers. While you cannot modify the built-in default profile itself (it is read-only), you can override its usage on a per-project basis by setting profile: default in a marker file or by creating and loading custom profiles that supersede the default behavior.

How does the skill handle missing or invalid project markers?

If a .diagram-design marker points to a non-existent profile or contains malformed syntax, the skill reports the specific error and offers the profile list command to help you select a valid profile. If no marker exists at all, the system gracefully falls back to the installed working copy, potentially triggering the style-guide onboarding flow if the working copy contains only default content.

Where are client profiles stored in diagram-design?

Client profiles are stored in the user's home directory at ~/.diagram-design/profiles/<slug>.md, with each profile existing as a separate markdown file. This location is distinct from the installed working copy of the style guide, allowing profiles to persist across project directories and skill updates.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}