@event4u/agent-config 2.17.0 → 2.19.0

package/scripts/audit_user_type_axis.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""Audit the user-type axis frontmatter coverage (step-9 Phase 4).
+
+Two checks across `.agent-src.uncompressed/skills/`:
+
+1. **Orphan values** — every `recommended_for_user_types` value must have
+   a corresponding `user-types/<value>.yml` config. Orphans are FATAL
+   (exit 1) — they imply the runtime filter would tag prompts against a
+   user-type with no documented identity.
+2. **Unused configs** — every `user-types/*.yml` should be consumed by
+   at least one skill. Unused configs are WARN-only (exit 0): seeding
+   future identities ahead of consumption is allowed.
+
+Writes a markdown report to `agents/reports/user-type-axis-audit.md` and
+emits a one-line summary to stdout. Stdlib-only — no PyYAML dependency.
+
+Usage:
+    python3 scripts/audit_user_type_axis.py            # human report + exit code
+    python3 scripts/audit_user_type_axis.py --quiet    # exit code only
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from collections import defaultdict
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SKILLS_ROOT = REPO_ROOT / ".agent-src.uncompressed" / "skills"
+USER_TYPES_ROOT = REPO_ROOT / "user-types"
+REPORT_PATH = REPO_ROOT / "agents" / "reports" / "user-type-axis-audit.md"
+
+_FRONTMATTER_LINE = re.compile(
+    r"^recommended_for_user_types:\s*\[([^\]]*)\]\s*$",
+    re.MULTILINE,
+)
+
+
+def _declared_user_types() -> set[str]:
+    """Read `user-types/*.yml` stems (one identity per YAML file)."""
+    if not USER_TYPES_ROOT.is_dir():
+        return set()
+    return {p.stem for p in USER_TYPES_ROOT.glob("*.yml")}
+
+
+def _scan_skill_values() -> dict[str, list[Path]]:
+    """Map every frontmatter user-type value → list of declaring SKILL.md paths."""
+    by_value: dict[str, list[Path]] = defaultdict(list)
+    if not SKILLS_ROOT.is_dir():
+        return by_value
+    for skill_md in sorted(SKILLS_ROOT.rglob("SKILL.md")):
+        text = skill_md.read_text(encoding="utf-8", errors="replace")
+        # Frontmatter is the leading `---` block — strip everything after.
+        if text.startswith("---\n"):
+            end = text.find("\n---", 4)
+            fm = text[4:end] if end >= 0 else text
+        else:
+            fm = text[:4096]
+        match = _FRONTMATTER_LINE.search(fm)
+        if not match:
+            continue
+        for raw in match.group(1).split(","):
+            value = raw.strip().strip('"').strip("'")
+            if value:
+                by_value[value].append(skill_md.relative_to(REPO_ROOT))
+    return by_value
+
+
+def _render_report(
+    declared: set[str],
+    by_value: dict[str, list[Path]],
+    orphans: set[str],
+    unused: set[str],
+) -> str:
+    lines: list[str] = [
+        "# User-type axis — frontmatter coverage audit",
+        "",
+        "Generated by `scripts/audit_user_type_axis.py` (step-9 Phase 4).",
+        "",
+        f"- Declared user-types (`user-types/*.yml`): **{len(declared)}**",
+        f"- Distinct frontmatter values across skills: **{len(by_value)}**",
+        f"- Orphans (FATAL): **{len(orphans)}**",
+        f"- Unused configs (WARN): **{len(unused)}**",
+        "",
+        "## Coverage matrix",
+        "",
+        "| user-type | declared | consuming skills |",
+        "| --- | --- | --- |",
+    ]
+    for ut in sorted(declared | set(by_value)):
+        flag_declared = "yes" if ut in declared else "**no (orphan)**"
+        count = len(by_value.get(ut, []))
+        lines.append(f"| `{ut}` | {flag_declared} | {count} |")
+    if orphans:
+        lines.extend(["", "## Orphans", ""])
+        for orphan in sorted(orphans):
+            lines.append(f"- `{orphan}` — referenced by:")
+            for path in by_value[orphan]:
+                lines.append(f"  - `{path}`")
+    if unused:
+        lines.extend(["", "## Unused configs (WARN)", ""])
+        for stem in sorted(unused):
+            lines.append(f"- `user-types/{stem}.yml` has no consuming skill yet.")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def main(argv: list[str]) -> int:
+    quiet = "--quiet" in argv
+    declared = _declared_user_types()
+    by_value = _scan_skill_values()
+    used = set(by_value)
+    orphans = used - declared
+    unused = declared - used
+
+    report = _render_report(declared, by_value, orphans, unused)
+    REPORT_PATH.parent.mkdir(parents=True, exist_ok=True)
+    REPORT_PATH.write_text(report, encoding="utf-8")
+
+    if not quiet:
+        sys.stdout.write(
+            f"user-type-axis audit — declared={len(declared)} "
+            f"used={len(used)} orphans={len(orphans)} unused={len(unused)}\n"
+        )
+        if orphans:
+            sys.stdout.write(
+                "  FAIL orphans: " + ", ".join(sorted(orphans)) + "\n"
+            )
+        if unused:
+            sys.stdout.write(
+                "  warn unused: " + ", ".join(sorted(unused)) + "\n"
+            )
+        sys.stdout.write(f"  report: {REPORT_PATH.relative_to(REPO_ROOT)}\n")
+
+    return 1 if orphans else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/scripts/compress.py

