How to Create and Manage Client Brand Profiles with the Marker System in Diagram Design

Diagram Design stores branding configurations in reusable named profiles within ~/.diagram-design/profiles/ and uses a project marker file (.diagram-design) containing profile: <slug> to automatically apply the correct brand to each workspace without modifying the core style guide.

The cathrynlavery/diagram-design repository provides a robust system for managing client brand identities through persistent profiles and project-specific markers. Instead of repeatedly editing the base style-guide.md file for different clients, you can create and manage client brand profiles with the marker system to maintain immutable skill installations while delivering fully branded diagrams across multiple projects.

Understanding the Profile Architecture

The Profile Library

Profiles are stored as individual Markdown files in the user configuration directory. According to skills/diagram-design/references/profiles.md, each profile resides at ~/.diagram-design/profiles/<slug>.md and contains a metadata header followed by the complete style guide body. The system automatically generates a default.md profile that mirrors the pristine shipped style guide upon first use.

The Project Marker File

The marker system relies on a file named .diagram-design placed at the project root. This file adheres to a strict grammar: a single line reading profile: <slug> where the slug matches the filename (lower-case, alphanumeric-hyphen, maximum 64 characters). The skill treats this file as untrusted data and ignores malformed markers with explanatory warnings.

Creating and Saving Brand Profiles

To capture the current effective style guide as a reusable profile, use the /profile command with the save verb. This creates a new file in the profile library with the required metadata header (<!-- diagram-design-profile … -->) and the full body of style-guide.md.

# Save current brand configuration as "acme-corp" profile

/diagram-design:profile save acme-corp

The CLI prompts for a display name and optional source URL during creation. The resulting file schema is validated against the current semantic role table and typography table, with missing rows automatically backfilled from shipped defaults.

Selecting Profiles with Project Markers

After creating a profile, apply it to a specific project by creating the marker file. This enables marker-first resolution, where the skill reads the profile directly instead of the installed style guide before every generation.

# Create marker file for the "acme-corp" profile

echo "profile: acme-corp" > /path/to/project/.diagram-design

This approach guarantees that parallel workspaces can use different brand skins without overwriting each other, as the marker is processed prior to any style guide copy-over operations.

Profile Resolution and Validation

The resolution logic, as implemented in the skill entry point (skills/diagram-design/SKILL.md), follows a strict hierarchy:

def resolve_style_guide(project_root):
    marker_path = os.path.join(project_root, ".diagram-design")
    if os.path.exists(marker_path):
        slug = read_marker(marker_path)  # validates "profile: <slug>"

        profile_path = os.path.expanduser(f"~/.diagram-design/profiles/{slug}.md")
        if os.path.isfile(profile_path):
            return read_file(profile_path)  # marker-first direct read

    # Fallback to installed style-guide.md

    return read_file(installed_dir / "references/style-guide.md")

Every profile undergoes schema-aware validation against the current skill version. If structural changes are detected, the user is offered an update command to persist repairs while maintaining backward compatibility.

Managing Profiles via CLI Commands

The /profile command interface (defined in commands/profile.md) implements seven verbs for comprehensive profile management:

• list: Display all available profiles in the library
• save: Persist current style guide as a new named profile
• load|switch: Change the active profile for the current project by updating the marker
• show: Display the currently active profile (checks marker first, then style guide)
• update: Repair profile structure against current schema
• reset: Restore profile to default state
• delete: Remove a profile from the library

All write, delete, and marker change operations require explicit confirmation. The command re-reads after every write to guarantee success.

# List all saved profiles

/diagram-design:profile list

# Switch current project to "beta-client" profile

/diagram-design:profile load beta-client

# Verify active profile

/diagram-design:profile show

Summary

• Profile Storage: Save reusable brand configurations to ~/.diagram-design/profiles/<slug>.md with metadata headers
• Marker Files: Create .diagram-design files containing profile: <slug> at project roots to enable automatic brand selection
• Resolution Order: The system checks markers before every generation, falling back to the installed style-guide.md only when markers are missing or invalid
• CLI Management: Use the /profile command with verbs like save, load, and show to manipulate profiles safely
• Schema Safety: All profiles validate against semantic and typography tables, with automatic backfilling of missing values

Frequently Asked Questions

What happens if the marker file points to a non-existent profile?

If the .diagram-design marker specifies a slug that does not exist in ~/.diagram-design/profiles/, the skill ignores the marker and falls back to the installed style-guide.md. The system may prompt you to save a new profile or correct the marker spelling.

Can I use different brand profiles for different projects simultaneously?

Yes. Because each project maintains its own .diagram-design marker file and resolution occurs before every generation, parallel workspaces can reference different profiles without interference. The marker-first architecture ensures complete isolation between client projects.

How does Diagram Design handle profile updates when the skill schema changes?

When the skill schema evolves (modifications to semantic role tables or typography tables), existing profiles are validated against the current version. Missing rows are backfilled from shipped defaults, and the user is offered an update command via /profile update to persist these structural repairs permanently.

Is the marker file syntax flexible or does it require exact formatting?

The marker file requires exact grammar: a single line reading profile: <slug> where the slug is lower-case, alphanumeric-hyphen, and 64 characters or fewer. The skill treats the marker as untrusted data and rejects malformed entries with explanatory warnings, then proceeds with the default style guide.

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