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

> Understand profile marker resolution in diagram design. Learn how project directories and installed skills determine style guides for effective project management and consistency.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: deep-dive
- Published: 2026-08-15

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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)](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`](https://github.com/cathrynlavery/diagram-design/blob/main/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/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/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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)](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:

```python
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**:

- [[`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md#L65-L94) – Canonical definition of marker grammar, slug validation, and both resolution branches.
- [[`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md#L23-L30) – High-level description of the first-time setup gate and marker-first check.
- [[`commands/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/profile.md)](https://github.com/cathrynlavery/diagram-design/blob/main/commands/profile.md#L28) – User-facing command documentation reflecting the same resolution logic.
- [[`scripts/verify-docs-sync.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-docs-sync.py)](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-docs-sync.py#L39-L52) – Tests that profile surfaces (commands, prompts) correctly route to [`references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/profiles.md).
- [[`prompts/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/prompts/profile.md)](https://github.com/cathrynlavery/diagram-design/blob/main/prompts/profile.md#L21) – Runtime prompt shown when a marker is present, reinforcing validation rules.

## 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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)](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)](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)](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-docs-sync.py#L39-L52) ensures consistency across all documentation surfaces.