@@ -346,6 +346,7 @@ TOOL_DIRS = {
 SKILLS_SOURCE = PROJECT_ROOT / ".agent-src" / "skills"
 COMMANDS_SOURCE = PROJECT_ROOT / ".agent-src" / "commands"
 PERSONAS_SOURCE = PROJECT_ROOT / ".agent-src" / "personas"
+USER_TYPES_SOURCE = PROJECT_ROOT / ".agent-src" / "user-types"
 CLAUDE_SKILLS_DIR = PROJECT_ROOT / ".claude" / "skills"
 
 PERSONA_TOOL_DIRS = {
@@ -353,6 +354,11 @@ PERSONA_TOOL_DIRS = {
     ".cursor/personas": "../../.agent-src/personas",
 }
 
+USER_TYPE_TOOL_DIRS = {
+    ".claude/user-types": "../../.agent-src/user-types",
+    ".cursor/user-types": "../../.agent-src/user-types",
+}
+
 # Map tool-projection directories to the canonical tool ID used by
 # `.agent-tools.yml`. Directories not in this map are always emitted.
 _DIR_TOOL_ID = {
@@ -361,6 +367,8 @@ _DIR_TOOL_ID = {
     ".clinerules": "cline",
     ".claude/personas": "claude-code",
     ".cursor/personas": "cursor",
+    ".claude/user-types": "claude-code",
+    ".cursor/user-types": "cursor",
 }
 
 
@@ -901,6 +909,43 @@ def generate_persona_symlinks() -> int:
     return total
 
 
+def generate_user_type_symlinks() -> int:
+    """Create symlink directories for user-types (.claude/user-types/, .cursor/user-types/).
+
+    Symlinks each user-type .md file from .agent-src/user-types/ into tool-specific
+    directories. Excludes README.md and _template/ — those are authoring scaffolding,
+    not user-type lenses.
+    """
+    if not USER_TYPES_SOURCE.exists():
+        print("  ⚠️  .agent-src/user-types/ not found — skipping user-types")
+        return 0
+
+    user_types = sorted([
+        f.name for f in USER_TYPES_SOURCE.glob("*.md") if f.stem != "README"
+    ])
+    tool_dirs = _filter_tool_dirs(USER_TYPE_TOOL_DIRS)
+    total = 0
+    for tool_dir, rel_prefix in tool_dirs.items():
+        target_dir = PROJECT_ROOT / tool_dir
+        target_dir.mkdir(parents=True, exist_ok=True)
+
+        # Clean stale symlinks
+        for item in target_dir.iterdir():
+            if item.is_symlink() and item.name not in user_types and item.name != "README.md":
+                item.unlink()
+
+        for user_type in user_types:
+            link = target_dir / user_type
+            target = Path(rel_prefix) / user_type
+            if link.exists() or link.is_symlink():
+                link.unlink()
+            link.symlink_to(target)
+            total += 1
+
+    info(f"  ✅  Created {total} user-type symlinks across {len(tool_dirs)} tool directories ({len(user_types)} user-types each)")
+    return total
+
+
 def generate_tools() -> None:
     """Generate all tool-specific directories and files.
 
@@ -916,13 +961,14 @@ def generate_tools() -> None:
     skills = generate_claude_skills() if _tool_active("claude-code") else 0
     commands = generate_claude_commands() if _tool_active("claude-code") else 0
     personas = generate_persona_symlinks()
+    user_types = generate_user_type_symlinks()
     cursor_mdc = generate_cursor_mdc_rules() if _tool_active("cursor") else 0
     windsurf_modern = generate_windsurf_modern_rules() if _tool_active("windsurf") else 0
     cursor_cmds = generate_cursor_commands() if _tool_active("cursor") else 0
     windsurf_wf = generate_windsurf_workflows() if _tool_active("windsurf") else 0
     summary = (
         f"✅  generate-tools — rules={rules} skills={skills} "
-        f"commands={commands} personas={personas} "
+        f"commands={commands} personas={personas} user_types={user_types} "
         f"cursor_mdc={cursor_mdc} windsurf_rules={windsurf_modern} "
         f"cursor_commands={cursor_cmds} windsurf_workflows={windsurf_wf} "
         f"windsurfrules={windsurfrules}"
@@ -943,7 +989,7 @@ def generate_tools() -> None:
 # them to symlinks (everything else is always symlinked).
 
 # Subdirectories of .agent-src/ that map into .augment/ as symlinks.
-AUGMENT_SYMLINK_DIRS = ("skills", "commands", "guidelines", "personas", "templates", "contexts", "scripts")
+AUGMENT_SYMLINK_DIRS = ("skills", "commands", "guidelines", "personas", "user-types", "templates", "contexts", "scripts")
 # Top-level files to symlink into .augment/ (README, etc.)
 AUGMENT_SYMLINK_FILES = ("README.md",)
 

package/scripts/install

@@ -15,6 +15,10 @@
 #   --source <dir>    Package source directory (default: auto-detect)
 #   --target <dir>    Target project root (default: cwd)
 #   --profile <name>  Cost profile for bridges (minimal|balanced|full)
+#   --user-type <id>  Primary user-type for skill filtering (step-9 axis).
+#                     Valid ids: consultant | creator | developer | finance
+#                     | founder | gtm | ops. Default: empty (no filter).
+#                     Written to personal.user_type in .agent-settings.yml.
 #   --tools <list>    Comma-separated tool IDs to install (default: all).
 #                     Valid: claude-code,claude-desktop,cursor,windsurf,
 #                            cline,gemini-cli,copilot,augment,aider,codex,
@@ -82,12 +86,13 @@ SCOPE=""
 CUSTOM_PATH=""
 OFFLINE=false
 MINIMAL=false
+USER_TYPE=""
 
 # Single source of truth for valid tool IDs (also referenced by install.sh / install.py).
 VALID_TOOLS="claude-code claude-desktop cursor windsurf cline gemini-cli copilot augment aider codex roocode continue kilocode zed jetbrains kiro all"
 
 show_help() {
-    sed -n '3,54p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+    sed -n '3,58p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
 }
 
 list_tools() {
@@ -146,6 +151,8 @@ while [[ $# -gt 0 ]]; do
         --target=*)      TARGET_DIR="${1#*=}"; shift ;;
         --profile)       PROFILE="$2"; shift 2 ;;
         --profile=*)     PROFILE="${1#*=}"; shift ;;
+        --user-type)     USER_TYPE="$2"; shift 2 ;;
+        --user-type=*)   USER_TYPE="${1#*=}"; shift ;;
         --tools)         TOOLS="${TOOLS:+$TOOLS,}$2"; TOOLS_EXPLICIT=true; shift 2 ;;
         --tools=*)       TOOLS="${TOOLS:+$TOOLS,}${1#*=}"; TOOLS_EXPLICIT=true; shift ;;
         --ai)            TOOLS="${TOOLS:+$TOOLS,}$2"; TOOLS_EXPLICIT=true; shift 2 ;;
@@ -309,6 +316,7 @@ run_bridges() {
 
     local args=(--project "$TARGET_DIR" --package "$SOURCE_DIR")
     [[ -n "$PROFILE" ]] && args+=(--profile="$PROFILE")
+    [[ -n "$USER_TYPE" ]] && args+=(--user-type="$USER_TYPE")
     $FORCE && args+=(--force)
     $QUIET && args+=(--quiet)
     $GLOBAL && args+=(--global)

package/scripts/install.py

@@ -45,6 +45,8 @@ except ImportError:  # pragma: no cover — alt sys.path layout
 DEFAULT_PROFILE = "balanced"
 SUPPORTED_PROFILES = ("minimal", "balanced", "full")
 COST_PROFILE_PLACEHOLDER = "__COST_PROFILE__"
+USER_TYPE_PLACEHOLDER = "__USER_TYPE__"
+USER_TYPES_DIR = "user-types"
 
 # Env-var equivalent of --force for CI / scripted installs (P3.4).
 # When set to "1" the install run treats every conflict as
@@ -781,7 +783,44 @@ def _render_template(template: str, profile_values: "dict[str, str]") -> str:
     return body
 
 
-def ensure_agent_settings(project_root: Path, package_root: Path, profile: str, force: bool) -> None:
+def _load_valid_user_types(package_root: Path) -> list[str]:
+    """Return the sorted user-type slugs shipped under ``user-types/``.
+
+    Maps `user-types/<id>.yml` → `<id>`. The ``README.md`` is skipped.
+    Empty list when the directory is absent (older package payloads).
+    """
+    directory = package_root / USER_TYPES_DIR
+    if not directory.is_dir():
+        return []
+    return sorted(p.stem for p in directory.glob("*.yml"))
+
+
+def _validate_user_type(package_root: Path, value: str) -> str:
+    """Return the validated user-type slug (empty string allowed → no filter)."""
+    cleaned = (value or "").strip()
+    if not cleaned:
+        return ""
+    valid = _load_valid_user_types(package_root)
+    if not valid:
+        fail(
+            f"--user-type={cleaned} requested but no user-types/*.yml present "
+            f"under {package_root}"
+        )
+    if cleaned not in valid:
+        fail(
+            f"Unknown --user-type={cleaned}. Valid: {', '.join(valid)} "
+            "(empty string disables the filter)."
+        )
+    return cleaned
+
+
+def ensure_agent_settings(
+    project_root: Path,
+    package_root: Path,
+    profile: str,
+    force: bool,
+    user_type: str = "",
+) -> None:
     target = project_root / SETTINGS_FILE
     profile_source = package_root / "config" / "profiles" / f"{profile}.ini"
     template_source = package_root / "config" / "agent-settings.template.yml"
@@ -794,12 +833,16 @@ def ensure_agent_settings(project_root: Path, package_root: Path, profile: str,
     template = template_source.read_text(encoding="utf-8")
     if COST_PROFILE_PLACEHOLDER not in template:
         fail(f"Template is missing placeholder {COST_PROFILE_PLACEHOLDER}")
+    if USER_TYPE_PLACEHOLDER not in template:
+        fail(f"Template is missing placeholder {USER_TYPE_PLACEHOLDER}")
     profile_values = _parse_profile_ini(profile_source)
     if profile_values.get("cost_profile") != profile:
         fail(
             f"Profile preset {profile_source.name} has cost_profile="
             f"{profile_values.get('cost_profile')!r} but --profile={profile}"
         )
+    # Inject runtime-only values (not part of the .ini profile presets).
+    profile_values["user_type"] = _validate_user_type(package_root, user_type)
     template_body = _render_template(template, profile_values)
 
     legacy_target = project_root / LEGACY_SETTINGS_FILE
@@ -822,7 +865,9 @@ def ensure_agent_settings(project_root: Path, package_root: Path, profile: str,
         return
 
     write_file(target, template_body)
-    success(f"{SETTINGS_FILE} created (cost_profile={profile})")
+    user_type_value = profile_values.get("user_type", "")
+    suffix = f", user_type={user_type_value}" if user_type_value else ""
+    success(f"{SETTINGS_FILE} created (cost_profile={profile}{suffix})")
 
 
 def ensure_vscode_bridge(project_root: Path, package_type: str, force: bool) -> None:
@@ -3130,6 +3175,17 @@ def parse_options(argv: list[str]) -> argparse.Namespace:
         default=DEFAULT_PROFILE,
         help=f"cost_profile value ({'|'.join(SUPPORTED_PROFILES)}, default: {DEFAULT_PROFILE})",
     )
+    parser.add_argument(
+        "--user-type",
+        dest="user_type",
+        default="",
+        help=(
+            "primary user-type for skill filtering (step-9 axis). "
+            "Valid ids: consultant | creator | developer | finance | "
+            "founder | gtm | ops. Default: empty (no filter, every skill "
+            "surfaces). Written to personal.user_type in .agent-settings.yml."
+        ),
+    )
     parser.add_argument("--force", action="store_true", help="overwrite existing files")
     parser.add_argument("--skip-bridges", action="store_true", help="only create .agent-settings.yml")
     parser.add_argument(
@@ -3354,7 +3410,7 @@ def _write_install_mode_marker(project_root: Path, mode: str) -> None:
         pass
 
 
-def install_minimal(target_root: Path, force: bool) -> int:
+def install_minimal(target_root: Path, force: bool, user_type: str = "") -> int:
     """Bootstrap the project-local override layer only (D2-compliant).
 
     Writes:
@@ -3421,8 +3477,16 @@ def install_minimal(target_root: Path, force: bool) -> int:
     if settings_dst.exists() and not force:
         skip(f"{SETTINGS_FILE} already exists (use --force to overwrite)")
     else:
-        settings_dst.write_text(settings_src.read_text(encoding="utf-8"), encoding="utf-8")
-        success(f"Wrote {SETTINGS_FILE}")
+        body = settings_src.read_text(encoding="utf-8")
+        if user_type:
+            body = body.rstrip() + (
+                "\n\n# --- Personal (step-9 user-type axis) ---\n"
+                "personal:\n"
+                f"  user_type: {user_type}\n"
+            )
+        settings_dst.write_text(body, encoding="utf-8")
+        suffix = f" (user_type={user_type})" if user_type else ""
+        success(f"Wrote {SETTINGS_FILE}{suffix}")
 
     # 3. install-mode marker (Step 8 A5) — authoritative state for
     # doctor --context and future install-aware tooling. Written even
@@ -3592,7 +3656,13 @@ def main(argv: list[str]) -> int:
         target_root = Path(
             opts.custom_path or opts.project or os.environ.get("PROJECT_ROOT") or os.getcwd()
         ).resolve()
-        return install_minimal(target_root, opts.force)
+        # Validate --user-type early so the minimal short-circuit fails
+        # fast on a bogus slug instead of writing a half-formed stub.
+        # _minimal_templates_root() returns <package_root>/templates/minimal;
+        # walk two parents up to reach the package root where user-types/ lives.
+        minimal_package_root = _minimal_templates_root().parent.parent
+        validated_user_type = _validate_user_type(minimal_package_root, opts.user_type)
+        return install_minimal(target_root, opts.force, validated_user_type)
 
     # Multi-signal scope detection (Phase 1.3) + scope resolution
     # (Phase 1.4). Order of precedence (highest first):
@@ -3670,9 +3740,13 @@ def _main_project_install(
         info(f"Package:  {package_root}")
         info(f"Type:     {package_type}")
         info(f"Profile:  {opts.profile}")
+        if opts.user_type:
+            info(f"UserType: {opts.user_type}")
         print()
 
-    ensure_agent_settings(project_root, package_root, opts.profile, opts.force)
+    ensure_agent_settings(
+        project_root, package_root, opts.profile, opts.force, opts.user_type
+    )
 
     # Install-mode marker (Step 8 A5) — full path flips any prior
     # minimal marker to "full" so doctor --context reflects the

package/scripts/install.sh

@@ -79,6 +79,13 @@ parse_args() {
             --skip-gitignore) SKIP_GITIGNORE=true; shift ;;
             --tools)   TOOLS="$2"; shift 2 ;;
             --tools=*) TOOLS="${1#*=}"; shift ;;
+            # --user-type is consumed by install.py (settings persistence).
+            # Accepted here so direct `bash scripts/install.sh --user-type=...`
+            # invocations from the `install` wrapper / standalone users do not
+            # trip the "Unknown argument" guard. Value is intentionally unused
+            # by the payload-sync stage.
+            --user-type)   shift 2 ;;
+            --user-type=*) shift ;;
             --minimal|--settings-only) MINIMAL=true; shift ;;
             --help|-h) show_help; exit 0 ;;
             *) log_error "Unknown argument: $1"; show_help; exit 1 ;;

