deep-dive

Profile Marker Resolution in Diagram Design: Project Directories vs Installed Skills

August 15, 2026 cathrynlavery/diagram-design ↗

Profile marker resolution selects the effective style guide by reading a project-level .diagram-design marker file first, validating its slug against the regex [a-z0-9][a-z0-9-]{0,63}, and loading the profile from ~/.diagram-design/profiles/<slug>.md, or falling back to the installed references/style-guide.md if the marker is missing or invalid.

Diagram Design separates style guide sources from installed skill files through a mechanism called profile marker resolution. In the cathrynlavery/diagram-design repository, this system determines whether to load a user-defined profile from the home directory or use the default style guide shipped with the skill. Understanding this resolution order ensures that project-specific styling takes precedence without modifying the installed skill files.

Marker-First Resolution in Project Directories

When a project root contains a .diagram-design marker file, the runtime executes the marker-first resolution path. According to the "Resolution before every generation" section in [skills/diagram-design/references/profiles.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md#L65-L84), the system performs the following steps:

  1. Read the marker as untrusted data – The file must contain exactly one line matching the grammar profile: <slug> with optional whitespace. Any extra keys, comments, or malformed lines cause rejection.
  2. Validate the slug – The extracted slug must match the regex [a-z0-9][a-z0-9-]{0,63} (starting with alphanumeric, followed by up to 63 characters of alphanumerics or hyphens).
  3. Resolve the profile file – If validation passes, the runtime loads ~/.diagram-design/profiles/<slug>.md directly from the home directory.
  4. Never copy to installed skills – The working copy at references/style-guide.md remains untouched, ensuring parallel projects using different markers never interfere with each other.

This approach guarantees that project directories control their own style guides without mutating the installed skill.

Marker-Less Fallback Resolution

When no marker file exists or the marker is malformed, profile marker resolution falls back to the installed skill files. As documented in [profiles.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md#L86-L93) and referenced in [SKILL.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md#L23-L30), the system checks the installed references/style-guide.md:

  • If the file contains a profile header, that header determines the active profile.
  • If the header is absent, the generator compares semantic-role and typography tokens against shipped defaults. Any deviation marks the style guide as custom-unsaved, prompting the user to execute a save operation to persist it as a named profile.

Both resolution paths converge on the same structural validation step, ensuring required rows exist before any diagram generation proceeds.

Validation Grammar and Constraints

The marker file enforces strict parsing rules to prevent injection or misconfiguration. The acceptable grammar allows:

  • Optional leading/trailing whitespace
  • The literal string profile: followed by a single space
  • A valid slug matching [a-z0-9][a-z0-9-]{0,63}
  • Exactly one newline (or EOF)

The system rejects markers containing additional keys, comments, or multi-line content. This strict validation appears in the resolution logic described in the profile reference documentation and reinforced in [prompts/profile.md](https://github.com/cathrynlavery/diagram-design/blob/main/prompts/profile.md#L21).

Resolution Logic in Practice

The following Python illustrates the profile marker resolution mechanism as implemented in the Diagram Design skill:

import re, pathlib, json

HOME = pathlib.Path.home()
PROFILE_LIB = HOME / ".diagram-design" / "profiles"
MARKER_FILE = pathlib.Path(".diagram-design")
SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9-]{0,63}$")

def read_marker(root: pathlib.Path) -> str | None:
    """Return a valid slug from the marker file, or None."""
    marker = root / MARKER_FILE
    if not marker.is_file():
        return None
    text = marker.read_text(encoding="utf-8").strip()
    # Grammar must be exactly `profile: <slug>`

    if not text.startswith("profile:"):
        return None
    slug = text.split(":", 1)[1].strip()
    return slug if SLUG_RE.fullmatch(slug) else None

def load_profile(slug: str) -> pathlib.Path:
    """Return the absolute path of a profile file (raises if missing)."""
    profile_path = PROFILE_LIB / f"{slug}.md"
    if not profile_path.is_file():
        raise FileNotFoundError(f"Profile '{slug}' not found")
    return profile_path

def resolve_style_guide(project_root: pathlib.Path) -> pathlib.Path:
    """Resolve the effective style‑guide file for a generation."""
    slug = read_marker(project_root)
    if slug:
        # Marker‑first path – load the home‑directory profile directly

        return load_profile(slug)
    # Marker‑less fallback – use the installed copy

    installed = project_root / "references" / "style-guide.md"
    return installed

This implementation mirrors the official documentation: read the marker, validate the slug, and either load the home-directory profile or fall back to the installed copy.

Key Files in the Resolution System

Several files in the cathrynlavery/diagram-design repository implement and verify profile marker resolution:

Summary

  • Profile marker resolution prioritizes project-level .diagram-design marker files over installed skill files to determine the active style guide.
  • Valid markers must contain exactly profile: <slug> where the slug matches [a-z0-9][a-z0-9-]{0,63}, directing the runtime to load ~/.diagram-design/profiles/<slug>.md.
  • When markers are missing or invalid, the system falls back to references/style-guide.md in the installed skill, detecting unsaved customizations through semantic-role and typography comparisons.
  • The resolution mechanism never copies profile content into installed skills, ensuring project isolation and immutability of the skill package.

Frequently Asked Questions

What happens if the .diagram-design marker file contains invalid syntax?

The runtime treats the marker as untrusted data and rejects any content that deviates from the strict profile: <slug> grammar. If the file contains extra keys, comments, or malformed slugs that fail the [a-z0-9][a-z0-9-]{0,63} regex validation, the system discards the marker and immediately falls back to the marker-less resolution path using the installed references/style-guide.md.

Does the marker file modify the installed skill's style guide?

No. When profile marker resolution succeeds using a valid marker, the system loads the profile directly from ~/.diagram-design/profiles/<slug>.md without copying or modifying the installed references/style-guide.md. This design ensures that multiple projects can use different profile markers simultaneously without interfering with each other or mutating the skill's working copy.

How does the system detect unsaved customizations in the fallback path?

During marker-less resolution, the generator compares every semantic-role and typography token in the installed references/style-guide.md against the shipped defaults. If any values deviate from the defaults and no profile header exists in the file, the system classifies the configuration as custom-unsaved and offers the user a save operation to persist these settings as a named profile in ~/.diagram-design/profiles/.

Where is the canonical documentation for profile marker resolution?

The authoritative specification resides in [skills/diagram-design/references/profiles.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md#L65-L94), specifically lines 65-84 (marker-first resolution) and lines 86-93 (marker-less fallback). The high-level behavior is summarized in [skills/diagram-design/SKILL.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md#L23-L30), while [scripts/verify-docs-sync.py](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-docs-sync.py#L39-L52) ensures consistency across all documentation surfaces.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →