codexmgr 0.4.0__tar.gz → 0.5.0__tar.gz

{codexmgr-0.4.0 → codexmgr-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codexmgr
-Version: 0.4.0
+Version: 0.5.0
 Summary: Manage project-local Codex configuration from reusable templates
 Project-URL: Repository, https://github.com/JulianKimmig/codexmgr/
 Keywords: agents,cli,codex,configuration,skills
@@ -14,12 +14,12 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6.0.3
 Requires-Dist: textual>=8.2.7
 Requires-Dist: tomlkit>=0.15.0
 Provides-Extra: dev
 Requires-Dist: pytest-asyncio>=1.4.0; extra == 'dev'
 Requires-Dist: pytest>=9.0.3; extra == 'dev'
-Requires-Dist: pyyaml>=6.0.3; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # codexmgr
@@ -211,17 +211,30 @@ Named `AGENTS.md` snippets resolve from
 `$CODEXMGR_HOME/agentsmd/<name>.toml`. Path-like snippet values resolve
 relative to the project unless they are absolute paths.
 
-Named skills resolve from `$CODEXMGR_HOME/skills/<name>/SKILL.md` or
-`$CODEX_HOME/skills/<name>/SKILL.md`. Duplicate names across distinct homes
-fail so the selected skill is not ambiguous.
+Bare skill names resolve across the project `.agents/skills`,
+`$CODEXMGR_HOME/skills`, and `$CODEX_HOME/skills` stores. If the same folder
+name exists in more than one store, apply fails and asks for an explicit path.
+The project copy recorded for an enabled `$CODEXMGR_HOME` skill is recognized
+as a managed mirror and does not create a false collision on later applies.
 
 Enabled skills from `$CODEXMGR_HOME` are copied into `.agents/skills/<name>` on
 every apply. The copy overlays source files while preserving extra local files.
 Path-like skill values can point to a `SKILL.md` file or a directory containing
-`SKILL.md`.
-
-Missing skills are still written as name-based entries. That lets Codex resolve
-them later from another installed skill source.
+`SKILL.md`; a path-like value that does not exist is an error.
+
+Project-local and copied manager-home skills generate portable `name` selectors
+using the `name` value in their `SKILL.md` YAML frontmatter. Selected skills in
+those stores must therefore have valid frontmatter and a non-empty name. Apply
+also fails if two discoverable skills declare the same generated name. Skills
+resolved directly from `$CODEX_HOME` and explicit path references keep absolute
+`path` selectors because those sources are machine-specific or explicitly
+requested. Missing bare names remain name-based entries so Codex can resolve
+them later from another installed source.
+
+Managed skill-copy lock entries use the logical source `codexmgr_home` and a
+project-relative `.agents/skills/<name>` target. Apply accepts legacy absolute
+copy entries and rewrites them in this portable form, so moving or cloning a
+project does not churn generated skill config or lock state.
 
 Named custom agents resolve from `$CODEXMGR_HOME/agents/<name>.toml`. Enabled
 agents are copied into `.codex/agents/<name>.toml`; disabled agents remove the
@@ -474,14 +487,19 @@ codexmgr codex --simple <args...>
 ```
 
 By default, `codexmgr codex` applies the current project config, launches the
-real `codex` command with `CODEX_HOME` set to `<project>/.codex`, and forwards
-Codex arguments unchanged. Codex reads `.codex/config.toml` directly, so
-user-provided `-c` and `--config` arguments retain their normal Codex behavior.
-
-The wrapper links the global authentication file into `.codex/auth.json`. It
-uses `CODEX_GLOBAL_AUTH` when that variable is non-empty and otherwise uses
-`$HOME/.codex/auth.json`. A missing auth source produces a warning but does not
-stop Codex, which can then authenticate normally.
+real `codex` command with `CODEX_HOME` set to
+`<project>/.codex/.runtime`, and forwards Codex arguments unchanged. For a
+trusted project, Codex discovers the tracked `.codex/config.toml` as its
+project configuration independently of `CODEX_HOME`. This keeps generated MCP
+servers and other shared project settings in Git while mutable Codex state is
+written below the ignored `.codex/.runtime` directory. User-provided `-c` and
+`--config` arguments retain their normal Codex behavior.
+
+The wrapper links the global authentication file into
+`.codex/.runtime/auth.json`. It uses `CODEX_GLOBAL_AUTH` when that variable is
+non-empty and otherwise uses `$HOME/.codex/auth.json`. A missing auth source
+produces a warning but does not stop Codex, which can then authenticate within
+the project runtime home.
 
 Use `--simple` immediately after `codex` to run the basic command without
 applying project state, changing the child `CODEX_HOME`, or managing an auth

{codexmgr-0.4.0 → codexmgr-0.5.0}/README.md

@@ -187,17 +187,30 @@ Named `AGENTS.md` snippets resolve from
 `$CODEXMGR_HOME/agentsmd/<name>.toml`. Path-like snippet values resolve
 relative to the project unless they are absolute paths.
 
-Named skills resolve from `$CODEXMGR_HOME/skills/<name>/SKILL.md` or
-`$CODEX_HOME/skills/<name>/SKILL.md`. Duplicate names across distinct homes
-fail so the selected skill is not ambiguous.
+Bare skill names resolve across the project `.agents/skills`,
+`$CODEXMGR_HOME/skills`, and `$CODEX_HOME/skills` stores. If the same folder
+name exists in more than one store, apply fails and asks for an explicit path.
+The project copy recorded for an enabled `$CODEXMGR_HOME` skill is recognized
+as a managed mirror and does not create a false collision on later applies.
 
 Enabled skills from `$CODEXMGR_HOME` are copied into `.agents/skills/<name>` on
 every apply. The copy overlays source files while preserving extra local files.
 Path-like skill values can point to a `SKILL.md` file or a directory containing
-`SKILL.md`.
-
-Missing skills are still written as name-based entries. That lets Codex resolve
-them later from another installed skill source.
+`SKILL.md`; a path-like value that does not exist is an error.
+
+Project-local and copied manager-home skills generate portable `name` selectors
+using the `name` value in their `SKILL.md` YAML frontmatter. Selected skills in
+those stores must therefore have valid frontmatter and a non-empty name. Apply
+also fails if two discoverable skills declare the same generated name. Skills
+resolved directly from `$CODEX_HOME` and explicit path references keep absolute
+`path` selectors because those sources are machine-specific or explicitly
+requested. Missing bare names remain name-based entries so Codex can resolve
+them later from another installed source.
+
+Managed skill-copy lock entries use the logical source `codexmgr_home` and a
+project-relative `.agents/skills/<name>` target. Apply accepts legacy absolute
+copy entries and rewrites them in this portable form, so moving or cloning a
+project does not churn generated skill config or lock state.
 
 Named custom agents resolve from `$CODEXMGR_HOME/agents/<name>.toml`. Enabled
 agents are copied into `.codex/agents/<name>.toml`; disabled agents remove the
@@ -450,14 +463,19 @@ codexmgr codex --simple <args...>
 ```
 
 By default, `codexmgr codex` applies the current project config, launches the
-real `codex` command with `CODEX_HOME` set to `<project>/.codex`, and forwards
-Codex arguments unchanged. Codex reads `.codex/config.toml` directly, so
-user-provided `-c` and `--config` arguments retain their normal Codex behavior.
-
-The wrapper links the global authentication file into `.codex/auth.json`. It
-uses `CODEX_GLOBAL_AUTH` when that variable is non-empty and otherwise uses
-`$HOME/.codex/auth.json`. A missing auth source produces a warning but does not
-stop Codex, which can then authenticate normally.
+real `codex` command with `CODEX_HOME` set to
+`<project>/.codex/.runtime`, and forwards Codex arguments unchanged. For a
+trusted project, Codex discovers the tracked `.codex/config.toml` as its
+project configuration independently of `CODEX_HOME`. This keeps generated MCP
+servers and other shared project settings in Git while mutable Codex state is
+written below the ignored `.codex/.runtime` directory. User-provided `-c` and
+`--config` arguments retain their normal Codex behavior.
+
+The wrapper links the global authentication file into
+`.codex/.runtime/auth.json`. It uses `CODEX_GLOBAL_AUTH` when that variable is
+non-empty and otherwise uses `$HOME/.codex/auth.json`. A missing auth source
+produces a warning but does not stop Codex, which can then authenticate within
+the project runtime home.
 
 Use `--simple` immediately after `codex` to run the basic command without
 applying project state, changing the child `CODEX_HOME`, or managing an auth

{codexmgr-0.4.0 → codexmgr-0.5.0}/pyproject.toml

@@ -1,10 +1,11 @@
 [project]
 name = "codexmgr"
-version = "0.4.0"
+version = "0.5.0"
 description = "Manage project-local Codex configuration from reusable templates"
 readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
+    "pyyaml>=6.0.3",
     "textual>=8.2.7",
     "tomlkit>=0.15.0",
 ]
@@ -30,7 +31,6 @@ codexmgr = "codexmgr.interface.cli:entrypoint"
 [project.optional-dependencies]
 dev = [
     "pytest>=9.0.3",
-    "pyyaml>=6.0.3",
     "pytest-asyncio>=1.4.0",
 ]
 

{codexmgr-0.4.0 → codexmgr-0.5.0}/src/codexmgr/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"

{codexmgr-0.4.0 → codexmgr-0.5.0}/src/codexmgr/commands/codex_launch.py

@@ -6,6 +6,8 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import TextIO
 
+from ..core.paths import project_codex_dir, project_codex_runtime_dir
+
 
 @dataclass(frozen=True)
 class CodexLaunchRequest:
@@ -47,19 +49,21 @@ def build_project_codex_environment(
         environ: Source process environment, or ``os.environ`` when omitted.
 
     Returns:
-        A copied child environment. ``CODEX_HOME`` points to ``.codex`` when
-        that directory contains ``config.toml``.
+        A copied child environment. ``CODEX_HOME`` points to
+        ``.codex/.runtime`` when the project ``.codex`` directory contains
+        ``config.toml``.
     """
     environment = dict(os.environ if environ is None else environ)
-    project_codex_dir = cwd / ".codex"
-    if not (project_codex_dir / "config.toml").is_file():
+    config_dir = project_codex_dir(cwd)
+    if not (config_dir / "config.toml").is_file():
         return environment
 
-    project_codex_dir.mkdir(parents=True, exist_ok=True)
-    environment["CODEX_HOME"] = str(project_codex_dir)
+    runtime_dir = project_codex_runtime_dir(cwd)
+    runtime_dir.mkdir(parents=True, exist_ok=True)
+    environment["CODEX_HOME"] = str(runtime_dir)
     global_auth = _global_auth_path(environment)
     if global_auth.is_file():
-        _replace_auth_link(project_codex_dir / "auth.json", global_auth)
+        _replace_auth_link(runtime_dir / "auth.json", global_auth)
     else:
         stderr.write(
             "codexmgr codex: warning: no global auth found at "
@@ -87,7 +91,7 @@ def _replace_auth_link(auth_link: Path, global_auth: Path) -> None:
     """Replace the project auth entry with a link to global authentication.
 
     Args:
-        auth_link: Project-local ``.codex/auth.json`` link path.
+        auth_link: Project-local ``.codex/.runtime/auth.json`` link path.
         global_auth: Existing global authentication source file.
 
     Returns:

{codexmgr-0.4.0 → codexmgr-0.5.0}/src/codexmgr/core/paths.py

@@ -36,6 +36,18 @@ def project_codex_dir(cwd: Path) -> Path:
     return cwd / ".codex"
 
 
+def project_codex_runtime_dir(cwd: Path) -> Path:
+    """Return the project-local Codex runtime-home path.
+
+    Args:
+        cwd: Project directory.
+
+    Returns:
+        The ignored ``.codex/.runtime`` directory used as ``CODEX_HOME``.
+    """
+    return project_codex_dir(cwd) / ".runtime"
+
+
 def config_path(cwd: Path) -> Path:
     """Return the project codexmgr.toml path.
 

codexmgr-0.5.0/src/codexmgr/skills/candidates.py

@@ -0,0 +1,138 @@
+"""Discover every source that may satisfy a configured skill reference."""
+
+from pathlib import Path
+
+from .sources import (
+    CODEX_HOME_SOURCE,
+    CODEXMGR_HOME_SOURCE,
+    LOCAL_SOURCE,
+    PATH_SOURCE,
+    SkillSource,
+    is_named_skill,
+    project_skill_dir,
+)
+
+
+def skill_reference_candidates(
+    skill: str,
+    cwd: Path,
+    codex_home: Path,
+    codexmgr_home: Path,
+) -> list[SkillSource]:
+    """Return every existing source matching one configured reference.
+
+    Args:
+        skill: Bare skill name or explicit path reference.
+        cwd: Project directory used for local and relative-path skills.
+        codex_home: Codex home directory.
+        codexmgr_home: codexmgr home directory.
+
+    Returns:
+        Matching sources in stable store-priority order.
+    """
+    if is_named_skill(skill):
+        return _named_skill_candidates(skill, cwd, codex_home, codexmgr_home)
+    source = _resolve_path_skill(skill, cwd)
+    return [] if source is None else [source]
+
+
+def all_named_skill_sources(
+    cwd: Path,
+    codex_home: Path,
+    codexmgr_home: Path,
+) -> list[SkillSource]:
+    """Return all folder-addressable skill sources from configured stores.
+
+    Args:
+        cwd: Project directory whose local skills should be included.
+        codex_home: Codex home directory.
+        codexmgr_home: codexmgr home directory.
+
+    Returns:
+        Sources ordered by store and folder name.
+    """
+    stores = [
+        (CODEXMGR_HOME_SOURCE, codexmgr_home / "skills"),
+        (CODEX_HOME_SOURCE, codex_home / "skills"),
+        (LOCAL_SOURCE, cwd / ".agents" / "skills"),
+    ]
+    sources: list[SkillSource] = []
+    for source_type, root in stores:
+        for name in _skill_names(root):
+            skill_file = root / name / "SKILL.md"
+            sources.append(SkillSource(name, skill_file.resolve(), source_type))
+    return sources
+
+
+def _named_skill_candidates(
+    name: str,
+    cwd: Path,
+    codex_home: Path,
+    codexmgr_home: Path,
+) -> list[SkillSource]:
+    """Return every store source whose folder matches a bare name.
+
+    Args:
+        name: Bare skill folder name.
+        cwd: Project directory used for local skills.
+        codex_home: Codex home directory.
+        codexmgr_home: codexmgr home directory.
+
+    Returns:
+        Existing sources in codexmgr-home, Codex-home, then project order.
+    """
+    candidates = [
+        SkillSource(
+            name,
+            (codexmgr_home / "skills" / name / "SKILL.md").resolve(),
+            CODEXMGR_HOME_SOURCE,
+        ),
+        SkillSource(
+            name,
+            (codex_home / "skills" / name / "SKILL.md").resolve(),
+            CODEX_HOME_SOURCE,
+        ),
+        SkillSource(
+            name,
+            (project_skill_dir(cwd, name) / "SKILL.md").resolve(),
+            LOCAL_SOURCE,
+        ),
+    ]
+    return [candidate for candidate in candidates if candidate.skill_file.is_file()]
+
+
+def _resolve_path_skill(skill: str, cwd: Path) -> SkillSource | None:
+    """Resolve a path-like reference without applying named-store priority.
+
+    Args:
+        skill: Path-like skill reference.
+        cwd: Project directory used for relative paths.
+
+    Returns:
+        Resolved explicit source, or None when it does not exist.
+    """
+    path = Path(skill).expanduser()
+    if not path.is_absolute():
+        path = cwd / path
+    skill_file = path if path.name == "SKILL.md" else path / "SKILL.md"
+    if not skill_file.is_file():
+        return None
+    return SkillSource(skill, skill_file.resolve(), PATH_SOURCE)
+
+
+def _skill_names(skills_dir: Path) -> list[str]:
+    """Return sorted child-folder names containing a skill file.
+
+    Args:
+        skills_dir: Store directory containing named skill folders.
+
+    Returns:
+        Sorted folder names with an immediate ``SKILL.md`` child.
+    """
+    if not skills_dir.is_dir():
+        return []
+    return sorted(
+        path.name
+        for path in skills_dir.iterdir()
+        if path.is_dir() and (path / "SKILL.md").is_file()
+    )

{codexmgr-0.4.0 → codexmgr-0.5.0}/src/codexmgr/skills/copies.py

@@ -8,6 +8,7 @@ from typing import Any
 
 from ..core.errors import CommandError
 from ..core.toml_io import plain_toml_value
+from .sources import CODEXMGR_HOME_SOURCE, project_skill_dir
 
 
 @dataclass(frozen=True)
@@ -38,24 +39,39 @@ class SkillCopyFile:
     content: bytes
 
 
-def validate_copy_targets(copies: list[SkillCopy], previous_lock: Mapping[str, Any]) -> None:
+def validate_copy_targets(
+    copies: list[SkillCopy],
+    previous_lock: Mapping[str, Any],
+    cwd: Path,
+    codexmgr_home: Path,
+) -> None:
     """Reject first-time copies over unmanaged target folders.
 
     Args:
         copies: Current managed copies to create or refresh.
         previous_lock: Previous codexmgr lock data.
+        cwd: Current project root used to rebind portable targets.
+        codexmgr_home: Current codexmgr home used to rebind portable sources.
     """
-    previous = previous_skill_copies(previous_lock)
+    previous = previous_skill_copies(previous_lock, cwd, codexmgr_home)
     for copy in copies:
         if copy.name not in previous and copy.target.exists():
-            raise CommandError(f"Refusing to overwrite unmanaged skill copy: {copy.target}")
+            raise CommandError(
+                f"Refusing to overwrite unmanaged skill copy: {copy.target}"
+            )
 
 
-def previous_skill_copies(previous_lock: Mapping[str, Any]) -> dict[str, SkillCopy]:
+def previous_skill_copies(
+    previous_lock: Mapping[str, Any],
+    cwd: Path,
+    codexmgr_home: Path,
+) -> dict[str, SkillCopy]:
     """Read managed skill-copy metadata from previous lock data.
 
     Args:
         previous_lock: Parsed .codex/codexmgr.lock data.
+        cwd: Current project root used to rebind portable targets.
+        codexmgr_home: Current codexmgr home used to rebind portable sources.
 
     Returns:
         Previous managed copies keyed by skill name.
@@ -65,7 +81,7 @@ def previous_skill_copies(previous_lock: Mapping[str, Any]) -> dict[str, SkillCo
         raise CommandError("codexmgr.lock skills.copies must be a list")
     copies: dict[str, SkillCopy] = {}
     for raw_copy in raw_copies:
-        copy = _copy_from_lock_entry(raw_copy)
+        copy = _copy_from_lock_entry(raw_copy, cwd, codexmgr_home)
         copies[copy.name] = copy
     return copies
 
@@ -73,12 +89,16 @@ def previous_skill_copies(previous_lock: Mapping[str, Any]) -> dict[str, SkillCo
 def obsolete_copy_targets(
     previous_lock: Mapping[str, Any],
     current_copies: list[SkillCopy],
+    cwd: Path,
+    codexmgr_home: Path,
 ) -> list[Path]:
     """Return previous managed copy targets absent from current state.
 
     Args:
         previous_lock: Previous codexmgr lock data.
         current_copies: Current managed copies.
+        cwd: Current project root used to rebind portable targets.
+        codexmgr_home: Current codexmgr home used to rebind portable sources.
 
     Returns:
         Sorted target directories to remove.
@@ -86,7 +106,11 @@ def obsolete_copy_targets(
     current_names = {copy.name for copy in current_copies}
     return sorted(
         copy.target
-        for name, copy in previous_skill_copies(previous_lock).items()
+        for name, copy in previous_skill_copies(
+            previous_lock,
+            cwd,
+            codexmgr_home,
+        ).items()
         if name not in current_names
     )
 
@@ -103,8 +127,8 @@ def copy_lock_entries(copies: list[SkillCopy]) -> list[dict[str, str]]:
     return [
         {
             "name": copy.name,
-            "source": str(copy.source.resolve()),
-            "target": str(copy.target.resolve()),
+            "source": CODEXMGR_HOME_SOURCE,
+            "target": f".agents/skills/{copy.name}",
         }
         for copy in copies
     ]
@@ -156,11 +180,17 @@ def remove_skill_copy_target(target: Path) -> None:
         target.unlink()
 
 
-def _copy_from_lock_entry(raw_copy: Any) -> SkillCopy:
+def _copy_from_lock_entry(
+    raw_copy: Any,
+    cwd: Path,
+    codexmgr_home: Path,
+) -> SkillCopy:
     """Parse one skill-copy lock entry.
 
     Args:
         raw_copy: Plain lock entry value.
+        cwd: Current project root used to rebind the target.
+        codexmgr_home: Current codexmgr home used to rebind the source.
 
     Returns:
         Parsed managed skill copy.
@@ -170,9 +200,20 @@ def _copy_from_lock_entry(raw_copy: Any) -> SkillCopy:
     name = raw_copy.get("name")
     source = raw_copy.get("source")
     target = raw_copy.get("target")
-    if not isinstance(name, str) or not isinstance(source, str) or not isinstance(target, str):
-        raise CommandError("codexmgr.lock skills.copies entries must include name, source, and target")
-    return SkillCopy(name, Path(source), Path(target))
+    if not all(isinstance(value, str) for value in (name, source, target)):
+        raise CommandError(
+            "codexmgr.lock skills.copies entries must include name, source, "
+            "and target"
+        )
+    if name in {"", ".", ".."} or Path(name).name != name:
+        raise CommandError(
+            "codexmgr.lock skills.copies entries must use a safe skill name"
+        )
+    return SkillCopy(
+        name,
+        codexmgr_home / "skills" / name,
+        project_skill_dir(cwd, name),
+    )
 
 
 def _source_dirs(source: Path) -> list[Path]:

codexmgr-0.5.0/src/codexmgr/skills/metadata.py

@@ -0,0 +1,100 @@
+"""Read and validate metadata declared by Codex skill instruction files."""
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+import yaml
+from yaml import YAMLError
+
+from ..core.errors import CommandError
+
+
+def read_skill_name(skill_file: Path) -> str:
+    """Return the non-empty skill name declared in YAML frontmatter.
+
+    Args:
+        skill_file: Existing ``SKILL.md`` file to inspect.
+
+    Returns:
+        The trimmed frontmatter ``name`` value.
+
+    Raises:
+        CommandError: When frontmatter is missing, malformed, or has no valid
+            ``name`` value.
+    """
+    metadata = _read_frontmatter(skill_file)
+    name = metadata.get("name")
+    if not isinstance(name, str) or not name.strip():
+        raise _metadata_error(skill_file, "name must be a non-empty string")
+    return name.strip()
+
+
+def try_read_skill_name(skill_file: Path) -> str | None:
+    """Return a declared skill name or ``None`` for unrelated invalid files.
+
+    Args:
+        skill_file: Existing ``SKILL.md`` file to inspect.
+
+    Returns:
+        The declared name when metadata is valid, otherwise ``None``.
+    """
+    try:
+        return read_skill_name(skill_file)
+    except CommandError:
+        return None
+
+
+def _read_frontmatter(skill_file: Path) -> Mapping[str, Any]:
+    """Parse the YAML mapping at the beginning of one skill file.
+
+    Args:
+        skill_file: Existing ``SKILL.md`` file to inspect.
+
+    Returns:
+        Parsed YAML frontmatter mapping.
+
+    Raises:
+        CommandError: When the frontmatter boundaries or YAML are invalid.
+    """
+    lines = skill_file.read_text(encoding="utf-8").splitlines()
+    if not lines or lines[0].strip() != "---":
+        raise _metadata_error(skill_file, "missing YAML frontmatter")
+    closing_index = _closing_boundary(lines)
+    if closing_index is None:
+        raise _metadata_error(skill_file, "missing YAML frontmatter closing boundary")
+    try:
+        parsed = yaml.safe_load("\n".join(lines[1:closing_index]))
+    except YAMLError as exc:
+        raise _metadata_error(skill_file, "invalid YAML frontmatter") from exc
+    if not isinstance(parsed, Mapping):
+        raise _metadata_error(skill_file, "YAML frontmatter must be a mapping")
+    return parsed
+
+
+def _closing_boundary(lines: list[str]) -> int | None:
+    """Return the closing frontmatter-boundary index when present.
+
+    Args:
+        lines: Complete skill file split into lines.
+
+    Returns:
+        Closing boundary index, or ``None`` when it is missing.
+    """
+    for index, line in enumerate(lines[1:], start=1):
+        if line.strip() == "---":
+            return index
+    return None
+
+
+def _metadata_error(skill_file: Path, detail: str) -> CommandError:
+    """Build one consistently formatted metadata error.
+
+    Args:
+        skill_file: Invalid skill instruction file.
+        detail: Focused validation failure.
+
+    Returns:
+        Command error containing the resolved file location and detail.
+    """
+    return CommandError(f"Invalid skill metadata in {skill_file.resolve()}: {detail}")