package/scripts/mcp_server/prompts.py

@@ -18,7 +18,8 @@ helpers (caller decides whether to log).
 """
 from __future__ import annotations
 
-from dataclasses import dataclass
+import dataclasses
+from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Literal
 
@@ -36,6 +37,7 @@ PHASE_1_SKILLS: tuple[str, ...] = (
 )
 
 PromptKind = Literal["skill", "command"]
+UserTypeMatch = Literal["", "match", "universal", "outside"]
 
 
 @dataclass(frozen=True)
@@ -46,6 +48,12 @@ class SkillPrompt:
     field is the frontmatter `name:` value verbatim (e.g.
     `test-driven-development` or `research:report`); MCP wire names
     are derived in `to_mcp_prompt_meta` with `kind`-aware prefixing.
+
+    `recommended_for_user_types` mirrors the SKILL.md frontmatter
+    array (step-9 user-type axis). Empty tuple = universal (no
+    user-type constraint declared). `user_type_match` is the
+    cache-computed match label against the active `personal.user_type`
+    in `.agent-settings.yml`; empty string means filtering is disabled.
     """
 
     name: str
@@ -53,6 +61,8 @@ class SkillPrompt:
     body: str
     source: str
     kind: PromptKind = "skill"
+    recommended_for_user_types: tuple[str, ...] = ()
+    user_type_match: UserTypeMatch = ""
 
 
 def _project_root() -> Path:
