Where Are Diagram-Design Client Profiles Stored? File Paths, Format & CLI Commands

Diagram-design client profiles are stored in ~/.diagram-design/profiles/<slug>.md as standalone Markdown files, keeping them isolated from the skill package to survive updates.

The diagram-design skill persists named client profiles in a dedicated library outside the installed plugin. According to the cathrynlavery/diagram-design source code, this separation ensures user-created profiles remain intact through version upgrades and reinstalls. Each profile functions as a complete style-guide document with embedded metadata, accessible through a simple CLI interface.

Profile Storage Location

Directory Structure

All client profiles live in a single directory under the user's home folder:

• Profile library root: ~/.diagram-design/profiles/
• Individual profile file: ~/.diagram-design/profiles/<slug>.md

The slug serves as the unique identifier and filename base. The official specification in skills/diagram-design/references/profiles.md (lines 9-13) defines this path structure and naming convention as the authoritative reference for profile storage.

File Format

Each .md file contains:

1. A metadata comment block with fields: slug, name, source-url, and additional attributes
2. A complete style-guide.md document body

This format allows profiles to be version-controlled, manually edited, or shared between systems while maintaining compatibility with the diagram-design engine.

How the Profile System Works

The diagram-design engine uses a three-stage workflow for profile management:

1. Creating and Saving Profiles

The save <slug> command writes the current effective style guide to ~/.diagram-design/profiles/<slug>.md. This captures the active configuration as a reusable template.

# Save current style guide as "acme" profile

diagram-design save acme

2. Project-Level Profile Selection

A marker file .diagram-design in the project root determines which profile loads for that workspace. The file contains a single line:

profile: <slug>

When the engine detects this file, it reads the corresponding profile from the library. This allows different projects to use different client branding guidelines without global switches.

3. Profile Lifecycle Operations

All management verbs operate directly on files in ~/.diagram-design/profiles/:

Command	Action	Target File
list	Enumerate all saved profiles	Scans directory
show	Display active profile contents	Reads <slug>.md
update <slug>	Overwrite with current style guide	Rewrites <slug>.md
delete <slug>	Remove permanently	Deletes <slug>.md

The default profile operates differently—it generates from a built-in snapshot rather than a persisted file.

Complete CLI Reference

# List all saved client profiles

diagram-design list

# Save current effective style guide as new profile

diagram-design save acme

# Activate profile for current project (creates/updates .diagram-design marker)

diagram-design load acme

# Alternative syntax:

diagram-design switch acme

# Display details of currently active profile

diagram-design show

# Update existing profile after style guide modifications

diagram-design update acme

# Remove profile permanently

diagram-design delete acme

All commands read from or write to ~/.diagram-design/profiles/<slug>.md except where noted.

Key Source Files

Path	Purpose
skills/diagram-design/references/profiles.md	Definitive profile storage specification, path definitions, and command documentation
skills/diagram-design/SKILL.md	General skill description with profile handling overview
README.md	High-level introduction to the diagram-design ecosystem

Summary

• Profile location: ~/.diagram-design/profiles/<slug>.md in the user's home directory
• Isolation from updates: Profiles survive skill package upgrades because they live outside the installation directory
• Project binding: .diagram-design marker files in project roots link workspaces to specific profiles
• Direct file access: The CLI operates on plain Markdown files, enabling manual editing and version control

Frequently Asked Questions

Can I manually edit a profile file?

Yes. Because profiles are standard Markdown files at ~/.diagram-design/profiles/<slug>.md, you can edit them directly with any text editor. Run diagram-design update <slug> afterward if you want to refresh the engine's cached view, though the system typically reads fresh on each invocation.

What happens to profiles when I reinstall diagram-design?

Nothing. The profile library location outside the skill package means pip install upgrades, git pull updates, or complete reinstalls leave your ~/.diagram-design/profiles/ directory untouched. This design intentionally separates user data from application code.

How do I share profiles between machines?

Copy the <slug>.md files from ~/.diagram-design/profiles/ on one machine to the same directory on another. The metadata header ensures proper registration. For team environments, consider committing these files to a shared repository and symlinking them into each developer's profile library.

Why does the default profile behave differently?

The default profile is generated on first use from an internal snapshot rather than a persisted file. This guarantees a working baseline even when no custom profiles exist. Once you save a custom profile, you have full file-based control over your configuration.

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