How the Client Profile System Uses .diagram-design Project Markers

The client profile system uses a .diagram-design marker file in the project root to bind projects to specific brand profiles, loading custom styling from isolated files rather than the default style guide.

The cathrynlavery/diagram-design repository implements a marker-first resolution system that enables multiple client projects to share a single plugin installation without interference. By parsing a simple marker file, the diagram skill identifies which client profile to apply, allowing project-specific branding tokens to travel with your source code.

Understanding the .diagram-design Marker File

A .diagram-design file is a plain-text marker placed in the project root directory. This file contains a single configuration line that specifies which client profile to load:

profile: <slug>

The <slug> value must follow strict validation rules defined in skills/diagram-design/references/profiles.md: lowercase ASCII letters, digits, and hyphens only, with a maximum length of 64 characters. When the skill initializes, it searches for this marker before attempting to load any styling resources.

Profile Resolution Workflow

The resolution logic implemented in skills/diagram-design/SKILL.md follows a marker-first approach to determine which style guide to apply.

When processing a diagram request, the skill executes the following steps:

1. Check for the marker – The skill scans the project root for a .diagram-design file.
2. Validate the slug – If found, the skill extracts and validates the profile slug against the naming constraints.
3. Load the profile – The system reads the profile file from ~/.diagram-design/profiles/<slug>.md.
4. Fallback handling – If the marker is missing or invalid, the skill falls back to the built-in references/style-guide.md or the currently active user profile.

This architecture ensures that the installed style-guide.md remains untouched, preventing updates from overwriting customized branding.

Creating and Managing Client Profiles

Client profiles are standalone markdown files containing brand-specific tokens, colors, and typography settings. You create these profiles using the CLI commands defined in commands/profile.md.

To create a new profile from your current style configuration:

/profile save acme

This command writes a complete copy of the current style guide to ~/.diagram-design/profiles/acme.md. The profile persists across plugin updates, providing an isolated storage mechanism for client branding.

Practical Implementation Examples

The following examples demonstrate the complete workflow for binding a project to a specific client profile using the marker system.

Create a Profile and Add the Project Marker

First, save the current styling as a named profile:

/profile save acme-brand

Then, in your project root, create the marker file:

echo "profile: acme-brand" > .diagram-design

Generate Diagrams with Custom Branding

Once the marker exists, all diagram requests automatically load the specified profile:

/diagram-design "Create an architecture diagram of the authentication flow"

The skill reads the marker, validates the slug acme-brand, and renders the diagram using the tokens stored in ~/.diagram-design/profiles/acme-brand.md.

Switch Between Client Profiles

To change branding for a different client, overwrite the marker:

echo "profile: beta-client" > .diagram-design

Alternatively, remove the marker entirely to revert to the default behavior:

rm .diagram-design

Key Source Files and Architecture

The marker-based resolution system spans several files in the repository:

• skills/diagram-design/SKILL.md – Contains the core logic that checks for the .diagram-design marker before loading the style guide. This file implements the gate that prioritizes marker-based profiles over the default configuration.

• skills/diagram-design/references/profiles.md – Defines the profile storage format, slug validation rules, and the marker-first resolution specification.

• commands/profile.md – Implements the CLI interface for creating, listing, updating, and deleting profiles. This handles the /profile save command and manages the ~/.diagram-design/profiles/ directory structure.

• skills/diagram-design/references/onboarding.md – Provides the flow for extracting brand tokens from existing assets and saving them as new profiles, often followed by writing the initial marker file.

According to the source code in profiles.md, the validation regex ensures slugs contain only lowercase alphanumeric characters and hyphens, preventing filesystem conflicts and ensuring cross-platform compatibility.

Summary

• The .diagram-design marker file binds a project root to a specific client profile via a profile: <slug> declaration.
• Profile files are stored in ~/.diagram-design/profiles/<slug>.md and remain isolated from the plugin's default style-guide.md.
• Resolution follows a marker-first approach: the skill checks for the marker in SKILL.md logic before falling back to default styles.
• Slug validation enforces lowercase ASCII characters with a 64-character limit to ensure filesystem safety.
• Profiles persist across updates, allowing multiple projects to share one installation while maintaining distinct branding through their respective markers.

Frequently Asked Questions

What is the exact format of the .diagram-design marker file?

The marker file must contain a single line specifying the profile slug in the format profile: <slug>. The file should reside in the project root directory. The slug must consist of lowercase ASCII letters, digits, and hyphens only, with a maximum length of 64 characters. Any deviation from this format causes the skill to reject the marker and fall back to default styling.

Where are client profile files physically stored?

Client profiles are stored as individual markdown files in the ~/.diagram-design/profiles/ directory, with each file named <slug>.md corresponding to the profile identifier. This location is separate from the plugin installation directory, ensuring that profiles survive plugin updates and remain available across different projects on the same machine.

How does the system handle missing or invalid markers?

If the .diagram-design marker is absent, the skill falls back to the built-in style guide located at references/style-guide.md or uses the currently active user profile configured through the /profile command. Invalid slugs—those containing uppercase letters, special characters, or exceeding 64 characters—trigger the same fallback behavior, ensuring the system fails gracefully without breaking the diagram generation workflow.

Can I switch between profiles without recreating the marker file?

Yes, you can overwrite the existing marker file to switch profiles instantly. Run echo "profile: new-slug" > .diagram-design from the project root to replace the current binding. The skill reads the marker fresh on each request, so subsequent diagram commands immediately use the new profile's styling tokens without requiring a restart or reinstallation of the plugin.

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