@@ -84,6 +94,69 @@ def _strip_frontmatter(text: str) -> tuple[dict[str, str], str]:
     return meta, body.lstrip("\n")
 
 
+def _parse_inline_array(value: str) -> tuple[str, ...]:
+    """Parse `[a, b, c]` inline-array frontmatter value into a tuple.
+
+    Returns `()` for any malformed or empty value. Quotes around items
+    are stripped. This is intentionally a tiny parser — the canonical
+    schema for skill frontmatter is enforced upstream by
+    `task lint-skills` / `scripts/validate_frontmatter.py`.
+    """
+    v = value.strip()
+    if not (v.startswith("[") and v.endswith("]")):
+        return ()
+    inner = v[1:-1].strip()
+    if not inner:
+        return ()
+    items: list[str] = []
+    for raw in inner.split(","):
+        item = raw.strip().strip('"').strip("'")
+        if item:
+            items.append(item)
+    return tuple(items)
+
+
+def _load_active_user_type(root: Path) -> str:
+    """Read `personal.user_type` from `.agent-settings.yml`.
+
+    Returns `""` when the file is missing, the key is unset, or the
+    value is still the install-time placeholder (`__USER_TYPE__`).
+    Empty string disables the runtime filter (legacy behavior — every
+    skill surfaces with its native sort order).
+
+    Tiny line-based parser to avoid a `pyyaml` runtime dependency for
+    the loader (consistent with `_strip_frontmatter`). Only matches
+    `user_type:` directly under the top-level `personal:` block.
+    """
+    settings = root / ".agent-settings.yml"
+    if not settings.is_file():
+        return ""
+    try:
+        text = settings.read_text(encoding="utf-8")
+    except OSError:
+        return ""
+    in_personal = False
+    for raw in text.splitlines():
+        if not raw or raw.lstrip().startswith("#"):
+            continue
+        if not raw[0].isspace():
+            # Top-level key — flip in_personal based on whether it's `personal:`.
+            head = raw.split("#", 1)[0].strip().rstrip(":")
+            in_personal = head == "personal"
+            continue
+        if not in_personal:
+            continue
+        stripped = raw.strip()
+        if not stripped.startswith("user_type:"):
+            continue
+        _, _, value = stripped.partition(":")
+        value = value.split("#", 1)[0].strip().strip('"').strip("'")
+        if value.startswith("__") and value.endswith("__"):
+            return ""
+        return value
+    return ""
+
+
 def load_skill(name: str, root: Path | None = None) -> SkillPrompt:
     """Load a single skill by name. Raises FileNotFoundError if missing."""
     base = root or _project_root()
@@ -107,6 +180,9 @@ def _load_file(
         body=body.rstrip() + "\n",
         source=meta.get("source", "package"),
         kind=kind,
+        recommended_for_user_types=_parse_inline_array(
+            meta.get("recommended_for_user_types", "")
+        ),
     )
 
 
@@ -231,20 +307,48 @@ def to_mcp_prompt_meta(prompt: SkillPrompt) -> dict[str, Any]:
     Colons in command names (e.g. `research:report`) become `.` so
     the wire identifier is a single-segment dotted path that survives
     every MCP client we have tested.
+
+    When the user-type axis is active (`PromptCache` resolves a
+    non-empty `personal.user_type`), each prompt carries a
+    `user_type_match` label and the projected `_meta` surfaces it so
+    MCP clients can render the "outside <id> filter" collapse group.
+    Absent / empty label means filtering is off — meta is unchanged
+    from the legacy shape, preserving back-compat.
     """
     if prompt.kind == "command":
         wire = f"command.{prompt.name.replace(':', '.')}"
     else:
         wire = f"skill.{prompt.name}"
+    meta: dict[str, Any] = {"source": prompt.source, "kind": prompt.kind}
+    if prompt.user_type_match:
+        meta["user_type_match"] = prompt.user_type_match
     return {
         "name": wire,
         "title": prompt.name,
         "description": prompt.description,
         "arguments": [],
-        "_meta": {"source": prompt.source, "kind": prompt.kind},
+        "_meta": meta,
     }
 
 
+def _user_type_rank(prompt: SkillPrompt, user_type: str) -> tuple[int, UserTypeMatch]:
+    """Return `(sort_rank, match_label)` for the step-9 axis.
+
+    Ranks (lower sorts first):
+        0 = match     — user_type is in `recommended_for_user_types`
+        1 = universal — prompt declares no recommended_for_user_types
+        2 = outside   — declared, but user_type is not in the list
+
+    Caller must guarantee `user_type` is non-empty (filter is on).
+    """
+    declared = prompt.recommended_for_user_types
+    if not declared:
+        return (1, "universal")
+    if user_type in declared:
+        return (0, "match")
+    return (2, "outside")
+
+
 class PromptCache:
     """In-memory cache with mtime-based invalidation (B5 hot-reload).
 
@@ -264,6 +368,7 @@ class PromptCache:
         self._errors: list[str] = []
         self._signature: tuple[tuple[str, float], ...] = ()
         self._index: dict[str, SkillPrompt] = {}
+        self._active_user_type: str = ""
 
     def _current_signature(self) -> tuple[tuple[str, float], ...]:
         entries: list[tuple[str, float]] = []
@@ -278,10 +383,32 @@ class PromptCache:
             for path in sorted(cmd_root.rglob("*.md")):
                 if path.is_file():
                     entries.append((str(path), path.stat().st_mtime))
+        # `.agent-settings.yml` participates in the signature so a
+        # user_type flip (re-run install with a different --user-type)
+        # invalidates the cache without needing a SKILL.md touch.
+        settings = self._root / ".agent-settings.yml"
+        if settings.is_file():
+            entries.append((str(settings), settings.stat().st_mtime))
         return tuple(entries)
 
     def _refresh(self) -> None:
         prompts, errors = load_all_prompts(self._root)
+        user_type = _load_active_user_type(self._root)
+        self._active_user_type = user_type
+        if user_type:
+            # Tag every prompt with its match label and resort:
+            #   match (0) → universal (1) → outside (2), then wire name.
+            tagged: list[SkillPrompt] = []
+            for prompt in prompts:
+                _rank, label = _user_type_rank(prompt, user_type)
+                tagged.append(dataclasses.replace(prompt, user_type_match=label))
+            prompts = sorted(
+                tagged,
+                key=lambda p: (
+                    _user_type_rank(p, user_type)[0],
+                    to_mcp_prompt_meta(p)["name"],
+                ),
+            )
         self._prompts = prompts
         self._errors = errors
         self._index = {to_mcp_prompt_meta(p)["name"]: p for p in prompts}
@@ -299,6 +426,11 @@ class PromptCache:
         """Cached `(path, mtime)` tuples (Phase-6 F1 input). Call `get()` first."""
         return self._signature
 
+    @property
+    def active_user_type(self) -> str:
+        """Currently resolved `personal.user_type` (or `""` if no filter)."""
+        return self._active_user_type
+
     def lookup(self, wire_name: str) -> SkillPrompt | None:
         """Resolve an MCP wire name to its SkillPrompt, refreshing first."""
         self.get()